Contents 1 Introduction 1 2 Getting Started 1 2.1 Preparing Disks . . . . . . . . . . . . . . . . . . . . . . . 2 2.1.1 Testing the TRS-80 Disk . . . . . . . . . . . . . . . . 2 2.1.2 Making a TRS-80 Disk Readable on the PC. . . . . . . . . 2 2.2 Installing the ROM . . . . . . . . . . . . . . . . . . . . . . 3 3 Running the Emulator 4 4 The Keyboard 5 4.1 General Usage . . . . . . . . . . . . . . . . . . . . . . . . 5 4.2 Customizing the Keyboard . . . . . . . . . . . . . . . . . . . 6 5 Options Menu 8 6 Virtual Drives 10 6.1 Using the Virtual Disk Menu . . . . . . . . . . . . . . . . . 10 6.2 Moving Data between Virtual Disk Files and Real Disks . . . . 11 7 Snapshots 12 8 Z-80 Monitor and Debug Facility 13 9 Model III-Only Option 16 10 TRS-80 DOS Utilities 17 10.1 Emulator Functions . . . . . . . . . . . . . . . . . . . . . 17 10.2 File Transfer Utilities . . . . . . . . . . . . . . . . . . . 18 11 Troubleshooting 19 12 Technical Data 23 12.1 Virtual Disk Structure . . . . . . . . . . . . . . . . . . . 23 12.2 Snapshot Structure . . . . . . . . . . . . . . . . . . . . . 24 12.3 "GENERAL.CFG" Structure . . . . . . . . . . . . . . . . . . . 25 12.4 "DRIVES.CFG" Structure . . . . . . . . . . . . . . . . . . . 26 12.5 Additional Z-80 Opcodes . . . . . . . . . . . . . . . . . . . 26 TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 1 1 Introduction The TRS-80 MODEL 4 EMULATOR is a powerful program allowing your MS-PC to act as a full-featured TRS-80 Model III or 4, running virtually all software available for either machine. The emulated TRS-80 includes 128K of RAM, four disk drives, and an RS-232 (for PCs with a serial port). In addition, the Radio Shack high resolution graphics standard is supported on PCs with VGA graphics capability. It requires a PC with at least 384K, CGA graphics, and at least version 3.3 of MS-DOS. A hard drive and at least 12MHz is also recommended. The speed will vary depending on the speed of your PC; however, for programs that run too fast (games, for example) a speed control is provided. For running Model III applications on slow machines, a faster Model III-only emulator is also included with this package. Details of this feature may be found in Section 9 of this manual. You will need a genuine TRS-80 Model III or 4 present when first setting up either emulator, but once installation is complete, they will be fully contained on your PC. 2 Getting Started Before you will be able to use the emulator, you will have to follow a couple of installation procedures. First, you will have to have a disk with a TRS-80 DOS available for the emulator to use. Disks to be used in the PC, including DOSes, must be prepared. This procedure is described in Section 2.1. Also, if you are planning on using ROM BASIC or a Model III DOS (such as TRSDOS 1.3 or NEWDOS/80), you will need to copy your Model III/4 ROM to your PC. Section 2.2 explains how to do this. Before you get started though, you should make a backup of the emulator's Master Disks, as installation will alter the programs. For users with a hard drive, it is recommended that you place the emulator in a subdirectory on your hard drive. It will work much more efficiently that way. Use the following commands: MD \TRS80 CD \TRS80 COPY d:*.* where "d:" is the drive containing the emulator diskette. If you are using the 5 1/4" disks, be sure to copy BOTH disks to your hard disk. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 2 2.1 Preparing Disks 2.1.1 Testing the TRS-80 Disk Disks formatted by older TRS-80 DOSes are not normally readable by an MS-DOS PC due to timing problems. Disks formatted by newer TRS-80 DOSes such as TRSDOS/LDOS 6.2 (or higher) and MultiDOS are usually compatible, though a special program like the emulator is needed for a PC to make sense of them. The program TESTDISK.EXE provided with the emulator will determine whether a disk is readable by your PC. If it isn't readable, don't worry. This section also describes how to format a PC-readable TRS-80 disk onto which you can copy your files or DOS. The format of the TESTDISK command is: TESTDISK d: [/H] where "d:" is the drive containing the TRS-80 disk. The parameter /H is is optional and should only be included if the disk being tested is an 80-track 5 1/4" TRS-80 disk.* TESTDISK will briefly analyse the disk. If it reports "disk readable", then the disk may be used with the emulator without any further preparation. Otherwise, read the next section on how to make the disk usable. 2.1.2 Making a TRS-80 Disk Readable on a PC The simplest solution to the timing problem is to format a disk with the proper timing and then use "BACKUP" (or "COPY" in NEWDOS/80) without format on your TRS-80 to put your DOS or data onto the emulator-compatible disk. The program PUTDISK.EXE, found on the emulator Master Disks, is provided for this purpose. To format a TRS-80 disk on the PC, look up the disk type from Table 1 (see next page) and then type the associated command at the MS-DOS prompt. If you omit the "d:" destination drive, PUTDISK will assume that the disk to be formatted is in drive A:. Examples: PUTDISK 40TRK -------- will format a standard 40-track single-sided disk in drive A:, and PUTDISK B: 80TRK2SD will format a double-sided 80-track 3 1/2" disk in drive B:. ----------------------------- *Standard TRS-80s have 40-track drives, so unless you've installed an 80-track upgrade in your TRS-80 ignore this parameter. If you wish to use 80-track 5 1/4" disks in your PC, you will require a 1.2Mb high density drive. The /H option is not needed for 3 1/2" disks. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 3 .--------------------------------------------------------------------------. | PC drive type Disk type Command | :==========================================================================: | 5 1/4" drive 40-track single-sided PUTDISK d: 40TRK | | 40-track double-sided PUTDISK d: 40TRK2SD | | Model III's TRSDOS 1.x PUTDISK d: TRSDOS1X | |--------------------------------------------------------------------------| | 1.2Mb 5 1/4" drive only 80-track single-sided PUTDISK /H d: 80TRK | | 80-track double-sided PUTDISK /H d: 80TRK2SD | |--------------------------------------------------------------------------| | 3 1/2" drive 80-track double-sided PUTDISK d: 80TRK2SD | `--------------------------------------------------------------------------' Table 1: Look up the type of TRS-80 disk on the left to determine the format command on the right. 80-track disks can only be formatted on 3 1/2" or 1.2Mb 5 1/4" drives. Most Model III and 4 DOS disks are 40-track single-sided, so you will usually use "PUTDISK 40TRK". "PUTDISK TRSDOS1X" should be used only if you want to create Model III TRSDOS 1.x-compatible disks. Once you have a properly formatted disk, take it to your TRS-80 and type "BACKUP". With the PC-formatted disk in one drive and your TRS-80 DOS disk in another, copy the DOS onto the PC-formatted disk. BE SURE TO REPLY "NO" IF BACKUP ASKS YOU IF YOU WISH TO FORMAT THE DESTINATION DISK. Once the backup is complete, the disk is ready for use on your PC. You can prepare as many disks as you like (both DOS and data disks) using this method, though be warned that it will not work for non-standard disks such as those that are copy-protected. If your DOS was TRSDOS 6.x or LDOS 6.x, you can now skip to Section 3. If you are planning on using ROM BASIC or another DOS, you should follow the steps in Section 2.2 next. 2.2 Installing the ROM The TRS-80 Model III, its DOSes, and many programs rely on the software in the TRS-80's ROM to function. This software is proprietary to Tandy/Radio Shack, and so cannot be included with the emulator. If you plan on using Model 4 DOS and programs, this may not be a problem. In any event, this package provides a simple method whereby users who do own a TRS-80 can transfer the contents of their ROMs to the emulator. With a blank disk in your PC drive and with the emulator in your default MS-DOS directory, type the command: PUTDISK d: GETROM Again, d: is the drive containing the disk. (The default is A:.) This command will format the disk and place a small TRS-80 program on it. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 4 Take this disk and place it in your Model III or 4's drive 0, and boot it.* A bar graph will appear along with the message "Writing ROM". Once the graph reaches the end and the message "Done" appears, bring the disk back to your PC and enter the command: GETDISK /R d: MODEL4.EXE It is important that you remember the "/R" option. The ROM is now installed in the emulator program. You can check this by typing "MODEL4" at the MS-DOS prompt, and then pressing and holding the [ESC] key when the title screen appears. If the ROM installation was successful, you should see the familiar "Cass?" prompt of ROM BASIC. Once you have followed the steps in Sections 2.1 and 2.2, installation is complete. You should now be ready to use the emulator. 3 Running the Emulator Running the emulator is as simple as typing "MODEL4" at the MS-DOS prompt. If you want to boot a disk rather than using ROM BASIC, however, you must tell the emulator what to use for a TRS-80 "drive 0". After typing "MODEL4", press [F7] to select the "Virtual Disk Menu". This will allow you to identify drives. In this menu, press [0] to select drive 0, and then type the letter designation of the PC drive containing your prepared TRS-80 DOS disk. Example: If you have your TRSDOS disk in your PC's drive A:, run the ------- emulator by typing "MODEL4". Select the Virtual Disk Menu by pressing [F7], then press [0] and type "A:" followed by [ENTER]. This information will be saved when you exit the emulator, so you will only have to do this once unless you want to redefine your drive 0. To boot the disk, first remove the menu by pressing [ESC], then press [CTRL] [F10] (which is equivalent to the reset button on the TRS-80). The emulator should now load the TRS-80 DOS. The Virtual Disk Menu includes many advanced functions and features not mentioned here. More about the Virtual Disk system can be found in Section 6. ----------------------------- *Users with Model 4P's must first load the MODELA/III image. This is done by booting the DOS disk containing MODELA/III while holding down the [P] and [L] keys. You should get a "loading ROM image" message. Once loading has completed, you will be prompt to swap disks. Release the [P] and [L] keys, place the "GETROM" disk in drive 0, and press [ENTER]. The remainder of the procedure is the same. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 5 4 The Keyboard 4.1 General Usage Several special features are available through the [F4] through [F10] keys when running the emulator. These are summarized below: [F4] SOUND ON/OFF. TRS-80 sound, both the internal buzzer of the Model 4 and the output of the cassette port, can be heard through your PC's internal Speaker. It can be enabled or disabled by pressing this key. [F5] KEYBOARD MODE. The PC keyboard is slightly different than that of the TRS-80's. To accomodate this while maintaining the best compatibility, two preprogrammed keyboard layouts are provided along with one customizable layout. These layouts are summarized below. [F5] will allow you to cycle through these different layouts. Use the Help screen or Options Menu to see the current setting. [CTRL] MODIFY CUSTOM KEYBOARD LAYOUT. When the custom keyboard layout is +[F5] selected using [F5], this menu will allow you to rearrange your PC keyboard so it more comfortably approximates the TRS-80 keyboard or your personal preferences. [F6] OPTIONS MENU. Here, you can control the speed of the emulator, set the screen colour, select the COM port to use as an RS-232, etc. A more detailed description can be found in Section 5. [F7] VIRTUAL DISK MENU. This menu allows you to specify what the emulator should use for TRS-80 drives 0 through 3. You may select physical drives for each (e.g. "A:" or "B:"), or "virtual disk files". More on this in Section 6. [F8] SNAPSHOT MENU. Snapshots allow you to save whatever you are doing on the emulator in its entirety, and load it back at a later time, even if you exit the emulator or turn off your computer between sessions. (It's great for games!) See Section 7 for details. [F9] DEBUGGER/EXIT. To exit the emulator, you should enter [F9] followed by [Q]. For assembly-language programmers, this option also provides a powerful debugging tool for monitoring the execution of Z-80 code. If you invoked this option accidentally, you can cancel it by pressing [C]. More on this in Section 8. [F10] HELP. This key will bring up a summary of special function keys and also tell you the current state of the sound on/off switch and the currently selected keyboard layout. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 6 [CTRL] RESET. This is equivalent to the red reset button on the TRS-80's +[F10] keyboard. The [F1] through [F3] keys behave exactly as the same keys on the Model 4 keyboard, and so don't represent emulator features. There are several keys on the TRS-80 keyboard, though, for which their PC counterparts are not obvious. They are listed below: TRS-80 key PC key ---------- ------ [BREAK] -> [ESC] [CLEAR] -> [ALT] [UP ARROW] -> "[" [DOWN ARROW] -> "]" [RIGHT ARROW] -> [TAB] [LEFT ARROW] -> [BACKSPACE] [SHIFT][@] -> [SCROLL LOCK] You can also use the arrow keys on your numeric keypad or cursor pad, but [NUM LOCK] must be off. (If [NUM LOCK] is on, the numeric keypad will return numbers, while the cursor keypad on extended keyboards will not work.) As mentioned above, there are three keyboard modes. In the PC keyboard mode, the keys work exactly as they are labelled (excluding those listed above). For example, [SHIFT][2] will be an "@". The only exception is [SHIFT][-], which becomes the Model III CAPS LOCK (equivalent to [SHIFT][0] on the Model III/4 keyboard). The second mode is the TRS-80 layout. This layout more closely resembles that of the Model III/4 keyboard. For example, [SHIFT][2] becomes a quotation mark, the parantheses are found on the [SHIFT][8] and [SHIFT][9], and various symbols are rearranged to correspond to their positions on the TRS-80 keyboard. In this layout, the ['] key becomes the [@] key. The final mode is the custom mode, which can be modified using the [CTRL][F5] menu. Details of this option are found in the next section. Use the [F6] or [F10] functions to see the current setting of the keyboard layout. 4.2 Customizing the Keyboard The [CTRL][F5] menu allows you to modify the custom keyboard layout. You will probably not want to use this feature until you have become TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 7 experienced with other aspects of the emulator. If you are a new user of the emulator, it would be best to read Sections 5 and 6 now. If you enter this menu accidentally, [ESC] will resume emulation. Note: Changes made in this section will not take effect unless you have selected the CUSTOM keyboard layout using either the [F6] Options Menu or the [F5] key during normal emulation. Selecting this option will display a picture of the TRS-80 keyboard in the upper-left portion of the screen, with a list of the standard PC keys on the right. Initially "ESC" will be highlight on the list, and the "[BRK]" key will be highlighted on the TRS-80 keyboard. This is telling you that the [ESC] key on the PC keyboard represents the TRS-80's [BREAK] key. The custom keyboard layout starts out the same as the "PC" layout described in the previous section. Using the up and down arrow keys or [PG UP] and [PG DN], you can scroll through the list of PC keys. For each PC key highlighted, the associated TRS-80 key translation will be coloured on the picture of the TRS-80 keyboard. Move the yellow arrows down the PC key list until you reach the entry "2 @". You will notice that for this key two keys on the TRS-80 keyboard are highlighted. That is because the "2" and "@" are found on separate keys on that keyboard. The emulator maps the SHIFTed and unSHIFTed [2] key separately in order to get the proper characters. This can be done for all keys, though in most cases the SHIFTed and unSHIFTed PC keys correspond to the same TRS-80 key. The [F1] and [F2] keys are used to change the definition of the current key highlighted in the PC key list. Press [F1] to change the definition of the unSHIFTed PC key or [F2] to change the definition used when the PC key is SHIFTed. A new definition is selected using the arrow keys to move the cursor around the picture of TRS-80 keyboard. Pressing [ENTER] will assign the key under the cursor as the new definition. [ESC] will abort the change. Example: With "3 #" highlighted in the PC key list, press [F1]. Move ------- the cursor to the "X" key on the TRS-80 keyboard and press [ENTER]. Now, whenever you press [3] while running a TRS-80 program, the program will think you are yping "X". Pressing [SHIFT][3] will still give a "#" symbol, however, since the SHIFTed definition was not changed. While modifying a key in the [F1] or [F2] options, pressing [S] will toggle the state of the TRS-80's SHIFT key for that map. That is, you may notice that [SHIFT][2] is mapped to "@" and not "SHIFT+@" (as indicated in the lower-left section of the screen). The TRS-80 will not see the SHIFT key being pressed for that combination. [S] toggles whether or not the TRS-80 sees a SHIFT key being pressed. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 8 Example: With "E" highlighted in the PC key list, press [F1]. Move ------- the cursor to the "- =" key on the TRS-80 keyboard, then press [S] followed by [ENTER]. As shown in the lower left, the unSHIFTed [E] key will appear on the TRS-80 keyboard as a SHIFTed [-] which is the "=" character. The SHIFT key will appear reversed to the TRS-80. The combination [SHIFT][E] is unaffected. Also found on the lower left is a line indicating whether or not "NUM LOCK exchanges SHIFTed/unSHIFTed bindings" for the highlighted PC key. This means that when the NUM LOCK light is on, the PC's SHIFT key is reversed. For example, with NUM LOCK off, the numeric keypad's [8] key is the up arrow and the SHIFTed key is the number "8". With NUM LOCK on, the unSHIFTed key is "8" and the SHIFTed key becomes the up arrow. [F3] toggles this option, determining whether or not the NUM LOCK affects the PC key highlighted. (If this option where set to "Yes" for all keys on the keyboard, NUM LOCK would effectively become a SHIFT LOCK.) As a practical example, a more common use of this feature would be to make the SHIFTed arrow keys on the numeric keypad work as "SHIFT+UP", etc. on the TRS-80 rather than as keypad numbers. The next example illustrates how to do this: Example: Select "Keypad 8/Up arrow" in the PC key list. Press [F2] and ------- move the cursor to the "up arrow" on the TRS-80 keyboard. Press [S] and then [ENTER]. Then press [F3] to disable the effect of the NUM LOCK state. The unSHIFTed arrow key was already mapped to the proper key, now the SHIFTed key is also. This should be repeated for the keypad 2, 4, and 6 to get all of the arrow keys. These features are best understood through a little experimentation. For the ambitious, this feature could even be used to remap the entire keyboard into the modern Dvorak layout rather than the traditional "QWERTY" design. If you scramble the custom keyboard beyond recovery, however, you can always reset it to one of the two preprogrammed layouts using the [F4] option. 5 Options Menu The [F6] option of the Model 4 Emulator allows you to configure the emulator for your system. This menu will display all options along with their current settings. Pressing the letter associated with an option will cycle between its different settings. Each option is summarized below: [A] KEYBOARD LAYOUT. This is the same as the [F5] option discussed in Section 4.1. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 9 [B] SOUND. Same as the [F4] option in Section 4.1. [C] MONITOR COLOUR. If you have a colour monitor, you can choose the emulator screen to be green or white. [D] ADD LFs TO PRINTER OUTPUT? TRS-80s and PCs treat their printers differently. PCs output the two-code CR/LF sequence to start a new line while TRS-80s usually output only a CR. If this option is set to "Yes" the emulator will take all CRs sent to the printer by a TRS-80 program and turn them into CR/LFs. This avoids the need to change the switches in your PC's printer to use it with TRS-80 programs. [E] TREAT 1.2Mb DRIVE AS 40/80 TRACK. Normally, the emulator assumes that any 5 1/4" disk used with it is a 40-track disk (as is the standard equipment with a Model III/4). If your PC has a 1.2Mb drive, you can read the 80-track disks generated by customized Model III/4s by selecting the "80 track" setting of this option. In the usual "40 track" mode the emulator will "double step" on 1.2Mb drives making it appear as a 40-track 360K drive. This option does not affect 3 1/2" or 360K-only drives. [F] USE AS SERIAL PORT... If you have a serial port in your computer, the emulator can use it as an RS-232 for TRS-80 communications software. Use this option to select either COM1: or COM2: for this feature. [G] CHARACTER SET. There are two character generators available for the Model 4. In older machines, the BASIC command "?CHR$(21) CHR$(22);:FOR X=192 TO 255:?CHR$(X);:NEXT" will display Japanese Kana characters. In newer machines, it will produce an "international" foreign character set used by some word processors. This option allows you to select one of these two character generators. (Note: This is distinct from the "alternate" character set shown in the back of the Model III/4 manual, which is available in both modes.) Your selection will take effect upon exiting the Options Menu. [H] PC GRAPHICS ADAPTER. You may select either CGA or VGA graphics with this option. The VGA mode provides a more authentic-looking 80-column Model 4 screen and is necessary to use the Model 4's hires graphics capability, but your PC must support VGA graphics. EGA users should use the CGA mode. Also, for users who are running the emulator on fast PCs, such as a 33MHz 486, there may be times when you find that the TRS-80 programs are running too fast. The emulator can be slowed down by using the speed "slider" control in this menu. Press [+] to increase the emulator's speed, or [-] to slow it down. You can exit the Options Menu and return to the emulated TRS-80 by pressing [ESC]. All settings will be saved when you exit the emulator. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 10 6 Virtual Drives Though the emulator is capable of reading and writing to TRS-80 disks directly, this is not the most effective way to use the emulator. For one thing, most PCs these days have only one 5 1/4" disk drive, which would effectively make the emulator a one-drive Model 4. Also, many users have hard drives, which operate much faster than floppies. Thus, the emulator actually has two modes of disk operation. You've already seen the Virtual Disk Menu [F7]) in Section 3. This menu allows you to identify where to find the disks for each of the four TRS-80 disk drives. However, not only can you enter a drive label such as "A:" or "B:" for a drive, you can also enter a file name. These files are known as "virtual disk files", and have the extension ".DSK". They are created through the Virtual Disk Menu, described below, and contain the entire contents of one TRS-80 disk. Ideally, you would place these files on your hard drive to increase speed and avoid size problems. (These files are 8.5K larger than an equivalent real disk.) The remainder of this chapter explains how to take full advantage of this feature. 6.1 Using the Virtual Disk Menu The Virtual Disk Menu can be brought up at any time during the normal operation of the emulator by pressing [F7]. (Any other menus must be closed first, though.) The menu will list each of the four TRS-80 drive numbers (0 through 3), followed by the current file or drive which has been assigned to them. On the right side of the screen, a directory listing of all ".DSK" files in the current directory will be shown. Several functions are available by pressing the associated key: [ESC] Exit the Virtual Disk Menu and return to the emulated TRS-80. [0] to [3] This selects one of the four TRS-80 drives, allowing you to change the drive or file associated with it. Pressing [ESC] once in this mode will clear the field, twice will cancel the change. [SHIFT] This will "write protect" a virtual disk file in the associated +[0] to [3] TRS-80 drive 0 to 3. Pressing it a second time will turn off the write protection. If a drive is write protected, its number will be highlighted. (Note: This applies only if a virtual disk file is in the drive. Real TRS-80 disks in a drive are write protected in the usual manner.) TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 11 If you select a TRS-80 drive, you will then be able to enter a PC drive or virtual file name. Drive designations are simply "A:", "B:", etc. A virtual file name may be typed in or chosen from the directory on the right using the arrow keys or mouse pointer. Press [ENTER] or the left mouse button to use the highlighted file name. If a directory is highlighted, selecting it will then list all ".DSK" files in that directory. TO CREATE A NEW VIRTUAL DISK FILE, simply type an unused disk name after selecting a drive. This virtual disk will be unformatted, so you will need to run "FORMAT" on it when you return to the emulated TRS-80's DOS. (Note: A TRS-80 DOS's "FORMAT" will also work on physical disks in your PC's drive, and provides an alternative to the method described in Section 2.1 once you have a TRS-80 DOS installed on your PC.) 6.2 Moving Data between Virtual Disk Files and Real Disks For all practical purposes, the emulator treats a virtual disk (i.e. ".DSK") file exactly as a real disk. Therefore, if, for example, you had set the emulator such that drive 1 was your PC's A: drive, and drive 2 was a virtual disk file "MYDATA.DSK", you could simply transfer files using the TRS-80 DOS's "COPY" or "BACKUP" from within the emulator. There may be times, however, that you may wish to do this from the MS-DOS prompt, for either speed or practical reasons. Two MS-DOS programs are provided to assist you with this. They are GETDISK.EXE and PUTDISK.EXE and will copy the entire disk contents between a virtual disk file and a disk in a PC drive. (This will erase any previous data contained at the destination.) PUTDISK.EXE will write a virtual disk file to a real disk. The general syntax is: PUTDISK [/H] [d:] disk-name where "d:" is the destination drive contain the real disk (the default is A:) and "disk-name" is the name of the virtual disk file. The ".DSK" extension may be omitted from the file name, and a path may be included if necessary. Typing "PUTDISK" without any parameters will print a command summary. The optional parameter "/H" is used to tell PUTDISK to use a 1.2Mb 5 1/4" drive as an 80-track drive. This serves the exact same function as option F of the Options Menu within the emulator, discussed in Section 5 above. This option has no effect on 360K-only or 3 1/2" drives. GETDISK complements this, reading the contents of a real disk to a virtual disk file. As discussed in Section 2.1, the disk must have been formatted by a PC to be readable, either by PUTDISK, or by a TRS-80 DOS's "FORMAT" EXECUTED FROM WITHIN THE EMULATOR. The syntax is: GETDISK [/H] [/2] [/R] [d:] disk-name TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 12 In this case "d:" is the source drive containing the disk to be read (default A:) and "disk-name" is the name of the virtual disk file to which the data is to be written. The "/H" option serves the same purpose as for PUTDISK. GETDISK assumes that, if the disk being read is a 5 1/4" one, it will be single-sided. The "/2" option tells GETDISK that the disk is double-sided. (This option has no meaning when reading 3 1/2" disks, which are always assumed to be double-sided.) The third option, "/R" is a special one that should only be used in conjunction with the ROM retrieval procedure described in Section 2.2. Examples: PUTDISK B: MYDATA -------- will write the contents of the virtual disk named "MYDATA.DSK", found in the current MS-DOS directory, to the disk in the PC's drive B:. GETDISK /2 GAMES\SPACE will read the contents of a double-sided disk in drive A: and write it to a virtual disk file called "SPACE.DSK" to be placed in the MS-DOS subdirectory "GAMES". It is recommended that users copy their TRS-80 DOS disk to their hard drive using GETDISK, and then set drive 0 in the Virtual Disk Menu to point to this virtual disk file. You will find that the TRS-80 DOS operates much faster this way. Users may notice that the procedure for formatting TRS-80 compatible disks on the PC described in Section 2.1 actually writes virtual disk files named "40TRK.DSK", "TRSDOS1X.DSK", etc. to real disks. These are ".DSK" files found on the emulator's Master Disk, and are blank LDOS/TRSDOS-formatted virtual disks. 7 Snapshots One feature that is unique to the emulator is the snapshot option. This option allows you to save whatever you are currently doing on the emulator in its entirety, and reload it at a later date. The Snapshot Menu may be displayed using the [F8] key during normal operation of the emulator. The options are simple: Pressing [S] will save a snapshot while [L] will load one. [ESC] will cancel the Snapshot Menu. After selecting save or load, you can enter a file name or select it from the directory on the right with the arrow keys or mouse, exactly as for the Virtual Disk Menu. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 13 The normal extension for snapshot files is ".IMG". They include the entire 128K of TRS-80 RAM, 2K of video RAM, all Z-80 registers and Model 4 port settings. Also all of the emulator settings in the [F6] Options Menu and [F7] Virtual Disk Menu are saved so that the proper disks, etc. will be in the drives when the snapshot is reloaded. If the Model 4's hires graphics screen is active, it will also be included in the snapshot. Thus, virtually any application or program can be saved and recovered later. Snapshot names may also be included as a parameter when running "MODEL4". This allows you to directly enter a presaved TRS-80 application from the MS-DOS prompt. It also provides a way of launching TRS-80 applications direct from MS-WINDOWS. Examples: [F8] [S] "ROBOT" [ENTER] entered during normal execution of the emulated TRS-80 will call up the Snapshot Menu and save the current TRS-80 program in-execution to a file called "ROBOT.IMG". [F8] [L] "UTILITY\SUPERZAP" [ENTER] will summon the Snapshot Menu and load the snapshot "SUPERZAP.IMG" from the MS-DOS subdirectory "UTILITY". "MODEL4 NEWDOS80" [ENTER] entered at the MS-DOS prompt will run the Model 4 Emulator and immediately load a snapshot called "NEWDOS80.IMG" from the default directory. A beep indicates that a snapshot could not be loaded or saved successfully. If this happens, check that the name and directory is valid, and, if saving, that there is at least 131K of space available (163K if using hires graphics) in the destination MS-DOS directory. 8 Z-80 Monitor and Debug Facility For Z-80 assembly and machine language programmers, the debugger is a very useful tool. It is invoked by the [F9] key during emulation. For users not interested in this feature, all that you need to know is that pressing [Q] in the debugger will exit the emulator, while [C] will cancel this option and continue with normal emulation. The debugger screen is divided up into several functions. On the left-hand side are the Z-80 registers and flags. A 128-byte memory dump is given at the upper-right in both hexidecimal and ASCII. The lower-middle section of the screen gives a Z-80 source code disassembly. A command summary is given on the lower right. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 14 Also, the lower section of the register display includes the contents of the Z-80 stack starting at the memory address in SP and running to SP+8. The stack entries are given in MSB/LSB format for ease of reading rather than LSB/MSB as they are stored in memory. Several command options are available in the debugger, and are described below: [B] BREAKPOINT. This option will prompt for a hexidecimal address and then return to the emulated TRS-80. When Z-80's PC register reaches the breakpoint address, the emulator will automatically stop and return to the debugger screen. Note that the emulator may run slower while checking for a breakpoint. The breakpoint is automatically cleared the next time the debugger screen appears, either when the breakpoint is reached or if [F9] is again pressed. [C] CONTINUE. This option will return to the emulated TRS-80, cancelling the debugger screen. [D] DISASSEMBLE. This allows you to specify the starting memory address for the Z-80 disassembly listing (found in the lower-middle section of the screen). The default is the address immediately following the last instruction shown on the current listing. [E] EDIT MEMORY. Selecting this option will place a cursor at the first byte of the memory dump, located in the upper-righthand portion of the screen. You may use the arrow keys to move the cursor or type any hexidecimal number to change the memory contents at the cursor address. [PG UP] or [PG DN] will move the memory dump address up or down by 128 bytes. Press [ESC] or [ENTER] when your changes are complete. [F] FLAGS. This option allows you to change the six Z-80 flags. Once selected, pressing the letters S, Z, H, P, N, or C will toggle the appropriate Z-80 flag between 0 (false) and 1 (true). [ENTER] exits this option. [ESC] will cancel the changes. [H] HEX MATH. This is a hexidecimal calculator. Upon selecting this option, enter a hexidecimal number or register name (as described below), and then select one of the options: [+] To add a second hexidecimal number. [-] To subtract a second hexidecimal number. [*] To perform unsigned multiplication with a second hex number. [/] To perform unsigned division by a second hex number. [A] To logically AND with a second hex number. [O] To logically OR with a second hex number. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 15 [X] To logically XOR with a second hex number. [N] To NEGate the number (i.e. two's complement). [S] To perform a logical SHIFT on the number. The left and right arrow keys are used to perform a left shift or right shift. [ESC] returns to the main math options. [R] To perform a logical binary ROTation, used as "Shift" above. [D] To display the signed decimal equivalent for the given hex number. You may also enter a new signed decimal number at this prompt. [ENTER] returns to the main math options. [ESC] Exit the hexidecimal calculator and return to the debugger options. [M] MEMORY DUMP. This allows you specify a new starting address for the 128-byte memory dump on the upper-righthand portion of the screen. [Q] QUIT. This will exit the emulator and return to MS-DOS. You must reply [Y] to confirm. [R] REGISTERS. This option allows you to change the contents of the Z-80 registers. To select a register, move the pointer to it using the up or down arrows and press [ENTER]. (As a shortcut, you may press the first letter of the registers A, BC, DE, HL, PC, or SP to select them. The IX or IY registers may be selected with the second letter.) Then, type in a new hexidecimal value for the selected register and press [ENTER], or press [ESC] to cancel the change. [S] SINGLE STEP. This will execute a single Z-80 instruction at the current address of the Program Counter and update all the registers appropriately. [V] VIEW VIDEO. Selecting this option will show the current (frozen) state of the emulated TRS-80's video screen. Pressing any key will return to the debugger. With the exception of the Breakpoint option, all prompts that require a hexidecimal number can also be answered with any register pair. Register names must be enclosed in parenthesis (e.g. "(BC)") to avoid confusion with hex numbers. The accumulator register may also be used, and is entered as "(A)". Examples: [D] 4000 [ENTER] will change the Z-80 disassembly listing to display the instructions starting at memory location 4000H. [M] (HL) [ENTER] TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 16 will cause the memory dump to display the 128 bytes of memory starting at the address contained in HL. (i.e. if HL contains 3C00H, the memory dump will show addresses 3C00H through 3C7FH.) [H] (IX) [ENTER] [+] (IY) [ENTER] [/] 2 [ENTER] will calculate the average of the IX and IY registers (i.e. (IX+IY)/2). [H] 1234 [ENTER] [S] [<-] [<-] [ENTER] will shift the number 1234H left by two bit fields, giving 48D0H. [R] [H] ABCD [ENTER] will set the HL register equal to ABCDH. [F] [C] [ENTER] will change the true/false state of the Z-80's Carry flag. [B] 402D [ENTER] will return to the emulated TRS-80, which will continue to run as normal until the Program Counter reaches 402DH, at which point the debugger will reappear. 9 Model III-Only Option Starting with release 2.2 of the emulator, a new program, MODEL3.EXE is being included on the Master Disk. It is a separate emulator, very similar to MODEL4.EXE, but behaves exclusively as a four disk drive, 48K Model III with RS-232 option. THERE IS NO HIRES GRAPHICS SUPPORT IN MODEL3.EXE. As with MODEL4.EXE, you must install the ROM before using this emulator. The procedure is the same as that outlined in Section 2.2, except that you must instead use: GETDISK /R d: MODEL3.EXE to copy the captured ROM from the GETROM disk to MODEL3.EXE. The emulator may then be executed by typing "MODEL3" at the MS-DOS prompt. The advantage over MODEL4.EXE is speed. MODEL3.EXE runs up to three times as fast as its Model 4 counterpart. The reason for this is that a great deal of overhead on the Model 4 emulator goes to managing the various memory modes and configurations of the machine, which were not available on a Model III. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 17 The configurations for the two emulators are maintained independently. (The Model III emulator uses "GENERAL3.CFG" and "DRIVES3.CFG".) This allows you to have separate Virtual Disk choices for the Model III and 4, thereby avoiding having to "swap disks" when moving between the two. The snapshots generated by MODEL3.EXE can be loaded in the Model 4 emulator, and snapshots saved in MODEL4.EXE operating as a Model III can be loaded on MODEL3.EXE. MODEL3.EXE WILL NOT RUN MODEL 4 PROGRAMS. 10 TRS-80 DOS Utilities Provided on the emulator's Master Disks are two virtual disks -- UTILITY.DSK and UTIL_T1X.DSK -- containing a number of useful utilities. These two actually contain the same programs, however, they have been formatted for use with different DOSes. You should use UTIL_T1X.DSK if you are using the Model III TRSDOS 1.x, or UTILITY.DSK if you are using any other DOS (LDOS, MultiDOS, NEWDOS/80,* Model 4's TRSDOS 6.x, etc.) Note that these programs are designed specifically to be used within this emulator package. They will not work on a genuine TRS-80 or other emulators. You can access the contents of these virtual disks by selecting the [F7] Virtual Disk Menu, selecting a drive number, and then entering the virtual disk name appropriate to your DOS at the prompt. [ESC] will then return to the emulated TRS-80. These utilities are TRS-80 "/CMD" programs which are executed at the TRS-80's DOS prompt. They may be broken down into two categories: emulator functions and file transfer utilities. For many of these utilities, MS-DOS file names are required. In these cases, they are given in MS-DOS form "filename.ext" rather than the TRS-80 "filename/ext" form. Also, since the TRS-80 has no "\" key, subdirectories are instead separated by "/". The default MS-DOS path for these commands is the current directory upon entry to the emulator unless changed by the "CD" command described in Section 10.2. 10.1 Emulator Functions The emulator functions largely repeat features available through the various special function keys and menus. Their advantage is that these programs may be incorporated into TRS-80 "batch" files and executed automatically rather than requiring the commands to be issued manually by the user. ----------------------------- *Users of NEWDOS/80 should be sure to set the PDRIVE for the virtual drive containing UTILITY.DSK to that of a single density Model I diskette. Consult your NEWDOS/80 manual for details. A single density format was chosen to ensure maximum compatibility. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 18 These commands are issued at the TRS-80 DOS prompt: QUIT Simply, this command will exit the emulator and return to the MS-DOS prompt. SAVESNAP [-Q] [name] This command will save a snapshot of the current state of the emulator just as the [S] option of the [F8] menu. If the "name" is omitted, the name of the last snapshot loaded or saved will be used. If an error occurs, you will be notified by a beep. With the "-Q" option, the emulator will exit to MS-DOS if the snapshot is successfully saved. LOADSNAP [name] This command will load a snapshot as if using the [L] option of the [F8] menu. Omitting the "name" will cause the name of the last loaded or saved snapshot to be used. Again, a beep indicates an error. 10.2 File Transfer Utilities These commands provide a way of moving files between the emulator environment and your MS-DOS directory. Since the emulator can also read genuine TRS-80 disks, once a TRS-80 DOS has been installed in the emulator, this provides a method of moving files directly between your TRS-80 and your PC. CD [path] Change the default MS-DOS directory used by the utilities to "path". The default drive can also be changed with this command (e.g. "CD A:"). If you omit "path", the current path will be displayed. XDIR [-P] [-W] [path] "External Directory". This command gives an MS-DOS-style directory of the files in the specified MS-DOS "path". The option "-P" causes the directory to pause when the screen fills, while "-W" selects the "wide" display which omits file lengths and date/times. If "path" is omitted, the default directory is used. (Note: When using wildcards in "path" you must use, for example, "*.DAT" rather than just ".DAT". Also if "path" is a subdirectory, it must end with "/".) IMPORT [-E] [-L] path :d TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 19 This command copies the MS-DOS files matching "path" to TRS-80 files of the same name. If ":d" is specified, the files will be written to TRS-80 virtual drive d. The name "path" may include wildcards. The "-E" and "-L" options are used for ASCII files. If the "-L" option is included, linefeed characters will be stripped from the file. (TRS-80 ASCII files have only CRs at the end of lines, while PC files have CR/LF combinations at the end.) If "-E" is specified, the PC's end-of-file marker will be removed, and all data after the marker will be truncated. (Note: If you are using both "-E" and "-L", you may abbreviate this combination as "-EL". Entering this command without parameters will print a summary of its syntax. EXPORT [-E] [-L] file The opposite of "IMPORT", this command copies the TRS-80 file named "file" to the default MS-DOS directory set by "CD". The "-E" option will add a PC-style end-of-file marker to the end of the file, and "-L" will add linefeeds to the end of each line (turning CRs into CR/LFs as needed by MS-DOS). The combination of "-E" and "-L" can again be abbreviated as "-EL". This is the only command that requires a TRS-80-style file name rather than an MS-DOS-style file name. Wildcards are NOT supported for this command. As with "IMPORT", typing "EXPORT" without parameters will print a syntax summary. 11 Troubleshooting It is hard to anticipate all the questions a user may have, but the following list may be helpful with the more common problems you may encounter. Q: When using GETDISK, I get the message "May not have found all sectors on track". What does this mean? A: The disk you are using was most likely formatted on a TRS-80 and the first sector is too close to the physical start of the track. You must format a new disk on your PC using the method described in Section 2.1, or using a TRS-80 DOS's "FORMAT" FROM WITHIN THE EMULATOR. This will create a disk that the PC can read. You must then copy the files onto the disk using a TRS-80 via either "COPY" or "BACKUP" with the NO FORMAT option. Q: When I run "MODEL4", I get the message "This DOS requires ROM to be installed". Why? A: The DOS or programs you are using were probably designed for the Model III. Such programs require the ROM BASIC, which cannot be included TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 20 with the emulator for copyright reasons. Follow the procedure in Section 2.2 to copy the ROM image from your TRS-80 to the emulator. Q: I'm using a different DOS than TRSDOS on my Model III/4, and I can't seem to get a directory of the disks formatted by PUTDISK. What's wrong? A: The standard "40TRK", "80TRK", etc. formats used to prepare disks in Section 2.1 are in TRSDOS/LDOS 6.x format. DOSes such as NEWDOS/80 use a different format. Even so, a full disk backup WITHOUT FORMAT (rather than file copy) should work. Try it and then see if the directory is readable. Q: Why does nothing happen when I run the emulator? A: If you have followed the installation procedure successfully, then most likely the Virtual Disk Menu (function [F7]) does not point to a usable DOS disk or virtual disk file for drive 0. Check that drive 0 is set correctly in this menu. As a check, you can also try loading ROM BASIC if it is installed. This is done by holding down the [ESC] key while pressing [CTRL][F10]. Q: I don't have a TRS-80 available to me to prepare disks. Is there another way to read TRS-80 disks? A: Computer News 80 provides a disk transfer service which can prepare standard TRS-80 disks for use with the emulator. If you would like to be able to do this on your own, however, there are a couple of options: On SOME older computers, it is possible to trick the PC into reading sectors that are normally too close to the beginning of the physical track. This is done by covering the index hole (the small hole next to the hub of a 5 1/4" disk) with a write protect tab. Do this to an MS-DOS disk and try the MS-DOS "DIR" command on it. If a directory appears, then TRS-80 disks with the index hole covered should be readable directly without being prepared (though the tab must be off if you wish to format them). The way the PC treats these disks all depends on the specific disk controller chip in your PC. Rarely one may have a PC for which the positioning of the sector is not a problem. If this doesn't work, talk to a technician: they may be able to recommend a replacement chip that will not be "deaf" to sectors near the beginning of the physical track. Of course, the easiest solution is to find someone with a TRS-80 Model III or 4 to help you with the conversion. Q: A disk formatted on my PC's 1.2Mb drive can't be read by my TRS-80. What's wrong? A: The 1.2Mb drive is an 80-track drive. The tracks on this drive are narrower than those on a 40-track, so the old data may not be completely erased by the format, confusing your 40-track TRS-80 drive. Try completely erasing the disk with a magnet and reformatting it, or use a brand new disk. Q: The CAPS LOCK light on my keyboard is backwards in the emulator. What's wrong? TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 21 A: Whether a TRS-80 is in upper or lowercase is determined by the TRS-80's ROM or DOS, and in some cases the powerup-state can be changed. Your PC's keyboard does not know what state the TRS-80 DOS is set to power up in, and so the light will not necessarily match what you see on the screen. Q: Why doesn't my [CAPS LOCK] key work in the emulator? A: Only the Model 4 had a [CAPS LOCK] key. The Model III used the combination [SHIFT][0] as a CAPS LOCK. If you are using a Model III ROM or program you may have to use [SHIFT][0] instead (or [SHIFT][-] if you are in the PC keyboard mode). Q: The arrow keys on my cursor keypad don't work. Why? A: Your [NUM LOCK] is probably on. It must be off to use the arrow keys, even on the cursor pad of extended keyboards. Q: Can I read single density disks on my PC? A: Again, the PC's disk controller is somewhat more restrictive than that of the TRS-80. Most PCs will not be able to read single density. The easiest solution is to use a TRS-80 to copy the relevant files to a double density disk, which can be used. For those interested, there ARE some PC-compatible controllers which are capable of reading single density. Consult a technician if you are interested in this option. Within the emulator, however, Virtual Disk Files CAN be single density, though PUTDISK may not be able to write them to real disks due to the limitations of your PC hardware. Q: My printer is not working properly when I try to print graphics or use special features within the emulator. What's wrong? A: The Options Menu includes an option which adds the linefeed (LF) code to all carriage returns (CRs) sent to the printer. Some graphics or mode commands for your printer may include the CR code, and the addition of the LF may be interfering. Try changing option "D" in the Options Menu. Q: When I ran the emulator, the previous settings of my Virtual Drives and/or Options Menu were lost. What happened? A: There are two possibilities. First, if you have reloaded a snapshot previously, the settings will have been changed to match those present when the snapshot was saved. If this was not the case, then most likely you ran the emulator from a different default directory and it could not find the configuration files "DRIVES.CFG" or "GENERAL.CFG" which it created when the emulator was last exited. Q: Why does the emulator run so slow when there is no disk in my PC's disk drive? TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 22 A: Because of the difficulties with reading TRS-80 disks from within the emulator, it tries for several seconds to read the drive before giving up. If you plan to use the emulator without a disk in the drive for any amount of time, select the Virtual Disk Menu and clear drive entries such as "A:" and "B:" from the list. Q: Why does my TRS-80's clock lose time in the emulator? A: A real Model 4 has two speeds of operation, 2MHz and 4MHz. The clock is updated either 30 or 60 times a second depending on which speed is being used. The emulator, however, cannot regulate its speed and the clock is always updated 30 times a second. Try using TRSDOS/LDOS's "SYSTEM (SLOW)" option. It will not change the speed of the emulator, but it will let your TRS-80 DOS know that the clock is running at 30Hz and not 60Hz. Another way the clock will lose time is by using the emulator's various menus or the debugger a lot. The emulated TRS-80 will stop whenever a menu is present. Therefore, the clock will not be incremented. Finally, if you load a snapshot, everything will be recalled from the time the snapshot was saved, including the time and date on the TRS-80's clock. Q: Why won't the emulator or "PUTDISK" format my 3 1/2" disk? A: Your drive and the disk are probably "high density". This means that there should be a second hole on the disk itself, opposite the write protect switch. TRS-80 3 1/2" disks are not high density and should not have this hole. Q: If I use the speed slider in the Options Menu to slow down the emulator, the emulated TRS-80 stops. What's happened? A: The emulator is probably running so slow now that it is spending all its time updating the TRS-80's clock. Try using a faster speed. Q: Why can't I set the debugger's breakpoint to FFFFH? A: This is the value that the debugger uses to tell the emulator that there is no breakpoint. If the emulator finds this address for the breakpoint, it will not check the Program Counter. Q: Why do I get write errors when I exit the emulator? A: The emulator tries to save all configurations upon exiting to whatever the default directory was when it was entered. If the path is not valid or the disk is write protected, an error will occur. This is harmless, but it can be avoided by making sure you are in the emulator's directory before running it. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 23 12 Technical Data The following sections may be of interest to the more technically-minded or those curious about the inner workings of the emulator. 12.1 Virtual Disk Structure The ".DSK" virtual disk files are divided into two sections. The first is an 8.5K (8704-byte) header, and the second is the data area which can be of variable length. There can be up to 2901 entries in the header, each a three-byte "sector ID" sequence, which identifies one sector on the virtual disk. The 256 bytes of sector data corresponding to any sector ID can be located in the ".DSK" file by applying the formula Data_offset = Sector_ID_offset x 256 / 3 + 8704 where all offsets are measured from the start of the file. The first two bytes of the sector ID is the track and sector number, respectively, on which the sector is to be found. The third is a multi-purpose byte with the following meaning: Bit 7 DENSITY. If this bit is set, the sector is double density. If it reset, it is single density. 6 LOCKED/DELETED SECTOR. This is the most-significant bit of the data address mark ID. For most TRS-80 disks, this should be zero. 5 READ PROTECTED SECTOR. This is the least-significant bit of the sector's data address mark. In most TRS-80 DOS's, this distinguishes directory sectors from data sectors on the disk. 4 HEAD NUMBER. If this bit is zero, the sector is on the front side (head 0) of the disk, one indicates it is on the back (head 1). 3 CRC ERROR. This indicates whether the sector has a CRC error. Since virtual disks are actually files, this usually only applies to artificially-induced CRC errors due to copy protection schemes, or indicates a CRC error that occurred on a real disk during the construction of the virtual disk file via GETDISK. Sector IDs are written to the header on a first-come, first-serve basis. Since most DOSes use an interleaving pattern during format, you will usually find that the sectors are not arranged sequentially in the virtual disk file. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 24 12.2 Snapshot Structure The ".IMG" snapshot files are either 133473 or 166241 bytes long, depending on whether the hires graphics screen is active or not, and are broken down as follows: Offset Length Description ------ ------ ----------- 0 131072 Model 4's full 128K of RAM. 131072 32 Snapshot path and file name. 131104 1 Always zero. (File name terminator) 131105 1 Identifies register used as start address of memory dump in debugger. Value is an index between 0 and 12 as given below. 131106 1 Register index for start address of disassembly in debugger. This index is between 1 and 13. 131107 2 Explicit address for memory dump (index=0). 131109 1 Z-80 register A (index=1). 131110 1 Always zero. (MSB of A register) 131111 2 Z-80 BC register pair (index=2). 131113 2 Z-80 DE register pair (index=3). 131115 2 Z-80 HL register pair (index=4). 131117 2 Z-80 IX register pair (index=5). 131119 2 Z-80 IY register pair (index=6). 131121 2 Z-80 SP register (index=7). 131123 2 Z-80 PC register (index=8). 131125 2 Z-80 AF' register (index=9). 131127 2 Z-80 BC' register (index=10). 131129 2 Z-80 DE' register (index=11). 131131 2 Z-80 HL' register (index=12). 131133 2 Explicit address for disassembly (index=13). 131135 1 Z-80 F register (flags). 131136 1 Z-80 I register. 131137 1 Z-80 R register. 131138 1 Maskable interrupt status. Bit 0 set if enabled, 1-7 are ignored. 131139 1 Last output to Z-80 port address 84H. 131140 1 Input value for Z-80 port address E0H. 131141 1 Last output to Z-80 port address E0H. 131142 1 Input value for Z-80 port address E4H. 131143 1 Last output to Z-80 port address E4H. 131144 1 Last output to Z-80 port address E9H. 131145 1 Last output to Z-80 port address EAH. 131146 1 Last output to Z-80 port address ECH. 131147 2048 2K of video RAM (as it would appear at F800H for page 1 mode). 133195 195 Copy of "DRIVES.CFG". (See Section 12.4) 133390 77 First 77 bytes of "GENERAL.CFG". (See Section 12.3) 133467 1 Last output to Z-80 port address 80H. 133468 1 Last output to Z-80 port address 81H. 133469 1 Last output to Z-80 port address 83H. 133470 1 Last output to Z-80 port address 8CH. (continued) TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 25 Offset Length Description ------ ------ ----------- (continued) 133471 1 Last output to Z-80 port address 8DH. 133472 1 Last output to Z-80 port address 8EH. 133473 32768 Hi-res graphics screen. (LSB of offset is row, MSB is column. Included only if bit 0 of port 83H is set.) Warning: Changing these fields to illegal values may have disastrous results! For MODEL3.EXE, the snapshot format is the same, however, the data for Z-80 ports 80H through 8EH have no meaning. They are all set to zero to ensure compatibility when loading the snapshot in MODEL4.EXE. In addition, only bytes 16384 through 65535 of the RAM segment are used. The video memory is stored in and retrieved from the first 1K of the video RAM segment starting at offset 131147 in the snapshot. 12.3 "GENERAL.CFG" Structure The GENERAL.CFG file is saved upon exiting the emulator and contains the Options Menu settings as well as the directory path to use for snapshots. This file is 326 bytes long, and is constructed as follows: Offset Length Description ------ ------ ----------- 0 1 Last drive viewed by directory in Snapshot Menu. (1=drive A:, etc.) 1 64 Driveless path name for directory in Snapshot Menu. 65 1 Always zero. (Path name terminator) 66 1 Obsolete. (Discontinued in version 2.3) 67 1 Keyboard mode. (0=PC, 1=TRS-80, 2=CUSTOM) 68 2 Delay counter from Options Menu's speed slider. Add 2 for every step on slider. 70 1 Sound on/off. (255=On, 0=Off) 71 1 Screen colour. (Bit 0 set=White, bit 0 reset=Green) 72 1 Add LFs to Printer Output. (255=Yes, 0=No) 73 1 1.2Mb drive mode. (0=80-track, 1=40-track) 74 1 Serial port select. (0=COM1:, 1=COM2:) 75 1 Character set. (0=Kana, 255=International) 76 1 PC graphics adapter. (6=CGA, 17=VGA) 77 249 Custom keyboard map. (3 bytes for each scancode from 1 to 83. Byte 0 is unSHIFTed map, byte 1 is SHIFTed map, bit 0 of byte 2 set if affected by NUM LOCK. Bits 4-6 of map are keyboard row, bits 2-0 are column, bit 7 set if SHIFT reversed, bit 4 set if key disabled.) Warning: Changing these fields to illegal values may have disastrous results! TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 26 The format for "GENERAL3.CFG" in the Model III-only emulator is the same. 12.4 "DRIVES.CFG" Structure The DRIVES.CFG file is saved upon exiting the emulator and contains the last settings of the four virtual disk drives. The file is 195 bytes long, broken down as follows: Offset Length Description ------ ------ ----------- 0 1 Write protect status. Bits 0 to 3 correspond to the status of drives 0 through 3. Set means write protected. 1 1 Last drive viewed by Virtual Disk Menu. (1=drive A:, etc.) 2 64 Driveless path name of last directory viewed in the Virtual Disk Menu. 66 1 Always zero. (Path name terminator) 67 31 Path name assigned to drive 0, padded with zeroes. 98 1 Always zero. (File name terminator) 99 31 Path name assigned to drive 1, padded with zeroes. 130 1 Always zero. (File name terminator) 131 31 Path name assigned to drive 2, padded with zeroes. 162 1 Always zero. (File name terminator) 163 31 Path name assigned to drive 3, padded with zeroes. 194 1 Always zero. (File name terminator) The format for "DRIVES3.CFG" in the Model III-only emulator is the same. 12.5 Additional Z-80 Opcodes Two opcodes have been added to the Z-80 instruction set for the use of the UTILITY.DSK programs as well as any interested assembly language programmers. IMPORTANT: AVOID ADDRESSING OUTSIDE THE 32K BANK IN WHICH THE INSTRUCTION IS EXECUTING WHEN MEMORY IS NOT IN THE USUAL CONFIGURATION OF BANK 0 AT 0000- 7FFF, BANK 1 AT 8000-FFFF.) In other modes, RAM banks that may appear contiguous to the TRS-80 will not appear so to MS-DOS. Also, memory will always appear to be in addressing mode 3 (64K RAM only) to MS-DOS. ED 20 xx: Emulator service request In the debugger's disassembly, this opcode appears as "request xx". "xx" represents one of six subfunctions: 00 Set the new MS-DOS default directory path to the name pointed to by HL. The path may include a new default drive, and must be terminated by a null character. 01 Re-establish default path set by last "ED 20 00" instruction. Usage of the virtual disks or the [F8] menu may have changed the default path since "ED 20 00" was executed. TRS-80 Model 4 Emulator (C) 1993, 1994 Jeff Vavasour 27 02 Set new snapshot path name to the name pointed to by HL. 32-character maximum. Must be terminated by a null character. 03 Load snapshot using last set name. 04 Save snapshot and jump to address in HL if successful. When the snapshot is reloaded, the Z-80's program counter will be at the next address following this instruction. 05 Quit emulator. An illegal subfunction is equivalent to a NOP. ED 21 xx: MS-DOS function call This opcode appears as "func call xx" in the debugger's disassembler. With the 8086's DS: and ES: segments set equal to the segment containing the current address of the Z-80 program counter, the Z-80 registers are loaded into the PC registers as follows: A -> AL BC -> CX DE -> DX HL -> BX IX -> SI IY -> DI SP -> BP AH is then loaded with "xx" and an INT 21H is executed. Upon return, the 8086 registers are loaded back into their appropriate Z-80 registers, with AH being stored in the Z-80 I register. Shelling out of the emulator, or otherwise compromising control of the emulator using this opcode is not advised. ---------------------------------------------------------------------------- TRS-80 and TRSDOS are trademarks of Tandy Corporation. MS-DOS and MS-WINDOWS are trademarks of Microsoft, Inc. LDOS is a trademark of Logical Systems, Inc. NEWDOS/80 is a trademark of Apparat, Inc.