File: cbmlink.html

package info (click to toggle)
cbmlink 0.9.6-1
links: PTS
area: main
in suites: sarge
size: 856 kB
ctags: 1,304
sloc: ansic: 5,849; asm: 2,904; makefile: 188; sh: 60
file content (1949 lines) | stat: -rw-r--r-- 81,706 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en" dir="ltr">
<head>
<title>cbmlink release notes</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rev="made" href="mailto:msmakela@nic.funet.fi">
<style type="text/css">
body {
 color: black;
 background: white;
 font-family: helvetica, sans-serif;
}
h1 { text-align: center; }
h2, h3, h4 { text-align: left; }
A:link, A:visited, A:active, A:hover {
 display: inline;
 color: red;
 font-weight: normal;
}
A:link, A:visited { text-decoration: none; }
A:hover, A:active { text-decoration: underline; }
A:link.ext, A:visited.ext, A:active.ext, A:hover.ext {
 color: blue;
 text-decoration: underline;
}
td, th { text-align: left; }
td.c { text-align: center; }
address { text-align: right; }
.bar { text-decoration: overline; }
</style>
</head>

<body>
<h1><code>cbmlink</code> release notes</h1>

<dl>
 <dt><code>cbmlink</code> 0.9.6</dt>
 <dd>a data transfer system between Commodore 8-bit computers and
 other systems (Amiga, <acronym
 title="International Business Machines">IBM</acronym>
 <acronym title="Personal Computer">PC</acronym> compatible, Apple, Unix
 workstations)</dd>
</dl>

<h2>Copyright information</h2>

<p>The <code>cbmlink</code> utility is based on <code>prlink</code>,
which was developed from 1994 to 1998 by Marko Mkel and Olaf Seibert.
The first version of <code>cbmlink</code> was developed by Marko
Mkel in 2001&ndash;2002.</p>

<blockquote><p>This program is free software; you can redistribute it
and/or modify it under the terms of the <acronym
title="GNU's Not Unix">GNU</acronym> General Public License as
published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version.</p>

<p>This program is distributed in the hope that it will be useful, but
<strong>without any warranty</strong>; without even the implied
warranty of <strong>merchantability</strong> or <strong>fitness for a
particular purpose</strong>.  See the <a class="ext"
href="http://www.fsf.org/copyleft/gpl.html"><acronym
title="GNU's Not Unix">GNU</acronym> General Public License</a> for
more details.</p></blockquote>

<p>The 1541 quick format option is based on the work of <a
href="mailto:daniel@kahlin.net">Daniel Kahlin</a>.  The original
copyright message follows:</p>

<blockquote><p>Copyright  1995, 1996, 2002, Daniel Kahlin.
All rights reserved.</p>

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

<ol>
 <li>Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.</li>
 <li>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.</li>
 <li>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.</li>
</ol>
</blockquote>

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

<blockquote><p>Copyright  Andreas <q>pitch</q> Andersson
1995&ndash;2002.</p>

<p>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:</p>

<ol>
 <li>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.</li>
 <li>Altered source versions must be plainly marked as such, and must
 not be misrepresented as being the original software.</li>
 <li>This notice may not be removed or altered from any source
 distribution.</li>
</ol>
</blockquote>

<h2>Table of Contents</h2>

<dl>
 <dd><a name="toc-pref" href="#pref">0</a>
 Preface</dd>
 <dd><a name="toc-start" href="#start">1</a>
 Getting started
 <dl>
  <dd><a name="toc-start-boot" href="#start-boot">1.1</a>
  Bootstrapping
  <dl>
   <dd><a name="toc-start-boot-c2n232" href="#start-boot-c2n232">1.1.1</a>
   The C2N232 connection</dd>
   <dd><a name="toc-start-boot-serial" href="#start-boot-serial">1.1.2</a>
   Null modem cable</dd>
   <dd><a name="toc-start-boot-par" href="#start-boot-par">1.1.3</a>
   Parallel cables</dd>
  </dl></dd>
  <dd><a name="toc-start-usage" href="#start-usage">1.2</a>
  Usage</dd>
  <dd><a name="toc-start-auto" href="#start-auto">1.3</a>
  Automatic startup on the Commodore128</dd>
 </dl></dd>
 <dd><a name="toc-func" href="#func">2</a>
 Functions
 <dl>
  <dd><a name="toc-func-mem" href="#func-mem">2.1</a>
  Memory transfers
  <dl>
   <dd><a name="toc-func-mem-load" href="#func-mem-load">2.1.1</a>
   Loading a file to memory</dd>
   <dd><a name="toc-func-mem-save" href="#func-mem-save">2.1.2</a>
   Saving memory to a file</dd>
  </dl></dd>
  <dd><a name="toc-func-invoke" href="#func-invoke">2.2</a>
  Remote Program Invocation
  <dl>
   <dd><a name="toc-func-invoke-basic" href="#func-invoke-basic">2.2.1</a>
   Starting a <acronym
   title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
   program</dd>
   <dd><a name="toc-func-invoke-mach" href="#func-invoke-mach">2.2.2</a>
   Starting a machine language program</dd>
   <dd><a name="toc-func-invoke-cart" href="#func-invoke-cart">2.2.3</a>
   Starting a VIC-20 cartridge</dd>
   <dd><a name="toc-func-invoke-music" href="#func-invoke-music">2.2.4</a>
   Playing Commodore64 music tunes</dd>
   <dd><a name="toc-func-invoke-perf" href="#func-invoke-perf">2.2.5</a>
   Performance measurements</dd>
  </dl></dd>
  <dd><a name="toc-func-copy" href="#func-copy">2.3</a>
  File and disk transfer
  <dl>
   <dd><a name="toc-func-copy-fr" href="#func-copy-fr">2.3.1</a>
   Reading Commodore files</dd>
   <dd><a name="toc-func-copy-fw" href="#func-copy-fw">2.3.2</a>
   Writing Commodore files</dd>
   <dd><a name="toc-func-copy-disk" href="#func-copy-disk">2.3.3</a>
   Disk transfer</dd>
   <dd><a name="toc-func-copy-dmem" href="#func-copy-dmem">2.3.4</a>
   Disk memory transfer</dd>
  </dl></dd>
  <dd><a name="toc-func-quick" href="#func-quick">2.4</a>
  Quick 1541 disk operations</dd>
 </dl></dd>
 <dd><a name="toc-hw" href="#hw">3</a>
 Hardware
 <dl>
  <dd><a name="toc-hw-conn" href="#hw-conn">3.1</a>
  Cable pin-outs
  <dl>
   <dd><a name="toc-hw-conn-serial" href="#hw-conn-serial">3.1.1</a>
   The null modem cable (<code>serial</code>)</dd>
   <dd><a name="toc-hw-conn-pc64" href="#hw-conn-pc64">3.1.2</a>
   The <acronym title="Personal Commodore64 emulator">PC64</acronym> cable
   (<code>pc64</code>)</dd>
   <dd><a name="toc-hw-conn-prlink" href="#hw-conn-prlink">3.1.3</a>
   The prlink cable (<code>prlink</code> a.k.a. <code>prlink48</code>)</dd>
   <dd><a name="toc-hw-conn-amiga" href="#hw-conn-amiga">3.1.4</a>
   The Amiga cable (<code>prlink88</code>, <code>prlink48</code>,
   <code>transnib</code>)</dd>
   <dd><a name="toc-hw-conn-x1541" href="#hw-conn-x1541">3.1.5</a>
   The serial bus cable for <acronym title="International Business Machines"
   >IBM</acronym> <acronym title="Personal Computer">PC</acronym> compatibles
   (<code>x1541</code>)</dd>
   <dd><a name="toc-hw-conn-amiec" href="#hw-conn-amiec">3.1.6</a>
   The serial bus cables for the Amiga (<code>em1541</code>,
   <code>emul1541</code>)</dd>
   <dd><a name="toc-hw-conn-kontros" href="#hw-conn-kontros">3.1.7</a>
   The Kontros cable (<code>kontros</code>)</dd>
   <dd><a name="toc-hw-conn-64net" href="#hw-conn-64net">3.1.8</a>
   The 64NET cable (<code>c64net</code>)</dd>
  </dl></dd>
  <dd><a name="toc-hw-prob" href="#hw-prob">3.2</a>
  Transfer trouble</dd>
 </dl></dd>
 <dd><a name="toc-comp" href="#comp">4</a>
 Compiling
 <dl>
  <dd><a name="toc-comp-src" href="#comp-src">4.1</a>
  The <code>cbmlink</code> executable</dd>
  <dd><a name="toc-comp-cbmsrc" href="#comp-cbmsrc">4.2</a>
  The Commodore servers</dd>
  <dd><a name="toc-comp-cbmsrc-start" href="#comp-cbmsrc-start">4.2.1</a>
  Changing the start address</dd>
  <dd><a name="toc-comp-cbmsrc-reuplay"
  href="#comp-cbmsrc-reuplay">4.2.2</a> Using the <acronym
  title="RAM Expansion Unit">REU</acronym> with an Action Replay</dd>
 </dl></dd>
 <dd><a name="toc-credit" href="#credit">5</a>
 Credits</dd>
 <dd><a name="toc-plans" href="#plans">6</a>
 Known bugs and future plans</dd>
 <dd><a name="toc-dist" href="#dist">7</a>
 Distribution</dd>
