			    Turbo-Tape Collection
			    =====================

Since the Commodore 64's built-in tape routines are very slow, some of the
first programs that appeared in the early days of this home computer were 
tape accelerators. One of the most popular ones was Turbo-Tape. With a rate
of about 400 Bytes per second, it is even a little bit faster than the
1541 floppy disk drive. So Turbo-Tape is quite ideal for tape based data 
exchange, even between different platforms, since it can easily be ported 
due to its simple format.

0. Table of contents
====================

1. Where can I download new versions of this software?
2. What does this archive contain?
3. Turbo-Tape for Commodore computers
   3.1 How to transfer the Turbo-Tape loader to my Commodore?
   3.2 How to use Turbo-Tape on my Commodore?
   3.3 Where does the Turbo-Tape code reside in memory?
4. Turbo-Tape for the IBM PC
   4.1 What is needed?
   4.2 How to connect the Datassette to my PC?
   4.3 How to use Turbo-Tape on my PC?
   4.4 How to configure the Turbo-Tape software?
   4.5 Known problems
5. Turbo-Tape format specification
6. Further comments
7. Related WWW links

1. Where can I download new versions of this software?
======================================================

You can always download the newest version of this software from
http://www.informatik.uni-rostock.de/~ajung/Tape/index.html .
I will also contact the people of the funet archive so that this software
might eventually also be available via ftp as
ftp://ftp.funet.fi/pub/cbm/transfer/datassette/ttapeXYZ.zip
where XYZ stands for the version number.

2. What does this archive contain?
==================================

This archive contains implementations of Turbo-Tape for various computers
(well, three at the moment ;-). TTAPE64.PRG is the original program for the
C64 that I found on some tape long years ago. When I bought a C16, I dis-
assembled the program and made some minor changes so that it also runs on
this computer. The resulting program TTAPE16.PRG was published in some
"Sonderheft" for the C16/Plus4/VC-20 of the German "64'er Magazin". The 
program TTAPE162.PRG is a variant of TTAPE16.PRG for C16's with at least 
32 kBytes of RAM. Last but not least, the DOS executables TTLOAD.COM and 
TTSAVE.COM allow a PC with Datassette and X1541 cable/adaptor to load and 
save programs in Turbo-Tape format.

Here is a list of the files in this archive:

README.TXT      the file that you are reading just now
TTAPE64.PRG     Turbo-Tape for the C64
TTAPE16.PRG     Turbo-Tape for the C16/Plus4
TTAPE162.PRG    Turbo-Tape for the C16/Plus4 with at least 32 kBytes RAM
TTLOAD.COM      Turbo-Tape loader for the PC
TTSAVE.COM      Turbo-Tape saver for the PC
TTCONFIG.COM    Configuration software for TTLOAD.COM and TTSAVE.COM

3. Turbo-Tape for Commodore computers
=====================================

3.1 How to transfer the Turbo-Tape loader to my Commodore?
----------------------------------------------------------

Well, here occurs the first problem. How do I put the *.PRG files on a
1541 disk or on tape so that my Commodore computer can load them?
Of course, if this step has been taken once, then tape based data transfer
between Commodore computers and PCs is no more a problem. 
But thanks goodness, there are several possibilities, for example 

  * to transfer the files with Kermit or some other terminal program over
    a null modem serial cable, 
    
  * to connect a 1541 floppy to your PC (see [3] below) or

  * to use the tool cbmtt100.zip which can be found in [4] or [5] and
    which enables the PC to write a Datassette in the original Commodore
    format. This is the preferred solution, because cbmtt100.zip has
    the same hardware requirements as TTLOAD/TTSAVE, namely a Datassette
    and an X1541 cable/adaptor.

The last chance would be to use a monitor and to hack in the code one byte
after another. Since the Turbo-Tape *.PRG files are quite small (<1kByte),
this is possible, but I would first try other solutions.

3.2 How to use Turbo-Tape on my Commodore?
------------------------------------------

Okay, let's assume that you have taken the above step and that you have a 
file called "TURBO-TAPE" (one of the *.PRG files according to your computer) 
on your floppy disk. After doing

  LOAD "TURBO-TAPE", 8
  RUN

you have the following additional BASIC commands which work analogously to 
SAVE and LOAD, but use the Turbo-Tape format rather than the original 
Commodore format:

  <-S           ; save a program with empty filename
  <-S "NAME"    ; save a program with filename "NAME"
  <-L           ; load the next program from tape
  <-L "NAME"    ; load program "NAME" from tape
  <-V           ; verify: compare with next program on tape
  <-V "NAME"    ; verify: compare with program "NAME" on tape

Here, the <- denotes the left arrow which is not part of the IBM-ASCII
charset. Note that on the C16/Plus4, you have to type :<-S instead of 
<-S as well as :<-L and :<-V, because the C16's basic works a little 
bit different.

