AtariSIO driver and utilities V0.30 beta

Copyright (C) 2002-2004 Matthias Reichl <hias@horus.com>

This program is proteced under the terms of the GNU General Public
License, version 2. Please read LICENSE for further details.

Visit http://www.horus.com/~hias/atari/ for new versions of AtariSIO.


Installation
============

Please read the file "INSTALL".


About Atarisio
==============

AtariSIO basically consists of two parts:
- a kernel module to handle the low-level part of the Atari SIO
  protocol, and
- a set of utilities (atarserver emulates Atari floppy disk
  drives, atarixfer can read/write floppy disks from/to a
  floppy drive connected to the PC)

AtariSIO supports the following interfaces:
- one chip SIO2PC (with MAX232), command connected to RI
- one chip SIO2PC, command connected to DSR
- one chip SIO2PC, command connected to RTS
- 1050-2-PC (with MAX232), command connected to RTS
- Ape ProSystem cable (with 14C89), command connected to DTR
   
The old two-chip SIO2PC interface (with a MAX232 and an LS368)
is NOT supported, and probably never will be.

At the moment atariserver supports 2 (and a half :-) different
SIO speeds:
- standard 19200 bit/sec
- 57600 bit/sec
- 57600 bit/sec with short pauses between bytes

The 57600 bit/sec speed is usually called "high speed SIO". This
speed is supported by most high speed SIO routines.

The 57600 bit/sec speed with pauses is only needed if the
high-speed SIO routine of your Atari reacts slightly too slow,
resulting in sporadic (sometimes also frequent) "hangs".


Utilities
=========

Starting with version V0.20 both atariserver and atarixfer support
reading and writing of DCM, DI and XFD images, in addition to the
standard ATR images. Furthermore, transparent compression and
decompression is supported if you compile AtariSIO with zlib support.
This means, for example, that you can directly read and write from/to
an .atr.gz file without needing to (de)compress it by hand.

The file type is determined by examining the file-extension.
Recognized extensions are .atr, .atr.gz, .dcm, .dcm.gz, .xfd, .xfd.gz
(which are not case-sensitive, so .ATR.gz will also work).

In case the image-file has a non-recognized extension (eg. .foo),
the ATR-format is assumed.


Using atarixfer
===============

atarixfer is used to read/write disk images from/to a Atari drive
connected to your Linux box with an 1050-2-PC cable. An APE
ProSystem cable  will also work, but you have to add the
command-line switch "-p".

If you want to write a disk image to a floppy disk, simply
type "atarixfer -w filename.atr".

If you want to read a disk inserted into your 1050 and create
a disk image from it, type "atarixfer -r filename.atr".

That's it - currently there are no more options in atarixfer :-)


Using atariserver
=================

atariserver is an SIO-server, like SIO2PC or APE for MSDOS-machines.

Starting with V0.30 atariserver comes with a new curses frontend.
The old atariserver (with the text-only frontend) is still included
in this package but has to be built and installed separately
(read "INSTALL" for details).

1. Command line options

-h          display help
-c          use alternative SIO2PC cable (command=DSR)
-C          use alternative SIO2PC/nullmodem cable (command=CTS)
-m          monochrome mode
-o file     save trace output to <file>
-p          write protect the next image
-s          slow mode - disable highspeed SIO
-S          high speed SIO mode with pauses
-t          increase SIO trace level (default:0, max:3)
-1..-8      set current drive number (default: 1)
<filename>  load <filename> into current drive number, and then
            increment drive number by one

-h just prints the above help screen.

-c tells AtariSIO that your Atari is connected via an alternative
   SIO2PC cable. The standard SIO2PC cable uses the RI pin for
   command line input. Some Windows SIO emulators use a slightly
   modified SIO2PC cable, using DSR instead of RI. If you are not
   sure what kind of SIO2PC cable you have, just try starting
   atariserver with and without the "-c" switch and test if your
   Atari can boot from atariserver.
   BTW: there's no performance benefit using the DSR line instead
   of the RI line, both cables work identically with AtariSIO.

-C is similar to '-c' except that the CTS pin is used. This is
   quite useful for testing purposes: connect two PCs with a
   nullmodem-cable, start atariserver with '-C' on one machine
   and atarixfer with '-p' on the other.

-m monochrome mode: disable colors, even if your terminal
   reports color support.

-o set trace file: all output displayed in the log-window will
   also be saved to the specified file.