</dl>

<h2><a name="pref" href="#toc-pref">0</a>
Preface</h2>

<p>This document describes the <code>cbmlink</code> utility, a program
package that lets you to transfer data over a parallel connection or
an <acronym title="Recommended Standard">RS</acronym>-232 connection
between a Commodore 8-bit computer and a bigger system (Amiga,
<acronym title="International Business Machines">IBM</acronym>
<acronym title="Personal Computer">PC</acronym> compatibles, Apple,
Unix workstation).</p>

<p>The utility is based on a daemon, or a memory resident <acronym
title="Interrupt ReQuest">IRQ</acronym> 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.</p>

<p>Currently daemons are available for the following Commodore systems:</p>
<ul>
 <li><acronym title="Personal Electronic Transactor">PET</acronym>
 series: 3000 series (may not work), 4000/8000/200 series [no support
 yet for the 2000 series (<acronym
 title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
 1.0)]</li>
 <li><acronym title="Personal Electronic Transactor">PET</acronym>-II
 series: <acronym title="Commodore Business Machines">CBM</acronym>
 510, 610, 620, 710 and 720 (P500 or the B series) [not very well
 tested]</li>
 <li>Commodore VC-20, VIC-20 or VIC-1001</li>
 <li>Commodore 64, 4064, SX-64, 64c or 64G</li>
 <li>Commodore 128, 128<acronym title="desktop">D</acronym> or 128<acronym
 title="desktop, cost reduced">DCR</acronym></li>
 <li>Commodore 264 series: 16, 116, plus/4 or 232</li>
</ul>

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

<p>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 <acronym
title="GNU's Not Unix">GNU</acronym>/<abbr
title="Linus' Minix">Linux</abbr>.  The are Intel 8086, 80286 and
80386 optimised transfer routines for parallel cables.  The software
should work at least on the following systems:</p>

<dl>
 <dt><acronym title="GNU's Not Unix">GNU</acronym>/<abbr
 title="Linus' Minix">Linux</abbr></dt>
 <dd>This is the main development platform.  Also <acronym
 title="International Business Machines">IBM</acronym> <acronym
 title="Personal Computer">PC</acronym> compatible parallel ports are
 supported.</dd>

 <dt>Apple Mac<acronym title="Operating System">OS</acronym>X</dt>
 <dd>The code can be compiled in Mac<acronym
 title="Operating System">OS</acronym>X.  It is possible to use <acronym
 title="Recommended Standard">RS</acronym>-232 via a <acronym
 title="Universal Serial Bus">USB</acronym> adapter.</dd>

 <dt>Other UNIX-like systems</dt>
 <dd>The code should compile on all <acronym
 title="Portable Operating System Interface">POSIX</acronym>
 compliant systems.  Only the <acronym
 title="Recommended Standard">RS</acronym>-232 connection is
 supported.  We have successfully tested it on an old <acronym
 title="International Business Machines">IBM</acronym> workstation
 running <acronym title="Advanced Interactive eXecutive">AIX</acronym>.
 The serial line driver in Solaris 5.7 turned out to be buggy.  We had
 technical problems trying to set up an Silicon Graphics workstation
 as well as an <acronym
 title="Hewlett&ndash;Packard">HP</acronym>-<acronym
 title="Unix">UX</acronym> workstation for testing.</dd>

 <dt>32-bit versions of Microsoft Windows (95 and later)</dt>
 <dd>The parallel cables do not work in NT, 2000 and XP without
 special tricks.  The <acronym title="Recommended Standard">RS</acronym>-232
 connection should work on all versions.</dd>

 <dt>Older Apple computers</dt>
 <dd>The <acronym title="Recommended Standard">RS</acronym>-422 port
 of older Apple systems can be converted to <acronym
 title="Recommended Standard">RS</acronym>-232 with a simple cable.
 The <acronym title="Recommended Standard">RS</acronym>-232 code needs
 some modifications; other cables cannot be supported easily by Apple
 hardware.  Are there any volunteers for porting the code?</dd>

 <dt>CommodoreAmiga</dt>
 <dd>The code can be compiled with <code>gcc-2.95.3</code>,
 <a href="http://www.lysator.liu.se/~lcs/files/gg-cross/">packaged</a>
 by <a href="mailto:martin@blom.org">Martin Blom</a>.  Due to copyright
 reasons, the AmigaOS header files are not distributed with the compiler.
 Probably the easiest way of obtaining the headers is downloading the <a
 href="http://www.amiga.com/3.9/download/NDK3.9.lha">Native Developer
 Kit 3.9</a>.</dd>

 <dt><acronym title="Microsoft">MS</acronym>-<acronym
 title="Disk Operating System">DOS</acronym> and its clones</dt>
 <dd>No support for <acronym title="Recommended Standard">RS</acronym>-232
 has been implemented yet (any volunteers?), but the parallel cables do
 work.</dd>
</dl>

<p>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 <acronym
title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
program.  The latter two commands deinstall the daemon for maximum
compatibility.</p>

<p>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 Commodore128, you can use a boot sector, so that the daemon
will be loaded and started automatically when you start the computer.
On the CommodoreVIC-20, the daemon can make use of the cartridge
auto-start signature.</p>

<h2><a name="start" href="#toc-start">1</a>
Getting started</h2>

<p>Until a binary distribution for your platform is available, you
will have to compile the source code for your system, as described
in <a href="#comp-src">Section 4.1</a>.</p>

<p>Patches and precompiled binaries are welcome.</p>

<p>For your convenience, we have composed the archive
<code>cbmlink-cbm.zip</code> of precompiled Commodore binaries.  The
<code>cbmprg</code> and <code>cbmc2n</code> subdirectories of this
archive are described in <a href="#comp-cbmsrc">Section 4.2</a>.</p>

<h3><a name="start-boot" href="#toc-start-boot">1.1</a>
Bootstrapping</h3>

<h4><a name="start-boot-c2n232" href="#toc-start-boot-c2n232">1.1.1</a>
The <a name="cable-c2n232">C2N232</a> connection</h4>

<p>The <a class="ext"
href="http://www.funet.fi/pub/cbm/crossplatform/transfer/C2N232/FAQ.html">C2N232</a>
is a small <acronym title="Recommended Standard">RS</acronym>-232 interface
that can be plugged to the cassette port of an 8-bit Commodore computer:</p>

<ul>
 <li><acronym title="Personal Electronic Transactor">PET</acronym>
 series: 2001, 3000 series, 4000 series, 8000 series, 200 series</li>
 <li><acronym title="Personal Electronic Transactor">PET</acronym>-II
 series: <acronym title="Commodore Business Machines">CBM</acronym>
 500, 600 or 700 series (P500 or the B series)</li>
 <li>Commodore VC-20, VIC-20 or VIC-1001</li>
 <li>Commodore 64, 4064, 64c or 64G</li>
 <li>Commodore 128, 128<acronym title="desktop">D</acronym> or 128<acronym
 title="desktop, cost reduced">DCR</acronym></li>
 <li>Commodore 264 series: 16, 116, plus/4 or 232</li>
</ul>

<p>The <acronym title="Recommended Standard">RS</acronym>-232 end of the
interface can be connected to any computer for which the following
are available:</p>

<ul>
 <li>an <acronym title="Recommended Standard">RS</acronym>-232
 interface at 38,400 bits per second, with <abbr
 title="transmitter on, Control-Q">XON</abbr>/<abbr
 title="transmitter off, Control-S">XOFF</abbr> or <acronym
 title="Ready To Send">RTS</acronym>/<acronym
 title="Clear To Send">CTS</acronym> handshaking</li>
 <li>an operating system that supports the <acronym
 title="Recommended Standard">RS</acronym>-232 interface</li>
 <li>a C compiler that supports the operating system</li>
</ul>

<p>The device consists of two integrated circuits: a micro-controller
and an <acronym title="Recommended Standard">RS</acronym>-232 line
driver.  There are two connectors in the C2N232.  The card edge
connector plugs into the Commodore cassette port, and the <abbr
title="9-pin female D-shaped connector">DE-9S</abbr> connector plugs
to a serial port with an <acronym
title="International Business Machines">IBM</acronym> <acronym
title="Personal Computer/Advanced Technology">PC/AT</acronym> style
pin-out.  Normally, you want to use an <acronym
title="Recommended Standard">RS</acronym>-232 extension cable that
connects at least pins 5 (ground), 2 (RxD) and 3 (TxD).  <em>A null
modem cable will not work!</em></p>

