README file for cbm_virtual_hd
==============================

This program emulates a Commodore PET compatible hard disk drive using a
standard GPIB card under Linux. It does not do true drive emulation, so don't
expect to be able to create and work with data files. The main purpose of
this is to be able to load and save programs quickly to and from the PET.

You will need
1) A PC GPIB card (ideally one from National Instruments or one that is
   supported by the linux-gpib driver)
2) A suitable PET IEEE488-GPIB cable (see below for details)



Installing the GPIB Drivers
===========================

You will need to download the driver source package as this is not part of
most standard Linux distributions.

    http://sourceforge.net/projects/linux-gpib/
    linux-gpib-3.2.14.tar.gz

Unpack this to a build location and look at the INSTALL file.

You will need either the full source for your kernel or the headers that
match it. For many people this will be a case of doing

    sudo yum install kernel-devel-2.6.20 (your kernel version)

To build the GPIB suite do

    ./configure
    make
    sudo make install

Check where the lib has been installed. If this is /usr/local/lib, then
make sure this dir is present in the system's lib search path.
On Fedora 5 this involves creating the following file

    /etc/ld.so.conf.d/usr_local_lib.conf

with the contents

    /usr/local/lib/

You should then do a 'sudo ldconfig -v' to update your system's lib cache.
You should see libgpib.so.0.1.7 listed somewhere in the output.

Now that's done, you should be able to do a

    sudo modprobe tnt4882 (or whatever GPIB card you have installed)

Check in /dev for a bunch of gpib<N> devices.

To make this driver load at boot time I added

    alias gpib tnt4882

to /etc/modprobe.conf This works for me but perhaps I should have created a new
file in /etc/modprobe.d ?

To make the device /dev/gpib0 accessible to non-root users I created the
following file

    /etc/udev/rules.d/90-gpib.rules

with the contents

    KERNEL="gpib0", MODE="0666", GROUP="gpib"

(You could do KERNEL="gpib[0-9]*", MODE="0666", GROUP="gpib" instead to change
permissions on all the gpib device files.)

Reboot & verify that /dev/gpib<N> exist and that gpib0 has permissions
look something like mine:

    crw-rw-rw- 1 root gpib 160,  0 Jan 29 08:44 /dev/gpib0



Run-Time GPIB Configuration
===========================

I find it is necessary to run the following command after each reboot
before I am able to access the card and library. (I could get this sorted
at boot time but its no big deal for me at the moment.)

    sudo gpib_config

This takes its config data from /etc/gpib.conf.
My 'interface' section is included below. The key changes I made were:
    1) Change the primary address to 'pad = 8'
    2) Set 'master = no' so that the card does not default to being
       Controller In Charge

interface
{
        minor = 0       /* board index, minor = 0 uses /dev/gpib0, minor = 1 uses /dev/gpib1, etc. */
        board_type = "ni_pci"   /* type of interface board being used */
        name = "tims_gpib_card" /* optional name, allows you to get a board descriptor using ibfind() */
        pad = 8 /* primary address of interface             */
        sad = 0 /* secondary address of interface           */
        timeout = T3s   /* timeout for commands */

        eos = 0x0a      /* EOS Byte, 0xa is newline and 0xd is carriage return */
        set-reos = yes  /* Terminate read if EOS */
        set-bin = no    /* Compare EOS 8-bit */
        set-xeos = no   /* Assert EOI whenever EOS byte is sent */
        set-eot = yes   /* Assert EOI with last byte on writes */

/* settings for boards that lack plug-n-play capability */
        base = 0        /* Base io ADDRESS                  */
        irq  = 0        /* Interrupt request level */
        dma  = 0        /* DMA channel (zero disables)      */

/* pci_bus and pci_slot can be used to distinguish two pci boards supported by the same driver */
/*      pci_bus = 0 */
/*      pci_slot = 7 */

        master = no     /* interface board is NOT system controller */
}



Compiling cbm_virtual_hd.c
==========================

There's no Makefile as this is such a simple program. Compile as follows:
    gcc -o cbm_virtual_hd cbm_virtual_hd.c -lgpib  
(How easy was that?)
If you want to install it I suggest you simply do

    sudo cp cbm_virtual_hd /usr/local/bin



Running cbm_virtual_hd.c
========================

Launch the program and give it the path you want to use as your virtual HD.
Press any key to exit.

Notes:
1) The program loads and saves VICE compatible program files in .prg format
2) The .prg file extension is not used (I remove these to make loading/saving
   easier inder VICE anyway).
3) All filenames on the PC must be in lower case. All finenames received from
   the PET will be translated into lower case.
4) The transfer rate is ~5000 bytes/s. This limit is set by the PET.
5) Version V0.80 is not yet able to respond with a directory listing if you
   issue a LOAD"$",8 command.



Making a PET IEEE488 - GPIB Lead
================================

Edge connectors for the PET are still easily available.
Basically they are 24 way 0.156" pitch to go on a PCB 1.57 or 2.0 mm thick.
I used EDAC 307-024-500-202 connectors. However, I wish I had noticed these
weren't gold plated when I ordered them!

The GPIB connector is also available. The ones I had have are from a
ready-made 2m GPIB cable with RS part number 200-014.
The plug itself is RS 239-1207


The pin numbering on the PET is as follows

    LOOKING AT THE REAR OF THE MACHINE

     1  2  3  4  5  6  7  8  9 10 11 12
    13 14 15 16 17 18 19 20 21 21 23 24

The pin numbering on the GPIB (Amphenol) connector is as follows

    LOOKING AT THE REAR OF THE PLUG

    12 11 10  9  8  7  6  5  4  3  2  1
    24 23 22 21 20 19 18 17 16 15 14 13

Use a 24-way shielded cable. All the pins are wired through 1:1
Note: It is recommended that the following pins should travel as twisted pairs
    6  and 18
    7  and 19
    8  and 20
    9  and 21
    10 and 22
    11 and 23
    12 and 24
You might get away with a plain 24 way cable, you might not.
Ensure that the cable shield is connected to pin 12 at each end.
200-014
See attached JPEGs of my reworked GPIB cable.



You Are Ready To Go
===================

Now go dig that PET out of the cupboard and let your kids loose on it !!!

Remember, the commands you need are:

    LOAD"FILENAME",8
    SAVE"FILENAME",8

Or to do an absolute save from the TIM monitor

    .S"FILENAME",08,SSSS,EEEE

where SSSS and EEEE are the start and end addresses in hex.

Other useful stuff:

SYS4 or SYS1024 - Enter TIM monitor (the correct entry point is SYS 64785)

Start of BASIC program $0028-$0029 - usually 01 04 for BASIC prog
End (start vars)       $002A-$002B \
End vars               $002C-$002D  } - all the same after a fresh load
End arrays             $002E-$002F /

Load address           $00C7-$00C8 - as start above
Load end address       $00C9-$00CA - as end above

If the ARROW ROM turboloader has been used then
Load start address is at  $02B0 - $02B1
and the end address is at $02B2 - $02B3



=========================================

Tim Howe
moc.dlrowltn@321ylbmit
30 January 2010

[EOF]
