
                            TOSBOX documentation
                            An Atari ST emulator
                                version 1.07


Copyright (c) 1997, 1998 by:

Mark Slagell
3716 Ross Road
Ames IA 50014
USA

  ------------------------------------------------------------------------
** What it is **

TOSBOX provides an environment for running TOS and GEM applications under
DOS or Windows. It uses an operating system image which you can create on
your actual Atari machine, and operates with most of the PC's peripherals.

The design of TOSBOX is unique in working from the system down rather than
from the hardware up. The goal was not to make a PC behave as exactly as
possible like an ST, but to run Atari applications as smoothly as possible
on a PC. Whenever possible, system calls were redirected and translated;
then, only in cases where that failed to be reliable, the behavior of the
actual hardware behavior was emulated. The resulting product is able to run
a considerable variety of popular software. I am interested to hear your
results on specific programs so I can make note of conflicts in future
documentation and continue to improve compatibility.

I wish to emphasize that TOSBOX is not a complete hardware-level emulation
of an Atari ST. As such, it is not intended to run games and graphics
demos. For that I suggest using PaCifiST, by Frederic Gidouin.

The CPU emulation core is written in assembly language, and its speed on a
Pentium 75 is typically about twice that of a stock STf, depending on the
task.  On a now typical 200mhz+ machine, it runs more like ten times as
fast as a stock STf. Because of the design objectives described above,
TOSBOX does a disproportionate amount of its work in the PC domain rather
than in CPU emulation, so in practical terms it generally works faster than
the numbers would suggest.
  ------------------------------------------------------------------------
** Requirements  **

You need ordinary VGA graphics (though an SVGA card that complies with VESA
1.2 or higher is recommended), a mouse and mouse driver, at least 4 megs of
memory, and a hard drive. Because TOSBOX runs in 32-bit protected mode, you
also need a '386 or newer processor. Finally, you need a TOS image file
derived from your Atari computer. ROMIMAGE.TOS, included in this archive,
will make that for you.

Supported TOS versions include 1.00, 1.04, 2.05 and 2.06. According to user
feedback, TOS 1.02, 1.06, 1.62 and an enhanced 2.06 called "SUPERTOS" are
all supposed to work. "KAOSTOS" is apparently too heavily modified for
TOSBOX to recognize it.
  ------------------------------------------------------------------------
** Summary of changes in this version **

   * It is possible to read data from old ST-formatted floppies.
   * New 1280x1024 video modes (2, 4, 16 colors) are supported.
   * There is a new integrated screen saver.
   * Setup for the first-time user is simplified so that in most cases it
     is not necessary to edit the initialization file.
   * CPU emulation has been expanded and enhanced: the BCD instructions
     were added, and some bugs in the handling of the X flag were fixed.
   * Support for the hardware video address counter was improved.
   * Omikron BASIC compiled programs now run without modification.
   * A new ST-domain desk accessory, TB.ACC, is included to help with a
     number of fundamental tasks.
   * Printer support now includes "use prn", which assigns the virtual
     parallel port to the system default printer. This has several benefits
     (see technical notes below).

  ------------------------------------------------------------------------
** Shareware and distribution rules **
TOSBOX is inexpensive by PC shareware standards, priced at $15 (US).
Payments and other correspondence may be sent to the address at the top of
this document. I can be contacted via email at bald_soprano@usa.net.

In Europe, you can register through Joe Connor's Interactive service;
consult the registration materials in EUROPE.ZIP or visit his web site at
http://www.cix.co.uk/~inactive/.

Permission is hereby granted to copy and distribute TOSBOX through
non-commercial channels, as long as the original ZIPped archive is provided
without modification.

  ------------------------------------------------------------------------
** Starting TOSBOX **

If you do not already have a TOS image file, create one using the supplied
program (ROMIMAGE.TOS) on your Atari computer.

Copy the TOS image file to the directory containing TB.EXE, and run TB.  To
exit, use the included TB.ACC desk accessory, or press control-Break.

The initialization file, TB.INI, provides many options for controlling the
behavior of TOSBOX. It contains comments explaining most of thosee options,
and it can be viewed or customized with any text editor.  You may find it
useful to have more than one initialization file for different tasks. If
so, specify in the command line which one you want to use, for example, TB
FOO.INI.

  ------------------------------------------------------------------------
** Recommendations **

The higher the screen mode you select, the more horsepower your machine
needs. Not only is the VDI working harder, but the emulator has to throw
around a lot more data between ST memory space and the PC's video memory. A
486/66 is enough for the ST-compatible modes, but you need something
considerably faster if you want to run in 1024x768x16 without spending a
lot of time waiting around for redraws.  You might find you need to use TOS
2.05 or 2.06 to make the 800x600 and higher modes run properly.