<p>The parts of the C2N232 cost something between 10 and 20&euro;,
which can be slightly more than the parts for a passive parallel
cable.  However, compared to passive cables, the C2N232 is</p>

<dl>
 <dt>universal:</dt>
 <dd>The C2N232 works in all 8-bit Commodores that have a cassette
 interface.</dd>
 <dt>based on widely supported standards:</dt>
 <dd><acronym title="Recommended Standard">RS</acronym>-232 is a
 <em lang="it">de facto</em> 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.</dd>
 <dt>electrically stable and safe:</dt>
 <dd><acronym title="Recommended Standard">RS</acronym>-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.</dd>
</dl>

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

<p>The driver program <code>c2n</code> transforms between the raw
Commodore cassette format, which consists of 192-byte blocks and
arbitrary-size program blocks, and these pulse streams.</p>

<p>The conversion utility <code>cbmconvert</code> supports the raw
Commodore cassette format.  In order to use the cassette drive
emulation to load a program via a C2N232 connected to the serial port
<code><var>/dev/ttyS0</var></code>, you can apply the following
steps:</p>

<ol>
 <li><code>cbmconvert -C <var>file</var>.c2n <var>file</var>.prg</code></li>
 <li><code>c2n -c <var>/dev/ttyS0</var> <var>file</var>.c2n</code></li>
</ol>

<p>Of course, it does not make sense to load long programs in this
way, since standard cassette loading is slow.  Rather, you can load
the appropriate <code>cbmlink</code> server in this way and then use
it for further transfers.</p>

<p>For your convenience, the <code>cbmlink</code> distribution
includes the C2N232 server programs in the Commodore cassette format.
To bootstrap the <code>cbmlink</code> server for the Commodore64, you
may type something like <code>c2n -vc <var>/dev/ttyS0</var>
cbmc2n/c64/plain.c2n</code>.</p>

<p>If the <code>c2n</code> 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 <kbd>NUL</kbd> character followed by <code>0</code>.
Try sending a <kbd>Ctrl-A</kbd>; the device should respond with
<code>1</code>.  If you now enter the <code>save</code> command on the
Commodore, the device should display a string of characters for
several seconds.</p>

<p>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 CommodoreVIC-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<acronym
title="Personal Electronic Transactor">PET</acronym>, the write line
is shared between the two cassette ports.</p>

<h4><a name="start-boot-serial" href="#toc-start-boot-serial">1.1.2</a>
Null modem cable</h4>

<p>If you already have a <a href="#cable-serial">null modem cable</a>,
you probably also have a terminal program that you can use for
transferring the <code>cbmlink</code> daemon to your Commodore.</p>

<h4><a name="start-boot-par" href="#toc-start-boot-par">1.1.3</a>
Parallel cables</h4>

<p>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 <a href="loader.txt">loader.txt</a>, there is a bare-bones <acronym
title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
implementation of the <code>cbmlink</code> 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.</p>

<p>On an <acronym title="International Business Machines">IBM</acronym>
<acronym title="Personal Computer">PC</acronym> compatible, the <a
href="#cable-pc64"><acronym
title="Personal Commodore64 emulator">PC64</acronym></a> cable is
recommended, because newer on-board enhanced bidirectional printer
interfaces may have problems with the <a
href="#cable-prlink">prlink</a> cable.  The <acronym
title="Personal Commodore64 emulator">PC64</acronym> cable is the
safest choice.  The <a href="#cable-x1541">X1541</a> and <a
href="#cable-c64net">64NET</a> cables are supported only for the sake
of completeness.</p>

<p>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 <a
href="#cable-transnib">transnib</a> protocol, which works over both
TransNib and prlink cables.  The most efficient protocol is <a
href="#cable-prlink88">prlink88</a>, which transfers 8 bits at a time
in both directions.</p>

<p>Start the bootstrapper program on your Commodore.  On the <q>big
computer</q>, execute the <code>cbmlink</code> program with the
desired protocol to transfer the desired daemon to the Commodore,
e.g.: <code>cbmlink -c pc64 0 -l cbmprg/pc64/c64/plain.prg</code>.</p>

<p>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 <acronym
title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
listing, so that it is adapted for your hardware.  Also, if you are
using an <acronym title="International Business Machines">IBM</acronym>
<acronym title="Personal Computer">PC</acronym> compatible, you may
have chosen the wrong printer port.  Try the <code>-c</code> parameter
with different device numbers (from 0 to 3) or <acronym
title="Input/Output">I/O</acronym> port addresses.  Also note that the
<abbr title="Linus' Minix">Linux</abbr> version requires super user
(root) privileges.  Remember to install the software as root, or use
<code>chown root</code> and <code>chmod u+s</code> on the
binaries.</p>

<p>If everything seems to run correctly, replace the
<code>print</code> statement on line 2050 with <code>poke</code>.  Now
the daemon will be really loaded to your computer.  Once the program
has been transferred, save it using your favourite method (an assembly
language monitor is usually easiest).  The addresses it occupies are
printed by the basic program.</p>

<p>Alternatively, if you have a disk drive, you can start the daemon
and use an appropriate command to copy the daemon to a Commodore
disk.</p>

<h3><a name="start-usage" href="#toc-start-usage">1.2</a>
Usage</h3>

<p>Start the 6502 side by issuing the command<br />
<code>SYS <var>[start address]</var></code><br />
where <var>[start address]</var> is the first byte of the program.</p>

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

<p>To make the 6502 side remove itself from the interrupt chain, issue
the command<br />
<code>SYS <var>[start address]</var> + 3</code>.</p>

<p>Note that the default VIC-20 version loads at 16384 ($4000).  This
means that you need at least 16kB of expansion memory to use the
program.  If you want to use <code>cbmlink</code> with an unexpanded
VIC, you have to recompile the executable, as explained in Section <a
href="#comp-cbmsrc">4.2</a>.</p>

<h3><a name="start-auto" href="#toc-start-auto">1.3</a>
Automatic startup on the Commodore128</h3>

<p>The Commodore128 tries to load a boot sector from device8 in its
startup routine.  With our special boot sector, it is possible to
start the server on the Commodore128 automatically.  It not only
starts the <code>cbmlink</code> server for the Commodore128; it can
also switch to Commodore64 mode and start the server there.</p>

<p>There are two variants of the boot sector:</p>

<dl>
 <dt><code>cbmutils/c128/bootsect.bin</code></dt>
 <dd>The standard boot sector.  No support for the <acronym
 title="Peripheral Interface Adapter">PIA</acronym> memory expansion.
 May load either <code>cbm128</code> or <code>cbm64</code>, depending on
 the selected mode.</dd>
 <dt><code>cbmutils/c128/bootsect-pia.bin</code></dt>
 <dd>A special boot sector with support for the <acronym
 title="Peripheral Interface Adapter">PIA</acronym> memory expansion.
 When told to load a server that does not support the <acronym
 title="Peripheral Interface Adapter">PIA</acronym> memory expansion,
 this boot sector disables the <acronym title="Peripheral Interface Adapter"
 >PIA</acronym> for maximum compatibility.</dd>
</dl>

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

<table>
<tr>
 <th>Key pressed</th>
 <th>File to load</th>
 <th>Mode</th>
</tr>
<tr>
 <td><kbd>STOP</kbd></td>
 <td>(none)</td>
 <td>C128</td>
</tr>
<tr>
 <td><kbd>Q</kbd></td>
 <td>(none)</td>
 <td>C64<sup>*</sup></td>
</tr>
<tr>
 <td><kbd>(none),&lt;-,1,2</kbd></td>
 <td><code>cbm128</code> or <code>cbm1028</code></td>
 <td>C128</td>
</tr>
<tr>
 <td><kbd>CTRL</kbd></td>
 <td><code>cbm128</code></td>
 <td>C128</td>
</tr>
<tr>
 <td><kbd>C=</kbd></td>
 <td><code>cbm64</code> or <code>cbm2564</code></td>
 <td>C64</td>
</tr>
<tr>
 <td><kbd>SPACE</kbd></td>
 <td><code>cbm64</code></td>
 <td>C64<sup>*</sup></td>
</tr>
</table>

<p><sup>*</sup> Note that drive 8 will be issued the
<code>U0&gt;M0</code> 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 <acronym
title="Keyboard Entry Read, Network And Link">KERNAL</acronym>
<acronym title="Read Only Memory">ROM</acronym> for the Commodore64
mode.  When the line is zero (or the key is down), the standard <acronym
title="Keyboard Entry Read, Network And Link">KERNAL</acronym>
is selected.  When the line is high, a <acronym
title="Keyboard Entry Read, Network And Link">KERNAL</acronym> <acronym
title="Read Only Memory">ROM</acronym> extension, such as
JiffyDOS, can be active.</p>

