# `cbmlink` release notes

`cbmlink` 0.9.7
  a data transfer system between Commodore 8-bit computers and other systems (Amiga, IBM PC compatible, Apple, Unix workstations)

## Copyright information

The `cbmlink` utility is based on `prlink`, which was developed from 1994 to 1998 by Marko Mäkelä and Olaf Seibert. The first version of `cbmlink` was developed by Marko Mäkelä in 2001–2002.

> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

> This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

The 1541 quick format option is based on the work of Daniel Kahlin. The original copyright message follows:

> Copyright © 1995, 1996, 2002, Daniel Kahlin. All rights reserved.

> Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

> 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
> 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
> 3. Neither the names of the copyright holders nor the names of their contributors may be used to endorse or promote products derived from this software without specific prior written permission.

The 1541 quick copy options (which do not work yet) are based on the work of Andreas pitch Andersson. The original copyright message follows:

> Copyright © Andreas pitch Andersson 1995–2002.

> Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

> 1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgement in the product documentation would be appreciated but is not required.
> 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
> 3. This notice may not be removed or altered from any source distribution.

## Table of Contents

  0 Preface
  1 Getting started
    1.1 Bootstrapping
      1.1.1 The C2N232 connection
      1.1.2 Null modem cable
      1.1.3 Parallel cables
    1.2 Usage
      1.2.1 Changing the start address
      1.2.2 Automatic startup on the Commodore 128
  2 Functions
    2.1 Memory transfers
      2.1.1 Loading a file to memory
      2.1.2 Saving memory to a file
    2.2 Remote Program Invocation
      2.2.1 Starting a BASIC program
      2.2.2 Starting a machine language program
      2.2.3 Starting a VIC-20 cartridge
      2.2.4 Playing Commodore 64 music tunes
      2.2.5 Performance measurements
    2.3 File and disk transfer
      2.3.1 Reading Commodore files
      2.3.2 Writing Commodore files
      2.3.3 Disk transfer
      2.3.4 Disk memory transfer
    2.4 Quick 1541 disk operations
  3 Hardware
    3.1 Cable pin-outs
      3.1.1 The null modem cable (`serial`)
      3.1.2 The PC64 cable (`pc64`)
      3.1.3 The prlink cable (`prlink` a.k.a. `prlink48`)
      3.1.4 The Amiga cable (`prlink88`, `prlink48`, `transnib`)
      3.1.5 The serial bus cable for IBM PC compatibles (`x1541`)
      3.1.6 The serial bus cables for the Amiga (`em1541`, `emul1541`)
      3.1.7 The Kontros cable (`kontros`)
      3.1.8 The 64NET cable (`c64net`)
    3.2 Transfer trouble
      3.2.1 The CIA FLAG signal
      3.2.2 Problems with the C2N232
      3.2.3 RS-232 Transfers
  4 Compiling
    4.1 The `cbmlink` executable
    4.2 The Commodore servers
      4.2.1 Using the REU with an Action Replay
  5 Credits
  6 Known bugs and future plans
  7 Distribution

## 0 Preface

This document describes the `cbmlink` utility, a program package that lets you to transfer data over a parallel connection or an RS-232 connection between a Commodore 8-bit computer and a bigger system (Amiga, IBM PC compatibles, Apple, Unix workstation).

The utility is based on a daemon, or a memory resident IRQ handler wedge running in the Commodore end of the cable. You always issue the commands from the other side. This arrangement does not need any server processes to be installed on the bigger computer.

Currently daemons are available for the following Commodore systems:

- PET series: 3000 series (may not work), 4000/8000/200 series [no support yet for the 2000 series (BASIC 1.0)]
- PET-II or B series: CBM P500, 510, 610, 620, 710 and 720
- Commodore VC-20, VIC-20 or VIC-1001
- Commodore 64, 4064, SX-64, 64c or 64G
- Commodore 128, 128D or 128DCR
- Commodore 264 series: 16, 116, plus/4, 232 or V364

For some computer and cable combinations, there exist several alternatives, either for supporting a memory expansion or an alternative loading address or cassette interface.

The client program has been written in such a way that it should compile on most C compilers with minor modifications. The programs were originally written for GNU/Linux. The are Intel 8086 and 80386 optimised transfer routines for parallel cables. The software should work at least on the following systems:

GNU/Linux
  This is the main development platform. Also IBM PC compatible parallel ports are supported.
Apple Mac OS X
  The code can be compiled in Mac OS X. It is possible to use RS-232 via a USB adapter.
Other Unix-like systems
  The code should compile on all POSIX® compliant systems. Only the RS-232 connection is supported. We have successfully tested it on an old IBM workstation running AIX. The serial line driver in Solaris 5.7 turned out to be buggy. We had technical problems trying to set up a Silicon Graphics workstation as well as an HP-UX workstation for testing.
32-bit versions of Microsoft Windows (95 and later)
  The parallel cables do not work in NT, 2000 and XP without special tricks. The RS-232 connection should work on all versions.
Older Apple computers
  The RS-422 port of older Apple systems can be converted to RS-232 with a simple cable. The RS-232 code needs some modifications; other cables cannot be supported easily by Apple hardware. Are there any volunteers for porting the code?
Commodore Amiga
  The code can be compiled with a modified version of `gcc-2.95.3` packaged by Martin Blom. Due to copyright reasons, the Amiga OS header files are not distributed with the compiler. Probably the easiest way of obtaining the headers is downloading the Native Developer Kit 3.9.
MS-DOS and its clones
  No support for RS-232 has been implemented yet (any volunteers?), but the parallel cables do work.

The idea of the transfer utility package is that a daemon runs on the Commodore side in an interrupt routine, without affecting the computer's performance. Invoked by the periodic system timer interrupt, it checks if the other side wants to send a command, and executes the commands when needed. The protocol includes commands for memory transfers and for starting a machine language routine or a BASIC program. The latter two commands deinstall the daemon for maximum compatibility.

With the current protocol, it is possible to make useful applications that run on the other end, like disk and file copiers, and possibly a remote debugger. It is convenient to develop Commodore programs on the other side and to transfer them over to test them out. On the Commodore 128, you can use a boot sector, so that the daemon will be loaded and started automatically when you start the computer. On the Commodore VIC-20, the daemon can make use of the cartridge auto-start signature.

