  opencbm 0.4.0 Users Guide
  Michael Klein, nip@c64.org, Spiro Trikaliotis,
  cbm4win@trikaliotis.net, Wolfgang Moser d81.de
  2006-04-28

  This document describes the opencbm package, a Linux kernel module and
  Windows kernel mode driver, and a few user space support programs to
  control and use serial devices as used by most Commodore (CBM) 8-bit
  machines.
  ______________________________________________________________________

  Table of Contents



  1. Overview
     1.1 Introduction to opencbm
     1.2 Supported operating systems
     1.3 Supported CBM hardware
     1.4 Cables

  2. News/Changelog
  3. Installation
     3.1 Installing opencbm on Linux (cbm4linux)
        3.1.1 Compile-time configuration
        3.1.2 Compilation
        3.1.3 Loading the module
        3.1.4 Troubleshooting
        3.1.5 Device access
        3.1.6 Runtime configuration
     3.2 Installing opencbm on Windows (cbm4win)

  4. Checking if the installation is complete
  5. Utilities
     5.1 instcbm (Windows only)
        5.1.1 instcbm invocation
        5.1.2 instcbm Examples
     5.2 cbmctrl
        5.2.1 Command structure
           5.2.1.1 Global options
           5.2.1.2 Actions overview
           5.2.1.3 Common action arguments
        5.2.2 Actions
        5.2.3 cbmctrl Examples
     5.3 cbmformat
        5.3.1 cbmformat invocation
        5.3.2 cbmformat Notes for 1571 drives
        5.3.3 cbmformat Examples
     5.4 cbmforng
        5.4.1 cbmforng invocation
        5.4.2 cbmforng Notes for 1571 drives
        5.4.3 cbmforng Examples
     5.5 d64copy
        5.5.1 d64copy invocation
        5.5.2 d64copy Examples
     5.6 cbmcopy
        5.6.1 cbmcopy invocation
        5.6.2 cbmcopy Examples
     5.7 rpm1541
        5.7.1 rpm1541 usage
        5.7.2 rpm1541 Example
     5.8 flash
        5.8.1 flash usage
        5.8.2 flash Example
     5.9 morse
        5.9.1 morse usage
        5.9.2 morse Examples

  6. opencbm API
     6.1 Preprocessor macros
     6.2 Enumeration types
     6.3 Generic types
     6.4 Functions
        6.4.1 Basic I/O
        6.4.2 Low-level port access
        6.4.3 Helper functions
        6.4.4 PetSCII functions
        6.4.5 Parallel Burst functions
        6.4.6 libd64copy TODO
        6.4.7 libcbmcopy TODO

  7. Known bugs and problems
  8. Misc
     8.1 Credits
     8.2 Contributions
     8.3 Feedback


  ______________________________________________________________________

  [1m1.  Overview[0m

  The popular Commodore 8-bit home-computers like the C-64 and the
  VIC-20 are using a custom serial bus to talk to attached devices (disk
  drive, printer).  The opencbm kernel module provides an interface to
  this so-called IEC bus at the level of simple TALK and LISTEN
  commands, similar to the one provided by the Commodore kernel
  routines. Additionally, some higher and lower level bus control is
  available as well, allowing for full control of the bus. The serial
  devices are connected to the PC's parallel port via an XM1541 or
  XA1541 cable and, optionally, an XP1541 or XP1571 add-on cable. For
  cables, cf. ``cable''.


  [1m1.1.  Introduction to opencbm[0m

  This is version 0.4.0 of opencbm, a kernel device driver for the
  serial CBM bus (C64, VIC-20, etc.) for Linux and Windows. opencbm is a
  re-join of the two projects cbm4linux (latest standalone version:
  0.3.2) and cbm4win (latest standalone version: 0.1.0a). It should be
  noted that both projects were highly related from the beginning, as
  cbm4win 0.1.0 was based on cbm4linux 0.3.2.

  Opencbm should work with any devices that understand the "normal" talk
  and listen commands of the CBM IEC bus. It has been tested with
  several 1541, 1541-II, 1571 and 1581 drives, and a MPS-1200 pritnter.
  1541 clones like the Oceanic OC-118 have also been reported to work.

  The following cable types are supported:



  +o  XM1541 and XA1541  (cbm4linux version >= 0.2.1, cbm4win version >=
     0.1.0)

  +o  XP1541             (cbm4linux version >= 0.2.0, cbm4win version >=
     0.1.0)

  +o  XP1571             (cbm4linux version >= 0.2.4, cbm4win version >=
     0.1.0)

  +o  Modified XE1541    (only on Linux, obsoleted by the XM1541, see
     `LINUX/config.make')

  More information on the different cable types can be found in
  ``cable''.

  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.


  [4m***[24m [4mWARNING[24m [4m*****************************************************[0m

  [4mHOTPLUGGING[24m [4mcan[24m [4mKILL[24m [4myour[24m [4mhardware.[0m

  [4mDo[24m [4mnot[24m [4mconnect[24m [4manything[24m [4mto[24m [4mthe[24m [4mparallel[24m [4mport[24m [4mwhile[24m [4mthe[24m [4msystem[24m [4mor[24m [4ma[0m
  [4mdrive[24m [4mis[24m [4mup.[0m
   [4mAlways[24m [4mSHUT[24m [4mDOWN,[24m [4mCONNECT,[24m [4mREBOOT.[0m

  [4mAgain,[24m [4mabsolutely[24m [4mNO[24m [4mWARRANTY.[0m

  [4m*****************************************************************[0m


  [1m1.2.  Supported operating systems[0m

  [4mopencbm[24m supports the following operating systems:


  +o  Linux 2.4 and 2.6; 2.0 and 2.2 might still work, but have not been
     tested for ages. For Linux, i386 and AMD64 architectures are
     supported.

  +o  Windows NT 4.0, 2000, XP and Server 2003. The i386 architecture is
     fully supported; additionally, there are experimental AMD64 and
     iA64 versions available.


  [1m1.3.  Supported CBM hardware[0m

  Currently, opencbm supports the following CBM devices:


  +o  VIC 1541 (all variants, including VIC 1540 and clones)

  +o  VIC 1570

  +o  VIC 1571

  +o  VIC 1581 (not with d64copy, not with cbmformat or cbmforng)

  +o  other CBM IEC drives, printers, and compatibles (only with cbmctrl)


  [1m1.4.  Cables[0m

  A standard X(E)1541 cable won't work with _this_ driver. In fact,
  there will probably never be a multitasking OS which works with one of
  these, that's why we call it XM1541, M for Multi tasking. Anyway, if
  you have a XE1541, the necessary modification is simple:


  [1mExchange pins 5 & 6 on the Commodore DIN plug[0m


  The ACK line is the only line on a PC parallel port that can generate
  a hardware interrupt. This way, we get an interrupt when the device
  releases the DATA line to signal "ready to receive". Without an
  interrupt, you would have to poll for this signal about every 100us,
  which is inacceptable for any multitasking system.

  Be sure to have your parallel port configured to use an IRQ, usually 7
  or 5, but both are often also used by soundcards.

  (ASCII art taken from the StarCommander README :))


  The PC parallel plug (male DB-25 connector):



          PaperEnd   Busy
      SelectIn   |   |   Ack        Data 7 - Data 0       Strobe
             |   |   |   |   +-------------+-------------+   |
             V   V   V   V   |                           |   V
          +------------------------------------------------------+
          | 13  12  11  10   9   8   7   6   5   4   3   2   1   |
          |  o   o   o   o   o   o   o   o   o   o   o   o   o   |
          +-+                                                  +-+
            |  o   o   o   o   o   o   o   o   o   o   o   o   |
            | 25  24  23  22  21  20  19  18  17  16  15  14   |
            +--------------------------------------------------+
               |                           |   ^   ^   ^   ^
               +-------------+-------------+   |   |   |   |
                          Ground          Select   |   |   AutoFeed
                                                Init   Error



  The Commodore drive serial bus plug (male 6-pin DIN connector) looks
  like:



                                        Reset
                                          |
                                          V
                                 +-------+ +-------+
                               +-+       +-+       +-+
                               |     5         1     |
                      Data --> |     o    6    o     | <-- SrqIn
                               |          o          |
                               |     4         2     |
                       Clk --> |     o    3    o     | <-- Gnd
                               |          o          |
                               +-+                 +-+
                                 +-----------------+
                                          ^
                                          |
                                         Atn



  This is the XE1541 cable (won't work with this driver):



           CBM drive serial port   PC parallel port

               2  Gnd ---------- 18-25  Ground
               3  Atn --------+---- 13  SelectIn
                              +->|-- 1  Strobe
               4  Clk --------+---- 12  PaperEnd
                              +->|- 14  AutoFeed
               5  Data -------+---- 11  Busy
                              +->|- 17  SelectIn
               6  Reset ------+---- 10  Ack
                              +->|- 16  Init



  This is the XM1541 (pins 5 & 6 on the CBM end exchanged)



           CBM drive serial port   PC parallel port

               2  Gnd ---------- 18-25  Ground
               3  Atn --------+---- 13  SelectIn
                              +->|-- 1  Strobe
               4  Clk --------+---- 12  PaperEnd
                              +->|- 14  AutoFeed
               6  Reset ------+---- 11  Busy
                              +->|- 17  SelectIn
               5  Data -------+---- 10  Ack
                              +->|- 16  Init



  Besides the XM1541, a XA1541 cable is also supported. That cable
  consists of the same connections as the XM1541, but instead of using
  diodes, it uses transistors which drive the lines better. Because of
  this difference, the logic for outputs is reversed between the XA1541
  and the XM1541.


  Additionally to the cable types above, opencbm also supports XP1541
  and XP1571 parallel cables, which have to be used [4min[24m [4mconjunction[24m with
  the XM1541 or XA1541 cable.


  For more information about the different supported cables (XM1541,
  XA1541, XP1541, XP1571) can be obtained on the Star Commander homepage
  (http://sta.c64.org/xcables.html)


  [1m2.  News/Changelog[0m


     [1mopencbm v0.4.0:[0m

        +o  General:

           +o  Reorganized structure so cbm4win and cbm4linux compile
              from the same sources

           +o  Fixed many minor and major errors

           +o  Added mnib36 (http://rittwage.com/c64pp/dp.php?pg=mnib)
              support

           +o  [4mcbmforng[24m: New tool, cf. ``cbmforng''

           +o  [4mrpm1541[24m: New tool, cf. ``rpm1541''


        +o  General, Windows specific:

           +o  Use a free build instead of a checked build. This
              significantly reduces the memory footprint.

           +o  compiles for AMD64, iA64, i386 (Windows only)

           +o  VDD to allow DOS programs to access cbm4win

           +o  new unit file for Delphi, to allow to access cbm4win from
              Delphi

           +o  New project opencbmvice for debugging with the help of
              VICE (http://www.viceteam.org/). For this, a special
              version of VICE is needed.


        +o  Linux driver:

           +o  Fixed kernel source directory (Dirk Jagdmann)

           +o  Fixed installation with GNU coreutils head (Dirk Jagdmann)

           +o  Added correct module installation dir for Linux 2.6 (Dirk
              Jagdmann)

           +o  Added descriptions for module parameters ([4mmodinfo[24m [4mcbm[24m)
              (Dirk Jagdmann)

           +o  Added "smart reset" for cbm4linux: Delay the reset until
              all drives are ready.


        +o  Windows driver:

           +o  Only access the bus if the parallel port was successfully
              acquired.

           +o  Added ECP and EPP support into NT4 driver (allowing XP1541
              cable to be used there)

           +o  On reset, do not wait a fixed timeout anymore, just wait
              until all drives are ready again



        +o  instcbm:

           +o  [4m--lock[24m, [4m--cabletype[24m: New options

           +o  [4m--automatic[24m is default now, new option [4m--on-demand[24m for old
              behaviour

           +o  Added [4m-V[24m ([4m--version[24m) command-line option

           +o  Reworked start of driver. It was unloaded and loaded
              before, which does not make sense


        +o  cbmctrl:

           +o  [4mcbmctrl[24m [4mpopen[24m, [4mcbmctrl[24m [4mpcommand[24m to do ASCII -> PETSCII
              conversions

           +o  [4mcbmctrl[24m [4mstatus[24m, [4mcbmctrl[24m [4mdir[24m: Output the status on stdout,
              not stderr

           +o  [4mcbmctrl[24m [4mlock[24m, [4mcbmctrl[24m [4munlock[24m: New commands

           +o  [4mcbmctrl[24m [4mread[24m, [4mcbmctrl[24m [4mwrite[24m: New commands

           +o  Added [4m--version[24m and [4m--help[24m command-line arguments.

           +o  [4mcbmctrl[24m [4mchange[24m [4mdrive[24m: New function (heavily based on Joe
              Forster/STA's "TDCHANGE" from SC, used with permission)
           +o  [4mcbmctrl[24m [4mdetect[24m outputs whether we have a parallel cable


        +o  cbmcopy:

           +o  Fixed some timing problems which resulted in hanging in
              rare cases;

           +o  Cosmetical fix: The device status is written on a separate
              line on exit.

           +o  Fixed some races between PC and drive code in the transfer
              functions serial1, serial2, parallel

           +o  New option [4m--transfer=auto[24m, which is default and finds out
              the best transfer method for the current setup.

           +o  Do not use $14 in the floppy drive as temporary variable,
              but $86. This fixes a problem with Rex-DOS.

           +o  Do not trash the file on the PC side if aborted with
              Ctrl+C.


        +o  d64copy:

           +o  Fixed some timing problems which resulted in hanging in
              rare cases;

           +o  [4m--warp[24m is default now; New option [4m--no-warp[24m for disabling
              it.

           +o  did not recognize .d71 files as valid images; fixed that.

           +o  Fixed some races between PC and drive code in the transfer
              functions [4mserial1[24m, [4mserial2[24m, [4mparallel[0m

           +o  New option [4m--transfer=auto[24m, which is default and finds out
              the best transfer method for the current setup.

           +o  Do not use $14 in the floppy drive as temporary variable,
              but $86. This fixes a problem with Rex-DOS.

           +o  Do not trash the file on the PC side if aborted with
              Ctrl+C.


        +o  API:

           +o  cbm_detect_xp1541(): New function

           +o  cbm_iec_setrelease(): New function

           +o  cbm_iec_set(), cbm_iec_release(): Extended API to allow
              setting/resetting more than one line at the same time


        +o  Build process (Windows):

           +o  reworked build process ([4mDDKBUILD_START.BAT[24m)

           +o  [4mDDKBUILD_LOCAL.BAT[24m contains settings for the CC65 build
              process, now.

           +o  [4mddkbuild_local.bat.sample[24m added as sample for a
              DDKBUILD_LOCAL.BAT file
           +o  [4mpostbuild_local.bat.sample[24m added as sample for a
              POSTBUILD_LOCAL.BAT file


        +o  Build process (Linux):

           +o  Moved makefiles into LINUX directory; thus, use [4mmake[24m [4m-f[0m
              [4mLINUX/Makefile[24m to compile now.



     [1mcbm4linux 0.3.3 (NEVER RELEASED!)[0m

        +o  documentation in [4m--help[24m for [4md64copy[24m and [4mcbmcopy[24m fixed: now,
           it is clearly stated that a XP cable must be used in
           combination with a serial cable, not as only one. (Spiro
           Trikaliotis)

        +o  fixed crash with unkown long options in d64copy, cbmformat
           and maybe cbmcopy (Spiro Trikaliotis)

        +o  [4mcbmctrl[24m [4mupload[24m accepts [4m-[24m as filename now (read from stdin)

        +o  [4mcbmctrl[24m [4mdownload[24m takes optionally a file name argument (Spiro
           Trikaliotis)

        +o  [4mlibd64copy[24m failed to recognize .d71 images as valid images.
           Because of this, you could not write a .d71 image back to a
           real floppy drive

        +o  [4md64copy[24m: If you copy a disc to an image which already exists,
           the error information was not removed from the file if
           necessary. This is fixed now.  (Spiro Trikaliotis)

        +o  [4mlibd64copy[24m: Fixed a crash on exit of d64copy if a .d64 file
           grows.

        +o  parport_enumerate()-fix for kernels>=2.6.4

        +o  new ioctl CBMCTRL_CLEAR_EOI and API function cbm_clear_eoi()
           (Robert Norris)

        +o  minor (still compatible) API changes (Spiro Trikaliotis)

        +o  [4mcbmformat[24m: make sure disk name is 0-terminated (Spiro
           Trikaliotis)



  [1m3.  Installation[0m

  Depending on the system you are running opencbm on, there are
  different ways to install opencbm. Use the appropriate category for
  you:


  [1m3.1.  Installing opencbm on Linux (cbm4linux)[0m

  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. `LINUX/config.make' comes
  with rules for A.Fachat's `xa' (available from
  http://www.floodgap.com/retrotech/xa/ or
  http://www.lb.shuttle.de/puffin/cbm4linux/; Note: xa has not been
  tested lately, and might not work anymore) and Ullrich von Bassewitz'
  `cl65' (comes with cc65, http://www.cc65.org/).  Starting with version
  cbm4linux 0.2.3, opencbm includes precompiled 6502 binaries, so as
  long as you don't touch the .a65 files, there's no need for a
  crossassembler.

  This package comes with a .spec file for those who want to build
  binary .RPMs.  See the RPM documentation (outside of this paper) for
  details about the build process. Additionally, all files needed to
  built Debian .DEB packages are included. If you upgrade from a
  previous (non-RPM and non-DEB) version and want to install a
  packetized binary version (RPM or DEB), don't forget to remove the old
  files hanging aroung (just do "[4mmake[24m [4muninstall[24m", preferably in the
  *old* source directory. For a >= 0.4.0 version of opencbm, change the
  line to "[4mmake[24m [4m-f[24m [4mLINUX/Makefile[24m [4muninstall[24m".).


  [1m3.1.1.  Compile-time configuration[0m

  The compile-time configuration is located in `LINUX/config.make'.
  Check the KERN_FLAGS line if you're running kernel 2.0.x or if you
  don't want to use the Linux parport subsystem for some reason. Same
  goes for SMP machines.



  [1m3.1.2.  Compilation[0m

  Type


  +o  [4mmake[24m [4m-f[24m [4mLINUX/Makefile[24m    (no root privileges required)

     to  build  the  kernel module, libraries and utility programs (no
     root privileges required),

  +o  [4mmake[24m [4m-f[24m [4mLINUX/Makefile[24m [4mdev[24m    (as root)

     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 :)). Finally

  +o  [4mmake[24m [4m-f[24m [4mLINUX/Makefile[24m [4minstall[24m     (as root)

     will  install  all  necessary  stuff  to  /usr/local/...  (can be
     changed in `LINUX/config.make')


  [1m3.1.3.  Loading the module[0m

  If  you're  using  the  parport subsystem (which is default), you
  should now be able to load the driver module by issuing (as root)



  +o  [4m/sbin/depmod[0m

  +o  [4m/sbin/modprobe[24m [4mparport[24m      (unless compiled into the kernel)

  +o  [4m/sbin/insmod[24m [4mcbm[24m [4mlp=[24myour_lp   (usually 0, which is default)


  or, when built with -DDIRECT_PORT_ACCESS:


  +o  [4m/sbin/insmod[24m [4mcbm[24m [4mport=your_ioport[24m [4mirq=your_irq[24m (default is 0x378
     for port, 7 for irq)

  Check /var/log/messages if the correct cable type was recognized
  (XA1541/XM1541).



  [1m3.1.4.  Troubleshooting[0m

  Finding the cause of a failure condition can be hard. Anyway, the
  following tips might help you:


  +o  Check /var/log/messages; it might give you some hints.

  +o  If you are using the parport subsystem (no -DDIRECT_PORT_ACCESS):


     +o  the port might be occupied by another device (e.g. `lp.o') cbm.o
        does NOT support port sharing (wouldn't work anyway).  Enter [4mcat[0m
        [4m/proc/parport/port/devices[24m to find out.

     +o  parport_pc might not use an IRQ.  [4m/etc/modules.conf[24m should
        contain something like:


                 alias parport_lowlevel parport_pc
                 options parport_pc io=0x378 irq=7



     Check the interrupts with [4mcat[24m [4m/proc/interrupts[24m.


  +o  Using direct port access (with -DDIRECT_PORT_ACCESS):


     +o  The port/IRQ might occupied by another driver (e.g. parport.o)
        Enter [4mcat[24m [4m/proc/interrupts[24m and [4mcat[24m [4m/proc/ioports[24m to find out.



  [1m3.1.5.  Device access[0m

  As a first test, try something simple like


  +o  [4mcbmctrl[24m [4mcommand[24m [4m8[24m [4mI0:[24m    (assuming drive 8)

  +o  [4mcbmctrl[24m [4mstatus[24m [4m8[0m


  (no root privileges required)


  Failure can be caused by:

  +o  Possibly, the shared library in /usr/local/lib/ cannot be found; in
     this case, add /usr/local/lib/ to /etc/ld.so.conf and execute
     [4mldconfig[24m (as root)

  +o  You might not have the necessary rights to the /dev/cbm device; try
     [4mchmod[24m [4m777[24m [4m/dev/cbm[0m
  +o  incorrect module parameters

  +o  wrong BIOS settings (esp. IRQ)

  +o  broken cable


  [1m3.1.6.  Runtime configuration[0m

  Most probably, you will want to add this to /etc/modules.conf to have
  the driver loaded on demand: (the file is called /etc/conf.modules on
  some older SuSE systems)



           alias char-major-10-177 cbm
           options cbm [options]



  With [options] being one or more of:


  +o  [4mlp=*lp*[24m       (parport only, as used in [4m/sbin/insmod[24m above)

  +o  [4mirq=*irq*[24m     (direct port only, as used in [4m/sbin/insmod[24m above)

  +o  [4mport=*port*[24m   (direct port only, as used in [4m/sbin/insmod[24m above)

  +o  [4mcable=*n*[24m      force cable type:

     +o  -1  for autodetection (default)

     +o  0  for XM1541 (non-inverting)

     +o  1  for XA1541 (inverting)

  +o  [4mreset=*n*[24m     initializing behaviour:

     +o  -1  smart IEC reset (direct port default); only change the
        status of the reset line if it was set on start

     +o  0  no IEC reset on driver start

     +o  1  force IEC reset (parport default); always reset the device on
        driver start


  Congratulation, you have successfully set up your opencbm
  installation!



  [1m3.2.  Installing opencbm on Windows (cbm4win)[0m

  [4mWARNING![24m [4mIf[24m [4myou[24m [4mhave[24m [4malready[24m [4minstalled[24m [4ma[24m [4mprevious[24m [4mversion[24m [4mof[24m [4mCBM4WIN[0m
  [4mon[24m [4myour[24m [4mmachine,[24m [4myou[24m [4mhave[24m [4mto[24m [4muninstall[24m [4mit[24m [4mbefore[24m [4minstalling[24m [4ma[24m [4mnew[0m
  [4mversion.[24m [4mFor[24m [4mthis,[24m [4mgo[24m [4mto[24m [4mthe[24m [4mdirectory[24m [4mwhere[24m [4mthe[24m [4mold[24m [4mversion[24m [4mis[0m
  [4mlocated,[24m [4mand[24m [4menter[24m [4minstcbm[24m [4m--remove.[0m

  First of all, Windows must know about the driver. For this, we must
  install it with the instcbm tool. This is done as follows:



  +o  Make sure you have a supported operating system up and running.

  +o  You need administrator privileges on the Windows machine to perform
     the following actions.

  +o  At first, you have to make sure you have the needed hardware ready.
     Do the following:


     +o  Get your supported drive ``''.

     +o  Moving cables with equipment turned on can damage either your
        PC, and/or the drive, so, be carefull!

     +o  Thus, switch off your PC and your VIC 15xx drive!

     +o  Connect your XA1541 or XM1541 cable to your PC. If you have a
        parallel port cable (XP1541), connect that one, too.

     +o  Connect your VIC 15xx floppy drive to the cable

     +o  Switch on the PC.


  +o  Just download the binary package, and unpack it into an arbitrary
     directory.

  +o  Get a command-line (Start/Run, and type "[4mcmd.exe[24m"), change into the
     directory you unpackaged the drivers into (with "[4mcd[24m").

  +o  Type "[4mcd[24m [4mexe[24m"

  +o  Type "[4minstcbm[24m" and check the outputs. Its last line should look
     like [4mNo[24m [4mproblems[24m [4mfound[24m [4min[24m [4mcurrent[24m [4mconfiguration[24m. In this case, you
     are done. In some rare cases, [4minstcbm[24m will suggest a reboot, which
     you should follow.

  +o  You might want to have a look at the possible options for instcbm.
     They are available by typing "[4minstcbm[24m [4m--help[24m". Also, cf.
     ``instcbm''.

  +o  If you had to reboot in the previous step, do the following:


     +o  Go to a command-line, and change into the directory you
        unpackaged the drivers into again.

     +o  Type "[4mcd[24m [4mexe[24m"

     +o  Type "[4minstcbm[24m [4m--check[24m". There should not be any further
        suggestion for a reboot. If there is, do not proceed, but
        contact me instead.


  +o  If you want to use another port than LPT1, you must tell this to
     the driver. I assume you want to use LPTX, with X being the correct
     value, then type: "[4minstcbm[24m [4m--lpt=X[24m [4m--update[24m"


  [1m4.  Checking if the installation is complete[0m

  After you installed opencbm (cf. ``Installation'', it is wise to check
  if the installation works as expected. For this, do the following:



  +o  Switch on the floppy drive. Depending on the type of cable you are
     using (XA1541 or XM1541) and the parallel port of your PC, the
     drive might keep spinning endless now, because it is continuously
     resetted.

  +o  Type "[4mcbmctrl[24m [4mreset[24m" and press enter. If it does not already, the
     red floppy drive LED should light up, and the drive should start
     spinning. After approximately one second (up to five seconds in the
     case of a 1581), the red LED should switch off again, and the drive
     stops spinning.

  +o  Now, type "[4mcbmctrl[24m [4mstatus[24m [4m8[24m" to get the status (error) code from
     the attached floppy drive. If everything works fine, your drive
     should answer with its identification string. For a 1541, this is
     something like [4m73,cbm[24m [4mdos[24m [4mv2.6[24m [4m1541,00,00[24m, while for a 1571, this
     line looks like [4m73,cbm[24m [4mdos[24m [4mv3.0[24m [4m1571,00,00[24m.  There might also be
     some variant of this line, depending on the firmware version of
     your drive.

  +o  Type "[4mcbmctrl[24m [4mstatus[24m [4m8[24m" to get the status (error) code from the
     floppy drive again. As the power on message has been read, your
     drive should answer with a [4m00,[24m [4mok,00,00[24m string.

  +o  Type "[4mcbmctrl[24m [4mdetect[24m". This command tries to detect the types of
     drive which are connected on the cable. You should see the drive
     which you posess.

  +o  Now, we want to check if we can send anything to the floppy drive.
     Remove any diskette from the drive and press "[4mcbmctrl[24m [4mopen[24m [4m8[24m [4m15[0m
     [4mI0[24m". (Make sure the "I" is an upper-case "I". A lower-case "I" will
     not work!) This command tries to initialize the disk. Anyway, since
     there isn't a disk in the drive, an error occurs. You should hear
     the floppy spinning, and in case of a 1541, the R/W-head should
     start bumping. After some seconds, the red LED starts starts
     flashing, indicating that an error occurred.

  +o  Now, try again "[4mcbmctrl[24m [4mstatus[24m [4m8[24m" to get the status (error) code
     from the floppy drive. As an error occurred before, an error string
     should be displayed. For my setup, it is the "[4m21,read[24m [4merror,18,00[24m"
     string. Furthermore, the red LED should stop flashing.

  If you have come so far, you are sure that you send commands to the
  floppy, and receive answers from it. This is very good so far.
  Furthermore, don't panic: you do not have to enter these commands over
  and over again, these are only tests to make sure that anything is
  correctly installed.

  Now, let's proceed. If you have a D64 file or a floppy disc ready, you
  can try transferring it over the cable. Do not use all of the
  following commands, but only the ones you want to perform.


  +o  If you want to transfer an existing floppy from the drive to the
     PC, use the following command: "[4md64copy[24m [4m8[24m [4mA.D64[24m", while replacing
     A.D64 by the name you want to give to the file.

  +o  [1mWARNING THE FOLLOWING COMMAND OVERWRITES ANYTHING THAT WAS ON THE[0m
     [1mFLOPPY BEFORE, so make sure you do not need that floppy anymore.[0m

     If you have a D64 or D71 on your PC, and you want to write it to a
     new, already formatted disc, enter "[4md64copy[24m [4mA.D64[24m [4m8[24m" if the file is
     called A.D64.

  +o  [1mWARNING THE FOLLOWING COMMAND OVERWRITES ANYTHING THAT WAS ON THE[0m
     [1mFLOPPY BEFORE, so make sure you do not need that floppy anymore.[0m

     If you have a disc you want to format, you have two options: Either
     use the command "[4mcbmctrl[24m [4mcommand[24m [4m8[24m [4mN0:NAME,ID[24m", or use the
     cbmformat program, cf.  ``cbmformat'', or the cbmforng program, cf.
     ``cbmforng''.


  If you want to completely remove the cbm4win driver from your machine,
  you can do so by issuing a "[4minstcbm[24m [4m--remove[24m" command.

  You can have a look at the available cbmctrl commands by issuing
  cbmctrl on your command line, or look at ``cbmctrl''. For the other
  programs, you get help by issuing the "--help" option, or look at the
  appropriate section in ``utilities''.


  [1m5.  Utilities[0m

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


  +o  [4mcbmctrl[0m

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

  +o  [4mcbmformat[0m

     fast 1541 disk formatter (for 1541, 1570 and 1571 drives).

  +o  [4mcbmforng[0m

     fast 1541 disk formatter (for 1541, 1570 and 1571 drives).

  +o  [4md64copy[0m

     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 Michael Klein's old
     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



  +o  [4mcbmcopy[0m

     fast 1541/1570/1571/1581 file copier.

  +o  [4mrpm1541[24m demo

     determines the drive rotation speed of 1541, 1570 and 1571 drives.

  +o  [4mflash[24m demo

     flashes the LED of 1541, 1570 and 1571 drives.

  +o  [4mmorse[24m demo

     morses arbitrary texts with the help of the LED of 1541, 1570 and
     1571 drives.


  [1m5.1.  instcbm (Windows only)[0m

  [4minstcbm[24m is used on Windows to install the opencbm driver.


  [1m5.1.1.  instcbm invocation[0m

  Synopsis: instcbm [4m[options][0m


     [1m-h, --help[0m
        display help and exit.


     [1m-V, --version[0m
        display version information about cbm4win.


     [1m-r, --remove[0m
        remove (uninstall) the driver.


     [1m-e, --enumpport[0m
        re-enumerate the parallel port driver.


     [1m-u, --update[0m
        update parameters if driver is already installed.


     [1m-l, --lpt=*no*[0m
        set default LPT port to number [4m*no*[24m. For example, for LPT2, use
        [4m--lpt=2[24m.

        If not specified, or [4m--lpt=0[24m is specified, use the first
        parallel port.


     [1m-t, --cabletype=*TYPE*[0m
        set cabletype to [4m*TYPE*[24m, which can be [4mauto[24m, [4mxa1541[24m or [4mxm1541[24m.

        If not specified, [4m--cabletype=auto[24m is assumed.


     [1m-L, --lock=*WHAT*[0m
        automatically lock the driver. [4m*WHAT*[24m can be [4myes[24m (automatically
        lock) or [4mno[24m (do not automatically lock).

        If not specified, [4m--lock=yes[24m is assumed.


     [1m-n, --nocopy[0m
        do not copy the driver files into the system directory. This is
        not recommended.
     [1m-c, --check[0m
        only check if the installation is ok. Do not install or
        uninstall anything.


     [1m-F, --forcent4[0m
        force the NT4 driver on a Win 2000, XP, or newer systems (NOT
        RECOMMENDED!).  This option is only available on i386
        architectures; AMD64 and iA64 do not support it.


     [1m-A, --automatic[0m
        (default) automatically start the driver on system boot.a

        The driver can be used from a normal user, no need for
        administrator rights.  The opposite of [4m--on-demand[24m.


     [1m-O, --on-demand[0m
        start the driver only on demand.

        The opposite of [4m--automatic[24m.



  [1m5.1.2.  instcbm Examples[0m

  Install the driver and the DLL on the machine. The driver and the DLL
  are copied into the Windows system directory, so opencbm can be used
  from every program:

  ______________________________________________________________________
  instcbm
  ______________________________________________________________________



  Install the driver, like above. Additionally, specify that you are
  using an XM1541 cable:

  ______________________________________________________________________
  instcbm --cabletype=xm1541
  ______________________________________________________________________



  Check if the installation was set up successfully:

  ______________________________________________________________________
  instcbm --check
  ______________________________________________________________________



  Remove the driver from the system. You will not be able to use opencbm
  after this command, unless you re-install it. If files were copied
  into the Windows system directory, they will be removed:

  ______________________________________________________________________
  instcbm --remove
  ______________________________________________________________________


  After opencbm has been installed (with [4minstcbm[24m>), change the parallel
  port to be used to 2:

  ______________________________________________________________________
  instcbm --lpt=2 --update
  ______________________________________________________________________



  Install opencbm, directly specifying LPT3 as the parallel port to use:

  ______________________________________________________________________
  instcbm --lpt=3
  ______________________________________________________________________



  Install the DLL and the driver on the machine. Do not copy the files
  to the Windows system directory, but leave them "where they are". If
  you use this option, the directory where your files resides must be
  accessible for the system while booting. For example, network drives,
  USB drives or FireWire drives are not allowed.

  ______________________________________________________________________
  instcbm --nocopy
  ______________________________________________________________________



  [1m5.2.  cbmctrl[0m

  [4mcbmctrl[24m is used to send commands to external devices. It can control
  all kinds of serial CBM devices like floppy drives and printers. So
  far, it has been successfully tested with the disk drives 1541(-II),
  1571 and a MPS-1200 printer.


  [1m5.2.1.  Command structure[0m

  The overall format of all [4mcbmctrl[24m actions is:


  Synopsis: cbmctrl [4m[global_options][24m ACTION [4m[action_args][0m

     [1mglobal_options[0m
        Some options that are related to [4mcbmctrl[24m in general of which
        affect the oervall behaviour of all actions

     [1maction[0m
        One of a bunch of different subcommands that direct [4mcbmctrl[24m what
        to do

     [1maction_args[0m
        Arguments that are required for the subcommand [4maction[24m to work


  [1m5.2.1.1.  Global options[0m

  [4mcbmctrl[24m understands the following global options


     [1m-h [4m[22m[ACTION][24m, --help [4m[ACTION][0m
        Outputs the help screen with a short listing of all available
        actions. If the optional [4mACTION[24m name is given also, you retrieve
        more information on a special action together with its arguments
        and parameters

     [1m-V, --version[0m
        Output version information as well as the built date and time


  [1m5.2.1.2.  Actions overview[0m

  [4mcbmctrl[24m understands the following subcommand actions

     [1mreset[0m
        Reset all drives on the IEC bus

     [1mdetect[0m
        Detect all drives on the IEC bus

     [1mlock[0m
        Lock the parallel port for opencbm (cbm4linux/cbm4win) use

     [1munlock[0m
        Unlock the parallel port from exclusive usage

     [1mlisten[0m
        Perform a listen on the IEC bus

     [1mtalk[0m
        Perform a talk on the IEC bus

     [1munlisten[0m
        Perform an unlisten on the IEC bus

     [1muntalk[0m
        Perform an untalk on the IEC bus

     [1mopen[0m
        Perform an open on the IEC bus

     [1mclose[0m
        Perform a close on the IEC bus

     [1mpopen[0m
        Same as open, but with ASCII to PETSCII conversion

     [1mread[0m
        Get a stream of raw data from an IEC bus device

     [1mwrite[0m
        Put a stream of raw data to an IEC bus device

     [1mstatus[0m
        Give the status of a specified drive

     [1mcommand[0m
        Issue a command to a specified drive

     [1mpcommand[0m
        Same as command, with ASCII to PETSCII conversion

     [1mdir[0m
        Output the directory of a disk in a specified drive

     [1mdownload[0m
        Download memory contents from a floppy drive

     [1mupload[0m
        Upload memory contents to a floppy drive

     [1mchange[0m
        Wait for a disk to be changed in a specified drive


  [1m5.2.1.3.  Common action arguments[0m

  Many of the [4mcbmctrl[24m subcommands understand the following common
  arguments:

     [1m[DEVICE][0m
        Advice [4mcbmctrl[24m to direct its communication to the IEC bus device
        with the number [4m[DEVICE][24m. IEC bus device numbers can be denoted
        in the range from 0 to 30, although no Commodore device is known
        to use device numbers 0 to 3. Most commonly used are the numbers
        4 (printer) and 8 to 11 (disk drives). Device number 31 is used
        to denote the UNTALK respectively the UNLISTEN command code on
        the IEC bus instead of the TALK respectively LISTEN command
        code, therefore device address 31 cannot be used in general.

     [1m[SECADR][0m
        With several [4mcbmctrl[24m actions the secondary address parameter
        [4m[SECADR][24m denotes a dedicated logical communication channel for
        the specifed [4m[DEVICE][24m . IEC bus channel numbers can be denoted
        in the range from 0 to 15. Take note that for floppy disk drive
        devices some secondary addresses are interpreted in a special
        way. Secondary address 0 is used, when a program is loaded,
        address 1, when a program is saved. Address number 15 represents
        the command channel of the disk drive, so eectively, for bulk
        data transfers to and from disk drives, only the logical channel
        numbers 2 to 14 can be used.


  [1m5.2.2.  Actions[0m

  [4mcbmctrl[24m understands the following actions:



     [1mreset[0m
        This action performs a hardware reset of all devices attached to
        the IEC bus.  Control is returned after it is made sure that all
        devices are ready.


     [1mdetect[0m
        This action tries to detect all devices attached to the IEC bus.
        For this, this subcommand accesses all possible devices and
        tries to read some bytes from its memory. If a devices is
        detected, its name is output. Additionally, this routine
        determines if the device is connected via a parallel cable
        (XP1541 companion cable, may be true for disk drives only).


     [1mlock[0m
        This command locks the parallel port for the use by opencbm, so
        that sequences of e.g. [4mtalk[24m/[4mread[24m/[4muntalk[24m [4mor[24m [4mlistenwrite[24m/[4munlisten[0m
        are not broken by concurrent processes wanting to access the
        parallel port.

        You should issue [4mcbmctrl[24m [4mlock[24m before doing any access to opencbm
        tools, and [4mcbmctrl[24m [4munlock[24m after you are done.


     [1munlock[0m
        This command unlocks the parallel port after the use by opencbm.

        You should issue [4mcbmctrl[24m [4mlock[24m before doing any access to opencbm
        tools, and [4mcbmctrl[24m [4munlock[24m after you are done.


     [1mlisten [4m[22mdevice[24m [4msecadr[0m
        Tell device [4mdevice[24m to listen on secondary address [4msecadr[24m. Until
        the next [4munlisten[24m command, everything output with [4mcbmctrl[24m [4mwrite[0m
        will be received by this device.


        This command corresponds to the following 6502 assembly code on
        a C64:

        ________________________________________________________________
        lda #device
        jsr $ffb1
        lda #secadr
        ora #$60
        jsr $ff93
        ________________________________________________________________



     [1mtalk [4m[22mdevice[24m [4msecadr[0m
        Tell device [4mdevice[24m to talk on secondary address [4msecadr[24m. Until
        the next [4muntalk[24m command, data from this device can be received
        device by using the command [4mcbmctrl[24m [4mread[24m.


        This command corresponds to the following 6502 assembly code on
        a C64:

        ________________________________________________________________
        lda #device
        jsr $ffb4
        lda #secadr
        ora #$60
        jsr $ff96
        ________________________________________________________________



     [1munlisten[0m
        Ends communication with listening devices after a [4mlisten[0m
        command. This corresponds to the C64 kernel routine $ffae.


     [1muntalk[0m
        Ends communication with talking devices after a [4mtalk[24m command.
        This corresponds to the C64 kernel routine $ffab.


     [1mopen [4m[22mdevice[24m [4msecadr[24m [4mfilename[0m
        Open file [4mfilename[24m on device [4mdevice[24m. After opening, data can be
        read/written by sending a [4mtalk[24m resp. [4mlisten[24m command with the
        secondary address [4msecadr[24m.

        If [4msecadr[24m is greater than 1, the file type and access mode must
        also be specified by appending ,type,mode to [4mfilename[24m. Valid
        types are D, P, S, U, R (DEL, PRG, SEQ, USR, REL), valid modes
        are R for reading and W for writing.
        Note: You cannot do an open without a filename. Although a CBM
        machine (i.e., a C64) allows this, this is an internal operation
        for the Computer only. It does not have any effect on the IEC
        bus.

        [4mcbmctrl[24m [4mopen[24m does not change any character encoding, that is, it
        does not convert between ASCII (used by the PC) and PETSCII
        (used by the CBM device). If this is needed, use [4mcbmctrl[24m [4mpopen[0m
        instead.


     [1mpopen [4m[22mdevice[24m [4msecadr[24m [4mfilename[0m
        Like [4mcbmctrl[24m [4mopen[24m, but converts the filename from ASCII to
        PetSCII before sending it to the floppy.


     [1mclose [4m[22mdevice[24m [4msecadr[0m
        Close the file associated with secondary address [4msecadr[24m on
        device [4mdevice[24m.


     [1mread [4m[22m[file][0m
        This command reads raw data from the IEC bus and outputs it into
        the given file, or to stdout if no file is given (or if it is a
        simple dash, "-").


     [1mwrite [4m[22m[file][0m
        This command writes raw data to the IEC bus; the data is taken
        from the given file, or from stdin if no filename is given (or
        if it is a simple dash, "-").



     [1mstatus [4m[22mdevice[0m
        Copies input from device [4mdevice[24m, secondary address 15
        (command/status channel), to the standard output stream. Note
        that all upper case characters are changed to lower case.
        Carriage return (0x0d) is also changed to the current operating
        system's line ending convention (0x0a on Unix oriented systems,
        0x0d 0x0a on Windows oriented systems or whatever else is
        appropriate for your operating system).

        Assuming the device number is 8, this command is similar to (in
        this case, no character conversions would be made)

        ________________________________________________________________
        cbmctrl lock
        cbmctrl talk 8 15
        cbmctrl read
        cbmctrl untalk
        cbmctrl unlock
        ________________________________________________________________



     [1mcommand [4m[22mdevice[24m [4mcmdstr[0m
        Sends [4mcmdstr[24m to device [4mdevice[24m, secondary address 15
        (command/status channel). Since there is no PetSCII->ASCII
        conversion, commands must be sent in [4mupper[24m [4mcase[24m (kind of poor
        man's PetSCII conversion). This is because charset conversion
        would break the M-W and M-E commands.

        Note: If you need PetSCII->ASCII conversion, use [4mpcommand[0m
        instead.
        Assuming the device number is 8, this command is identical to
        (Note: This does not work on Windows, because [4mecho[24m there does
        not know the [4m-n[24m option.)

        ________________________________________________________________
        cbmctrl lock
        cbmctrl listen 8 15
        echo -n cmdstr|cbmctrl write -
        cbmctrl unlisten
        cbmctrl unlock
        ________________________________________________________________



     [1mpcommand [4m[22mdevice[24m [4mcmdstr[0m
        Like [4mcommand[24m, but converts the data from ASCII to PetSCII before
        sending it.


     [1mdir [4m[22mdevice[0m
        Read directory from disk in device [4mdevice[24m, print on standard
        out.


     [1mdownload [4m[22mdevice[24m [4maddress[24m [4mcount[24m [4m[file][0m
        Read [4mcount[24m bytes from drive memory, starting at [4maddress[24m via one
        or more M-R commands. Memory contents are written to standard
        output if [4mfile[24m is ommited or equivalent to "-".


     [1mupload [4m[22mdevice[24m [4maddress[24m [4m[file][0m
        Send [4mfile[24m to drive memory, starting at [4maddress[24m via one or more
        M-W commands. If [4maddress[24m is -1, the first two bytes from [4mfile[0m
        are considered as start address. Reads standard input if [4mfile[24m is
        ommited or equivalent to "-".


     [1mchange [4m[22mdevice[0m
        Wait for a disc to be changed in the specified device. It waits
        for the current disc to be removed, for a new disc to be
        inserted and for the drive door to be closed. It does not return
        until the disc is ready to be read or written.


  [1m5.2.3.  cbmctrl Examples[0m

  Send file contents to printer 4:

  ______________________________________________________________________
  cbmctrl lock
  cbmctrl listen 4 0
  cbmctrl write file
  cbmctrl unlisten
  cbmctrl unlock
  ______________________________________________________________________



  Copy file to disk drive 8:



  ______________________________________________________________________
  cbmctrl lock
  cbmctrl open 8 2 FILENAME,P,W
  cbmctrl listen 8 2
  cbmctrl write file
  cbmctrl unlisten
  cbmctrl close 8 2
  cbmctrl unlock
  ______________________________________________________________________



  Copy file from disk drive 8:

  ______________________________________________________________________
  cbmctrl lock
  cbmctrl open 8 2 FILENAME,P,R
  cbmctrl talk 8 2
  cbmctrl read file
  cbmctrl untalk
  cbmctrl close 8 2
  cbmctrl unlock
  ______________________________________________________________________



  Dump 1541 ROM:

  ______________________________________________________________________
  cbmctrl download 8 0xc000 0x4000 > 1541.rom
  ______________________________________________________________________


  or

  ______________________________________________________________________
  cbmctrl download 8 0xc000 0x4000 1541.rom
  ______________________________________________________________________



  Write file buffer2.bin to drive 9, address 0x500:

  ______________________________________________________________________
  cbmctrl upload 9 0x500 buffer2.bin
  ______________________________________________________________________



  [1m5.3.  cbmformat[0m

  [4mcbmformat[24m is a fast low-level disk formatter for the 1541 and
  compatible devices (1570, 1571, third-party clones). A 1581 drive is
  not supported.

  The drive routine was taken from the Star Commander ((C) Joe
  Forster/STA) and highly improved.

  There is also another, very similar tool, ``cbmforng''.



  [1m5.3.1.  cbmformat invocation[0m

  Synopsis: cbmformat [OPTION]... DRIVE# NAME,ID

  [4mDRIVE#[24m has to be the drive number of the disc drive, [4mNAME[24m is a name
  with up to 16 characters which will be the name of the disc after
  formatting, [4mID[24m is the 2-letter disc ID.


  Note: Unlike the [4mN0[24m command of the drive, the ID must be given (thus,
  no so-called "short format" is possible).


  Here's a complete list of known options:


     [1m-h, --help[0m
        Display help and exit.


     [1m-V, --version[0m
        Display version information and exit.


     [1m-n, --no-bump[0m
        Do not bump drive head at the beginning. Don't use this on
        eventually misaligned drives.


     [1m-x, --extended[0m
        Format a 40 track disk, the BAM format is compatible to
        SpeedDOS.


     [1m-c, --clear[0m
        clear (demagnetize) this disc.  This is highly recommended if
        the disc is used for the first time, or if it was previously
        formatted for another system (i.e., MS-DOS).  Note that this
        option takes much time.


     [1m-v, --verify[0m
        verify each track after it is written.  As this needs an extra
        round of the drive for each track, the formatting time is almost
        doubled.

        cf. ``cbmformat Notes for 1571 drives''


     [1m-o, --original[0m
        Fill sectors with the original pattern (0x4b, 0x01, 0x01...)
        instead of zeroes.  The original pattern is probably due to a
        bug in the drive ROM, apart from this, zeroing out unused
        sectors should give (slightly) better results for compressed
        disk images.

        cf. ``cbmformat Notes for 1571 drives''


     [1m-s, --status[0m
        Display drive status after formatting. Normally, [4mcbmformat[24m exits
        after executing the drive code. With this option turned on,
        [4mcbmformat[24m waits until the drive has finished formatting and
        prints the drive status after initializing the BAM on standard
        out.

     [1m-p, --progress[0m
        Display a hash mark ('#') for each formatted track. Slows
        formatting down a bit.


  [1m5.3.2.  cbmformat Notes for 1571 drives[0m

  We encountered problems with decent revision/mechanics combinations of
  the 1571 disk drives when using cbmformat. We highly recommend to use
  [4m--original[24m and [4m--verify[24m with 1571 drives. From our experience, with
  [4m--original[24m, the problem does not occur; with [4m--verify[24m, the drive tests
  each track after it was formatted and ensures that the failure
  condition did not occur.

  We did not encounter these problems with either of 1541 (1541-II,
  1541C), 1570 or 1571CR (the drive which is part of the C128DCR)
  drives, only with original 1571 drives.

  In the current state, cbmformat is not able to format double-sided
  discs on a 1571 drive.


  [1m5.3.3.  cbmformat Examples[0m

  Format standard disk (35 tracks) in drive 8:

  ______________________________________________________________________
  cbmformat 8 GAMES,42
  ______________________________________________________________________



  Format standard disk (35 tracks) in drive 9, use (buggy) 1541 sector
  pattern (for example, because this is a 1571 drive), show drive status
  when done:

  ______________________________________________________________________
  cbmformat -os 9 1571disc,71
  ______________________________________________________________________



  SpeedDOS disk (40 tracks), show progress indicator, all sectors zeroed
  out, no head banging:

  ______________________________________________________________________
  cbmformat -npx 8 "40 TRACKS,OK"
  ______________________________________________________________________



  [1m5.4.  cbmforng[0m

  [4mcbmforng[24m is a fast and reliable low-level disk formatter for the 1541
  and compatible devices (1570, 1571, third-party clones). It was based
  on ``cbmformat'' and is designed to become the designated successor to
  ``cbmformat'', therefore its name: [4mCBM-Formatter,[24m [4mthe[24m [4mNext[24m [4mGeneration[24m.

  [4mcbmforng[24m does not support a 1581 drive.


  Because this is the first official release of [4mcbmforng[24m and because it
  was not used in the field by a wider user group, it still contains
  additional measurement routines and informational output after the
  formatting process was done. When [4mcbmforng[24m prooved its matureness and
  got back some features currently missing (progress bar), it will
  replace [4mcbmformat[24m.

  To date [4mcbmforng[24m should be considered as the more reliable formatter
  of both; whenever you should encounter any difficulties with
  [4mcbmformat[24m, go for [4mcbmforng[24m. If you like additional informational
  messages like e.g.  the RPM value each formatted track was measured,
  then [4mcbmforng[24m is the tool you want to use. Your feedback helps us to
  decide, if this additional output which was needed for developing may
  find its way into future releases.


  [1m5.4.1.  cbmforng invocation[0m

  Synopsis: cbmforng [OPTION]... DRIVE# NAME,ID

  [4mDRIVE#[24m has to be the drive number of the disc drive, [4mNAME[24m is a name
  with up to 16 characters which will be the name of the disc after
  formatting, [4mID[24m is the 2-letter disc ID.


  Note: Unlike the [4mN0[24m command of the drive, the ID must be given (thus,
  no so-called "short format" is possible).


  Here's a complete list of known options:


     [1m-h, --help[0m
        Display help and exit.


     [1m-V, --version[0m
        Display version information and exit.


     [1m-n, --no-bump[0m
        Do not bump drive head at the beginning. Don't use this on
        eventually misaligned drives.


     [1m-r, --retries n[0m
        Set the maximum number of retries on errors. This accounts for
        all errors that may happen when formatting all the tracks of the
        whole disc.


     [1m-x, --extended[0m
        Format a 40 track disk, the BAM format is compatible to
        SpeedDOS.


     [1m-c, --clear[0m
        clear (demagnetize) this disc.  This is highly recommended if
        the disc is used for the first time, or if it was previously
        formatted for another system (i.e., MS-DOS).  Note that this
        option takes much time.


     [1m-v, --verify[0m
        verify each track after it is written.  As this needs an extra
        round of the drive for each track, the formatting time is almost
        doubled.

        cf. ``cbmforng Notes for 1571 drives''


     [1m-o, --original[0m
        Fill sectors with the original pattern (0x4b, 0x01, 0x01...)
        instead of zeroes.  The original pattern is probably due to a
        bug in the drive ROM, apart from this, zeroing out unused
        sectors should give (slightly) better results for compressed
        disk images. In comparison to [4mcbmformat[24m, the pattern used with
        [4mcbmforng[24m is a little bit more original than the one from its
        predecessor. On track one the pattern consists of: 0x00, 0x01,
        0x01, ...  instead of the first byte beeing 0x4b. This perfectly
        reflects the original 1541 ROM format bug.

        cf. ``cbmforng Notes for 1571 drives''


     [1m-s, --status[0m
        In addition to the informational output of internal values from
        the formatting process, the drive status is displayed.


  [1m5.4.2.  cbmforng Notes for 1571 drives[0m

  We encountered rare failure conditions with decent revision/mechanics
  combinations of the 1571 disk drives when using cbmforng. We highly
  recommend to use [4m--original[24m and [4m--verify[24m with 1571 drives. From our
  experience, with [4m--original[24m, the problem does not occur. With
  [4m--verify[24m, the drive tests each track after it was formatted and
  ensures that the failure condition did not occur; otherwise the same
  track is formatted again, as often as the currently set retry value
  allows.

  We did not encounter these problems with either of 1541 (1541-II,
  1541C), 1570 or 1571CR (the drive which is part of the C128DCR)
  drives, only with original 1571 drives.

  In the current state, cbmforng is not able to format double-sided
  discs on a 1571 drive.


  [1m5.4.3.  cbmforng Examples[0m

  Format standard disk (35 tracks) in drive 8:

  ______________________________________________________________________
  cbmforng 8 GAMES,42
  ______________________________________________________________________



  Format standard disk (35 tracks) in drive 9, use (buggy) 1541 sector
  pattern (for example, because this is a 1571 drive), show drive status
  when done:

  ______________________________________________________________________
  cbmforng -os 9 1571disc,71
  ______________________________________________________________________



  SpeedDOS disk (40 tracks), verify formatted tracks, all sectors zeroed
  out, no head banging:

  ______________________________________________________________________
  cbmforng -nvx 8 "40 TRACKS,OK"
  ______________________________________________________________________



  [1m5.5.  d64copy[0m

  [4md64copy[24m is a fast disk image transfer (both read and write) program
  for the 1541 and compatible devices (1570, 1571, third-party clones).
  A 1581 drive is [4mnot[24m supported! Maximum transfer speed is achieved by
  custom drive- and transfer-routines based on the Star Commander ((C)
  Joe Forster/STA) routines.


  [1m5.5.1.  d64copy invocation[0m

  Synopsis: d64copy [OPTION]... SOURCE TARGET


  Either SOURCE or TARGET must be an external drive, valid names are 8,
  9, 10 and 11. The other parameter specifies the file name of the .d64
  image.

  Here's a complete list of known options:


     [1m-h, --help[0m
        Display help and exit


     [1m-V, --version[0m
        Display version information and exit.


     [1m-q, --quiet[0m
        Quiet output, fewer messages (also suppresses warnings, should
        not be used)


     [1m-v, --verbose[0m
        Verbose output, more messages (can be repeated)


     [1m-n, --no-progress[0m
        Omit progress display


     [1m-s, --start-track=[4m[22mstart[24m [4mtrack[0m
        Set start track (defaults to 1)


     [1m-e, --end-track=[4m[22mend[24m [4mtrack[0m
        Set end track (default is 35 for .d64 images, 70 for .d71
        images). [4md64copy[24m is able to access tracks 1-35 in original
        transfer mode and 1-42 with serial1, serial2 and parallel. The
        1571 supports tracks 1-70 in double sided (.d71) mode.


     [1m-t, --transfer=[4m[22mtransfer[24m [4mmode[0m
        Set transfermode. Valid modes are:

        +o  auto     (default)

        +o  original (slowest)

        +o  serial1

        +o  serial2

        +o  parallel (fastest)

        original and serial1 should work in any case.  serial2 won't
        work with more than one device connected to the IEC bus, paral-
        lel requires an additional XP1541/XP1571 cable.


        If auto is used, d64copy itself determines the best transfer
        mode usable with the current setup, and uses that one. Thus, you
        will seldom want to manually overdrive the [4mtransfer[24m [4mmode[24m option.


     [1m-i, --interleave=[4m[22minterleave[0m
        Set interleave value. This is ignored when reading in warp mode.
        Default is 16 for transfer mode original, for turbo and warp
        write as follows:



                    turbo (r/w)    warp (write only)
          serial1       3                 5
          serial2      12                11
          parallel      6                 3



     Lower values might slightly reduce transfer times, but if set a bit
     to low, transfer times will dramatically increase.


     [1m-w, --warp[0m
        Enable warp mode. This is default now; this option is only
        supported for backward-compatibility with opencbm
        (cbm4linux/cbm4win) versions before 0.4.0.


     [1m--no-warp[0m
        Disable warp mode. Warp mode is usually a good idea for
        transferring disk images unless you have a very slow CPU and/or
        bad disk material. Warp mode sends raw GCR data over the bus,
        which assures data integrity on the PC side and relieves the
        drive's CPU. Thus, it is unlikely you will want to use that
        option.


     [1m-b, --bam-only[0m
        BAM-only copy. Only blocks marked as allocated are copied. For
        extended tracks (36-40), SpeedDOS BAM format is assumed. Use
        with caution, at least one wide-spread directory editor tends to
        forget to allocate some directory blocks.


     [1m-B, --bam-save[0m
        Safe BAM-only copy. This is like the -b option but always copies
        the entire directory track (18, 18 and 53 in double-sided mode).


     [1m-d, --drive-type=[22mtype
        Skip drive type detection. 0 or 1541 specifies 1541 mode (1 MHz,
        parallel cable at VIA $1800), 1 or 1571 forces 1571 mode (2 MHz,
        parallel cable at CIA $4000).


     [1m-2, --two-sided[0m
        Double-sided mode for copying .d71 images to/from a 1571 drive.
        Warp mode is not supported (yet).


     [1m-r, --retry-count=[22mcount
        Number of retries.


     [1m-E, --error-mode=[22mmode
        Controls whether error is appended to the disk image (15x1->PC
        only).  Allowed values for mode are (abbreviations allowed):

        +o  always

        +o  on_error  (default)

        +o  never



  [1m5.5.2.  d64copy Examples[0m

  Read a D64 disc image from the floppy in drive 8 to the file
  image.d64, automatically selecting the fastest transfer method:

  ______________________________________________________________________
  d64copy 8 image.d64
  ______________________________________________________________________



  Copy the D64 disc image in image.d64 to the floppy in drive 9,
  automatically selecting the fastest transfer method:

  ______________________________________________________________________
  d64copy image.d64 9
  ______________________________________________________________________



  Copy a double-sided disc from a 1571 drive 9 to image.d71, using
  serial1 transfer method and only reading the blocks which are marked
  as used in the BAM:

  ______________________________________________________________________
  d64copy -2 -B --transfer=serial1 9 image.d64
  ______________________________________________________________________



  [1m5.6.  cbmcopy[0m

  [4mcbmcopy[24m is a fast file transfer program for various disk drives, in
  particular the 1541, 1570, 1571 and 1581 devices.  Maximum transfer
  speed is achieved by custom drive- and transfer-routines based on the
  Star Commander ((C) Joe Forster/STA) routines.


  [1m5.6.1.  cbmcopy invocation[0m

  Synopsis: cbmcopy [OPTION]... DEVICE# FILE...


  DEVICE# specifies the drive number for file copy.  The remaining
  arguments specify the files to be sent to/read from the disk drive.
  This version supports Raw, PC64 (P00) and T64 files. They are
  recognized when sending files to the disk drive, files read from
  external devices are always stored as raw binary data.

  Here's a complete list of known options:


     [1m-h, --help[0m
        Display help and exit


     [1m-V, --version[0m
        Display version information and exit.


     [1m-q, --quiet[0m
        Quiet output, fewer messages (also suppresses warnings, should
        not be used)


     [1m-v, --verbose[0m
        Verbose output, more messages (can be repeated)


     [1m-n, --no-progress[0m
        Omit progress display


     [1m-r, --read[0m
        Operate in read-mode, i.e. read data from an external device.
        Starting [4mcbmcopy[24m as [4mcbmread[24m has the same effect.


     [1m-w, --write[0m
        Operate in write-mode, i.e. send files to an external device.
        Starting [4mcbmcopy[24m as [4mcbmwrite[24m has the same effect.


     [1m-t, --transfer=[4m[22mtransfer[24m [4mmode[0m
        Set transfermode. Valid modes are:

        +o  auto    (default)

        +o  serial1  (slowest)

        +o  serial2

        +o  parallel (fastest, not possible with a 1581)

        serial1 should work in any case.  serial2 won't work with more
        than one device connected to the IEC bus, parallel requires a
        XP1541/XP1571 cable in addition to the XM/XA1541.  If auto is
        given, or this option is completely omitted, cbmcopy will auto-
        matically determine the fastest transfer method possible with
        the current setup. Thus, you will seldom want to  manually over-
        drive the [4mtransfer[24m [4mmode[24m option.



     [1m-d, --drive-type=[22mtype
        Skip drive type detection.  Valid types are 1541, 1570, 1571 and
        1581.


     [1m-o, --output=[22mname
        Specifies target name. ASCII/PetSCII conversion is performed
        when in write-mode.


     [1m-a, --address=[22maddress
        Overrides the file's first two bytes with [4maddress[24m.


     [1m-R, --raw[0m
        Skip file type detection. File data is sent as is.  This option
        is only valid in write-mode.


     [1m-f, --file-type=[22mtype
        Specifies/overrides file type. Supported types are P, S, D, U.
        Raw files default to P, whereas the T64 format contains meta
        data which includes the file type. For PC64 files, [4mcbmwrite[0m
        tries to guess the file type from the file extension.  This
        option is only valid in write-mode.



  [1m5.6.2.  cbmcopy Examples[0m

  Read a file called [4mcbmfile[24m from drive 8 and store its binary value
  into the file file.bin, automatically selecting the fastest transfer
  method:

  ______________________________________________________________________
  cbmcopy -r 8 cbmfile -o file.bin
  ______________________________________________________________________



  Write out the file file.p00 in P64 format to the disc in drive 9,
  using serial1 transfer method:

  ______________________________________________________________________
  cbmcopy -w 9 file.p00
  ______________________________________________________________________



  [1m5.7.  rpm1541[0m

  [4mrpm1541[24m is a demo program. It finds out the rotation speed (in rounds
  per minute, rpm) of the drive motor.  [4mrpm1541[24m supports a 1541, 1570 or
  1571 drive.  A 1581 drive is [4mnot[24m supported.

  For Linux, [4mrpm1541[24m is not installed automatically. You have to compile
  it yourself (found in demo/rpm1541/) if you want to use it.  For
  Windows, it is part of the binary distribution.


  [1m5.7.1.  rpm1541 usage[0m

  Synopsis: rpm1541 [4m[device][0m

  The optional parameter [4mdevice[24m is the device number of the drive which
  should be tested. If not specified, rpm1541 utilizes drive 8.


  [1m5.7.2.  rpm1541 Example[0m


  Find out the rotation speed of drive 11:

  ______________________________________________________________________
  cbmctrl lock
  rpm1541 11
  cbmctrl unlock
  ______________________________________________________________________



  [1m5.8.  flash[0m

  [4mflash[24m is a demo program. It flashes the drive LED.  [4mflash[24m works with
  1541, 1570 or 1571 drives. A 1581 drive is [4mnot[24m supported.

  For Linux, [4mflash[24m is not installed automatically. You have to compile
  it yourself (found in demo/flash/) if you want to use it.  For
  Windows, it is part of the binary distribution.


  [1m5.8.1.  flash usage[0m

  Synopsis: flash [4m[device][0m

  The optional parameter [4mdevice[24m is the device number of the drive which
  should flash its LED. If not specified, flash utilizes drive 8.


  [1m5.8.2.  flash Example[0m


  Let the drive LED flash on drive 10:

  ______________________________________________________________________
  cbmctrl lock
  flash 10
  cbmctrl unlock
  ______________________________________________________________________



  [1m5.9.  morse[0m

  [4mmorse[24m is a demo program. It uses the drive LED to output a text in
  morse code.  [4mmorse[24m works with 1541, 1570 or 1571 drives. A 1581 drive
  is [4mnot[24m supported.

  For Linux, [4mmorse[24m is not installed automatically. You have to compile
  it yourself (found in demo/morse/) if you want to use it.  For
  Windows, it is part of the binary distribution.


  [1m5.9.1.  morse usage[0m

  Synopsis: morse [4m[device][0m


  The optional parameter [4mdevice[24m is the device number of the drive which
  should flash its LED. If not specified, morse utilizes drive 8.


  [1m5.9.2.  morse Examples[0m


  Morse the text "SOS", "HELLO" and "YOU" (in this order) on drive 9.

  ______________________________________________________________________
  cbmctrl lock
  morse 9
  cbmctrl command 9 U3:HELLO
  cbmctrl command 9 U3:YOU
  cbmctrl unlock
  ______________________________________________________________________



  [1m6.  opencbm API[0m

  All communication between the user space applications and the kernel
  module is done with ioctl's. Since ioctl's are quite unportable and
  hardly provide any type-safety, there are a number of wrapper-
  functions along with a couple of convenience functions implemented in
  libopencbm.a (Linux) or opencbm.dll (Windows). The prototypes can be
  found in the header file opencbm.h.


  [1m6.1.  Preprocessor macros[0m



  +o  #define IEC_DATA 0x01

  +o  #define IEC_CLOCK 0x02

  +o  #define IEC_ATN 0x04

  These defines are used by the [4mcbm_iec_*()[24m functions. You will
  definitely need this if you intend to implement your own custom
  transfer routines. See the libd64copy/libcbmcopy source for more
  information.


  [1m6.2.  Enumeration types[0m



  +o  enum cbm_device_type_e

     +o  cbm_dt_unknown

     +o  cbm_dt_1541

     +o  cbm_dt_1570

     +o  cbm_dt_1571

     +o  cbm_dt_1581



  +o  enum cbm_cable_type_e

     +o  cbm_ct_unknown

     +o  cbm_ct_none

     +o  cbm_ct_xp1541


  [1m6.3.  Generic types[0m


  +o  CBM_FILE

  This type is used to take a handle to the CBM driver. Only use this
  type, as it hides the differences between Windows and Linux.

  An invalid CBM_FILE has value CBM_FILE_INVALID.


  [1m6.4.  Functions[0m


  (All functions except cbm_driver_open(): [4mf[24m must be a valid file
  descriptor)


  [1m6.4.1.  Basic I/O[0m


     [1mint cbm_driver_open(CBM_FILE *f, int port);[0m
        Opens the driver. port isn't used by now and should be 0.  After
        successful completion, 0 is returned along with a valid CBM_FILE
        descriptor in f.


     [1mvoid cbm_driver_close(CBM_FILE f);[0m
        Closes the driver.


     [1mvoid cbm_lock(CBM_FILE f);[0m
        The equivalent to [4mcbmctrl[24m [4mlock[24m. Make sure the parallel port is
        kept locked even if the driver is closed with
        cbm_driver_close().


     [1mvoid cbm_unlock(CBM_FILE f);[0m
        The equivalent to [4mcbmctrl[24m [4munlock[24m. Unlock the parallel port as
        soon is the driver is closed with cbm_driver_close().


     [1mint cbm_raw_read(CBM_FILE f, void *buf, size_t size);[0m
        Retrieve data after cbm_talk();. At most size bytes are read.
        Return value is the actual number of bytes read. < indicates an
        error.


     [1mint cbm_raw_write(CBM_FILE f, const void *buf, size_t size);[0m
        Send data after cbm_listen();. At most size bytes are written,
        Return value is the actual number of bytes written. < indicates
        an error.


     [1mint cbm_listen(CBM_FILE f, __u_char dev, __u_char secadr);[0m
        Tell device [4mdev[24m to listen on secondary channel [4msecadr[24m.  Return
        value is 0 on success, < 0 means error.
     [1mint cbm_talk(CBM_FILE f, __u_char dev, __u_char secadr);[0m
        Tell device [4mdev[24m to talk on secondary channel [4msecadr[24m.  Return
        value is 0 on success, < 0 means error.


     [1mint cbm_open(CBM_FILE f, __u_char dev, __u_char secadr);[0m
        Prepare device [4mdev[24m for opening a file. This device listens for
        the file name after this call which is normally sent by a call
        to the [4mwrite()[24m-function followed by an [4munlisten()[24m call.  Return
        value 0 on success, < 0 means error.


     [1mint cbm_close(CBM_FILE f, __u_char dev, __u_char secadr);[0m
        Close file associated with secondary address [4msecadr[24m on device
        [4mdev[24m.  Return value 0 on success, < 0 means error.


     [1mint cbm_unlisten(CBM_FILE f);[0m
        Send unlisten on bus.  Return value 0 on success, < 0 means
        error.


     [1mint cbm_untalk(CBM_FILE f);[0m
        Send untalk on bus.  Return value 0 on success, < 0 means error.


     [1mint cbm_get_eoi(CBM_FILE f);[0m
        Get EOI flag after bus read, return value is 0 with no EOI,
        otherwise 1.  When EOI is set to 1, the active talker has
        nothing more to send.


     [1mint cbm_clear_eoi(CBM_FILE f);[0m
        Reset EOI flag.  Return value 0 on success, < 0 means error.


     [1mint cbm_reset(CBM_FILE f);[0m
        Do a hardware reset on all connected devices. Control is
        returned after a 5 second delay.


  [1m6.4.2.  Low-level port access[0m


     [1m__u_char cbm_pp_read(CBM_FILE f);[0m
        Read byte from XP1541/XP1571 bus. No handshaking or such
        involved.


     [1mvoid cbm_pp_write(CBM_FILE f, __u_char c);[0m
        Write byte to XP1541/XP1571 bus. No handshaking or such
        involved.


     [1mint cbm_iec_poll(CBM_FILE f);[0m
        Read status of all bus lines. Return value is a combination of
        IEC_ATN, IEC_CLOCK and IEC_DATA.


     [1mint cbm_iec_get(CBM_FILE f, int line);[0m
        Get (logical) status of line [4mline[24m.


     [1mvoid cbm_iec_set(CBM_FILE f, int line);[0m
        Activate lines [4mline[24m (set to 0V).  [4mline[24m can be one of or a
        combination with OR of any of IEC_DATA, IEC_CLOCK, IEC_ATN.
     [1mvoid cbm_iec_release(CBM_FILE f, int line);[0m
        Release lines [4mline[24m (set to 5V).  [4mline[24m can be one of or a
        combination with OR of any of IEC_DATA, IEC_CLOCK, IEC_ATN.



     [1mvoid cbm_iec_setrelease(CBM_FILE f, int setline, int resetline);[0m
        Set lines [4msetline[24m (set to 0V) and release line [4mreleaseline[24m (set
        to 5V) [4msetline[24m and [4mresetline[24m can each be one of or a combination
        with OR of any of IEC_DATA, IEC_CLOCK, IEC_ATN. If a line is
        part of both [4msetline[24m and [4mresetline[24m, the outcome is undefined.



     [1mint cbm_iec_wait(CBM_FILE f, int line, int state);[0m
        Experimental, do not use.


  [1m6.4.3.  Helper functions[0m


     [1mint cbm_upload(CBM_FILE f, __u_char dev, int adr, void *prog, int[0m
        [1msize);[0m
        Write [4mprog[24m into device [4mdev[24m's memory space via a series of "M-W"
        commands.


     [1mint cbm_device_status(CBM_FILE f, __u_char drv, void *buf, int buf-[0m
        [1msize);[0m
        Read device status info [4mbuf[24m, at most [4mbufsize[24m bytes are read.
        Returns [4matoi(buf)[24m.


     [1mint cbm_exec_command(CBM_FILE f, __u_char drv, void *cmd, int len);[0m
        Execute command [4mcmd[24m. Returns number of bytes actually written.
        if [4mlen[24m is 0, [4mcmd[24m is considered a 0-terminated string.


     [1mint cbm_identify(CBM_FILE f, __u_char drv, enum cbm_device_type_e[0m
        [1m*t, const char **type_str);[0m
        Tries to identify the device [4mdrv[24m. The hardware type is returned
        in [4mt[24m, [4mtype_str[24m contains a descriptive string which also includes
        the drives' operating system. Both [4mt[24m and [4mtype_str[24m may be NULL in
        case the caller is not interrested in any of both values.

        The return value is 0 if the device responded to the "M-R"
        command, even if it could not be identified, < 0 indicates
        error.


     [1mint cbm_identify_xp1541(CBM_FILE f, __u_char drv, enum[0m
        [1mcbm_device_type_e *t1, enum cbm_cable_type_e *t2);[0m
        Tries to identify the device [4mdrv[24m. The hardware type is returned
        in [4mt1[24m, [4mt2[24m contains whether the drive has an parallel (XP1541)
        cable attached.  Both [4mt1[24m and [4mt2[24m may be NULL in case the caller
        is not interrested in any of both values.

        The return value is 0 if the device responded to the "M-R"
        command, even if it could not be identified, < 0 indicates
        error.



  [1m6.4.4.  PetSCII functions[0m


     [1mchar cbm_petscii2ascii_c(char character);[0m
        Converts one character [4mcharacter[24m from PetSCII to ASCII.


     [1mchar cbm_ascii2petscii_c(char character);[0m
        Converts one character [4mcharacter[24m from ASCII to PetSCII.


     [1mchar * cbm_petscii2ascii(char *str);[0m
        Convert a null-terminated string [4mstr[24m from PetSCII to ASCII.


     [1mchar * cbm_ascii2petscii(char *str);[0m
        Convert a null-terminated string [4mstr[24m from ASCII to PetSCII.



  [1m6.4.5.  Parallel Burst functions[0m


     [1m__u_char cbm_parallel_burst_read(CBM_FILE f);[0m
        Support function for mnib. Do not use.


     [1mvoid cbm_parallel_burst_write(CBM_FILE f, __u_char c);[0m
        Support function for mnib. Do not use.


     [1mint cbm_parallel_burst_read_track(CBM_FILE f, __u_char *buffer,[0m
        [1munsigned int length);[0m
        Support function for mnib. Do not use.


     [1mint cbm_parallel_burst_write_track(CBM_FILE f, __u_char *buffer,[0m
        [1munsigned int length);[0m
        Support function for mnib. Do not use.



  [1m6.4.6.  libd64copy TODO[0m

  Not documented yet. See [4mlibd64copy[24m and [4md64copy[24m source.

  Types and prototypes are defined in d64copy.h.


  [1m6.4.7.  libcbmcopy TODO[0m

  Not documented yet. See [4mlibcbmcopy[24m and [4mcbmcopy[24m source.

  Types and prototypes are defined in cbmcopy.h.



  [1m7.  Known bugs and problems[0m

  There are some known bugs in opencbm:


  +o  [4mcbmcopy[24m is still known to have some protocol races, especially with
     1581 drives; thus, it does not always work reliably.


  +o  [4mcbmctrl[24m [4mdetect[24m as well as [4mcbmcopy[24m and [4md64copy[24m do not recognize the
     drive type if some custom ROM is used.

  +o  Windows: If you have any other devices connected to your parallel
     port, you cannot use them as long as cbm4win is installed. In this
     case, either remove opencbm whenever you want to access that other
     device, or install opencbm with [4minstcbm[24m [4m--lock=no[24m and make sure to
     issue [4mcbmctrl[24m [4mlock[24m before accessing the drive, and [4mcbmctrl[24m [4munlock[0m
     afterwards.

  +o  Windows: No third party PCI parallel port card does work with
     opencbm on Windows currently; to say it with other words: there is
     no proof or positive report that any third party PCI parallel port
     card does or did work with opencbm on Windows. The exact failure
     reason is not known to date, but we are investigating further since
     that feature is a must, when integrated parallel ports were removed
     from mainstream mainboards in the future.


  [1m8.  Misc[0m

  [1m8.1.  Credits[0m

  The fast format drive routine used by `cbmformat' and the turbo and
  warp drive routines used in `libd64copy' and `libcbmcopy' 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


  [1m8.2.  Contributions[0m

  People who directly or indirectly contributed to opencbm (in no
  particular order):


  +o  [4mMichael[24m [4mKlein[24m started the original cbm4linux work (which was a very
     big part)

  +o  [4mJoe[24m [4mForster/STA[24m made the Star Commander and supplied the source and
     about the X?1541 interfaces; who knows, without this work, opencbm
     might never have appeared at all.

  +o  [4mNicolas[24m [4mWelte[24m helped with the XA1541 and XM1541 interfaces and
     supplied a free factory-new 1571 mechanic for Michael

  +o  [4mAndreas[24m [4mBoose[24m [4m&[24m [4mthe[24m [4mVICE[24m [4mteam[24m made VICE

  +o  [4mAndr[24m [4mFachat[24m made the xa 6502 crossassembler

  +o  [4mUllrich[24m [4mvon[24m [4mBassewitz[24m made the ca65 crossassembler

  +o  [4mWolfgang[24m [4mMoser[24m contributed [4mmany[24m discussions, patches, and hardware
     whenever it was needed.

  +o  [4mSpiro[24m [4mTrikaliotis[24m with discussions, lots of fixes and doing an
     overall great review while porting the driver to "other" operating
     systems ;-)


  And anyone else who sent patches, suggestions, praises & flames!



  [1m8.3.  Feedback[0m

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


  Have fun,

  The opencbm team.