<p>You have to copy the servers for the modes you use.  For instance,
if you have a <acronym title="Peripheral Interface Adapter">PIA</acronym>
expansion and a <acronym title="RAM Expansion Unit">REU</acronym> in
your Commodore128, and you are using the <acronym
title="Personal Commodore64 emulator">PC64</acronym> cable, you need
to copy the following files:</p>

<table>
<tr>
 <th>File name in distribution</th>
 <th>C128 file name</th>
</tr>
<tr>
 <td><code>cbmprg/pc64/c128/plain.prg</code></td>
 <td><code>cbm128</code></td>
</tr>
<tr>
 <td><code>cbmprg/pc64/c128/piareu.prg</code></td>
 <td><code>cbm1028</code></td>
</tr>
<tr>
 <td><code>cbmprg/pc64/c64/plain.prg</code></td>
 <td><code>cbm64</code></td>
</tr>
<tr>
 <td><code>cbmprg/pc64/c64/piareu.prg</code></td>
 <td><code>cbm2564</code></td>
</tr>
</table>

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

<p>It is possible to change the default behaviour of the boot sector.
As you can see from the source code in
<code>cbmutils/c128/bootsect.s</code>, 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 Commodore64 mode and loads the appropriate
server.</p>

<h2><a name="func" href="#toc-func">2</a>
Functions</h2>

<p>The <code>cbmlink</code> 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.</p>

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

<dl>
 <dt><a href="#cable-c2n232">c2n232</a>,
 <a href="#cable-serial">serial</a></dt>
 <dd>The device name is the special file that points to the <acronym
 title="Recommended Standard">RS</acronym>-232 interface, e.g.,
 <code>/dev/ttyS0</code>, <code>serial.device</code> or
 <code>COM1</code>.</dd>

 <dt><a href="#cable-pc64">pc64</a>, <a href="#cable-prlink">prlink</a>,
 <a href="#cable-kontros">kontros</a>, <a href="#cable-c64net">c64net</a>,
 <a href="#cable-x1541">x1541</a></dt>
 <dd>The device name is the <acronym
 title="Input/Output">I/O</acronym> port address of an <acronym
 title="International Business Machines">IBM</acronym> <acronym
 title="Personal Computer">PC</acronym> compatible printer port or an
 index to a table, e.g. <code>0x3bc</code> or <code>0</code>.
 Alternatively, if <code>cbmlink</code> has been compiled with support
 for the parallel port device, you may specify a <abbr
 title="Linus' Minix">Linux</abbr> or Free<acronym
 title="Berkeley Software Distribution">BSD</acronym> parallel port
 device name, such as <code>/dev/parports/0</code>.  In this way,
 super user privileges are not needed.</dd>

 <dt><a href="#cable-prlink48">prlink48</a>,
 <a href="#cable-prlink88">prlink88</a>,
 <a href="#cable-transnib">transnib</a>,
 <a href="#cable-emul1541">emul1541</a>,
 <a href="#cable-em1541">em1541</a></dt>
 <dd>The device name is ignored; these cables are connected to the
 parallel port of a CommodoreAmiga.</dd>
</dl>

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

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

<h3><a name="func-mem" href="#toc-func-mem">2.1</a>
Memory transfers</h3>

<p>The file-to-memory and memory-to-file transfers of
<code>cbmlink</code> support memory expansions and banked memory
access on the Commodore.</p>

<p>The <code>-b</code> 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.</p>

<p>Bank numbers 0 to f are for internal memory.  The two low-most bits
are for specifying the <acronym title="Memory Management Unit">MMU</acronym>
mapped memory bank on a Commodore128.  In other words, <acronym
title="Memory Management Unit">MMU</acronym> mapped memory banks on
the Commodore128 are numbered from 0 to 3.  On unexpanded units, the
banks 2 and 3 are the same than banks 0 and 1.</p>

<p>The bits 2 and 3 of the bank number specify the <acronym
title="Peripheral Interface Adapter">PIA</acronym> mapped expanded
memory bank on a Commodore128 or a Commodore64.  So, the 64kB banks
of a Commodore128 with 1 megabyte of internal memory are numbered
from 0 to 15.  On a 512kB expanded Commodore128, the unique bank
numbers are 0, 1, 4, 5, 8, 9, 12 and 13, as there are only two
<acronym title="Memory Management Unit">MMU</acronym> banks.  For
instance, the banks 11 and 9 are equivalent.  On a 256kB expanded
Commodore64, or on a <acronym
title="Peripheral Interface Adapter">PIA</acronym>-expanded
Commodore128 in Commodore64 mode, the bank numbers 0..3, 4..7, 8..11
and 12..15 are the same, so there are 4 different banks.</p>

<p>Bank numbers from 16 to 255 are for <acronym
title="RAM Expansion Unit">REU</acronym> memory banks, i.e. the banks
of a 512 kilobyte <acronym title="RAM Expansion Unit">REU</acronym>
are numbered from 16 to 23.</p>

<p>On a stock Commodore128, 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 bank0.
The version for the <acronym
title="Peripheral Interface Adapter">PIA</acronym> expansion does not
have this bug.</p>

<h4><a name="func-mem-load" href="#toc-func-mem-load">2.1.1</a>
Loading a file to memory</h4>

<p>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:</p>

<dl>
 <dt><code>-l</code>[<code>p</code>]<code> <var>file</var>.prg</code></dt>
 <dd>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 <code>-lp</code> support the P00 file format by
 skipping the 26-byte file header.</dd>

 <dt><code>-l</code>[<code>p</code>]<code>b <var>file</var>.prg</code></dt>
 <dd>Load a program, relocated to the start of the <acronym
 title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
 text area.</dd>

 <dt><code>-l</code>[<code>p</code>]<code>o,<var>address</var>
 <var>file</var>.bin</code></dt>
 <dd>Load a binary file (not containing a starting address) to the
 specified address.</dd>

 <dt><code>-l</code>[<code>p</code>]<code>r,<var>address</var>
 <var>file</var>.prg</code></dt>
 <dd>Load a program, relocated to the specified address.</dd>
</dl>

<p>Note that the file to be loaded may not overwrite the server code
or <acronym title="Input/Output">I/O</acronym> register space.  If
this happens, the transfer may hang.</p>

<h4><a name="func-mem-save" href="#toc-func-mem-save">2.1.2</a>
Saving memory to a file</h4>

<p>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:</p>

<dl>
 <dt><code>-s,<var>address1</var>,<var>address2</var>
 <var>file</var>.prg</code></dt>
 <dd>Save the memory bytes from <code><var>address1</var></code> up to but
 excluding <code><var>address2</var></code> in the specified bank to a
 program file.  Write <code><var>address1</var></code> to the first two bytes
 of the file.</dd>

 <dt><code>-so,<var>address1</var>,<var>address2</var>
 <var>file</var>.prg</code></dt>
 <dd>Save the memory bytes from <code><var>address1</var></code> up to but
 excluding <code><var>address2</var></code> in the specified bank to a
 binary file.</dd>
</dl>

<p>You may find indirect addressing useful.  In order to save a <acronym
title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
program in a Commodore64, try <code>-s,@0x2b,@0x2d
<var>file</var>.prg</code>.</p>

<p>Note that dumping the <acronym title="Input/Output">I/O</acronym>
register space may hang the transfer.</p>

<h3><a name="func-invoke" href="#toc-func-invoke">2.2</a>
Remote Program Invocation</h3>

<p>It is possible to remotely invoke both <acronym
title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
and machine language programs.  Before starting a program, the server
deinstalls itself in order to achieve maximum compatibility.</p>

<h4><a name="func-invoke-basic" href="#toc-func-invoke-basic">2.2.1</a>
Starting a <acronym
title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
program</h4>

<p>The <code>-r</code> switch performs the <acronym
title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
<code>RUN</code> command.  This switch is typically used at the end of
a command line, e.g. <code>cbmlink -c c2n232 /dev/ttyS0 -l Elite.prg
-r</code>.</p>

<h4><a name="func-invoke-mach" href="#toc-func-invoke-mach">2.2.2</a>
Starting a machine language program</h4>

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

<h4><a name="func-invoke-cart" href="#toc-func-invoke-cart">2.2.3</a>
Starting a VIC-20 cartridge</h4>

<p>Normally, switching cartridge games is a little annoying, because
you would have to physically remove and install <acronym
title="Read Only Memory">ROM</acronym> cartridges, or to power the
computer off until a <acronym
title="Random Access Memory">RAM</acronym> expansion cartridge has
forgot the <code>a0CBM</code> auto-start code in <abbr class="bar"
title="Block5, $a000-$bfff">BLK5</abbr>.</p>