## 1 Getting started

Until a binary distribution for your platform is available, you will have to compile the source code for your system, as described in Section 4.1.

Patches and precompiled binaries are welcome.

For your convenience, we have composed the archive `cbmlink-cbmbasic.zip` of precompiled Commodore binaries. This archive is described in Section 4.2.

### 1.1 Bootstrapping

#### 1.1.1 The C2N232 connection

The C2N232 is a small RS-232 interface that can be plugged to the cassette port of an 8-bit Commodore computer:

- PET series: 2001, 3000 series, 4000 series, 8000 series, 200 series
- PET-II or B series: CBM 500, 600 or 700 series or the P500
- Commodore VC-20, VIC-20 or VIC-1001
- Commodore 64, 4064, 64c or 64G
- Commodore 128, 128D or 128DCR
- Commodore 264 series: 16, 116, plus/4, 232 or V364

The RS-232 end of the interface can be connected to any computer for which the following are available:

- an RS-232 interface at 38,400 bits per second, with XON/XOFF or RTS/CTS handshaking
- an operating system that supports the RS-232 interface
- a C compiler that supports the operating system

The device consists of two integrated circuits: a micro-controller and an RS-232 line driver. There are two connectors in the C2N232. The card edge connector plugs into the Commodore cassette port, and the DE-9S connector plugs to a serial port with an IBM PC/AT style pin-out. Normally, you want to use an RS-232 extension cable that connects at least pins 5 (ground), 2 (RxD) and 3 (TxD). A null modem cable will not work!

The parts of the C2N232 cost something between 10 and 20 €, which can be slightly more than the parts for a passive parallel cable. However, compared to passive cables, the C2N232 is

universal:
  The C2N232 works in all 8-bit Commodores that have a cassette interface.
based on widely supported standards:
  RS-232 is a de facto standard, and supported in virtually all operating systems. There is no need to write a low-level device driver or to bypass the operating system.
electrically stable and safe:
  RS-232 tolerates voltage differences and grounding problems much better than logic-level interface chips. Even if a chip is toasted, the damage is often limited to the line driver chip and not to expensive and hard-to-obtain custom-made interface chips.

The C2N232 emulates tape transfers at a fairly low level, relaying pulse streams consisting of square waves of three configurable frequencies.

The driver program `c2nload` loads an automatically starting fastloader, which loads Commodore program files at 38,400 bits per second and executes them, like this: `c2nload -c /dev/ttyS0 cbmbasic/c2n232/c64/plain.prg`.

If the `c2nload` program does not appear to work, you can try accessing the C2N232 device with a terminal program. Set up the connection for 38,400 bits per second, eight bits per character, no parity bit, and one stop bit. The device should respond to the BREAK signal with a `NUL` character followed by `0`. Try sending a `Ctrl-A`; the device should respond with `1`. If you now enter the `SAVE` command on the Commodore, the device should display a string of characters for several seconds.

Note that on some Commodore computers, some cassette port lines are shared with other interfaces. This may limit the applications of the C2N232. On the Commodore VIC-20, the write line is shared with the keyboard, and some other lines are wired to the user port. On the Commodore 264 series, the write line is shared with the serial bus clock input. On the Commodore PET, the write line is shared between the two cassette ports.

#### 1.1.2 Null modem cable

If you already have a null modem cable, you probably also have a terminal program that you can use for transferring the `cbmlink` daemon to your Commodore.

#### 1.1.3 Parallel cables

If you do not currently have any possibility to transfer data to your Commodore 8-bitter from other computers, don't worry. In the file loader.txt, there is a bare-bones BASIC implementation of the `cbmlink` daemon with which you can download the real daemon to your Commodore. Just type it in and save it on tape or disk before starting it.

On an IBM PC compatible, the PC64 cable is recommended, because newer on-board enhanced bidirectional printer interfaces may have problems with the prlink cable. The PC64 cable is the safest choice. The X1541 and 64NET cables are supported only for the sake of completeness.

On the Amiga, there is one native cable, which works with all supported protocols except the Commodore serial bus protocols. For the bootstrapping you can only choose the 4-bit/8-bit protocol, but you can use any protocol after you have transferred the desired daemon to the 8-bit Commodore side. Furthermore there is the transnib protocol, which works over both TransNib and prlink cables. The most efficient protocol is prlink88, which transfers 8 bits at a time in both directions.

Start the bootstrapper program on your Commodore. On the big computer, execute the `cbmlink` program with the desired protocol to transfer the desired daemon from the cbmlink-cbmprg.zip package to the Commodore, e.g.: `cbmlink -c pc64 0 -l cbmprg/pc64/c64/plain.prg`.

Now you should see a list of addresses and byte values scroll by. If not, the connection does not work properly. Ensure that the cable is properly connected and you have typed in the appropriate lines of the BASIC listing, so that it is adapted for your hardware. Also, if you are using an IBM PC compatible, you may have chosen the wrong printer port. Try the `-c` parameter with different device numbers (from 0 to 3) or I/O port addresses. Also note that the Linux version requires super user (root) privileges or the parallel port device, e.g., `/dev/parports/0`.

If everything seems to run correctly, replace the keyword `PRINT` in line 2050 with `POKE`. Now the daemon will be really loaded to your computer. Once the program has been transferred, type `SYS` and the start address printed by the BASIC program.

Now you have the cbmlink daemon running, and you can transfer the a relocatable version of the daemon, from the cbmlink-cbmbasic.zip package, e.g., `cbmlink -c pc64 0 -l cbmbasic/pc64/c64/plain.prg`. Use the `SAVE` command to save it to disk or tape.

### 1.2 Usage

Start the 6502 side by issuing the `RUN` command.

The server will hook itself in the timer interrupt handler chain and you should get a `READY` prompt back immediately. Now you can use the `cbmlink` program.

To make the 6502 side remove itself from the interrupt chain, issue the command `SYS start+3` where `start` is the `SYS` address for restarting the server. For instance, `SYS52227` will disable the cbmlink daemon loaded to the default address on the Commodore 64.

