SIO2BSD version 1.17
====================
(c) 2005-12 drac030@krap.pl

This program is for an Unix box (preferably FreeBSD) and SIO2PC cable. It 
serves as a replacement for APE.

1. Terms of copying and use
2. Configuration
3. Turbo modes
4. Basic usage
5. PCLink
6. Acknowledgements

Terms of copying and use
------------------------

See COPYING file for detailed information.

Configuration
-------------

You may need to adjust the Makefile to properly define the path to the 
serial device and such.

Turbo modes
-----------

In order to use baudrates faster than standard 19200 the program must be 
recompiled with the -DULTRA assigned with the SIO multiplier. This will 
enable the UltraSpeed protocol. There are three possible values:

-DULTRA=1
-DULTRA=2
-DULTRA=3

corresponding to 1x19200, 2x19200 (38400) and 3x19200 (57600).

On my setup (a notebook, Pentium III 1.2 GHz, Prolific COM<->USB 
converter, FreeBSD 6.1) I get stable I/O at 38400. At 57600 it only works 
one way, i.e. transfers to the Atari (aka SIO reads) work fairly well, but 
when things go to SIO writes, serious problems begin.

Changing the converter to ELCOM EM213 (using the FTDI chip) allows to get 
a stable I/O at 57600.

The reason why it is so weird seems to have something to do with the 
baudrate precision. Namely, reads work, because the PC generates precisely 
as many bits per second as told to, and the Pokey buys it. But the 
baudrate generated by Pokey differs too much from the baudrate expected by 
the other side, and so the COM<->USB converter has problems transmitting 
larger data blocks (small ones, like 4 byte command + CRC, must be 
transmitted properly, otherwise the reads wouldn't work either).

If the turbo mode doesn't want to work stable for you, you may try to bump 
the kernel scheduling timer frequency on your system. On FreeBSD this is 
made by changing a sysctl "kern.hz". Set this to something around 1600 Hz.
On Linux machines it's possible only by recompiling kernel with options:

CONFIG_HZ_1000=y
CONFIG_HZ=1000

in .config file or by checking option "Timer frequency" at menu "Processor
type and features" and setting 1000Hz frequency with menuconfig.

As of version 1.11 the default turbo baudrate is adjustable without 
recompiling the program. You just need to specify -b n in the command 
line, where n is 1, 2 or 3 as above.

Starting with version 1.11 it's possible to set turbo baudrate by using 
POKEY AUDFx setting directly (aka HSINDEX). You need to set -i hsindex 
from command line.

Starting with version 1.14 it's posible setting of POKEY clock frequency 
by using of -q option. Valid values are:

- "pal" - 1773447 Hz,
- "ntsc" - 1789790 Hz,
- "ntscf" - 1789772.5 Hz (NTSC machines with Freddie),
- value of clock in Hz, for example "1789772.5".

A lack of -q option assumes average pal and ntscf frequency (1781610 Hz).

A typical command line which selects HS Index 1 could be thus:

./sio2bsd -q pal -i 1 foo.atr

Basic usage
-----------

./sio2bsd foo.atr bar.atr baba.atr mak.atr

assigns foo.atr, bar.atr, baba.atr and mak.atr to D1:, D2:, D3: and D4: 
respectively. You can attach up to 15 disk images this way.

./sio2bsd - foo.atr - - bar.atr

assigns foo.atr to D2: and bar.atr to D5: leaving D1:, D3: and D4: 
unassigned.

./mkatr

displays usage of an utility to make ATR files.

Invoking the program without parameters gives you a list of additional 
options.

PCLink
------

If you specify a directory instead of an ATR file in program's option, the 
directory will get mounted and will serve as a "PCLink" device.

The difference between the PCLink and the traditional approach is that in 
the latter the PC handles sector I/O requests. This has one disadvantage, 
namely to allow the access to the PC disk directly from the Atari, the PC 
program has to emulate entire file system and guess from sector writes and 
reads which data are actually for what file.

Some programs accomplish that, but they rely on an undocumented behaviour 
of the AtariDOS, namely on the actual *order* of sectors it uses when 
writing a file to the disk (that is: that it accesses VTOC/DIR on the 
opening, data area on the write, and VTOC/DIR again upon closing).

That seems logical at first glance, but is of course not true for more 
complex DOS-es, which use sector cache, such as SpartaDOS X. Queued sector 
buffer may disturb the named order, and then the PC program, which relies 
on such behaviour, of course fails (and a real disk drive does not).

The other disadvantage of such a solution becomes evident, when one uses 
SpartaDOS - the emulated FS is the AtariDOS FS for its simplicity. This 
unfortunately also means crapiness. SpartaDOS can access such disks, but 
they miss some information such as timestamps, and also have limitations 
such as 64 files per directory. Therefore usage under SpartaDOS is rather 
inconvenient. At the other hand, emulating SpartaDOS fairly complex 
filesystem is a complex task, also made more difficult by the sector cache 
named above.

Hence the idea of PCLink - a PC program, which, when connected via Sio2PC 
cable to the Atari, would process not the low-level sector I/O commands, 
but high-level DOS requests. Therefore, when PCLink is active, the 
commands sent by the Atari are not READ SECTOR or WRITE SECTOR, but OPEN 
FILE, READ BLOCK, CLOSE FILE.

At Atari side a DOS driver is necessary, of course, and such a driver is 
available for SpartaDOS X 4.4, called PCLINK.SYS. Once loaded, it installs 
a DOS device called "PCL:", which works similarly as already existing CAR: 
(with the one exception that PCL: is writable). Use regular DOS commands 
(DIR, COPY etc.) to access files stored directly on PC disk.

Acknowledgements
----------------

Many thanks to mikey for updating the Makefile for Linux, and to Mono for 
the FTDI cable, testing and general coding support.

Have fun
drac030@krap.pl

Warszawa, 22.X.2011.