<p>With <code>cbmlink</code>, playing CommodoreVIC-20 cartridge games
becomes more convenient.  The <code>-jc</code> (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 <code>cbmlink</code> server again.</p>

<p>This arrangement works notably well if the server resides at $4000
(<abbr class="bar" title="Block 3, $4000-$5fff">BLK3</abbr>, the
default) and the option is invoked with <code>-jc,20000</code>.  The
parameter specifies a <code>SYS</code> address that can be used for
restarting the same cartridge game.</p>

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

<h4><a name="func-invoke-music" href="#toc-func-invoke-music">2.2.4</a>
Playing Commodore64 music tunes</h4>

<p>There is a collection of Commodore64 music files on ftp.funet.fi
at <a class="ext"
href="http://www.funet.fi/pub/cbm/c64/audio/Vibrants/">/pub/cbm/c64/audio/Vibrants</a>.
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.</p>

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

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

<p>Assume that you have the player
(<code>cbmutils/c64/playtune.prg</code>) and Toccato (<a class="ext"
href="http://www.funet.fi/pub/cbm/c64/audio/Vibrants/Deek/">/pub/cbm/c64/audio/Vibrants/Deek</a>/14toccat.prg)
in the current directory.  To start playing the music on the
Commodore64, you may use the command <code>cbmlink -c c2n232
/dev/ttyS0 -l playtune.prg -l 14toccat.prg -j 0xc800</code>.
Alternatively, you can load <code>playtune.prg</code> and the tunes
separately.  To change the tune, you may omit
<code>playtune.prg</code>: <code>cbmlink -c c2n232 /dev/ttyS0 -l
14treasu.prg -j 0xc800</code>.</p>

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

<h4><a name="func-invoke-perf" href="#toc-func-invoke-perf">2.2.5</a>
Performance measurements</h4>

<p>The file <code>cbmutils/c64/tod.prg</code> 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.</p>

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

<h3><a name="func-copy" href="#toc-func-copy">2.3</a> File and disk transfer</h3>

<p>The file transfer commands use standard <acronym
title="Keyboard Entry Read, Network And Link">KERNAL</acronym>
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.</p>

<p>Note that these transfer commands only work with disk drives or
pseudo drives, like the <acronym title="RAM Expansion Unit">REU</acronym>
<acronym title="Random Access Memory">RAM</acronym> 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.</p>

<p>The switch <code>-d <var>drive</var>[,<var>secondary</var>]</code>
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.</p>

<p>As the file names are not translated between <acronym
title="Personal Electronic Transactor Standard Code for Information Interchange"
>PETSCII</acronym> and <acronym
title="American Standard Code for Information Interchange">ASCII</acronym>,
it is best to use upper-case file names on the local system, which
correspond to lower-case Commodore file names.</p>

<p><em>There may be some random problems with file and disk transfers
via the C2N232 cable on some platforms.  Please report any bugs you
encounter with it.</em> 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.</p>

<p>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 <q>big computer</q>, do not
specify more than one file or disk copying option on the command line
when using <code>-c serial</code>.</p>

<h4><a name="func-copy-fr" href="#toc-func-copy-fr">2.3.1</a>
Reading Commodore files</h4>

<p>The file-read extension can be used through several command-line
switches:</p>

<dl>
 <dt><code>-fr <var>file</var></code> ...</dt>
 <dd>Copy the specified files from the Commodore to the local file system.</dd>
 <dt><code>-dd <var>pattern</var></code></dt>
 <dd>Read the file <code>$<var>pattern</var></code> and display it on the
 standard output as  a directory listing.</dd>
 <dt><code>-ds</code></dt>
 <dd>Read the status channel of the drive, and display the result on the
 standard output.</dd>
 <dt><code>-dc <var>command</var></code></dt>
 <dd>Issue the specified command and read the status channel.  Note
 that the command needs to be in upper case, as no <acronym
 title="Personal Electronic Transactor Standard Code for Information Interchange"
 >PETSCII</acronym> translation takes place.  Also note
 that issuing the <code>UJ</code> command will probably hang the
 system.  To reset the drive, use <code>UI</code> instead.</dd>
</dl>

<h4><a name="func-copy-fw" href="#toc-func-copy-fw">2.3.2</a>
Writing Commodore files</h4>

<p>There is only one switch for using the file-write extension:</p>

<dl>
 <dt><code>-fr <var>file</var></code> ...</dt>
 <dd>Copy the specified files from the local file system to the Commodore.</dd>
</dl>

<p>It is best to rename the files to upper case before copying, as
<code>cbmlink</code> won't strip directory delimiters or translate
file names from <acronym
title="American Standard Code for Information Interchange">ASCII</acronym>
to <acronym
title="Personal Electronic Transactor Standard Code for Information Interchange"
>PETSCII</acronym>.</p>

<h4><a name="func-copy-disk" href="#toc-func-copy-disk">2.3.3</a>
Disk transfer</h4>

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

<dl>
 <dt><code>-dr</code>[<code>0</code>|<code>1</code>][<code>,<var>interleave</var></code>[<code>,<var>start</var></code>[<code>,<var>end</var></code>]]]
 <code><var>file</var></code></dt>
 <dd>Make a verbatim copy of the disk to the specified local file.
 The interleave factor may dramatically affect the copying speed.
 Note that <var>file</var> must be seekable when <var>interleave</var>
 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.</dd>
 <dt><code>-dw</code>[<code>0</code>|<code>1</code>][<code>,<var>interleave</var></code>[<code>,<var>start</var></code>[<code>,<var>end</var></code>]]]
 <code><var>file</var></code></dt>
 <dd>Copy a local file to Commodore disk sectors, starting from track
 1.  The interleave factor may dramatically affect the copying speed.
 Note that <var>file</var> must be seekable when <var>interleave</var>
 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.</dd>
</dl>

<p>When the file given to the <code>-dw</code> option is shorter than
the disk capacity, the rest of the disk is left uninitialised.</p>

<p>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.</p>

<h4><a name="func-copy-dmem" href="#toc-func-copy-dmem">2.3.4</a>
Disk memory transfer</h4>

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

<dl>
 <dt><code>-dmc <var>address1</var> <var>address2</var>
 <var>file</var>.prg</code></dt>
 <dd>Save the memory bytes from <code><var>address1</var></code> up to
 but excluding <code><var>address2</var></code> in a dual disk drive's
 controller address space to a program file.  Write
 <code><var>address1</var></code> to the first two bytes of the file.
 Note that the drive may act strangely once this command has been
 issued.  <em>Thanks to William Levak and Wolfgang Gnther for providing
 the information needed for implementing this option.</em></dd>

 <dt><code>-dmco <var>address1</var> <var>address2</var>
 <var>file</var>.prg</code></dt>
 <dd>Save the memory bytes from <code><var>address1</var></code> up to
 but excluding <code><var>address2</var></code> 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.</dd>

 <dt><code>-dml <var>file</var>.prg</code></dt>
 <dd>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.</dd>

 <dt><code>-dmlo <var>address</var> <var>file</var>.bin</code></dt>
 <dd>Load a binary file (not containing a starting address) to the
 specified address in the disk drive's main address space.</dd>

 <dt><code>-dmlr <var>address</var> <var>file</var>.prg</code></dt>
 <dd>Load a program, relocated to the specified address in the disk
 drive's main address space.</dd>

 <dt><code>-dms <var>address1</var> <var>address2</var>
 <var>file</var>.prg</code></dt>
 <dd>Save the memory bytes from <code><var>address1</var></code> up to
 but excluding <code><var>address2</var></code> in the disk drive's
 main address space to a program file.  Write
 <code><var>address1</var></code> to the first two bytes of the
 file.</dd>

 <dt><code>-dmso <var>address1</var> <var>address2</var>
 <var>file</var>.prg</code></dt>
 <dd>Save the memory bytes from <code><var>address1</var></code> up to
 but excluding <code><var>address2</var></code> in the disk drive's
 main address space to a binary file.</dd>
</dl>

<h3><a name="func-quick" href="#toc-func-quick">2.4</a>
Quick 1541 disk operations</h3>

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

<dl>
 <dt><code>-qf <var>name</var>,<var>id</var></code></dt>
 <dd>Format a 1541 disk in 24 seconds with verify.  The code works
 also on the 1571 in 1541 mode, but it crashes if the drive is in the
 1571 mode.</dd>

 <dt><code>-qr <var>file</var></code></dt>
 <dd>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.</dd>

 <dt><code>-qw</code>[<code>,<var>interleave</var></code>]<code>
 <var>file</var></code></dt>
 <dd>Copy a local file to 1541 disk sectors, starting from track 1.
 The interleave factor may dramatically affect the copying speed.</dd>
</dl>

<h2><a name="hw" href="#toc-hw">3</a>
Hardware</h2>

<p>The <code>cbmlink</code> utility requires either the <a
href="#cable-c2n232">C2N232 device</a>, a 3-wire <a
href="#cable-serial">null modem serial cable</a> or a special cable
that is connected to the parallel port of an Amiga or an <acronym
title="International Business Machines">IBM</acronym> <acronym
title="Personal Computer">PC</acronym> 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.</p>

<p>The <a href="#cable-pc64"><acronym
title="Personal Commodore64 emulator">PC64</acronym> cable</a> is the
cable used by the no longer developed <q>Personal C64</q> 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.</p>

<p>The <a href="#cable-prlink">prlink cable</a> allows 8-bit data
transfers from the <acronym
title="International Business Machines">IBM</acronym> <acronym
title="Personal Computer">PC</acronym> compatible to the Commodore
side, and 4 bits to the opposite direction.  It uses four
bidirectional lines on the <acronym
title="International Business Machines">IBM</acronym> <acronym
title="Personal Computer">PC</acronym> compatible.  <em>Beware that
these lines are no longer bidirectional on some newer enhanced
parallel ports.  Be prepared to build the <acronym
title="Personal Commodore64 emulator">PC64</acronym> cable if this
cable does not work.</em></p>

<p>The software also supports the <a href="#cable-x1541">X1541
cable</a> designed for connecting a Commodore disk drive to your
<acronym title="International Business Machines">IBM</acronym>
<acronym title="Personal Computer">PC</acronym> 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.</p>

<p>On the Amiga, there are three parallel cables: the native 8-bit
cable that works with most protocols supported by the Amiga version,
and <a href="#cable-em1541">two different</a> <a
href="#cable-emul1541">cables</a> for the serial bus connection.
Also, if you have built the <a href="#cable-transnib">cable for the
TransNib software</a>, <code>cbmlink</code> will work with it,
although slower than with the <a href="#cable-prlink88">prlink88</a>
cable.</p>

<h3><a name="hw-conn" href="#toc-hw-conn">3.1</a>
Cable pin-outs</h3>

<p>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
<acronym title="International Business Machines">IBM</acronym>
<acronym title="Personal Computer">PC</acronym> compatible with the
9-volt signal as Marko did.</p>

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

<p>On the Amiga 1000, pin 25 is not <acronym
title="Ground">GND</acronym> so Olaf picked 22 instead which should be
<acronym title="Ground">GND</acronym> on all Amiga models.  On
<acronym title="International Business Machines">IBM</acronym>
<acronym title="Personal Computer">PC</acronym> compatibles, all pins
from 18 to 25 should be <acronym title="Ground">GND</acronym>.</p>

<h4><a name="hw-conn-serial" href="#toc-hw-conn-serial">3.1.1</a>
The null modem cable (<code><a name="cable-serial">serial</a></code>)</h4>

<p>A 6551 <acronym
title="Asynchronous Communication Interface Adapter">ACIA</acronym>
based <acronym title="Recommended Standard">RS</acronym>-232C
connection is supported on the following Commodore computers:</p>

<ul>
 <li><acronym title="Personal Electronic Transactor">PET</acronym>-II
 series: <acronym title="Commodore Business Machines">CBM</acronym>
 500, 600 or 700 series (P500 or the B series)</li>
 <li>Commodoreplus/4 (with a voltage converter,
 such as the CommodoreVIC-1011A with its case removed)</li>
 <li>Commodore 64 and 128 (with the 6551 wired to <code>$de00</code> a.k.a.
 <acronym class="bar" title="Input/Output 1">I/O1</acronym>;
 this does not yet work with a Swiftlink cartridge)</li>
</ul>

<p>As the protocol makes no use of handshaking, three wires are
enough: TxD, RxD and ground.  Remember to connect TxD on one end to
RxD on the other end and vice versa.</p>

<p>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 standard data rates between 300 and 38,400 bits per second can be
specified by prefixing the device name with the desired data rate:
<code>-c serial 9600,<var>/dev/ttyS0</var></code> instead of <code>-c
serial <var>/dev/ttyS0</var></code>.  On the Amiga, any rate between
112 and 292,000 bits per second may be specified: <code>-c serial
9600,serial.device</code>.</p>

<h4><a name="hw-conn-pc64" href="#toc-hw-conn-pc64">3.1.2</a>
The <acronym title="Personal Commodore64 emulator">PC64</acronym>
cable (<code><a name="cable-pc64">pc64</a></code>)</h4>

<table>
<tr>
 <th><acronym title="International Business Machines">IBM</acronym>
 <acronym title="Personal Computer">PC</acronym>PC</th>
 <th>Pins</th>
 <th>Commodore</th>
 <th>Comment</th>
</tr>
<tr>
 <td><acronym
 title="Ground">GND</acronym></td><td class="c">25---A</td><td><acronym
 title="Ground">GND</acronym></td>
 <td>Ground</td>
</tr>
<tr>
 <td>D7</td><td class="c">9--&gt;B</td>
 <td>FLAG</td>
 <td>Handshake signal</td>
</tr>
<tr>
 <td>ERROR</td><td class="c">15&lt;--C</td><td>PB0</td>
 <td>Data from Commodore to <acronym
 title="International Business Machines">IBM</acronym> <acronym
 title="Personal Computer">PC</acronym></td>
</tr>
<tr>
 <td>SEL</td><td class="c">13&lt;--D</td><td>PB1</td>
 <td>"</td>
</tr>
<tr>
 <td>PE</td><td class="c">12&lt;--E</td><td>PB2</td>
 <td>"</td>
</tr>
<tr>
 <td>ACK</td><td class="c">10&lt;--F</td><td>PB3</td>
 <td>"</td>
</tr>
<tr>
 <td>D0</td><td class="c">2--&gt;H</td><td>PB4</td>
 <td>Data from <acronym title="International Business Machines">IBM</acronym>
 <acronym title="Personal Computer">PC</acronym> to Commodore</td>
</tr>
<tr>
 <td>D1</td><td class="c">3--&gt;J</td><td>PB5</td>
 <td>"</td>
</tr>
<tr>
 <td>D2</td><td class="c">4--&gt;K</td><td>PB6</td>
 <td>"</td>
</tr>
<tr>
 <td>D3</td><td class="c">5--&gt;L</td><td>PB7</td>
 <td>"</td>
</tr>
<tr>
 <td>BUSY</td><td class="c">11&lt;--M</td><td>PA2</td>
 <td>Handshake signal</td>
</tr>
</table>

<h4><a name="hw-conn-prlink" href="#toc-hw-conn-prlink">3.1.3</a>
The prlink cable (<code><a name="cable-prlink">prlink</a></code>
a.k.a. <code><a name="cable-prlink48">prlink48</a></code>)</h4>

<table>
<tr>
 <th><acronym title="International Business Machines">IBM</acronym>
 <acronym title="Personal Computer">PC</acronym></th>
 <th>Pins</th>
 <th>Commodore</th>
 <th>Comment</th>
</tr>
<tr>
 <td><acronym
 title="Ground">GND</acronym></td><td class="c">25---A</td><td><acronym
 title="Ground">GND</acronym></td>
 <td>Ground</td>
</tr>
<tr>
 <td>D3</td><td class="c">5--&gt;B</td><td>FLAG</td>
 <td>Handshake signal</td>
</tr>
<tr>
 <td>STROBE</td><td class="c">1&lt;-&gt;C</td><td>PB0</td>
 <td>Bidirectional data lines</td>
</tr>
<tr>
 <td>AUTO</td><td class="c">14&lt;-&gt;D</td><td>PB1</td>
 <td>"</td>
</tr>
<tr>
 <td>INIT</td><td class="c">16&lt;-&gt;E</td><td>PB2</td>
 <td>"</td>
</tr>
<tr>
 <td>SELECT</td><td class="c">17&lt;-&gt;F</td><td>PB3</td>
 <td>"</td>
</tr>
<tr>
 <td>D4</td><td class="c">6--&gt;H</td><td>PB4</td>
 <td>Data from <acronym title="International Business Machines">IBM</acronym>
 <acronym title="Personal Computer">PC</acronym> to Commodore</td>
</tr>
<tr>
 <td>D5</td><td class="c">7--&gt;J</td><td>PB5</td>
 <td>"</td>
</tr>
<tr>
 <td>D6</td><td class="c">8--&gt;K</td><td>PB6</td>
 <td>"</td>
</tr>
<tr>
 <td>D7</td><td class="c">9--&gt;L</td><td>PB7</td>
 <td>"</td>
</tr>
<tr>
 <td>BUSY</td><td class="c">11&lt;--M</td><td>PA2</td>
 <td>Handshake signal</td>
</tr>
</table>

<h4><a name="hw-conn-amiga" href="#toc-hw-conn-amiga">3.1.4</a>
The Amiga cable (<code><a name="cable-prlink88">prlink88</a></code>,
<code>prlink48</code>,
<code><a name="cable-transnib">transnib</a></code>)</h4>

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

<p>On the <acronym title="Personal Electronic Transactor">PET</acronym>,
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.</p>

<p>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:</p>

<dl>
 <dt>D0-3&lt;-&gt;PA0-3</dt>
 <dd>data in/out</dd>
 <dt>D6&lt;--PA6</dt>
 <dd>handshake in (from C= to Amiga)</dd>
 <dt>D7--&gt;PA7</dt>
 <dd>handshake out (from Amiga to C=)</dd>
</dl>

<p>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.</p>

<p>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 <a
href="mailto:m.p.francis@newcastle.ac.uk">Matt Francis</a>.</p>

<h4><a name="hw-conn-x1541" href="#toc-hw-conn-x1541">3.1.5</a>
The serial bus cable for <acronym title="International Business Machines"
>IBM</acronym> <acronym title="Personal Computer">PC</acronym> compatibles
(<code><a name="cable-x1541">x1541</a></code>)</h4>

<table>
<tr>
 <th><acronym title="International Business Machines">IBM</acronym>
 <acronym title="Personal Computer">PC</acronym></th>
 <th>Pins</th>
 <th>Commodore serial bus</th>
 <th>Comment</th>
</tr>
<tr>
 <td><acronym
 title="Ground">GND</acronym></td><td class="c">22---2</td><td><acronym
 title="Ground">GND</acronym></td>
 <td>Ground</td>
</tr>
<tr>
 <td>STROBE</td><td class="c">1--&gt;3</td><td><abbr title="Attention">ATN</abbr></td>
 <td>not used</td>
</tr>
<tr>
 <td>AUTOFD</td><td class="c">14&lt;-&gt;4</td><td><abbr title="Clock">CLK</abbr></td>
 <td>Bidirectional data/handshake line</td>
</tr>
<tr>
 <td>SELECT</td><td class="c">17&lt;--5</td><td>DATA</td>
 <td>Bidirectional data/handshake line</td>
</tr>
</table>

<p>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 <abbr
title="Attention">ATN</abbr> line is not required either, but it is
required by other transfer programs that use this cable.
<code>cbmlink</code> will work with these additions installed, so you
don't need to modify your existing X1541 cable.</p>

<h4><a name="hw-conn-amiec" href="#toc-hw-conn-amiec">3.1.6</a>
The serial bus cables for the Amiga (<code><a
name="cable-em1541">em1541</a></code>, <code><a
name="cable-emul1541">emul1541</a></code>)</h4>

<p>The description below is, slightly modified, taken from the Frodo
documentation.  The exact cable as used by Frodo (see
<code>Aminet:misc/emu/Frodo*</code>), however, is also usable by
<code>cbmlink</code>.  Even though it wires the <abbr
title="Attention">ATN</abbr> line as an output, we can use the cable
since we don't use the <abbr title="Attention">ATN</abbr> line. You
can also use the cable used by Emul_1541 (see
<code>Aminet:misc/emu/Emul1541v11.*</code>). 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.</p>

<p>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
<abbr title="Attention">ATN</abbr> line.</p>

<p>The cable with inverters, as shown below, is called
<code>emul1541</code>.  The cable without inverters is called
<code>em1541</code>.</p>

<p>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.</p>

<pre>
 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 |-----*--+--+------- <abbr title="Attention">ATN</abbr>    3
                \|        |  |
                          |  |
              3|\ 4       |  |
    6  PB4 ----| O--*-----*--+------- <abbr title="Clock">CLK</abbr>    4
               |/   |        |
                    |        |
              5|\ 6 |        |
    7  PB5 ----| O--+-*------*------- DATA   5
               |/   | |
                    | |
    8  PB6 ---------+ |
                      |
    9  PB7 -----------+

   22  <acronym
title="Ground">GND</acronym> -------------------------- <acronym
title="Ground">GND</acronym>    2
</pre>

<p>The 7406 (a 74LS05 will do as well) must be connected to +5V and
<acronym title="Ground">GND</acronym> of course. The trained
technician will notice that this is the same circuit found inside the
real Commodore64 (except that the inverter on <abbr
title="Attention">ATN</abbr> is inverted so <abbr
title="Attention">ATN</abbr> can be used for output).</p>

<p><em>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!</em></p>

<h4><a name="hw-conn-kontros" href="#toc-hw-conn-kontros">3.1.7</a>
The Kontros cable (<code><a name="cable-kontros">kontros</a></code>)</h4>

<p>The alert reader may have noticed from the source code that
<code>cbmlink</code> supports yet another cable, a buffered parallel
cable designed by <a href="mailto:frank@kontr.uzhgorod.ua">Frank
Kontros</a>.  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), Commodore64 and Commodore128.  E-mail
Frank if you are interested in his super-fast interface and software
(for <acronym title="Microsoft">MS</acronym>-<acronym
title="Disk Operating System">DOS</acronym>).</p>