As with an ST, a graphics accelerator is in some cases desirable. The most
popular accelerators (NVDI, Warp 9, Turbo ST) are reported to be compatible
with TOSBOX, though Turbo ST is only effective in the ST video modes. NVDI
users report varying success; generally speaking, later versions of NVDI
are more compatible with the custom video modes, and 16-color modes tend to
be more stable than 4-color modes.

On the other hand, PCs have become so fast that in many cases now, the
graphics speedup provided by NVDI and others may be outweighed by the
improved overall compatibility that is achieved without them.

Use an alternate desktop, especially if you use the custom screen modes. If
you don't have Neodesk, get Thing, Teradesk, or Ease.

Make SERIALFX or HSMODEM a permanent fixture in your AUTO folder. This is
important because the serial interrupt code built into TOS has always had
buggy flow control, and most PCs have relatively fast modems.


  ------------------------------------------------------------------------
                              TECHNICAL NOTES
  ------------------------------------------------------------------------
** Video **

Standard ST modes are provided for the sake of compatibility. Modes beyond
640x400 require TOS 1.04 or higher, and the SVGA modes require compliance
with VESA 1.2 or higher. A list of supported modes can be found in the
TB.INI comments. If you request a mode that for some reason cannot work
with your PC or your TOS version, a lower-resolution mode with the same
number of colors will automatically be selected.

Custom color modes are locked in and cannot be changed via Setscreen(), so
attempting to switch between low and medium res from the Atari desktop will
have unpredictable results. Since the system is prevented from choosing a
video mode itself, TOSBOX writes the correct resolution into the
DESKTOP.INF or NEWDESK.INF file, if it can be found, and then the desktop
synchronizes itself to that mode. Therefore, if menus don't drop and
retreat correctly, save the desktop and reboot the emulated ST.

As an accommodation to programs that neglect to read the VDI work_in[]
array, there is an "extend Getrez" command designed to keep those programs
from halting because they are sure, for instance, that ST mode 0 has to
mean a 40-column display. Specifically, the modified return value for
Getrez() is 5 for custom 4-color modes and 4 for custom 16-color modes.
This will convince some applications that TOSBOX mode 5 (640x480, 16
colors) is TT medium. Since this is a significant deviation from standard
ST behavior and confuses some properly-written software including Geneva,
it is a switchable option; uncomment the "extend Getrez" command in the
init file to enable it. When the option is disabled, all custom modes
return a Getrez() value corresponding to the ST mode with the same number
of color planes.

Vertical blanking is implemented, but horizontal blanking is not. The
display is refreshed at a variable rate, more frequently when keyboard or
mouse activity has been recently detected, less frequently otherwise to
optimize CPU emulation. (This feature can be disabled, giving constant
screen refreshes with a slight speed penalty; see the TB.INI comments.)
Refresh rates are automatically adjusted somewhat according to screen size.

Windows 95 does not fully support the 800x600 and higher planar VESA video
modes currently used in TOSBOX. For best compatibility you may need to
pause emulation before using Alt-Enter or Alt-Tab; see the FAQ for details.
Also a Windows screen saver can cause trouble when it interrupts a program
using one of those video modes.  One workaround is to tell Windows to
exempt TOSBOX from the screen saver (again, see the FAQ); another is to add
a "saver minutes" line to your init file, making sure that minutes is a
shorter interval than you have your Windows screen saver set for.  For
instance if your Windows screen saver starts after five minutes, specify
"saver 4" in your init file; then after 4 minutes of keyboard/mouse
inactivity, TOSBOX will display a blank screen in a text video mode, and
then later when the Windows screen saver engages, it will behave properly
because all it sees is a simple text-mode program running.

When TOSBOX is in its own screen saver mode, emulation is not paused; you
just can't see the ST screen.  Pressing any key restores normal ST video.

  ------------------------------------------------------------------------
** Blitter **

Blitter emulation is most useful in situations where there is no graphics
accelerator in place. On average it is faster to use the blitter than not,
but it is still not quite as fast as the real thing in hardware; it cannot,
on its own, compete with a good software accelerator like NVDI.

Known problems with the current blitter emulation:

  1. HOG mode is always used, which helps speed, but sometimes interferes
     with mouse and keyboard response because the ST interrupts are locked
     out during a large blit.

  1. When the blitter is fed a bad address (source or destination), it can
     crash not just the virtual ST but the emulator itself.

