============================================================================ ACORN ATOM EMULATOR v1.32 (c) Wouter Ras, Delft, Oct 1997 - May 1998 ============================================================================ CONTENTS -------- 1. Introduction 2. Configuration 3. Keyboard 4. Emulator desktop 4.1 Disk 4.2 Tape 4.3 Options 4.4 Monitor 5. ATOM Memory 5.1 ROM 5.2 RAM 5.3 I/O-devices ù PPIA ù VIA ù FDC ù BoxSwitch ù Printer ù Mouse 6. File transfer 6.1 The AtomTape utility 6.2 The AtomCom utility 7. Compatibility 8. Version history 9. Problem solving 10. References 11. Contacts 1. INTRODUCTION --------------- Welcome to the Acorn ATOM software emulator for PC's. This program enables you to run most of the original Acorn ATOM software on your PC. Minimum requirements: -80286 CPU (80486 DX-40 required for real time emulation) -VGA display -410 kB RAM conventional memory -MS-DOS 3.0 The full emulation pack contains the following files: -Atom.Exe - Acorn ATOM software emulator (286+) -AtomCom.Exe - Utility to transfer file from and to tape or original Atom -AtomTape.Exe - Utility to read ATOM tapes into PC-memory -ReadMe.1st - Latest information -ExtROM.Tap - A tape image containing extension boxes -*.Doc - Several documentation file The emulator has been tested on several computers and turned out to work on every one of them. The program is designed to run under an MS-DOS environ- ment. It also works with Windows 3.1 and Windows 95, however, the full screen mode is required. Timing, synchronisation and sound are better if run in native MS-DOS mode than under Windows. 2. CONFIGURATION ---------------- The emulator can be configured to your own satisfaction. The preferences may be saved in the ATOM.INI file. If there's no .INI-file at startup, the emulator uses default values (between brackets). The parameters marked with an asterisk (*) can be edited also from within the emulator desktop (see chapters 4.2 and 4.3). *ASMLayout : The assembly listings in the built-in monitor can be (0) displayed in two different ways, either using the ATOM notation (@ for immediate, # for hexadecimal numbers) or the regular notation (# for immediate, $ for hexadecimal numbers). *Sound : You can select whether or not you wish to have sound effects (1) outputted to the PC-speaker or through the SoundBlaster. Detection of a SoundBlaster is done automatically. -SpeedIndex : If you can't get the emulator to run at the right speed, you (auto) might want to specify a number here which sets emulation at a certain speed. The higher this number, the slower the emulation. For 486/Pentium machines this value should be about the speed of your CPU in MHz. On somewhat slower systems (eg. 486-40 MHz) the value of SpeedIndex must be a bit lower then the CPU speed. -ExtROMFile : The emulator is equipped with the AXR1 chip (see chapter 5.1) (EXTROM.TAP) in the memory range A000h-AFFFh as a standard. If you would like to use other (EP)ROMs (boxes) at this address, you can specify a name of the file containing one or more boxes designed for this address-range. See chapters 4.2 and 6.1 for information on this fileformat. Up to 16 different boxes can be used at a time. If no filename is specified here, the emulator will load from the file EXTROM.TAP (if it exists). -Use80x87 : The emulator now also supports the new Floating Point ROM at (0) D000h by Leendert Bijnagte. This rom links to 80x87 co-processor routines for super fast calculations. At least, an 80387 is required. If an older or no co-processor is present, this option should be set to 0. -IgnoreZpFEh : Before sending a character to the printer, the ATOM compares (1) it to the contents of zero page address FEh. If they are the same, the character is not sent to the printer. On BREAK, this value is set to 0Ah (LF), which for most printers means that all text is printed at the same spot. If this parameter in the .INI file is set to 1, the comparison to zero page address FEh is ignored, because memory address FF07h will be changed to 00h. -BoxSwitch : If you want to use only one box at A000h (no switching), set (1) this value to 0. The first box in the file specified in ExtROMFile will be loaded. If no file can be found, the AXR1 will be installed. See chapter 5.3 for more information. -Box0onBreak : If this value is set to 1, the (EP)ROM in box no.0 will be (1) reinstalled whenever the BREAK key (F12) is pressed. If this value is set to 0, the current (EP)ROM remains active. -NMIResponse : This value, in the range 15 to 255, sets the reaction time after which the processor responds, when the NMI request line has gone low. In the ATOM, the NMI is used for transferring data between ATOM and the disk drives. To achieve the same transfer rate as on a real ATOM, this value must be set to approximately 40. The default value (also minimum for proper transfer with the standard ATOM DOS routines) is 15. *Colors : You can set all seven colors that are used during emulation ù BackGr is the backgroundcolor. ù ForeGr is the foregroundcolor. ù GreySb is the color of the "grey symbols" (C0h-FFh). ù Color0-Color3 are the colors in HIRES color modes. Each color is a six digit (3 bytes) hexadecimal number; the first byte stands for the amount of RED, the second for the amount of GREEN and the third for the amount of BLUE. The range for each of these bytes is 00h to 3Fh. *Drives : You can set the names of the image files, which will be opened on startup, for each drive. 3. KEYBOARD ----------- Due to the fact that the ATOM's keyboard layout differs form the PC's keyboard layout, a few keys have been changed. The most important are: -F12 : Break -Tab : Copy -Alt : Rept -CapsLock : Lock -` : ^ Furthermore the ATOM-cursorkeys have been replaced by the PC-cursorkeys. Therefore the SHIFT keys are no longer required to move the cursor down or left. (Note: If NumLock is on, only the arrows on the numeric keypad will give the correct results!) In a lot of games, however, it would be better if some keys had been placed elsewhere or would have been swapped. This can be done by toggling between the standard keyboard (as described above) and an alternate keyboard. When the alternate keyboard has been selected, the following keys should be used: -Tab : Left/right arrow -CapsLock : Up/down arrow -Left Shift : Ctrl -Ctrl/Alt : Shift -Right Shift : Rept -Cursor Lf : Lock -Cursor Rt : Copy Swapping between the standard and the alternate keyboard layout is done during emulation by pressing the [F4] key. On BREAK (F12), the standard keyboard is selected automatically. The following keys have a special function: -F4 : Toggle between standard/alternate keyboard -F5 : Toggle between original/maximum CPU speed -F6 : Show box information -F8 : Enter emulator desktop, disk screen -F9 : Enter emulator desktop, tape screen -F10 : Enter emulator desktop, options screen -F11 : Enter emulator desktop, built-in monitor -Shift+F12 : Temporarily go to MS-DOS -Ctrl+F12 : Exit the emulator -Alt+F12 : Boot from disk-image in drive 0 (MouseDos Box required) -Print Scrn : Capture screen to .BMP file 4. EMULATOR DESKTOP ------------------- Press F8, F9, F10 or F11 during emulation to enter the emulator desktop. On the top line four divisions of the desktop are shown. They can be selected by pressing [Alt] and the highlighted letter simultaneously or the corresponding hotkeys F8, F9, F10 or F11. -Disk : Alt+D (or F8) -Tape : Alt+T (or F9) -Options : Alt+O (or F10) -Monitor : Alt+M (or F11) 4.1 DISK ~~~~~~~~ The Disk screen enables you to select the disk image (.DSK files). A disk image file is recognised as such, if it is (19000h) 102,400 bytes in size. A disk has of 40 tracks, with 10 sectors, consisting of 256 bytes, each. On the left hand side of the screen all the disk images are shown. On a real ATOM, with the 8271 FDC, it was possible to connect two double sided disk drives: +-----------+ +-----------+ | DRIVE 0 | | DRIVE 1 | | ========= | | ========= | | DRIVE 2 | | DRIVE 3 | +-----------+ +-----------+ The four drive numbers are shown in the area on the right hand side of the screen. Use the following keys: -Press the [Cursor Up] or [Page Up] key to move the cursor up. -Press the [Cursor Down] or [Page Down] key to move the cursor down. -Press [Tab] and [Shift+Tab] or the [0], [1], [2] and [3] keys to select a drive number. -Press the [N] key to create a new disk image. You must enter a file name. If there's no file with that name already, a new file will be created. It is not necessary to format it. -Press the [O] key or [Enter] to "insert" an image in the specified drive. If the cursor is pointing to the last spot (where there's no file name), the drive will be emptied. -Press the [S] key to save the names of the images into the .INI file. The next time the emulator is run, the same disk images will be opened automatically. -Press the [P] key to toggle the write protect attribute of the disk in the highlighted drive. Loading of files from a disk image is done from the ATOM itself. First, you must enter the ATOM DOS, by typing *DOS Each time BREAK is pressed, this statement must be re-entered, because on a BREAK the COS is restored. On the ATOM emulator, it is also possible to enter the COS again by typing: *COS See chapter 5.1 for a list of DOS commands. As stated above, a disk can be write protected. This is done by setting the "ReadOnly" attribute of the disk image. If a disk is write protected, this is shown in the disk screen of the desktop by a "#" behind the disk name. The write protect attribute only applies to the corresponding drive (and not to its "backside"). Another advantage that the emulator has with respect to an original ATOM is that the emulator doesn't have the limitations of the physical layout of the disk drives. In other words, it is possible to insert a disk in drive 0 and to insert another disk (than the backside of that disk) in drive 2. Whenever disk transfer takes place, an icon of the two drives is shown on the left hand side in the lower border, with the LED of the active drive on. 4.2 TAPE ~~~~~~~~ The Tape screen enables you to select the tape images (.TAP files) from which you can load ATOM files. The screen has two separate areas; the one on the left hand side shows the directory with all the tape images, the area on the right hand side shows the contents of the selected tape image. A tape image consists of a number of ATOM files (.ATM files; see chapter 6 for a description) all appended to each other. One tape image can hold up to a maximum of 500 ATOM files. If the cursor is in the left hand area, where the tape images are shown, the following actions can be taken: -Press the [Cursor Up] or [Page Up] key to move the cursor up. -Press the [Cursor Down] or [Page Down] key to move the cursor down. -Press the [N] key to create a new tape image. You must enter a file name. If there's no file with that name already, a new file will be created and its length will be set to 0. -Press [O], [Enter] or the [Cursor Right] key to move the cursor to the right hand side of the screen, in which the ATOM files are shown. If the cursor is shown in the right hand area, the selected tape image can be used and/or manipulated.The contents of the tape image are shown line by line. Each line represents one ATOM file, from which the name is displayed followed by three hexadecimal numbers: The first one is the program's start address, the second number is the program's execution address and the last number is the program's size in bytes. The following actions can be taken: -Press the [Cursor Up] or [Page Up] key to move the cursor up. -Press the [Cursor Down] or [Page Down] key to move the cursor down. -Press [S] or [Enter] to set the tape file pointer to the cursor position. -Press [L] to load the file the cursor is pointing to and return to the emulator. Now there are three possibilities: ù If the program's start address is 2900h and its execution address is C2B2h, a BASIC "LOAD" command will be issued. This means that the file is loaded into the ATOM's text area at 2900h. Then the text area is scanned through to set the value of TOP and the free space pointer. Remember, if the file is not a valid BASIC program, the prompt may not appear. ù If the program's start address is not 2900h, but the execution address is C2B2h, the COS command "*LOAD" will be issued. The value of TOP will not be set. ù In any other case the COS command "*RUN" will be issued. This will load the file at its start address and then execution is transferred to the execution address specified in the file. The value of TOP is not set. Remember that all commands that are preceeded by an asterisk (*) are COS commands and not BASIC commands, which in short means that the value op TOP will not be set after the file has been loaded. Statements like DIM will generate "Error 216", unless the END or OLD statement are entered prior to RUNning the program. If you would like to open a file using another command than the desktop generates, or if you would like to load it at another address, it must be typed in manually from the ATOM's BASIC prompt. If no file name is specified (or "" with the BASIC "LOAD" command), the file at the current cursor position will be loaded. The emulator also supports the "*" wild- card at the end of the file name. If you try to load a file that is not in the current tape image or if an MS-DOS load error occurs, "ERROR 6" (the infamous checksum error) will be generated. It is not possible to load files from the desktop when in debug mode. This must also be done by typing it from the ATOM basic prompt. -Press [R] to rename the current ATOM file. -Press [I] to import an ATOM file. In the right hand area all the importable files in the current directory will be shown. You can select one by pressing [Enter] and it will then be inserted in the tape image at the current cursor position. -Press [E] to export the current file. An MS-DOS name will generated by the emulator. The file cannot be exported if there already is a file with the same name. -Press [D] to delete the current file. You will be prompted for confir- mation. -Press [F] to freeze the current state of the emulator. -Press [T] or the [Cursor Left] key to move the cursor back to left hand side of the screen, in which the tape images are shown. 4.3 OPTIONS ~~~~~~~~~~~ The Options screen allows you to change the emulator settings and to save them to the .INI-file. The changeable settings are: -CPU speed : The emulator can run at two speeds, namely ù Original : The emulator will try to be as close as possible to the original 65C02 operating speed of 1 MHz. ù Maximum : The emulator will run at maximum speed. You can also press [F5] during emulation to toggle between these two CPU speed modes. On BREAK the CPU speed is reset to original. -ASM layout -Colors -Sound Outp -Illeg Opc -CPU type See chapter 2 for more information. Go to "Save options" and press [Enter] to save the preferences to the .INI file. The previous .INI-file will be overwritten. 4.4 MONITOR ~~~~~~~~~~~ The built-in monitor lets you watch the programs when running. In the monitor screen the following things are shown: -65C02 registers (top right) -Assembly code (top left) -Memory dump (bottom) -Active breakpoints (middle right) Move around with cursor keys, move faster with Page Up, Page Down keys. The actions available are: -Trace : Executes one instruction and moves the assembly code display. Screen updates are not turned off, so sometimes you might see a pixel or two appearing between the monitor-information. -Step : Steps over the instruction, skipping the assembly code display of subroutines (JSR). In case of a subroutine, it is executed in debug mode. You can interrupt debug mode by pressing [F1], [F9], [F10] or [F11]. -Here : Runs emulation in debug mode until CPU reaches the instruction at the position of the codedisplay or the [F1], [F9], [F10] or [F11] key is pressed. -BrkPnt : A new window is shown. Up to four breakpoints can be set at one time. Press the [A] key to add a breakpoint (the position of the codedisplay). Press the keys [1] to [4] to remove existing breakpoints. All active breakpoints are shown on the right hand side of the monitor-screen, and they remain active until they are removed as described here. -Goto : Prompts for a new address and jumps to it. -Where : Moves the assembly code display to the position of the Program Counter (PC), where the emulation was interrupted. -Mode : Switches focus between code and dump. The dump-values of various I/O-ports sometimes do not reflect their actual value. 5. ATOM MEMORY -------------- 5.1 ROM ~~~~~~~ The emulated Acorn ATOM has 20 kB of Read Only Memory: -Assembler and Casette Operating System (COS) at F000h (4 kB) -Disk Operation System (DOS) at E000h (4 kB) -Extension ROM (Floating Point) at D000h (4 kB) -Basic interpreter at C000h (4 kB) -Up to sixteen (EP)ROM boxes at A000h (4 kB per box) All the basic ATOM functions are supported, as well as floating point operations. The casette load & save routines have been replaced by fast ROM-trapped routines. However, the ATOM ROM has not been changed. The casette *CAT command has been ROM-trapped. It shows the index of a .TAP file on the ATOM screen. Examples: *CAT displays all the files in the current tape image. Note, that on the first line the name of the tape image is displayed. And *CAT "P*" or *CAT P* or *CAT P displays all files in the current tape image, starting with the letter P. The FIN, FOUT, GET, BGET and FGET functions and the SGET, PUT, BPUT, FPUT and SPUT statements for COS have been implemented as well, although their operation is a little bit different from a real ATOM: -A file can be opened for input, using the FIN function. Unlike the real ATOM COS, a filename can be specified. The * wilcard is allowed. It is even possible to use a variable (e.g. F=FIN S or F=FIN $S)! If no filename is given, the file that the cursor is pointing to will be assigned. The file will be completely loaded into a buffer. On every subsequent GET, BGET, FGET or SGET data will be transmitted from that buffer to the emulator. If no file has been selected using FIN, or if past the end of the file, BGET will return ASCII code 13 (0Dh); GET and FGET will return four resp. five codes 13 (0Dh) and SGET will return an empty string. -A file can be created, using the FOUT function. Unlike the real ATOM COS, a filename can be specified. It is even possible to use a variable (e.g. F=FOUT S or F=FOUT $S)! If no filename is given, it will be called FILE. The file will be created at the end of the current .TAP image. Subsequent PUT, BPUT, FPUT or SPUT statements write data into a buffer. Each time the buffer is full, the BREAK key (F12) is pressed, the desktop tape screen is entered or the emulator is exited, the contents of the buffer will be appended to the .TAP image. If for whatever reason the buffer cannot be written to the .TAP image, a short sound will be produced, meaning that the data in the buffer is lost. Since the SHUT statement is ignored in COS a file remains open until a buffer-error occurs, the BREAK key (F12) is pressed or the next output file is created. Every time the buffer is appended, however, the name of the last file in the image is compared to the name used when creating the file. If they do not match, data will be lost. The name of the tape image is checked as well. It is therefore advised not to change tape images while PUTting data to tape. -In DOS, the handling of random files is done exactly as on a real ATOM. Please see later on in this chapter for information on the DOS-commands. Up to sixteen (EP)ROM boxes at A000h can be used at the same time (See also chapter 2). If none are available, the AXR1 will be installed automatically. See also chapter 5.3 The AXR1 is an EPROM developed by Jos Horsmeier and Huibert Lincklaen Arriens from Stichting Electronica Workshop (ECD/SEW), Delft in 1981 and provides the ATOM with nineteen extra commands. Because it is not a standard Acorn ROM, the extra commands are briefly described below: Command Abbr. Description ------- ----- ----------------------------------------------------------- DATA DA. A sequential one line file marker Syntax: [ ... ] RESTORE RES. Resets the file pointer to a specified DATA line Syntax: [||