<h4><a name="hw-conn-64net" href="#toc-hw-conn-64net">3.1.8</a>
The 64NET cable (<code><a name="cable-c64net">c64net</a></code>)</h4>

<p>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.</p>

<h3><a name="hw-prob" href="#toc-hw-prob">3.2</a>
Transfer trouble</h3>

<p>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.</p>

<p>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.</p>

<p>Because of this, we have included bounce detection for the
<code>prlink48</code> and <code>prlink88</code> cables in the
following cases:</p>

<dl>
 <dt>Amiga</dt>
 <dd>The bounce on the handshake line to the Amiga (BUSY) happens with
 both Olaf's <acronym title="Personal Electronic Transactor">PET</acronym>
 and 64, but more with the 64.  When reading its state, we require its
 readout to be stable for 3 consecutive accesses.  Since the <acronym
 title="Complex Interface Adapter">CIA</acronym>s in the Amiga run at
 714kHz, an access takes about 1.4s.</dd>

 <dt>C64 and C128</dt>
 <dd>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.</dd>
</dl>

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

<p>If the transfer hangs, you can stop the server on the Commodore
side with STOP &amp; Restore.  The client can be stopped with normal
means, i.e. <kbd>Ctrl-D</kbd> on the Amiga, <kbd>Ctrl-C</kbd> on Unix
systems, or <kbd>Ctrl-Break</kbd> on <acronym
title="Microsoft">MS</acronym>-<acronym
title="Disk Operating System">DOS</acronym>.</p>