If you don't want to use the blitter, I recommend removing or commenting
out the "blitter" line in the TB.INI file because this is more reliable
than turning it off from the desktop.  The speed of a modern PC is such
that you probably don't need the blitter anyway.

  ------------------------------------------------------------------------
** CPU **

Almost all opcodes are emulated. A few instructions that I have not seen
used in any ST programs will produce an "undefined opcode" message if they
are encountered; please notify me if this happens.

Most bus errors and privilege violations are detected, but odd address
errors are not. Other known quirks:

   * 1. ASL and LSL are the same instruction. The 68000 treats the overflow
     bit differently for ASL.
   * 2. The trace bit has no effect except when it is popped off the stack
     via RTE.
   * 3. The stack offset is correct after bus errors so that programs that
     trigger them intentionally (including the ST desktop itself) can
     generally recover properly, but don't rely on any specific information
     on the stack.
   * 4. The $003f opcode, which is illegal on a real 68000, is reserved for
     certain internal functions.

  ------------------------------------------------------------------------
** Memory **

It is possible to have up to 14 megs of ST memory. If no request is
specified in TB.INI, the default is 1 meg.

Depending on your DPMI host, TOSBOX might use virtual memory if there is
not enough RAM to satisfy the request. This feature is a mixed blessing; if
the boot process takes too long, or programs slow to a crawl while the hard
drive keeps spinning, try reducing the memory request. If too much RAM is
requested and your DPMI host doesn't provide virtual memory, a smaller
amount will automatically be allocated.

  ------------------------------------------------------------------------
** GEMDOS **

Disk drive emulation is done entirely at the GEMDOS level. All PC drives
can be used, including CD-ROMs and high density floppies.

Swapping of A: and B: on single-floppy systems is handled by the host PC,
which instead of giving you the familiar alert box, displays an "insert
disk and press key" message superimposed over the ST screen. Press alt-end
to clean that off afterwards if necessary. There should be little need for
drive swapping on a modern machine with a hard drive, but some older
applications may insist on doing it anyway. Swapping is disabled if there
is no "mount B" line in the init file.

Mounted directories allow you to protect data from the emulator. For
instance, you may want to hide the root directory of your PC's boot drive
(typically with a line like mount C C:\ATARI in the init file) if you're
worried about your five-year-old kid dragging a drive icon to the trash.

Filenames that are legal under TOS but cause errors under MS-DOS are
modified in a simple way: all illegal characters are mapped into the
128-255 range by setting the high bit.

Files and folders are manipulated in customary ways. Directories may be
read using Fsfirst/Fsnext, but not from the file allocation tables
themselves. A few low-level disk functions (Floprw, Flopwr, Flopfmt,
Flopvfy, Rwabs) are incompatible or unsafe to use with mounted directories
and therefore just return error codes.

I have seen one CPX module that tries to determine drive space using
Getbpb() instead of Dfree(), so Getbpb() is partially supported, not enough
to supply all the correct information, but enough to keep that CPX from
crashing.

The redirection functions Fforce() and Fdup() are implemented only with
respect to Fread() and Fwrite().  Redirection has not yet been implemented
for Cconout() and similar functions.

The following characteristics of GEMDOS differ from MS-DOS but have been
faithfully emulated:

   * Files opened in mode 0 can be written to, if they were not read-only
     to begin with.
   * Filenames are allowed to have an extra extender, but only the first is
     used; FOOBAR.ABC.DEF and FOOBAR.ABC refer to the same file.
   * Wildcards can be used directly when opening files.

  ------------------------------------------------------------------------
** Floppy support **

As of version 1.07 it is possible to retrieve data from old ST-formatted
floppy disks.  Add a line like this to the init file (note that instead of
H you can use any drive letter not already assigned in the init file, and
the source drive can be A: or B:):

  floppy mount H A:

To read an ST floppy, pause emulation, then press the F key (there is a new
entry on the monitor screen to indicate this choice).  In the above
example, the contents of the disk in PC drive A: are loaded into what
appears within emulation as a new read-only drive H:,  with the original
directory structure and file time/date stamps intact.  From there the data
can be copied to any other location, including a PC-formatted floppy if
desired.  You will not be able to read copy-protected or corrupted disks,
but you should have no trouble with most nonstandard extended formats
employing extra sectors and tracks.
  ------------------------------------------------------------------------
** Desktop **

Resolution changes are only supported when you start up in one of the
standard ST screen modes. In the custom color modes, trying to switch
resolutions from the desktop will confuse the AES, but you can usually
switch back easily enough.