-p loads the next image with "write protect" enabled. This
   option is only valid for the next image, if you want to load
   multiple write protected images, you have to specify this
   options before each filename.

-s disables high speed (57600 bit/sec) SIO support. It sets
   the baudrate to fixed 19200 bit/sec and also disables several
   special commands like "get ultraspeed byte" or "flush disk"
   that are only supported by high-speed drives like the
   1050 speedy. Read the list of SIO commands at the end of this
   README for more details.

-S high speed (57600 bit/sec) mode with pauses between bytes.
   This is needed for some high speed SIO routines which are too
   slow to handle sustained 57600 bit/sec transfers. The effective
   speed will be approx. 48000 bit/sec.

-t increases the trace level. You may use this option up to
   three times if you want more output. Read below for a
   description of the various trace levels

To load several images you could start atariserver with
the following options (for example):

atariserver dos.atr -3 -p data1.atr data2.dcm

This will load dos.atr into D1:, data1.atr into D3: and data2.dcm
into D4:. Forthermore, D1: and D4: will be writeable, whereas
D3: will be write protected.


2. The user interface

The atariserver screen is divided into several regions:

The topmost line show the program version and the current
working directory (or the image name if you display the directory
of an Atari disk image, or some other information about the
currently displayed information).

The window below is the drive status window. It contains the
status of the 8 disk slots. From left to right the following
information is displayed:
- the slot number (D1: to D8:)
- the size of the loaded image in sectors
- the density of the image ('S' = SD, 'D' = DD)
- the write protect status ('W' = writable, 'P' = write protected)
- the modification status (<blank> = unchanged, 'C' = changed since
  last load/write/create operation)
- the full path and filename of the image

Below the drive status window is the current status line.
It displays the currently selected cable type, SIO speed mode,
and trace level.

Next comes the log window. All warning, error, debugging, and
status information will be shown in there.

Below the log window a help line is displayed. It contains some
hints about what input atariserver wants from you.

The input line is located at the very bottom of the screen. All
user input is displayed there.

Some commands (like the 'display directory' command or the file
selection screen) show a big window instead of the drive status
window, the status line, and the log window.


3. User interface commands

You can always abort the current command by pressing '^G' (control-G).

The key-assignment of the user interface was greatly inspired by
SIO2PC. So if you are already familiar with SIO2PC, you'll find
atariserver easy to use :-)

Here's an overview about the currently supported commands:

'q'   Quit atariserver. 

'l'  load a disk image file (ATR/DCM/DI/XFD) into a drive slot.
     The drive slot must be empty, you have to unload it in case
     another image is already loaded in that slot.

'w'  write the image of a disk drive into a disk image file.
     You may either specify a single drive number (1-8) or 'a' for
     'all changed' disks, to quickly write back all images that
     have been changed.

The filename input routine used for both 'l' and 'w' commands
supports filename completion (with the '<TAB>' key), quick access
to your home directory using '~/' at the beginning of a filename,
and a built-in history (accessible with '<cursor-up>' and
'<cursor-down>' keys). You can position the cursor within the line
with '<cursor-left>', '<cursor-right>', '<home>' or '^A' for start
of line, '<end>' or '^E' for end of line. Delete characters either
with '<backspace>' or '<delete>' keys. '^U' clears the whole
input field. If the first key pressed in file input is a standard
(alphanumeric) key, the input field will be cleared.

If you press '^F', the full-screen file selection mode is started:
In this mode the contents of the currently selected directory will
be listed on screen, use '<cursor-up>', '<cursor-down>', '<page-up>'
'<page-down>', '<home>', '<end>' to navigate through the list. You
can also search through the list by pressing the first letter(s)
of a filename. If you press '<TAB>' the next matching file will be
selected. Note: this search is case-insensitve.

Any time you have positioned the cursor over an Atari disk image
file you can view it's DOS2.x directory by pressing '^D'.

'c'  creates an empty image. You have to specify the drive slot
     in which the image should be created and the size. Just enter
     any (empty) drive number and then choose from the following
     image sizes:

     '1' is 90k SD (720 sectors, 128 bytes per sector)
     '2' is 130k SD (1040 sectors, 128 bytes per sector)
     '3' is 180k DD (720 sectors, 256 bytes per sector)
     '4' is 360k QD (1440 sectors, 256 bytes per sector)

     'S' is 1-65535 SD sectors (128 bytes per sector)
     'D' is 1-65535 DD sectors (256 bytes per sector)

     If you entered 'S' or 'D' you'll get asked how many sectors
     you'd like to have in the image. This input routine also supports
     cursor-movement and a history (like the filename input routine),
     but of course no filename-completion or file-selection mode :-)