<h2><a name="comp" href="#toc-comp">4</a>
Compiling</h2>

<h3><a name="comp-src" href="#toc-comp-src">4.1</a>
The <code>cbmlink</code> executable</h3>

<p>Generally, in order to compile <code>cbmlink</code>, you need
<acronym title="GNU's Not Unix">GNU</acronym> Make, <acronym
title="GNU's Not Unix">GNU</acronym> Compiler Collection and related
tools.  On UNIX systems, you should be able to use the native
<code>cc</code>.  If not, install <code>gcc</code>.</p>

<p>The 32-bit console-mode executable for Microsoft Windows is best
generated with gcc targeted for Minimalist <acronym
title="GNU's Not Unix">GNU</acronym> for Windows, running either on <abbr
title="Linus' Minix">Linux</abbr> or Windows.</p>

<p>The <acronym title="Microsoft">MS</acronym>-<acronym
title="Disk Operating System">DOS</acronym> executable can be
generated with Bruce Evans' C compiler <code>bcc</code>, packaged by
Robert de Bath as <a class="ext"
href="http://www.cix.co.uk/~mayday/">Dev86</a>.</p>

<p>The software supports several different cables.  The cable-specific
transfer routines are in the <code>comm</code> subdirectory.</p>

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

<p>In principle, compiling is as easy as typing</p>
<ol>
 <li><code>cd src</code></li>
 <li><code>make -f Makefile.<var>platform</var></code></li>
 <li><code>make install</code></li>
</ol>

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

<h3><a name="comp-cbmsrc" href="#toc-comp-cbmsrc">4.2</a>
The Commodore servers</h3>

<p>If you like to modify or to recompile the Commodore binaries, you need
to retrieve DASM from ftp.funet.fi as <a class="ext"
href="http://www.funet.fi/pub/cbm/programming/unix/">/pub/cbm/programming/unix</a>/dasm21204.zip.</p>

<p>The source code for the Commodore server programs is located in the
<code>cbmsrc</code> subdirectory.  There are two <q>main</q> files,
<code>server.s</code> and <code>c2n.s</code>, both of which act as
entry points to <code>server.s</code>, which uses include files from
the subdirectories.  The Bourne shell script <code>build.sh</code>
takes care of building all <code>cbmlink</code> server binaries.</p>

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

