
                   README for cbm4linux 0.2.4
                   --------------------------

This  is version 0.2.x of cbm4linux, a Linux kernel device driver
for the serial CBM bus (C64, VIC-20, etc.).  It should  work with
any  devices  that  understand  the "normal" talk and listen com
mands. It's been tested with several 1541, 1541-II, 1571  and   a
MPS-1200. The following cable types are supported: 

  XP1571             (version >= 0.2.4)
  XM1541 and XA1541  (version >= 0.2.1)
  XP1541             (version >= 0.2.0)
  Modified XE1541    (all versions, obsoleted by the XM1541, 
                      see config.make)

More  information on the different cable types can be obtained on
the Star Commander  homepage  (<http://sta.c64.org/sc.html>)  and
the file CABLE (included in this packages)

This package is provided `as is', no warranty of any kind will be
taken for any damage or data loss caused by it or by any  use  of
it.


INSTALLATION:
~~~~~~~~~~~~~

The kernel module (cbm.o) does not require any kernel patches and
should compile right out of the box, at least  with kernel  2.2.x
and 2.4.x, but 2.0.x might still work as well.

If  you  intend  to  modify  the drive routines for `d64copy and
`cbmformat you also need a crossassembler.  `config.make  comes
with   rules   for  A.Fachat's  `xa  (available  from  funet  or
<http://www.lb.shuttle.de/puffin/cbm4linux>)  and   Ullrich   von
Bassewitz'   `cl65  (comes  with  cc65,  <http://www.cc65.org>).
Starting with version 0.2.3,  cbm4linux  comes  with  precompiled
6502  binaries,  so  as  long  as  you don't touch the .a65 files
there's  no  need  for  a crossassembler.

This  version comes with a .spec file for those who want to build
binary .RPMs.  See the RPM documentation for  details  about  the
build process. If you upgrade from a previous version and want to
install a binary RPM, don't forget to remove the old files  hang
ing aroung (just do "make uninstall").


Manual installation:

Type

    make

to  build both the kernel module and the utility programs and (as
root)

    make dev

to   create   the  character  device "/dev/cbm" with major 10 and
minor 177 (this number is registered,  so  it  shouldn't  collide
with anything else :)). Then

    make install

to  install the binaries and the man pages, check config.make for
destination directories. After that, you should be able  to  load
the module with

    /sbin/insmod cbm port=your_ioport irq=your_irq

Be sure your parallel port really uses an interrupt (check BIOS).
"port" defaults to 0x378, "irq" to 7.

Check  /proc/ioports  and  /proc/interrupts  if  insmod tells you
something about "Driver or resource busy". You'll  probably  have
to unload the modules "lp" and "parport_pc" then.

Now try (I assume your drive is device #8)

    cbmctrl command 8 I0:

which should cause the drive to initialize the disk and

    cbmctrl status 8

to  read the error channel. You should get a "00, ok,00,00" if is
has a formatted disk, otherwise "21,read error,00,00".  If every
thing works fine, you probably want to add the lines

    alias char-major-10-177 cbm
    options cbm port=your_ioport irq=your_irq

to /etc/modules.conf (/etc/conf.modules on older SuSE systems) so
that the module gets loaded on demand.


Congratulations, that's all!


HOW TO USE:
~~~~~~~~~~~

As  the  kernel driver is quite useless for itself, the following
utility programs are included with this package:

  cbmctrl    command line utility for direct device access at
             talk/listen level.

  cbmprint   simple script to print on a serial IEC printer

  cbmformat  fast 1541 disk formatter.

  d64copy    copies .d64 images to 1541 compatible drives and
             vice versa. Type `d64copy -h' to get a list of valid
             options. Use the device number to address the disk
             drive, e.g. `d64copy -t serial2 8 img.d64'.

             This version contains the StarCommander Turbo and
             Warp routines and custom transfer routines as well
             as parallel cable (XP1541) support. These are the
             benchmarks for my Pentium-200/MMX system (seconds)

                 mode               write     read

                 parallel turbo     54.02    53.30
                 parallel warp      32.47    29.56
                 serial1 turbo     168.59   168.58
                 serial1 warp      183.57   158.87
                 serial2 turbo      95.02    95.26
                 serial2 warp       88.29    80.57

Documentation  comes in ASCII, DVI, HTML and Texinfo. If you have
the GNU info program installed you can access the latter one with

    info cbm4linux


CREDITS:
~~~~~~~~

The fast format drive routine used by `cbmformat' and the turbo
and warp drive routines used by `d64copy' are heavily based on
Joe Forster/STAs Star Commander routines.

The XP1541 and XP1571 cables (C) by Joe Forster/STA.
The original XE1541 cable (C) by Nicolas Welte and Wolfgang Moser
The XA1541 cable (C) by Michael Klein and Nicolas Welte


THANKS TO:
~~~~~~~~~~

Joe Forster/STA  for supplying the Star Commander source and
                 discussions about the X?1541 interfaces
Nicolas Welte    for help with the XA1541 and XM1541 interfaces
The VICE team    for VICE
Andr Fachat     for the xa 6502 crossassembler


FEEDBACK:
~~~~~~~~~

Feel free to drop me a note if you have ideas, patches etc. or if
you just want to tell me how happy you are with this program ;-)


Have fun,
Michael Klein <nip@c64.org>