'u'  unload (free) a disk drive.
     Specify a drive number to unload, or 'a' for all drives.

'x'  exchange two disk drive numbers.

'p','P' write-(un)-protect a disk drive
     Specify a drive number to (un)protect, or 'a' for all drives.
     If you save a drive to an ATR image, the write protect
     flag will also be saved. So this is a simple solution if you
     want a certain image to be write protected permanently.
     Note: this does not work with DCM, DI and XFD images, since these
     image formats don't support a write protect flag!

'd'  display the (DOS2.x) directory of an image.
     Please note that this function only works with DOS2.x compatible
     disk formats (like DOS2.x, MyDOS, Turbo-DOS, ...), but _not_
     with Sparta-DOS disks!

't'  set trace level

's'  set SIO speed (slow, high, high with pauses)

'C'  set SIO2PC cable type

4. SIO trace levels

By default (in debug level 0) atariserver will only print warnings
and error messages related to user input.

In trace level 1 atariserver will output all processed commands
in user readable form.

In trace level 2 atariserver will output all received command
frames in hex, together with the command result.

In trace level 3 atariserver will (in addition to level 2) also
dump the contents of the transmitted data blocks.


ATP format support
==================

Starting with V0.30, AtariSIO contains preliminary support for the
ATP format, version 1.6. The ATP format is an attempt to design an
open disk format suitable for storing copy protected disks (similar
to the APE .pro format).

At the moment the base classes for handling ATP images are already
implemented, and atariserver contains some code to emulate the
Atari 1050 timing. Please note that this code has not been tested
too well, because there is no application to create an ATP
image of a copy-protected disk yet. For now, all you can do is
create an ATP image completely by hand, or convert an (unprotected,
of course) ATR image into an ATP image and then start playing around
with it.

Currently, there are two small tools to start with:
- atr2atp creates and ATP image from an ATR image and
- atpdump dumps the internal structure and timing/status information
          of an ATP image.

If you are interested in the details of the ATP format and/or want
to help creating an application to create ATP images of "real" Atari
disks, please visit the Atari Preservation Project homepage:

http://www.abbuc.de/app/


Troubleshooting
===============

In case you experience troubles with AtariSIO you might consider
enabling debugging output:

At the moment the userspace utilities have debugging enabled by
default. If you (or someone else :-) switched it off, re-enable
it by setting -DATARISIO_DEBUG in the CXXFLAGS and CFLAGS
settings in the Makefile.

The kernel module supports three different debugging levels
(standard: only warnings, noisy, and very noisy) both for the
atarisio driver and the interrupt routine. You can enable
the debugging stuff by setting the "debug=x" and/or "debug_irq=x"
module parameters (default is '0', maximum is '3'). I'd recommend
you start with level '1' and enable the higher levels later.
Please note: debug level '3' is extremely noisy and may itself
cause troubles on slower PCs that can't handle the huge amount
of printk()s, especially in the irq handler!


Behind the scenes
=================

Atariserver emulates almost all commands of an enhanced 1050 drive.
It supports standard (19200 bit/sec) and high-speed (57600 bit/sec)
SIO. High-speed SIO even works on slower PC (like for example my
old 486SX/33).

Speaking of performance: When writing this document the Linux kernel
threads are still non-preemptable. Kernel 2.6 should support this,
but this feature still causes troubles.  Normally, the PC should be
able to respond to a received command frame within some 10mSec. If
another process is running, this process will be interrupted immediately
(due to the use of realtime scheduling priorities). But if a kernel
thread (like the kernel update daemon) is running, it won't get
preempted and atariserver is not able to respond quickly enough. Usually
this is not too bad, since the Atari will retry each command some 14
times, so there's a good chance at least one of those retries will
succeed. But under very bad circumstances the command may still
fail and the Atari will get a timeout error (error 138). So, if
you experience performance and/or reliability problems, try to shut
down as many background processes as you can.

Another source of performance problems are ATA harddisks (especially
old, slow ones) in PIO mode. If possible, enable the (U)DMA mode.
If DMA support doesn't work with your chipset, try to use
'hdparm -u' to enable interrupt-unmasking. Read the hdparm manpage
for more details.