<dl>
 <dt>cable type (<code>cable</code>)</dt>
 <dd>name of the supported transfer cable:
 <a href="#cable-c2n232">c2n232</a>,
 <a href="#cable-serial">serial</a>,
 <a href="#cable-pc64">pc64</a>,
 <a href="#cable-prlink48">prlink48</a>,
 <a href="#cable-prlink88">prlink88</a>,
 <a href="#cable-transnib">transnib</a>,
 <a href="#cable-kontros">kontros</a>,
 <a href="#cable-c64net">c64net</a>,
 <a href="#cable-x1541">x1541</a></dd>
 <dt>computer type (<code>host</code>)</dt>
 <dd>name of the computer:
 <dl>
  <dt>pet3001</dt>
  <dd>Commodore<acronym title="Personal Electronic Transactor">PET</acronym>
  30xx with <acronym
  title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
  2.0</dd>
  <dt>pet4001</dt>
  <dd>Commodore<acronym title="Personal Electronic Transactor">PET</acronym>
  40xx or 80xx with <acronym
  title="Beginners' All-purpose Symbolic Instruction Code">BASIC</acronym>
  4.0</dd>
  <dt>vic20</dt>
  <dd>Commodore VIC-20, VC-20 or VIC-1001</dd>
  <dt>c64</dt>
  <dd>Commodore 64, 4064, SX-64, 64c or 64G</dd>
  <dt>c128</dt>
  <dd>Commodore 128, 128<acronym title="desktop">D</acronym> or 128<acronym
  title="desktop, cost reduced">DCR</acronym></dd>
  <dt>c264</dt>
  <dd>Commodore 264 series: 16, 116, plus/4 or 232</dd>
  <dt>p500</dt>
  <dd>Commodore 510 or P500</dd>
  <dt>b128</dt>
  <dd>Commodore 610, 710 or B-128</dd>
  <dt>b256</dt>
  <dd>Commodore 620, 720 or B-256</dd>
 </dl></dd>
 <dt>memory expansion or other variation (<code>mem</code>)</dt>
 <dd>The basic configuration is called <code>plain</code>.  Other
 configurations are:
 <dl>
  <dt><code>pia</code> (c64, c128)</dt>
  <dd>Support for the internal <acronym
  title="Peripheral Interface Adapter">PIA</acronym>-controlled memory
  expansion.  The <acronym title="Peripheral Interface Adapter">PIA</acronym>
  base address is set in <code>piabase.s</code>.</dd>
  <dt><code>reu</code> (c64, c128)</dt>
  <dd>Support for the Commodore <acronym
  title="Random Access Memory">RAM</acronym> Expansion Unit</dd>
  <dt><code>piareu</code> (c64, c128)</dt>
  <dd>Support for both the internal <acronym
  title="Peripheral Interface Adapter">PIA</acronym>-controlled expansion
  and an external Commodore <acronym
  title="Random Access Memory">RAM</acronym> Expansion Unit</dd>
  <dt><code>cart</code> (vic20)</dt>
  <dd>The server is built at $a000 with the <code>a0CBM</code>
  auto-start signature.  The server is installed automatically
  on reset.  This configuration cannot be used for loading
  cartridge games.</dd>
  <dt><code>port2</code> (pet3001, pet4001)</dt>
  <dd>Use cassette port 2 for the <a href="#cable-c2n232">c2n232</a>
  device.</dd>
 </dl></dd>
</dl>

<p>The <code>cbmprg</code> subdirectory contains 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.</p>

<p>The <code>cbmc2n</code> subdirectory contains the contents of the
<code>cbmprg/c2n232</code> directory in the raw Commodore cassette
format, usable with the <code>c2n</code> utility.</p>

<h4><a name="comp-cbmsrc-start" href="#toc-comp-cbmsrc-start">4.2.1</a>
Changing the start address</h4>

<p>In order to change the start address of a server, have a look at the
appropriate include file in the <code>host</code> directory.</p>

<h4><a name="comp-cbmsrc-reuplay" href="#toc-comp-cbmsrc-reuplay">4.2.2</a>
Using the <acronym title="RAM Expansion Unit">REU</acronym> with an
Action Replay</h4>

<p>The Action Replay cartridge by Datel occupies all of the address
space at $de00-$dfff.  Nevertheless, it is possible to use a Commodore
<acronym title="RAM Expansion Unit">REU</acronym> simultaneously with
an Action Replay cartridge, if the <acronym
title="RAM Expansion Unit">REU</acronym> registers are modified to be
write-only:</p>

<pre>
           /o-------+
<acronym class="bar"
title="Input/Output 2">I/O2</acronym> ----o/        |
(from C64)  o-&gt;|----+--- <acronym class="bar"
title="Input/Output 2">I/O2</acronym> (to <acronym
title="RAM Expansion Unit">REU</acronym>)
                   |
<acronym title="Read">R</acronym>/<acronym class="bar"
title="Write">W</acronym>  --------&gt;|----+
           1N4148  |
           diodes  &lt;
                   &gt; 4k7
                   &lt; resistor
                   &gt;
                   |
                 --+--
</pre>

<p>When the switch is in its upper position, the <acronym
title="RAM Expansion Unit">REU</acronym> 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
<acronym title="RAM Expansion Unit">REU</acronym> (except
<code>cbmlink</code>).  Thus, whenever you want to use anything that
supports the <acronym title="RAM Expansion Unit">REU</acronym>, you
must disable the Action Replay cartridge and then move the switch to
the upper position.</p>

<p>To allow <code>cbmlink</code> to access the <acronym
title="RAM Expansion Unit">REU</acronym> when its registers are
write-only, set <code>actionreuplay=1</code> in
<code>reubase.s</code>.</p>

<p>If you also modify Action Replay so that its -<acronym
title="Input/Output 2">I/O2</acronym> gets disabled when <acronym
title="Read">R</acronym>/<acronym class="bar"
title="Write">W</acronym> is low, you won't need the actionreuplay
option.  But this modification cannot be implemented with diodes and
resistors.  Instead, you would need an <acronym
title="Integrated Circuit">IC</acronym> (quad <abbr
title="Negated AND gate">NAND</abbr> or something), which may be
difficult to fit in the Action Replay case.</p>

<h2><a name="credit" href="#toc-credit">5</a>
Credits</h2>

<p>The ancestor of <code>cbmlink</code>, <code>prlink</code>, was
originally programmed for <abbr title="Linus' Minix">Linux</abbr> and
C64/C128/VIC-20 by Marko Mkel.  Olaf Seibert joined the project and
ported <code>prlink</code> to Amiga and the <acronym
title="Personal Electronic Transactor">PET</acronym> 3000 and
4000/8000 series.  Since then, Marko has ported the code to numerous
other platforms, and improved the program structure greatly.</p>

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

<p>Special thanks go to Daniel Kahlin and Andreas <q>pitch</q> Andersson
for contributing fast 1541 disk routines.</p>

<h2><a name="plans" href="#toc-plans">6</a>
Known bugs and future plans</h2>

<p>Contributions are welcome, as Marko is busy with many things.</p>

<ol>
 <li>The support for Commodore <acronym
 title="Personal Electronic Transactor">PET</acronym> 3000 series
 is faulty.</li>
 <li>Quick 1541 disk operations (section <a href="#func-quick">2.4</a>)
 <ul>
  <li>The <code>-qf</code> option does not work on a 1571 unless it is
  in 1541 mode.  It should change modes automatically.</li>
  <li>The <code>-qr</code> and <code>-qw</code> options do not work at
  all.  It may be necessary to rewrite the communication protocol.</li>
  <li>The drive type is not detected to avoid problems with non-1541
  drives.  (It could be detected by issuing the <code>UI</code> command
  and reading the status channel).</li>
 </ul></li>
 <li>The null modem connection does not work on the Commodore64.  Marko
 has no 6551 cartridge to test with.</li>
 <li>The <code>-dmc</code> option (Section <a
 href="#func-copy-dmem">2.3.4</a>) may make drives behave strangely.</li>
 <li>It could be useful to integrate a modified version of the <a
 class="ext" href="http://www.cs.tut.fi/~albert/Dev/gunzip/">Gunzip.c64</a>
 decompression program to <code>cbmlink</code> in order to speed up the
 copying of 1541, 1571 or 1581 disk images.</li>
 <li>Implement support for <acronym
 title="Integrated Drive Electronics">IDE</acronym>64 and other third-party
 mass storage products.</li>
 <li>Integrate <code>cbmconvert</code> into <code>cbmlink</code>.</li>
</ol>

<h2><a name="dist" href="#toc-dist">7</a>
Distribution</h2>

<p>The primary distribution site of <code>cbmlink</code> is <a
class="ext"
href="http://www.funet.fi/pub/cbm/crossplatform/transfer/C2N232/index.html"
>http://www.funet.fi/pub/cbm/crossplatform/transfer/C2N232/</a>.</p>

<p>Precompiled binaries are available for other than Unix-like
platforms.  Currently these include Commodore AmigaOS, <acronym
title="Microsoft">MS</acronym>-<acronym
title="Disk Operating System">DOS</acronym> (8086) and 32-bit versions
of Microsoft Windows (95 and later).</p>

<hr>
<address><a href="mailto:msmakela@nic.funet.fi">Marko Mkel</a></address>
</body>
</html>