Copyright © 1997-2000 by:

Mark Slagell
3716 Ross Road
Ames IA 50014
USA
 

Introduction

Requirements

Summary of changes in this version

Shareware and distribution rules

Starting Tosbox

Recommendations

Technical notes

The Four Disclaimers

Acknowledgments

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 to their MS-DOS equivalents; then, only in cases where that failed to be reliable, the behavior of the actual hardware was emulated.

As the above implies, Tosbox is not a complete hardware-level emulation of an Atari ST.  To run games and graphics demos, I suggest you try PaCifiST, by Frederic Gidouin.

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.

You may find that you need to install a separate DOS-mode VESA driver for your video card in order to use some graphic modes.  A suitable driver should have been included on the disk or CD that came with your video hardware.

• The GFA BASIC 3.x EOF bug was fixed, again. :-/

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

1. If you do not already have a TOS image file, create one using the supplied program (ROMIMAGE.TOS) on your Atari computer.
2. Copy the TOS image file to the same directory into which you unzipped Tosbox.
3. Run CONFIG.BAT, which lets you make configuration choices and test them in the emulator.
4. When everything is configured to your satisfaction, you can bypass the configuration step and run Tosbox directly as TB.EXE.

• There are several ways to exit the emulator.  Use the provided desk accessory, or press Control+Break, or press Control+[Left Shift]+Q.
• It is possible to maintain more than one configuration.  The default configuration is stored in the file TB.INI.  To use a different configuration, supply its filename as a command line argument to CONFIG (or to Tosbox).

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.

Contents

Video

CPU

Blitter

Memory

GEMDOS

Floppy support

Desktop

Keyboard

Mouse

Serial port

Parallel port

Sound

Missing features

Detecting the presence of Tosbox

It is important to recognize that even if your video hardware is VESA-compatible, you may have to install a DOS-mode driver before the VESA modes can be used.  If you generally only use Windows programs, you may have never had a reason to think about this before.  So if the custom video modes don't work (or if you always get a lower-resolution mode than you asked for), consult the documentation for your video hardware, or browse the directories of the disk or CD that came with it, or see if the manufacturer has a webpage from which a DOS driver can be downloaded; most manufacturers do.

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.)  Refresh rates are automatically adjusted somewhat according to screen size.

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, it can crash not just the virtual ST but the emulator itself (I haven't observed this for a long time, but don't remember fixing it; so this may or may not be an extant bug. --MS).

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

• 1. The trace bit has no effect except when it is popped off the stack via RTE.
• 2. 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.
• 3. The $003f opcode, which is illegal on a real 68000, is reserved for certain internal functions.

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.

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 drive B: is not mapped in your configuration.

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 by mounting  C: as <cwd> during configuration) 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 (GFA BASIC 3.x relies on this quirk).
• Wildcards can be used directly when opening files.

To read an ST-formatted floppy, first pause emulation, then press the F key.  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.

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.

If you configure Tosbox so that kbrate is enabled, 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 control+[Left shift]-Q can be redefined according to your preference during configuration):

With NumLock off, the numeric keypad works as it normally would in DOS.

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.  You can also choose during configuration whether to make PC mode the default when Tosbox starts.

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.

If you are using Linux DOSEMU under X-windows (command "xdos"), dosemu's internal mouse driver works quite nicely so long as you specify mouse type 4 ("Linux/DOSEMU") in the Tosbox setup program.

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.

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.  When configuring Tosbox, assign the virtual parallel port to the default system printer, (prn: flushed).  Tosbox will flush and release the printer device whenever a short delay has elapsed since the last information was sent by your program.  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).

    [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.

The Soundblaster-rendered error ping did not work properly on some SB clone cards before version 1.10.  This was because the ping sound used a single operator tone (modulator with no carrier).  The Soundblaster mode built into the FIC VA-503A motherboard, at least, does not support this.  So two operators are used in version 1.10.

General sound chip emulation may possibly be included someday, if there is enough interest and I find enough time.  (Note, May 2000: this is looking highly unlikely.)

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

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.

1. Use at your own risk.  I specifically disclaim any liability for the consequences of the use or misuse of this program.
2. Although Atari is no longer with us, it is my understanding that its copyrights and patents belong to JTS (or is it Hasbro, now?) 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 disclaimer #3.
4. There is no disclaimer #4.

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.