#### 1.2.1 Changing the start address

If you type `LIST` before `RUN`ning the cbmlink daemon, you will see two lines of BASIC, like the following:

    64 SYS29+256*PEEK(44):NEW
    52224 SYS

The first line number indicates the computer model (64 for the Commodore 64). The second line number is the desired start address of the server program. The server can be relocated by simply changing the line number of the second line, like this:

    49152 SYS
    52224
    RUN

The server can be restarted by typing `SYS` and the number of the second line, e.g., `SYS49152`. Please note that the relocation address must be an integer multiple of 256. Also, the server must reside entirely in a memory area that is RAM in the default memory configuration of the operating system.

#### 1.2.2 Automatic startup on the Commodore 128

The Commodore 128 tries to load a boot sector from device 8 in its startup routine. With our special boot sector, it is possible to start the server on the Commodore 128 automatically. It not only starts the `cbmlink` server for the Commodore 128; it can also switch to Commodore 64 mode and start the server there.

The server programs must be non-relocatable variants, that is, you must choose them from the package cbmlink-cbmprg.zip instead of cbmlink-cbmbasic.zip.

There are two variants of the boot sector:

`cbmutils/c128/bootsect.bin`
  The standard boot sector. No support for the PIA memory expansion. May load either `cbm128` or `cbm64`, depending on the selected mode.
`cbmutils/c128/bootsect-pia.bin`
  A special boot sector with support for the PIA memory expansion. When told to load a server that does not support the PIA memory expansion, this boot sector disables the PIA for maximum compatibility.

By default, the boot sector loads the server for Commodore 128 mode. You can change this behaviour by holding a key down while the boot sector is being started. Remember not to press the `STOP` or `C=` keys down too early, or the start-up routine will not load the boot sector. The keys and their functions are as follows:

Key pressed | File to load | Mode
--- | --- | ---
`STOP` | (none) | C128
`Q` | (none) | C64*
`(none),<-,1,2` | `cbm128` or `cbm1028` | C128
`CTRL` | `cbm128` | C128
`C=` | `cbm64` or `cbm2564` | C64
`SPACE` | `cbm64` | C64*