Compared to SIO2PC and APE, atariserver uses a slightly different
philosophy when dealing with (virtual) disk images. SIO2PC and APE
both use a "harddisk type" philosophy: if you loaded a, lets say,
130k (enhanced density) image, the disk will always be a 130k disk
from the Atari's point of view - the Atari cannot change this,
just like you are not able to format a 10MB harddisk with 8MB or
with 20MB.

Atariserver uses a "floppy disk type" philosophy. When you insert
a disk into your 1050, you may choose to format it either with
90k (SD), with 130k (ED) or even with 180k (DD). The floppy disk
itself may store up to 360k (if you have a double-sided drive like
the XF551), so there's no reason why you should be limited to a
single density that you selected a long time ago.

Whenever atariserver receives a "format disk" command, it automatically
creates an image matching the selected format (i.e.: matching the
format the Atari sent via the "percom put" command). This make
copying disks really easy: just fire up your favourite sector copier
on your Atari, and be sure any image is loaded into a virtual disk
drive. When the sector copier finishes, just write the image to an
image file and copy the next disk.

At the moment atariserver only supports memory images. This means,
any changes (eg. writes / format disk) are stored in RAM. Be sure
to write back the changes using the 'w' or 'W' command if you don't
want to loose them!

If you want to write programs using the atarisio kernel driver by
yourself, here's a short introduction:

Most of the "dirty work", like handling timing constraints,
calculating and comparing checksums is already done in the
kernel driver. This means, you don't need to care about it when
writing a user space application.

The atarisio character device driver only supports two types
of operations (besides open/close): select/poll for waiting
for a new command frame, and IOCTLs for all other tasks.
atarisio doesn't support read/write IO (which wouldn't be
too useful anyway).

You can either use the ioctls (as defined in atarisio.h)
or you may use the C++ wrapper SIOWrapper.{cpp,h}.

If you want to do kind of a 1050-2-PC communication with a
connected disk drive, just look into the source of atarixfer.
It's not too complicated at all, in fact the interface is
quite similar to the Atari SIO call $E459.

In sioserver mode, you have to poll for the receipt of a command
frame, and then implement the rest of the SIO protocol 'by hand'.
Have a look at the source code (AtrSIOHandler) and try to get
the SIOspecs.pdf from the 'net.

******************** IMPORTANT NOTICE: *********************
* If you want to modify atariserver, either test it as     *
* a normal user (to disable realtime scheduling), or take  *
* the necessary precautions! Otherwise an endless loop     *
* might completely lock up your computer and you'll have   *
* to do a hard reset!                                      *
* A simple, but very effective solution for this problem   *
* is to un-comment the three lines of code in the          *
* set_realtime_scheduling function in atariserver.cpp that *
* will install an ALARM handler. This will shut down       *
* atariserver 5 minutes after startup. So if your PC locks *
* up, just wait a few minutes and everything will be fine. *
************************************************************

Finally, here's a list of the currently supported SIO commands.
The commands marked with an asterisk (*) are only available when
the high speed mode is activated.

0x20 - (*) format disk automatically (Speedy command)
0x21 - format disk (uses percom config)
0x22 - format enhanced
0x3f - (*) get ultra speed byte (returns 8 in high-speed mode)
0x4e - percom get
0x4f - percom put
0x50 - put sector
0x52 - read sector
0x53 - get status
0x57 - write sector (that's handled identically to put sector)
0x68 - (*) get SIO code length in bytes
0x69 - (*) get high speed SIO code, relocated to address found in
       AUX1 and AUX2

The following commands are just ACK'ed, but don't do anything:

0x44 - (*) configure drive (Speedy)
0x4b - (*) slow/fast config (Speedy)
0x51 - (*) flush drive cache (Speedy)


Credits
=======

Thanks to:

Atari Bit Byter User Club (ABBUC) for the 6502 highspeed SIO code.

Jindroush for the DCM codec and DI format documentation.

Bill Kendrick, Christopher Lang, Thomas Havemeister, Ryan Underwood
and many others for testing & submitting bugreports!

Freddy Offenga, Stephan Dorndorf and all other members of the
Atari Preservation Project for their work on the ATP format.


You have reached the end of the document
========================================

If you still have any problems, found a bug, have some ideas for
future versions, or if you just want to talk to me, feel free to
contact me by email at <hias@horus.com>.

so long,

Hias