In general, the 4-color modes do not work as well as the 16-color and
2-color (mono) modes. I am not sure of the reason for this.

One unusual -- if not necessarily useful -- feature of TOSBOX is that you
can launch not only Atari programs but DOS programs as well, provided you
inform your desktop program that EXE, COM and BAT are executable filetypes.
This requires hand-editing DESKTOP.INF or NEWDESK.INF if you're using the
built-in Atari desktop. Some work remains to be done on DOS program
launching, because the startup directory is not always correctly determined
and filenames in the command line are not yet translated out of the mounted
directories. It cannot launch Windows programs at all under Windows 3.x,
though it can be done in some circumstances under Windows 95/98.
  ------------------------------------------------------------------------
** Keyboard **

The method used for detecting and reporting keypresses is unique, and seems
to be mercifully free from the glitches and lockups that plague at least
two other emulators. There are two limitations: first, programs wanting to
sense more than one alphanumeric key being held down at a time cannot do
so, but that is a very uncommon practice except in games anyway; second,
the mouse cannot be 'clicked' from the keyboard using alt-insert or
alt-home, though the alt-arrows work.

If you enable kbrate in the init file, the control panel is allowed to
change the keyboard delay/repeat settings, and TOSBOX attempts to restore
the original values on exit. Since some PCs do not allow the settings to be
read reliably, the keyboard settings are tied to the host PC's settings by
default.

Some of the PC special keys are mapped as follows (note that
Lshift-cntrl-end can be redefined according to your preference, as
described in the init file comments):
    page up              shift - up arrow
    page down            shift - down arrow
    end                  shift - right arrow
    shift - end          shift - left arrow
    F11                  Help
    F12                  Undo
    cntrl - break
    Lshift - cntrl - end {stop the emulator}
    alt - end            {manually refresh screen after a floppy swap}
    home                 {mode dependent - see below}

The IKBD clock is read-only, and implemented at the XBIOS level.

With NumLock off, the numeric keypad works pretty much as on the regular
PC.

The Home key can work in two different modes. By default, it behaves like
the standard Atari Clr/Home key. Also available is a native PC mode that
makes Home the intuitive counterpart of End: just as End normally maps to
shift+right, Home then maps to shift+left. This only applies when no
modifiers (shift, control, alt) are used. To make the emulated ST see a
normal unshifted Home key while in this mode, press control+shift+home.

You can switch between the default and PC home key modes at any time, by
pressing shift+shift+Home. To make the PC mode the default when TOSBOX
starts, add this line to your init file:
   PC home key
  ------------------------------------------------------------------------
** International keyboard adjustment **

To improve keyboard behavior on machines set up for languages other than
English.  Add this line to your init file:

  auto ascii 20 7f

Because this is an experimental feature, further documentation will be
added only after more testing has been done and I have learned more about
its effects from some international correspondents. It is hoped that it
will prove stable and useful enough that the key sub feature (see the init
file comments) can be eventually considered obsolete, and eliminated.
  ------------------------------------------------------------------------
** Mouse **

A mouse driver must be installed before TOSBOX runs. In most situations you
don't need to worry about this. But if you find that the TOSBOX mouse
pointer can be moved when running from Windows but not from DOS, you need
to install a DOS-mode mouse driver. Consult the FAQ for instructions.

For better compatibility with certain unusual mouse drivers, TOSBOX no
longer refuses to run when it cannot immediately detect a driver, though it
does briefly display a warning message. You will only know for sure that
there is a problem if the mouse pointer refuses to be moved.
  ------------------------------------------------------------------------
** Serial port **

The ST serial port is emulated at the hardware level. It can be mapped to
any of the four PC COMx: devices, at speeds up to 115200 baud.  Flow
control is supported in hardware (RTS/CTS), as are the DCD, DTR and Ring
Indicator lines and their associated interrupts.  Because Atari never quite
got it right in TOS, proper use of RTS/CTS requires installation of a patch
program in the AUTO folder; I've had good luck with SERIALFX.

Users in England, and nowhere else as far as I know, have reported
difficulty establishing PPP and SLIP connections.  I acknowledge the
problem but don't know where to begin fixing it, since it can't be
reproduced here.  If anyone can give me more detailed information to help
with that (or room and board and airline tickets), I'll see what I can do.
  ------------------------------------------------------------------------
** Parallel (printer) port **

In the beta versions of TOSBOX, the parallel port was emulated at the
hardware level only. That code is still in place, but from version 1.00
onward, the GEMDOS and BIOS calls that speak to the parallel port do so
directly, with the result that they are now almost as fast as writing to
the hardware registers.