* Note that drive 8 will be issued the `U0>M0` command in this case. (Effectively, a 1571 drive will be reset to 1541 mode.) Also, the 40/80 key sense line will be zeroed. (This line can be used for selecting the KERNAL ROM for the Commodore 64 mode. When the line is zero (or the key is down), the standard KERNAL is selected. When the line is high, a KERNAL ROM extension, such as JiffyDOS, can be active.

You have to copy the servers for the modes you use. For instance, if you have a PIA expansion and a REU in your Commodore 128, and you are using the PC64 cable, you need to copy the following files:

File name in cbmlink-cbmprg.zip | C128 file name
--- | ---
`cbmprg/pc64/c128/plain.prg` | `cbm128`
`cbmprg/pc64/c128/piareu.prg` | `cbm1028`
`cbmprg/pc64/c64/plain.prg` | `cbm64`
`cbmprg/pc64/c64/piareu.prg` | `cbm2564`

In addition, you need to copy `cbmutils/c128/bootsect-pia.bin` to track 1, sector 0 on drive 8 by using the `cbmlink` switch `-dw0 bootsect-pia.bin`.

It is possible to change the default behaviour of the boot sector. As you can see from the source code in `cbmutils/c128/bootsect.s`, a default value will be loaded if none of the special keys is being pressed during the boot. By changing the default value, you can create a boot sector that e.g. automatically switches to Commodore 64 mode and loads the appropriate server.

## 2 Functions

The `cbmlink` interprets and executes its command line from left to right, one switch at a time. If an error occurs, the rest of the command line is ignored, and the program exits with a nonzero status.

Typically, every `cbmlink` invocation starts with the switch `-c protocol device`, which specifies the hardware protocol and the device address to be used for communications. The device name is protocol-specific:

c2n232, serial
  The device name is the special file that points to the RS-232 interface, e.g., `/dev/ttyS0`, `serial.device` or `COM1`.
pc64, prlink, kontros, c64net, x1541
  The device name is the I/O port address of an IBM PC compatible printer port or an index to a table, e.g. `0x3bc` or `0`. Alternatively, if `cbmlink` has been compiled with support for the parallel port device, you may specify a Linux or FreeBSD parallel port device name, such as `/dev/parports/0`. In this way, super user privileges are not needed.
prlink48, prlink88, transnib, emul1541, em1541
  The device name is ignored; these cables are connected to the parallel port of a Commodore Amiga.

Probably the most frequently used features of `cbmlink` are loading a program to memory and invoking it. But `cbmlink` can also be used for copying files and entire disks.

If `cbmlink` has been compiled with debugging support, you may prepend the protocol name with `debug_` in order to get a listing of transmitted and received data.

### 2.1 Memory transfers

The file-to-memory and memory-to-file transfers of `cbmlink` support memory expansions and banked memory access on the Commodore.

The `-b` switch is used for overriding the default bank, which is 1 for the Commodore 610, 710, 620 and 720, and 0 for all other Commodores.

Bank numbers 0 to f are for internal memory. The two low-most bits are for specifying the MMU mapped memory bank on a Commodore 128. In other words, MMU mapped memory banks on the Commodore 128 are numbered from 0 to 3. On unexpanded units, the banks 2 and 3 are the same than banks 0 and 1.

The bits 2 and 3 of the bank number specify the PIA mapped expanded memory bank on a Commodore 128 or a Commodore 64. So, the 64 kB banks of a Commodore 128 with 1 megabyte of internal memory are numbered from 0 to 15. On a 512 kB expanded Commodore 128, the unique bank numbers are 0, 1, 4, 5, 8, 9, 12 and 13, as there are only two MMU banks. For instance, the banks 11 and 9 are equivalent. On a 256 kB expanded Commodore 64, or on a PIA-expanded Commodore 128 in Commodore 64 mode, the bank numbers 0..3, 4..7, 8..11 and 12..15 are the same, so there are 4 different banks.

Bank numbers from 16 to 255 are for REU memory banks, i.e. the banks of a 512 kilobyte REU are numbered from 16 to 23.

On a stock Commodore 128, memory will be accessed through the FETCH ($2a2) and STASH ($2af) subroutines. Due to their design, there's a bug: any data read between 0x0 and 0x3ff will be fetched from bank 0. The version for the PIA expansion does not have this bug.

#### 2.1.1 Loading a file to memory

It is possible to load Commodore program files as well as raw binary files to the Commodore memory space, at most 64 kilobytes at a time, by using one of the following options:

`-l`[`p`]`file.prg`
  Load a program at its specified absolute address. The first two bytes of the file indicate the 16-bit loading address (least significant byte first), and the remaining bytes contain the file data. The options beginning with `-lp` support the P00 file format by skipping the 26-byte file header.
`-l`[`p`]`b file.prg`
  Load a program, relocated to the start of the BASIC text area.
`-l`[`p`]`o,address file.bin`
  Load a binary file (not containing a starting address) to the specified address.
`-l`[`p`]`r,address file.prg`
  Load a program, relocated to the specified address.

Note that the file to be loaded may not overwrite the server code or I/O register space. If this happens, the transfer may hang.

#### 2.1.2 Saving memory to a file

The Commodore memory space may be copied to a program file or to a raw binary file, at most 64 kilobytes at a time, by using one of the following options:

`-s,address1,address2 file.prg`
  Save the memory bytes from `address1` up to but excluding `address2` in the specified bank to a program file. Write `address1` to the first two bytes of the file.
`-so,address1,address2 file.bin`
  Save the memory bytes from `address1` up to but excluding `address2` in the specified bank to a binary file.

You may find indirect addressing useful. In order to save a BASIC program in a Commodore 64, try `-s,@0x2b,@0x2d file.prg`.

Note that dumping the I/O register space may hang the transfer.

### 2.2 Remote Program Invocation

It is possible to remotely invoke both BASIC and machine language programs. Before starting a program, the server deinstalls itself in order to achieve maximum compatibility.

#### 2.2.1 Starting a BASIC program

The `-r` switch performs the BASIC `RUN` command. This switch is typically used at the end of a command line, e.g. `cbmlink -c c2n232 /dev/ttyS0 -l Elite.prg -r`.

#### 2.2.2 Starting a machine language program

The `-j` switch invokes a machine language program. Again, indirect addressing may be useful: `-j,@0xfffc` performs a soft reset.

#### 2.2.3 Starting a VIC-20 cartridge

Normally, switching cartridge games is a little annoying, because you would have to physically remove and install ROM cartridges, or to power the computer off until a RAM expansion cartridge has forgot the `a0CBM` auto-start code in BLK5.

With `cbmlink`, playing Commodore VIC-20 cartridge games becomes more convenient. The `-jc` (jump cartridge) switch installs a small machine language program that modifies the cartridge reset vector. When the reset button is pressed, the computer resets itself and installs the `cbmlink` server again.

This arrangement works notably well if the server resides at $4000 (BLK3) and the option is invoked with `-jc,20000`. The parameter specifies a `SYS` address that can be used for restarting the cartridge game after pressing the reset button.

Typical usage of the switch is: `cbmlink -c c2n232 /dev/ttyS0 -l "Pole Position-6000.prg" -l "Pole Position-a000.prg" -jc,20000`.

#### 2.2.4 Playing Commodore 64 music tunes

There is a collection of Commodore 64 music files on ftp.funet.fi at /pub/cbm/c64/audio/Vibrants. These modules use a common format. They must be initialised with a call to $1000, and the music will be played by calling $1003 once per picture frame.

As there are loads of these files, Marko did not want to transfer them first to my Commodore 64, but he wanted to play them easily with a simple `cbmlink` command. So, he created a simple player that also reinstalls the `cbmlink` daemon.

The player is very simple. By default, it will compile to $c800, and it assumes that the `cbmlink` daemon starts at $cc00.

Assume that you have the player (`cbmutils/c64/playtune.prg`) and Toccato (/pub/cbm/c64/audio/Vibrants/Deek/14toccat.prg) in the current directory. To start playing the music on the Commodore 64, you may use the command `cbmlink -c c2n232 /dev/ttyS0 -l playtune.prg -l 14toccat.prg -j 0xc800`. Alternatively, you can load `playtune.prg` and the tunes separately. To change the tune, you may omit `playtune.prg`: `cbmlink -c c2n232 /dev/ttyS0 -l 14treasu.prg -j 0xc800`.

Beware that there are some musics with different init and play addresses. If you keep hearing the same piece after loading a new tune, make sure that the new tune starts at $1000.

#### 2.2.5 Performance measurements

The file `cbmutils/c64/tod.prg` measures the time spent in an interrupt in hours, minutes, seconds and tenth of seconds, as read from the Time of Day clock register. It assumes that the power frequency is 50 Hz. The times will be displayed on the screen, if they are at least two tenths of a second.

The utility was developed in order to measure `cbmlink` performance. It also works on the Commodore 128. Start it with `SYS12288` after starting the server, and see how much time a 64-kilobyte transfer (`-s,0,0 file`) will consume on your equipment.

### 2.3 File and disk transfer

The file transfer commands use standard KERNAL routines. This means very slow speed, but it also guarantees maximum compatibility. For instance, disk transfers support any disk geometry for up to 999 tracks consisting of up to 1000 sectors.

Note that these transfer commands only work with disk drives or pseudo drives, like the REU RAM disk. The commands might work with sequential files stored on tapes, but not with program files. (This has not been tested.) Bad news for those who use a Commodore serial bus cable: As you cannot use serial devices while the daemon is running, you won't have much use for these commands.

The switch `-d drive[,secondary]` overrides the default device number (8) and secondary address (0 for reading and 1 for writing files). The secondary address cannot be overridden for other disk operations.

As the file names are not translated between PETSCII and ASCII, it is best to use upper-case file names on the local system, which correspond to lower-case Commodore file names.

#### 2.3.1 Reading Commodore files

The file-read extension can be used through several command-line switches:

`-fr file` ...
  Copy the specified files from the Commodore to the local file system.
`-dd pattern`
  Read the file `$pattern` and display it on the standard output as a directory listing.
`-ds`
  Read the status channel of the drive, and display the result on the standard output.
`-dc command`
  Issue the specified command and read the status channel. Note that the command needs to be in upper case, as no PETSCII translation takes place. Also note that issuing the `UJ` command will probably hang the system. To reset the drive, use `UI` instead.

#### 2.3.2 Writing Commodore files

There is only one switch for using the file-write extension:

`-fw file` ...
  Copy the specified files from the local file system to the Commodore.

It is best to rename the files to upper case before copying, as `cbmlink` won't strip directory delimiters or translate file names from ASCII to PETSCII.

#### 2.3.3 Disk transfer

By default, the disk transfer commands refer to drive unit 0. The unit can be specified as an additional parameter.

`-dr`[`0`|`1`][`,interleave`[`,start`[`,end`]]] `file`
  Make a verbatim copy of the disk to the specified local file. The interleave factor may dramatically affect the copying speed. Note that file must be seekable when interleave differs from 0. The optimal value depends on the hardware. On C64+1541+C2N232, the value 3 is fastest. On C128+1571+C2N232 with JiffyDOS, the value 0 is fastest. The default is 10. Also, the default start and end tracks of 1 and 1000 can be overridden.
`-dw`[`0`|`1`][`,interleave`[`,start`[`,end`]]] `file`
  Copy a local file to Commodore disk sectors, starting from track 1. The interleave factor may dramatically affect the copying speed. Note that file must be seekable when interleave differs from 0. The optimal value depends on the hardware. On C64+1541+C2N232, the values 0 and 1 are fastest. On C128+1571+C2N232 with JiffyDOS, the value 1 is fastest. The default is 10. Also, the default start and end tracks of 1 and 1000 can be overridden.

When the file given to the `-dw` option is shorter than the disk capacity, the rest of the disk is left uninitialised.

All media sizes are supported. The only requirement is that the first track is 1 and the first sector on each track is 0. Tracks and sectors increment up to 999.

#### 2.3.4 Disk memory transfer

It is possible to load and save a disk drive's memory space. These functions are based on the `M-R` and `M-W` disk commands.

`-dmc address1 address2 file.prg`
  Save the memory bytes from `address1` up to but excluding `address2` in a dual disk drive's controller address space to a program file. Write `address1` to the first two bytes of the file. Note that the drive may act strangely once this command has been issued. Thanks to William Levak and Wolfgang Günther for providing the information needed for implementing this option.
`-dmco address1 address2 file.bin`
  Save the memory bytes from `address1` up to but excluding `address2` in a dual disk drive's controller address space to a binary file. Note that the drive may act strangely once this command has been issued.
`-dml file.prg`
  Load a program at its specified absolute address in the disk drive's main address space. The first two bytes of the file indicate the 16-bit loading address (least significant byte first), and the remaining bytes contain the file data.
`-dmlo address file.bin`
  Load a binary file (not containing a starting address) to the specified address in the disk drive's main address space.
`-dmlr address file.prg`
  Load a program, relocated to the specified address in the disk drive's main address space.
`-dms address1 address2 file.prg`
  Save the memory bytes from `address1` up to but excluding `address2` in the disk drive's main address space to a program file. Write `address1` to the first two bytes of the file.
`-dmso address1 address2 file.bin`
  Save the memory bytes from `address1` up to but excluding `address2` in the disk drive's main address space to a binary file.

### 2.4 Quick 1541 disk operations

The built-in firmware of Commodore disk drives is not particularly fast. Therefore, `cbmlink` implements some options that speed up operations on probably the most common Commodore disk drive, the 1541.

`-qf name,id`
  Format a 1541 disk in 24 seconds with verify. The code works also on the 1571 in 1541 mode (switch with `-dc U0>M0`), but it crashes if the drive is in the 1571 mode.
`-qr file`
  Make a verbatim copy of a 1541 disk to the specified local file. The interleave factor is adjusted dynamically; the drive reads the sectors as it encounters them.
`-qw`[`,interleave`]`file`
  Copy a local file to 1541 disk sectors, starting from track 1. The interleave factor may dramatically affect the copying speed.

## 3 Hardware

The `cbmlink` utility requires either the C2N232 device, a null modem serial cable or a special cable that is connected to the parallel port of an Amiga or an IBM PC compatible (also known as the printer port or the Centronics port). The other end of the cable must be connected to the Commodore user port or to the Commodore serial bus.

The PC64 cable is the cable used by the no longer developed Personal C64 emulator written by Wolfgang Lorenz. It uses 4 independent data lines for both directions. If you are using or are planning to use this emulator, then you are best off using this cable.

The prlink cable allows 8-bit data transfers from the IBM PC compatible to the Commodore side, and 4 bits to the opposite direction. It uses four bidirectional lines on the IBM PC compatible. Beware that these lines are no longer bidirectional on some newer enhanced parallel ports. Be prepared to build the PC64 cable if this cable does not work.

The software also supports the X1541 cable designed for connecting a Commodore disk drive to your IBM PC compatible. The transfer is slow, 1 bit at a time. As the X1541 cable uses the serial bus for the transfers, the transfer daemon might get confused by any disk activities. This means that you cannot copy files or disks via this cable.

On the Amiga, there are three parallel cables: the native 8-bit cable that works with most protocols supported by the Amiga version, and two different cables for the serial bus connection. Also, if you have built the cable for the TransNib software, `cbmlink` will work with it, although slower than with the prlink88 cable.

### 3.1 Cable pin-outs

Note that we disclaim any warranties, so you are using these instructions at your own risk. Do not insert the plug to the user port the wrong way around, or you'll blow your printer port on the IBM PC compatible with the 9-volt signal as Marko did.

Note that the lower user port connections are named ABCDEFHJKMMN, skipping G and I.

On the Amiga 1000, pin 25 is not GND so Olaf picked 22 instead which should be GND on all Amiga models. On IBM PC compatibles, all pins from 18 to 25 should be GND.

#### 3.1.1 The null modem cable (`serial`)

A 6551 ACIA based RS-232C connection is supported on the following Commodore computers:

- PET-II or B series: CBM 500, 600 or 700 series or the P500
- Commodore plus/4 (with a voltage converter, such as the Commodore VIC-1011A with its case removed)
- Commodore 64 and 128 (with the 6551 wired to `$de00` a.k.a. I/O1 using IRQ instead of NMI; the Swiftlink uses NMI by default)

As the protocol makes no use of handshaking, three wires should be enough: TxD, RxD and ground. However, the transmitter of the 6551 will be disabled unless it is provided with a valid CTS signal.

In a null modem cable, the signals are crossed over: TxD on one end is connected to RxD on the other end and vice versa, CTS to RTS, and DSR to DTR.

For reference, the connections for the 25-pin and 9-pin RS-232 connectors are described below:

Acronym | In/Out | DE-9 | DB-25
--- | --- | --- | ---
TxD | output | 3 | 2
RxD | input | 2 | 3
RTS | output | 7 | 4
CTS | input | 8 | 5
DSR | input | 6 | 6
DTR | output | 4 | 20
DCD | input | 1 | 8
RI | input | 9 | 22
SG | ground | 5 | 7

The default data rate is 19,200 bits per second, corresponding to the top speed of the 6551 clocked with the default 1.8432 MHz crystal. Other data rates can be specified by prefixing the device name with the desired data rate: `-c serial 9600,/dev/ttyS0` instead of `-c serial /dev/ttyS0`. On the Amiga, any rate between 112 and 292,000 bits per second may be specified: `-c serial 9600,serial.device`. On Microsoft Windows, any rate accepted by `SetCommState` can be specified: `-c serial 115200,com1`. On POSIX® compliant systems, only standard data rates between 300 and 38,400 bits per second are available.

#### 3.1.2 The PC64 cable (`pc64`)

IBM PC | Pins | Commodore | Comment
--- | --- | --- | ---
GND | 25---A | GND | Ground
D7 | 9-->B | FLAG | Handshake signal
ERROR | 15<--C | PB0 | Data from Commodore to IBM PC
SEL | 13<--D | PB1 | "
PE | 12<--E | PB2 | "
ACK | 10<--F | PB3 | "
D0 | 2-->H | PB4 | Data from IBM PC to Commodore
D1 | 3-->J | PB5 | "
D2 | 4-->K | PB6 | "
D3 | 5-->L | PB7 | "
BUSY | 11<--M | PA2 | Handshake signal

#### 3.1.3 The prlink cable (`prlink` a.k.a. `prlink48`)

IBM PC | Pins | Commodore | Comment
--- | --- | --- | ---
GND | 25---A | GND | Ground
D3 | 5-->B | FLAG | Handshake signal
STROBE | 1<->C | PB0 | Bidirectional data lines
AUTO | 14<->D | PB1 | "
INIT | 16<->E | PB2 | "
SELECT | 17<->F | PB3 | "
D4 | 6-->H | PB4 | Data from IBM PC to Commodore
D5 | 7-->J | PB5 | "
D6 | 8-->K | PB6 | "
D7 | 9-->L | PB7 | "
BUSY | 11<--M | PA2 | Handshake signal

#### 3.1.4 The Amiga cable (`prlink88`, `prlink48`, `transnib`)

Amiga | Pins | C= | Comment
--- | --- | --- | ---
GND | 22---A | GND | Ground
POUT | 12-->B | CA1 | Handshake signal (strobe/flag)
D0 | 2<->C | PA0 | Bidirectional data lines
D1 | 3<->D | PA1 | "
D2 | 4<->E | PA2 | "
D3 | 5<->F | PA3 | "
D4 | 6<->H | PA4 | Data from Amiga to PET
D5 | 7<->J | PA5 | "
D6 | 8<->K | PA6 | "
D7 | 9<->L | PA7 | "
BUSY | 11<--M | CB2 | Handshake signal (ack)

On the PET, Olaf chose to use CB2 even though that pin is normally connected to a speaker. He did this because it makes the cable identical to the 64 and VIC cable, and allows you to use a single-sided connector. Make sure though that it does not connect the top and bottom fingers! Also you can hear nicely when the transfer is going on.

The Amiga cable allows for two protocols: the prlink compatible 4-bit/8-bit transfer, and a full 8-bit transfer, the option prlink88. In addition, the Amiga software supports a third protocol, the one for the TransNib cable. TransNib is an older transfer system for the Amiga and the Commodore 64. Its cable has only 6 Centronics data bits connected:

D0-3<->PA0-3
  data in/out
D6<--PA6
  handshake in (from C= to Amiga)
D7-->PA7
  handshake out (from Amiga to C=)

The Amiga cable is downward compatible with the TransNib cable, so you can use it with the TransNib cable protocol, but of course it is slower.

If you need to make a cable there is no reason not to make the full prlink88 cable; The transnib protocol is provided for people who already have a cable for TransNib V1.00 devised by Matt Francis.

#### 3.1.5 The serial bus cable for IBM PC compatibles (`x1541`)

IBM PC | Pins | Commodore serial bus | Comment
--- | --- | --- | ---
GND | 22---2 | GND | Ground
STROBE | 1-->3 | ATN | not used
AUTOFD | 14<->4 | CLK | Bidirectional data/handshake line
SELECT | 17<--5 | DATA | Bidirectional data/handshake line

As you may note, not all lines of the original X1541 cable are required. The loop from D0 (pin 2) to ERROR (pin 15) is missing, as well as the connection from INIT (pin 16) to RESET (pin 6). The ATN line is not required either, but it is required by other transfer programs that use this cable. `cbmlink` will work with these additions installed, so you don't need to modify your existing X1541 cable.

#### 3.1.6 The serial bus cables for the Amiga (`em1541`, `emul1541`)

The description below is, slightly modified, taken from the Frodo documentation. The exact cable as used by Frodo (see `Aminet:misc/emu/Frodo*`), however, is also usable by `cbmlink`. Even though it wires the ATN line as an output, we can use the cable since we don't use the ATN line. You can also use the cable used by Emul_1541 (see `Aminet:misc/emu/Emul1541v11.*`). There is even a third variant of this sort of cable which differs by having no inverters or pull-ups at all. This is in fact the sort of cable that Olaf tested.

If you are building a cable and won't need to use it for any of these other programs, you can safely leave out the connections to the ATN line.

The cable with inverters, as shown below, is called `emul1541`. The cable without inverters is called `em1541`.

Building a serial bus cable is fairly simple, it connects the parallel port of the Amiga with the round 6-pin connector on Commodore devices.

     Parallel port                  Serial bus connector
        Amiga                               1541
     DSUB, 25-pin                        DIN, 6-pin

      Pin  Name                           Name  Pin
       14  +5V ------------*--*--+
                           |  |  |
                  7406    |¯||¯||¯|
                (74LS05)  | || || | 1k each
                          |_||_||_|
                  2 /|1    |  |  |
        5  PB3 ----O |-----*--+--+------- ATN    3
                    \|        |  |
                              |  |
                  3|\ 4       |  |
        6  PB4 ----| O--*-----*--+------- CLK    4
                   |/   |        |
                        |        |
                  5|\ 6 |        |
        7  PB5 ----| O--+-*------*------- DATA   5
                   |/   | |
                        | |
        8  PB6 ---------+ |
                          |
        9  PB7 -----------+

       22  GND -------------------------- GND    2

The 7406 (a 74LS05 will do as well) must be connected to +5V and GND of course. The trained technician will notice that this is the same circuit found inside the real Commodore 64 (except that the inverter on ATN is inverted so ATN can be used for output).

Important note: If you plan to build and connect such a cable, please remember that you do it on your own risk. Olaf will not take any responsibility if there is blue smoke coming out from the back of your computer!

#### 3.1.7 The Kontros cable (`kontros`)

The alert reader may have noticed from the source code that `cbmlink` supports yet another cable, a buffered parallel cable designed by Frank Kontros. As Frank was working on yet better solutions (involving automatic handshaking), he requested Marko not to publish the schematic diagram of this cable. The interface works with VIC-20 (with a small modification), Commodore 64 and Commodore 128. E-mail Frank if you are interested in his super-fast interface and software (for MS-DOS).

#### 3.1.8 The 64NET cable (`c64net`)

The 64NET cable pin-out won't be listed, as the 64NET documentation claims that it is copyrighted. (It is a bogus claim, since copyright does not cover ideas, but only the expression of them.) Besides, other cables allow more efficient protocols.

### 3.2 Transfer trouble

If the transfer hangs, you can stop the server on the Commodore side with STOP & Restore. The client can be stopped with normal means, i.e. `Ctrl-D` on the Amiga, `Ctrl-C` on Unix-like systems, or `Ctrl-Break` on MS-DOS.

#### 3.2.1 The CIA FLAG signal

For some reason Olaf had weird problems with his 64 when using the prlink88 protocol. He might be the only one suffering from this, but if you too get hung transfers when transferring from the 64 to the Amiga, try to run the transnib protocol. It is slower but generally causes less hung transfers.

To get more technical: When the data lines are changed by the 64, the handshake line from the 64 sometimes starts bouncing, causing the Amiga side to get so confused that the computers get too much out of synchronisation. Olaf doesn't know if it's a problem with his cable (perhaps it is a bit long), his 64, or his Amiga, or any of those in general.

Because of this, we have included bounce detection for the `prlink48` and `prlink88` cables in the following cases:

Amiga
  The bounce on the handshake line to the Amiga (BUSY) happens with both Olaf's PET and 64, but more with the 64. When reading its state, we require its readout to be stable for 3 consecutive accesses. Since the CIAs in the Amiga run at 714 kHz, an access takes about 1.4 µs.
C64 and C128
  The edge-sensitive handshake line to the 64 (FLAG) is apparently rather sensitive. When a false trigger occurs this fact is latched in the interrupt bit. By reading (and thereby clearing) the Interrupt Flag Register at the latest possible moment before the next handshake could come in, phantom handshakes caused by bounce seem to be significantly reduced.

If you wish to turn off the bounce detection, you can do this by changing some flags. For the 6502 side, edit the file `c64common.s` and change the definition of `ciadebounce` to 0. For the Amiga side, change `DEBOUNCE` in `prlink48.c` and `prlink88.c` to 0. Next you need to recompile and test if the transfer still works correctly.

#### 3.2.2 Problems with the C2N232

There may be some random problems with the C2N232 device on some platforms. It works most reliably on the VIC-20 and the PET. Detailed problem reports, measurement reports and patches are welcome.

File and disk transfers do not work at all on the 264 series via the C2N232, because the write line of the cassette port is shared with the clock line of the serial bus.

File and disk transfers work unreliably on the Commodore 64 and almost not at all on the Commodore 128 via the C2N232, probably due to the KERNAL interfering with the tape interface, either by reading `$dc0d` (clearing the status of the read line) or by changing the write line. Burst mode transfers are unlikely to work on these computers, because the cassette read line is shared with the serial bus SRQ line.

#### 3.2.3 RS-232 Transfers

The 6551 based serial servers tend to lose the command character if several disk or file transfer commands are invoked in a sequence. In order to avoid hanging the client on the big computer, do not specify more than one file or disk copying option on the command line when using `-c serial`.

If the transfer does not work at all, please check the following:

- Is the 6551 provided with an active CTS signal? If not, it will refuse to transmit anything.
- If you are using a 6551 cartridge, is the IRQ output of the 6551 connected to the IRQ input of the computer? A connection to NMI will not work.

## 4 Compiling

### 4.1 The `cbmlink` executable

Generally, in order to compile `cbmlink`, you need GNU Make, GNU Compiler Collection and related tools. On UNIX systems, you should be able to use the native `cc`. If not, install `gcc`.

The 32-bit console-mode executable for Microsoft Windows is best generated with gcc targeted for Minimalist GNU for Windows, running either on Linux or Windows.

The MS-DOS executable can be generated with Bruce Evans' C compiler `bcc`, packaged by Robert de Bath as Dev86.

The software supports several different cables. The cable-specific transfer routines are in the `comm` subdirectory.

The extensions for copying files and disks are located in the `ext` subdirectory. The 6502 source code for the extensions is in `ext/asm`; they can be compiled with the Bourne shell script `ext/asm/cgen.sh`.

In principle, compiling is as easy as typing

1. `cd src`
2. `make -f Makefile.platform`
3. `make install`

In practice, it may be a bit more complicated. If `make -f Makefile.unixpc` fails, try removing `-DUSE_PPDEV` from `DEFINES` to disable the use of the parallel port device. Then, the resulting `cbmlink` program must be run with the super-user privileges (`chown root cbmlink; chmod u+s cbmlink`) to access the parallel port.

### 4.2 The Commodore servers

If you like to modify or to recompile the Commodore binaries, you need to retrieve XA from ftp.funet.fi as /pub/cbm/programming/unix/xa-2.1.4h.tar.gz. The assembler is also available as the xa65 package of Debian GNU/Linux.

The source code for the Commodore server programs is available from ftp.funet.fi in a separate package, /pub/cbm/crossplatform/transfer/C2N232/cbmlink-cbmsrc.tar.gz. Precompiled executables are available as cbmlink-cbmbasic.zip at the same place. There are also precompiled versions that lack the relocator, in cbmlink-cbmprg.zip.

There are three major variations for the Commodore servers, reflected by the include file subdirectories:

cable type (`cable`)
  name of the supported transfer cable: c2n232, serial, pc64, prlink48, prlink88, transnib, kontros, c64net, x1541
computer type (`host`)
  name of the computer:
  pet3001
    Commodore PET 3000 series with BASIC 2.0
  pet4001
    Commodore PET or CBM 4000, 8000 or 200 series with BASIC 4.0
  vic20
    Commodore VIC-20, VC-20 or VIC-1001
  c64
    Commodore 64, 4064, SX-64, 64c or 64G
  c128
    Commodore 128, 128D, 128CR or 128DCR
  c264
    Commodore 264 series: 16, 116, plus/4, 232 or V364
  p500
    Commodore 510 or P500
  b128
    Commodore 610, 710 or B-128
  b256
    Commodore 620, 720 or B-256
memory expansion or other variation (`mem`)
  `plain`
    The basic configuration.
  `pia` (c64, c128)
    Support for the internal PIA-controlled memory expansion. The PIA base address is set in `piabase.s`.
  `reu` (c64, c128)
    Support for the Commodore RAM Expansion Unit
  `piareu` (c64, c128)
    Support for both the internal PIA-controlled expansion and an external Commodore RAM Expansion Unit
  `cart` (vic20)
    The server is built at $a000 with the `a0CBM` auto-start signature. The server is installed automatically on reset. This configuration cannot be used for loading cartridge games.
  `port2` (pet3001, pet4001)
    Use cassette port 2 for the c2n232 device.

In the distribution of precompiled executables, there is a subdirectory for each supported protocol. Each protocol subdirectory contains a subdirectory for each supported computer type, which in turn contain programs for each supported variation.

#### 4.2.1 Using the REU with an Action Replay

The Action Replay cartridge by Datel occupies all of the address space at $de00-$dfff. Nevertheless, it is possible to use a Commodore REU simultaneously with an Action Replay cartridge, if the REU registers are modified to be write-only:

               /o------+
    I/O2 ----o/        |
    (from C64)  o->|---+--- I/O2 (to REU)
                       |
    R/W  --------->|---+
               1N4148  |
               diodes  <
                       > 4k7
                       < resistor
                       >
                       |
                     --+--

When the switch is in its upper position, the REU will operate as previously, i.e. it won't work with the Action Replay cartridge. When it is in the lower position, the Action Replay cartridge will work, but you will most probably have problems with any software that uses the REU (except `cbmlink`). Thus, whenever you want to use anything that supports the REU, you must disable the Action Replay cartridge and then move the switch to the upper position.

To allow `cbmlink` to access the REU when its registers are write-only, set `actionreuplay=1` in `reubase.s`.

If you also modify Action Replay so that its I/O2 gets disabled when R/W is low, you won't need the actionreuplay option. But this modification cannot be implemented with diodes and resistors. Instead, you would need an IC (quad NAND or something), which may be difficult to fit in the Action Replay case.

## 5 Credits

The ancestor of `cbmlink`, `prlink`, was originally programmed for GNU/Linux and C64/C128/VIC-20 by Marko Mäkelä. Olaf Seibert joined the project and ported `prlink` to Amiga and the PET 3000 and 4000/8000 series. Since then, Marko has ported the code to numerous other platforms, and improved the program structure greatly.

Marko would like to express his thanks to all transfer program writers and everyone who has shown interest towards `prlink` or `cbmlink` or offered help, mostly by supplying either documentation or hardware.

Nicolas Welte and Edward Shockley helped me to debug the null modem serial cable connection.

Special thanks go to Daniel Kahlin and Andreas pitch Andersson for contributing fast 1541 disk routines.

## 6 Known bugs and future plans

Contributions are welcome, as Marko is busy with many things.

1. The support for Commodore PET 3000 series may be faulty. Test reports are welcome.
2. The file and disk copying protocols (section 2.3) may hang when a disk error occurs. The protocols should be formally modelled and verified by state space exploration.
3. Quick 1541 disk operations (section 2.4)
   - The `-qf` option does not work on a 1571 unless it is in 1541 mode. The modes should be changed automatically.
   - The `-qr` and `-qw` options do not work at all. It may be necessary to rewrite the communication protocol.
   - The drive type is not detected to avoid problems with non-1541 drives. (It could be detected by issuing the `UI` command and reading the status channel).
4. The `-dmc` option (Section 2.3.4) may make drives behave strangely.
5. It could be useful to integrate a modified version of the Gunzip.c64 decompression program to `cbmlink` in order to speed up the copying of 1541, 1571 or 1581 disk images.
6. Implement support for IDE64 and other third-party mass storage products.
7. Integrate `cbmconvert` into `cbmlink`.

## 7 Distribution

The primary distribution site of `cbmlink` is http://www.funet.fi/pub/cbm/crossplatform/transfer/C2N232/.

Precompiled binaries are available for other than Unix-like platforms. Currently these include Commodore Amiga OS, MS-DOS (8086) and 32-bit versions of Microsoft Windows (95 and later).