3.3 Where does the Turbo-Tape code reside in memory?
----------------------------------------------------

The machine code of the C64 version TTAPE64.PRG resides in the area 
between $C000 and $D000, so the maximum program size you can load is 
about 46 kBytes. 

For the C16 version TTAPE16.PRG, Turbo-Tape resides at the end of the 
first 16 kByte block, i.e. between $3C00 and $4000, so the maximum 
program size you can load is about 11 kBytes.

For C16's with more than 16 kBytes of RAM and for the Plus4, this would be 
right in the middle of the available RAM, and so it would unnecessarily
restrict the maximum program size. So there is a variant TTAPE162.PRG 
especially for C16's with at least 32 kBytes of memory, which resides at the 
end of the second 16 kByte block, i.e. between $7C00 and $8000, so that you 
can load programs up to the length of approximately 27 kBytes. 

For C16's with full 64 kBytes of RAM and Plus4 computers, this is also an
unnecessary restriction, but putting the Turbo-Tape routines to the end of 
the available RAM between $EC00 and $F000 would pose additional problems, 
since this RAM lies hidden under the ROM bank. However, I think that in the 
near future, I will find some time and do the job to write an appropriate 
version TTAPE164.PRG.

4. Turbo-Tape for the IBM PC
============================

4.1 What is needed?
-------------------

The PC version of Turbo-Tape TTLOAD/TTSAVE requires a 16 MHz 386SX or better
with at least 256 kBytes of RAM, DOS 2.1 or higher, a Commodore Datassette 
and an X1541 cable/adaptor. You may be lucky that Turbo-Tape even works on an 
old 80286 or 8088 machine, but I didn't try it out.

TTLOAD/TTSAVE only run under plain DOS, since all interrupts are disabled
during loading and saving. Don't run them under Windows 95/98/NT or within
a DOS box of these operating systems.

4.2 How to connect the Datassette to my PC?
-------------------------------------------

The X1541 adaptor connects your Datassette and, if you want, a 1541 floppy 
disk drive to the parallel port of your PC. The schematics of the adaptor can 
be found in [2], but you can also purchase it from there if you don't want to 
play around with a soldering iron.

If you only want to connect a Datassette to your PC, not a 1541 floppy disk
drive, you only need a simplified version of the X1541 cable which is
connected as follows:

Ŀ GND (18-25)
Ŀ
                               +5V                                      
 +5V          
Ŀ                                                        
                MOTOR (+5V)                             
                            
                               READ (10)                                
Ŀ                            
                               WRITE (3)                               
Ŀ              
                               SENSE (12)                             
Ŀ                              
                                       
      Datassette connector                                             
				    Ŀ       
    parallel port connector    (13)   O O O O O O O O O O O O O   (1)   
	(solder side)          (25)    O O O O O O O O O O O O    (14)  
				             
					

The +5V that is needed for the Datassette can't be taken from the PC's
parallel port. Use a separate power supply or, if it exists, the game port.

No guarantee is given for the correctness of this schematics, and I won't
take any responsibility for possible damages. So please also have a look 
at [2] to be sure that you made the right connections.

4.3 How to use Turbo-Tape on my PC?
-----------------------------------

First you have to copy the files TTLOAD.COM and TTSAVE.COM to a directory
that is in the search PATH. But that was already clear to you, wasn't it?

Turbo-Tape loads and saves Commodore program files in .PRG format, i.e. files
that contain as their first two bytes the start address of the program in lo-
hi-order. It is the same format in which program files are stored on a 1541-
readable floppy disk.

Let's assume that you have connected a Datassette to your PC as described
above and that there is a cassette in the Datassette. To save the .PRG file
hello.prg in Turbo-Tape format under the name "hello world" on the cassette,
just type

  TTSAVE hello.prg "hello world"

and follow the instructions appearing on the screen. The second parameter
must always be in quotes, the first mustn't at all. However, the second
parameter is optional. If you leave it away, then the file is saved under
the name given in the first parameter.

An additional option -1 allows you to save the program file with secondary
address 1.

To load the file "hello world" from the tape and to store it in the disk file
hello.prg, just type

  TTLOAD hello.prg "hello world"

and also follow the instructions that appear on the screen. As above, the
second parameter must always be in quotes, and the first mustn't at all.
Furthermore, the second parameter is optional in this case, too. If it isn't
specified, then the next file on tape is loaded and stored as hello.prg on
your disk.

Loading and saving can be interrupted by pressing the STOP button on your
Datassette. Since all interrupts are disabled during loading and saving,
there is no other way to intterrupt TTLOAD and TTSAVE.

4.4 How to configure the Turbo-Tape software?
---------------------------------------------