You may at first experience significant delays in printing because of the
way Windows spools DOS printer output; if you don't like this behavior,
there are three known solutions.

1. Assign the virtual parallel port to the default system printer, that is,
file device PRN. Do this by specifying:

 use prn idleticks

in the init file.  TOSBOX will flush and release the printer device
whenever idleticks 200hz ticks have elapsed since the last information was
sent by your program.  1000 ticks corresponds to five seconds.  Besides
just giving you more reasonable printer response times, using prn instead
of lptx for the ST parallel port has these advantages:

   * The TBC.ACC accessory allows you to also flush the printer manually,
     in case you ever need to do that.
   * On-demand opening and closing of the prn device means other processes
     on your PC will be able to use it when necessary (for instance it is
     possible to start a long printout in a PC application, then start
     TOSBOX without causing a device conflict; when the first job is done,
     TOSBOX will automatically have access to the printer).

2. Or, modify your \WINDOWS\SYSTEM.INI file to contain these lines:

    [Network]
    PrintBufTime=5

    [ifsmgr]
    PrintBufTime=5

An easy way to edit this file is to select "Run..." from the W95/98 Start
menu and type "SYSEDIT".  If the [Network] and [ifsmgr] groups do not exist
in SYSTEM.INI, add them just after the [386Enh] section.  The parameter "5"
here determines the idle time between automatic flushes of the Windows
print queue. Values between 1 and 10 may be desirable; the default is much
higher, reportedly 45 seconds.  Windows typically treats DOS programs as
batch jobs, so such a long delay is assumed to help such programs get done
with their work and exit more quickly.

3. Or, in Windows 95/98, open your "Printers" folder from the control
panel, right-click on the printer you are using, select "properties", then
"details", then "spool settings", then "print directly to printer."  But
this means you lose the capability of spooling print data within Windows,
which is likely to be undesirable, depending on what sort of printer you
have and what kind of work you do.
  ------------------------------------------------------------------------
** Sound **

There is limited sound support.  Only the predefined system sounds are
emulated (the error bell and keyclick). Within the init file, you may
specify that those sounds be disabled, or played through the PC speaker, or
played through a Soundblaster-compatible card.
  ------------------------------------------------------------------------
** Missing features **

There are no plans to support sound or joysticks; get PaCifiST if you need
those. The IKBD command $16 (send single joystick report) always returns
codes meaning "joysticks centered, fire buttons not pressed".

General sound chip emulation may possibly be included someday, if there is
enough interest and I find enough time.

Also there are no plans to emulate the MIDI ports, a 68030 CPU, or any
machine-specific hardware.
  ------------------------------------------------------------------------
** Detecting the presence of TOSBOX **

The approved method, a la PaCifiST, is to call Vsync() with D6 = D7 =
'Emu?'($456D753F). On return, D6 will contain 'TBox' ($54426F78) and D7
will contain the ASCII-encoded version number.

Programmers who don't use assembly can get the same information from ST
memory locations $3f0 and $3f4, unless some application has thoughtlessly
polluted that area.

  ------------------------------------------------------------------------
** The Four Disclaimers **
(with apologies to Michael Feldman)

  1. Use at your own risk. I am confident that the design of TOSBOX ensures
     the safety of your PC's data. Nonetheless, neither I nor any
     authorized agent involved with the distribution of TOSBOX or
     collection of shareware fees shall be held liable for consequences of
     the use or misuse of this program.
  2. All trademarks used in this document are recognized and acknowledged.
     Although Atari is no longer with us, it is my understanding that its
     copyrights and patents belong to JTS and remain legally in force. I do
     not wish to condone or encourage illegal copying of the Atari ST
     operating system.
  3. There is no man so deluded as he who claims enlightenment.
  4. On startup, TOSBOX occasionally displays a message reminding you that
     it is a shareware product. This ceases when the fee is paid. The low
     $15 price point was chosen in the hope that most users would actually
     register, not just a few wealthy or painfully conscience-bound souls.

  ------------------------------------------------------------------------
** Thanks to: **

All the users who have registered, or helped with debugging, or conveyed
their encouragement;

Dan Wilga, for helping me read the entrails of GEMDOS and offering some
welcome advice;

Frederic Gidouin, for writing PaCifiST and convincing me that a patient,
mild-mannered guy without Micro$oftish arrogance can do this kind of thing
after all;

Sam Vincent, for the SVAsync library, around which the serial emulation is
built;

and DJ Delorie and Robert Hoehne, for their work on DJGPP and RHIDE
respectively.