The configuration software TTCONFIG.COM allows you to change

  * the address of the parallel port via which TTLOAD/TTSAVE communicate with
    the Datassette,

  * the address of the counter chip that is used to measure pulse lengths,

  * the average length of a pulse which is used by TTLOAD to distinguish
    between short and long pulses, and

  * the timings that TTSAVE uses to write signals to tape.

So if you prefer using LPT2 or some other parallel port rather than LPT1, or
if you have a non-standard PC which doesn't have its counter chip at the port
address 64, then you can change the appropriate values. For this purpose,
copy TTCONFIG.COM to some directory which is in your search path, go into the
directory in which TTLOAD.COM and TTSAVE.COM reside (very important) and
start TTCONFIG by typing the command

  TTCONFIG

The program will fetch TTLOAD.COM and TTSAVE.COM and show the above mentioned
values so that you can change them by choosing the appropriate program point.
When quitting TTCONFIG, the modified versions of TTLOAD.COM and TTSAVE.COM
are written back to disk.

If you have problems with load errors, or if you just want to find out the
maximum speed at which your Datassette still works properly, then play around 
with the timings. If there were problems that you could get rid off by 
adjusting the timings, then please drop me a note so that I can make future
versions more reliable. My email address is given at the end of this
document.

4.5 Known problems
------------------

Since all interrupts are disabled during saving and loading, the clock 
counter isn't incremented properly, so the clock is significantly wrong after
several calls to TTLOAD or TTSAVE. This could be avoided by synchronizing the 
clock with the CMOS real time clock after each tape access, which will be
implemented in some future version.

5. Turbo-Tape format specification
==================================

1. A bit is represented by a pulse of the following form:

      
   hi                             Ŀ
                                                          
                                                          
   lo                             
      
       time
	   t0         space         t1         mark          t2

   The pulse length t2-t1 is approximately 217us for a 0-bit and 326us for 
   a 1-bit, i.e. a 1-bit pulse is 1.5 times longer than a 0-bit pulse. Since 
   the C64 is only able to recognize a hi-lo transition, the exact position 
   of t1 is of minor importance. However, it should be approximately in the 
   middle between t0 and t2.

2. A byte is represented by a sequence of eight pulses where the first pulse 
   represents the most significant bit, and the last pulse represents the 
   least significant bit. So for example, the byte $8A is represented by the 
   pulse sequence 10001010.

3. A tape file consists of a header block and a data block. There is no gap 
   between these two parts, i.e. the first pulse of the data block immediate-
   ly follows the last pulse of the header block.

4. The header block has the following form:

   1271 = $4F7 times $02                ; long sync
   $09 $08 $07 $06 $05 $04 $03 $02 $01  ; countdown
   $01                                  ; key for 'header block'
   $XX $XX                              ; start address
   $XX $XX                              ; end address plus 1
   $XX                                  ; secondary address, normally $00
   187 = $BB bytes CBM-ASCII            ; filename, filled up with blanks $20

   The start address gives the position to which the data has to be loaded.
   The end address plus 1 points to the position just behind the data. So the 
   difference between these to values is the data length n. Both values are 
   given in little-endian format, i.e. the least significant byte is the 
   first one, as it is usual in the 6502 world.
   Note that the header contains, if the overhead for sync, countdown and key 
   is not regarded, exactly 192 bytes. This is the length of the C64's tape 
   buffer.
   The header block has no checksum.

5. The data block has the following form:

   503 = $1F7 times $02                 ; short sync
   $09 $08 $07 $06 $05 $04 $03 $02 $01  ; countdown
   $00                                  ; key for 'data block'
   n bytes data                         ; data, n is specified in the header
   $XX                                  ; checksum
   256 = $FF times $00                  ; for safety reasons

   The checksum is the XOR value over all n bytes of data. In other words,
   if you XOR the n data bytes and the checksum, you must get the value $00.
   The data length n is the difference between the end address plus 1 and
   the start address which are both given in the header.

6. Further comments
===================

You may freely copy and distribute this software. However, I won't take
responsibility for any damages that are caused directly or indirectly by
using it. If you have problems or suggestions, or if you are a native
English speaker and find some errors in this README.TXT file or in the
output ot the programs, then feel free to write some comments to

  ajung@informatik.uni-rostock.de .

Have fun!

7. Related WWW links
====================

[1] http://www.phs-edv.de/c64s                        C64S Home Page (Europe)
[2] http://www.phs-edv.de/c64s/doc/lpt64.htm          C64S Adaptor Scheme
[3] ftp://ftp.funet.fi/pub/cbm/transfer               Transfer Software
[4] ftp://ftp.funet.fi/pub/cbm/transfer/datassette    Datassette Transfer
[5] http://cia.c64.org/tools                          Further Tools

--
Andreas Jung, November 1998
http://www.informatik.uni-rostock.de/~ajung
mailto:ajung@informatik.uni-rostock.de
