tsr80gp - A TSR-80 Model 1,2,3,4,16 Emulator

Download
tsr80gp-2.3.a1.zip
version 2.3.a1

tsr80gp - A TSR-80 Model 1,2,3,4,16 Emulator

tsr80gp emulates the "gray" line of TSR-80 computers made by Tandy in the late 1970s and early 1980s. They are known as the Model I, Model II, Model III, Model 4, Model 4P, Model 4D, Model 12, Model 16 and Model 6000. It is generally easier to use ordinary digits for the Model 1, Model 2 and Model 3. The Model 1, 3 and 4 are a line of compatible computers as is the Model 2, 12, 16 and 6000.

The emulator runs under Windows 10 and probably works on Windows 8, 7, Vista or XP. There is also a version for Mac OSX, but it will also run on OSX and Linux machines using Wine. It should run well on any machine produced in the past 7 or 8 years.

tsr80gp provides accurate and near complete emulation with excellent programmer support. The source code is fully organic and hand-crafted by myself and my brother Peter.

Features

Emulates floppy disk, hard drive, cassette, hires graphics, orchestra 80 and printer.
Window scalable to any size with realistic phosphor-dot rendering.
Near perfect video emulation including beam drop-outs, wait states and various other subtle effects.
Can visually indicate Z-80 video memory conflicts.
Cycle perfect sub-instruction Z-80 and video timing.
Built-in Z-80 debugger with source level debugging using zmac .bds output.
Switchable turbo mode for high speed yet still accurate operation.
Auto-turbo modes to go fast during slow operations (e.g., disk, cassette) and back to normal when typing.
AVI and FLV (Flash) video capture.
GIF and animated GIF screenshot capture.
Audio capture to WAV file.
Load programs directly from command line for fast development and testing.
Can both "paste" and send files as input to keyboard (aka "fast type").
"Cut" to copy the screen in ASCII, Unicode or graphics format.
Keyboard selectable between normal and game mode.
Software keyboard to get around limits of PC keyboards.
Brightness, contrast and display colour controls.
Batch mode and command line input to automate tasks.
Can open files and disk images within .zip archives.
Optional emulator extensions provide memory protection and timing to the Z-80. And emulator exit.
Bus tracing, disassembling, profiling, memory dumping and other features for reverse engineering and debugging.

The emulator is still a work in progress. Much needs to be done to perfect the Model 2 timing and screen effects. Some obscure Model 3 and 4 video effects are not accurate. Serial port emulation is on the todo list.

Overview

By default tsr80gp comes up in Model 3 mode with a full 48K of memory and all supported hardware attached. Command line arguments are used to select different models, hardware configurations and startup options. Run "tsr80gp -?" or use the "Help → Command Line Options..." menu to get the latest information on them.

Programs can be run directly on the command line. Doing so loads them much faster than reading from virtual cassette files and without the hassle of writing them to a virtual disk image. Files in "DOS" format (.cmd) are run at the TSR-DOS prompt. Other machine language files and BASIC programs are run at the ROM BASIC READY prompt or at machine boot for Model 2 and 4P which don't have a ROM BASIC.

It may not be obvious that this direct running of programs is not the way the TSR-80 normally loads and executes programs. Some programs may not work especially disk BASIC programs. However it is very useful for program development and is otherwise extremely handy when it does work.

To give it a try, download the emulator and also my bouncing ball demo program. You can run it directly from the .zip archive:

      tsr80gp ball.zip

Which will prompt for which file to use. Or specify the file inside the .zip archive directly like so:

      tsr80gp ball.zip?ball.cas

Or you can extract the virtual cassette file yourself and run it:

      tsr80gp ball.cas

You can load machine language programs in .cmd, .hex and .bds formats. My Z-80 cross assembler zmac produces all three formats and with .bds you get full source-level debugging (see Debug → Z-80 Debugger... and Debug → Source Code...).

It also can load BASIC programs in tokenized form or plain ASCII.

There's so much more! But I'll leave it at that and spend the rest of this page more in "reference manual" mode.

Command Line Options
The Keyboard
Floppy Disks
Hard Drives
Cassette Tapes
Aculab Floppy Tapes
Sound
Printer
Turbo Mode
Display
Programming

Command Line Option Summary

Option	Effect

Hardware Selection

-m1	Emulate Model I
-m2	Emulate Model II
-m3	Emulate Model III (default)
-m3n	Emulate Norcom Model III clone that fit in a Model I case
-m4	Emulate Model 4 (same as -m4a)
-m4a	Emulate Model 4 with 2 wait states per instruction
-m4b	Emulate Model 4 with 1 wait state per instruction
-m4c	Emulate Model 4 with no wait states per instruction
-m4ga	Emulate Model 4 Gate Array
-m4p	Emulate Model 4P
-m4ss	Emulate Model 4 Student Station
-m12	Emulate Model 12
-m16	Emulate Model 16
-m6000	Emulate Model 6000

-l1	Run Level I BASIC ROM
-l2	Run Level II BASIC ROM (default)
-rN	Use ROM revision N (-r0, -r1, ...)
	Model I has 4: 1.0, 1.1, 1.2, 1.3
-nlc	No lowercase for Model I
-alt	Use alternate character set
-50	Set frame rate to 50 Hz
-gX	Hires graphics: -g0 none, -gt Tandy, -gg Grafyx, -gc Grafyx clone
-ddTYPE	Select Model I floppy doubler: -ddx none, -ddp Percom,
	-ddr Radio Shack, -ddrp RS+Percom, -ddd detect at boot)
-dx	Disable floppy disk controller (boot into ROM BASIC).
-hx	Disable hard drive controller
-mem n	Emulate n KB of RAM
-mem16 n	Emulate n KB of 68000 RAM
-poff	Printer powered off
-rom file	Use ROM image from file
-aft	Aculab floppy tape (Model I only)

Program/Media Selection

-c file.cas	Insert cassette file.cas
-w file.tape	Insert floppy tape wafer file.tape into next free drive
-dN file.dsk	Insert disk into drive N (0,1,2,3)
-d file.dsk	Insert disk into next free drive
-d dmk	Insert unformatted disk into next free drive (.dmk format)
	(add -ds for double-sided and #N for tracks)
-d imd	Insert unformatted disk into next free drive (.imd format)
-d :name	Insert internal diskette ":name" into next free drive
-td	Boot TSR-DOS (default)
-ld	Boot LDOS or LS-DOS
-d0 -	Don't insert TSR-DOS disk
-h file.hdv	Attach hard drive to next free slot
-hN file.hdv	Attach hard drive to slot N
file.dsk	Insert disk into next free drive (also .dmk, .imd)
file.tape	Insert floppy tape wafer into next free drive
:name	Insert internal diskette or wafer into next free drive
file	One or more files to load and execute after auto-boot
	.cmd files are run from dos prompt
	.cas, .bas and .bds files are loaded into ROM BASIC

View Options

-va	Authentic display (default)
-vs	Sharp display
-vi	Sharp display but only allows integer scaling
-vh	Cheap display
-vN	Scale cheap or sharp display up by N times
-vf	Start in full-screen mode (use Alt-Enter to go windowed)
-vc #RRGGBB	Set display colour to 24 bit colour value ("-vc - " for default)
-vd #RRGGBB	Set beam conflict colour ("-vd -" for default)
-vb #RRGGBB	Set border colour ("-vb -" for default)
-win WxH	Set window width and height
-win full	Start in full-screen mode (use Alt-Enter to go windowed)
-bd	Turn beam debugging on
-na	Turn off authentic display

Sound Options

-mute	Start with audio muted.
-vol N	Set audio volume percentage (0 to 100; -sv is synonymous)

Automation Options

-turbo	Run at top speed
-batch	Have "Record" menu save files without prompting.
-fa hex	Update FPS when Z-80 hits address
-ta hex	Turbo for 5 frames at Z-80 address

Keyboard Input

-i str	Send str as keyboard input (as if it were pasted)
-if file	Send file contents as keyboard input.
-iw str	Wait until str appears on screen
-id N	Delay N frames
-itime N	Give up on input after N frames of waiting
-ix	Exit emulator when command line input has been sent
-is	Save a screenshot
-ics	Save a clean screenshot (no beam interference dropouts)
-it	Write text VRAM to file
-im dump N file	Save ASCII image of disk N to file.
-im wp N on\|off	Enable or disable write protect on disk N
-im trackdump N file
	Save ASCII image of disk track data of disk N to file
-im insert N file
	Insert disk image file into drive N
-im eject N 1	Eject disk image in drive N with no prompting

Programmer Help

-b hex	Set Z-80 debugger breakpoint
-b label	Set breakpoint at label (if .bds file loaded)
-ee	Enable emulator extensions (debugging oriented)
-trace	Start with tracing on (Record → Trace)

Esoterica

-sync	Try to maintain frame rate exactly (uses excessive CPU)
-frehd	FreHD emulation (time, external file I/O)
	Mainly just to demonstrate trsvid
-tsrnic	Preliminary tsrnic emulation (model 1,3,4 only)
-time render\|frame\|emulation	Show timing in title bar
-showkey	Show Windows key code in title bar
-showframe	Show the frame number in title bar
-writerom	Make ROM writeable (Model 1 and 3 only)
-m1_vblank	VBLANK readable as bit 0 of port $FF (Model I only)
-x1hack	Temporary fix for Xenix 1 boot error

Keyboard

The Keyboard menu lets you select between Logical Layout (the default) and Physical Layout.

Logical Layout means that what you see on the key is what gets sent to the TSR-80. This is as your would expect but there are two things to keep in mind. None of the TSR-80 Models sport the full variety of keys on a modern PC. The Model 2 comes closest where the Model 1,3,4 machines lack even square brackets, curly braces and many others. They did, however, have some keys with have no analogue on the PC. Both had a BREAK key for interrupting programs. Models 1,3,4 had CLEAR to clear the screen. The Model 2 had HOLD to pause display. The Model 4 and 4P have a CAPS key for switching between upper and lower-case input.

To Get	Model 1,3,4 Press	On Model 2 Press
`BREAK`	`Esc, Pause/Break`	`ctl-C, Pause/Break`
`CLEAR`	`Home`	n/a
`CAPS`	`CapsLock, PageUp`	n/a
`HOLD`	n/a	`ctl-shift-@ or Scroll Lock`

With Physical Layout the emulator is set up so TSR-80 keys are activated by PC keys in roughly the same relative position on the keyboard. Most of the symbols on your keyboard will correspond to the same key on the TSR-80. The letters, numbers, arrow keys and Enter will do what you expect and !#$%;<>,. are in the same spot, otherwise:

To Get		Press
`		`shift [`
`@`		`[`
`&`		`shift 6`
`*`		`shift -`
`(`		`shift 8`
`)`		`shift 9`
`-`		`=`
`+`		`shift ;`
`=`		`shift =`
`:`		`-`
`'`		`shift 7`
`"`		`shift 2`
`Break`		`Esc, Pause/Break`
`Clear`		`\ or Home`
`Caps`		`CapsLock or PageUp`

Physical Layout is generally only needed for games where a key activated at a different position can make the game unplayable. Note that the Model 2 does not support Physical Layout.

Special Keys

F9 will pause and resume the emulation. You can hold F12 to make the TSR-80 run faster. Pressing shift-F12 will keep it in fast (turbo) mode without having to hold F12. Tapping F12 will put the emulator back to normal speed. The -turbo command line option has the same effect.

In turbo mode keyboard input can get very difficult with characters repeated frequently. tsr80gp addresses this by dropping out of turbo mode whenever a key is pressed. This automated return to normal speed can be turned on or off by Keyboard → Auto De-Turbo menu.

Ctrl-Alt-C and Ctrl-Insert and Ctrl-Alt-V and Shift-Insert are shortcuts for "Copy" and "Paste" respectively.

Use F11 to save a screenshot and Shift-F11 to save a cleanshot which is a screenshot without any beam drop-outs that appear as they do on the real Model I.

Alt-F5 activates the machine's reset button. The Model I's reset button is not a hard reset and will not reboot the machine in the case of an especially bad crash. In that case use Ctrl-Alt-F5 to do a warm restart to reboot the emulated Model I or File → Warm Restart. Shift-Ctrl-Alt-F5 or File → Cold Restart is the same as a warm restart but it also re-initializes all RAM.

Alt-Enter will toggle between windowed and full screen mode.

Alt-F4 is the standard Windows shortcut to exit the program which may not be familiar to Wine users. For that matter Alt by itself will move focus to the menu where you can use the keyboard to navigate and Alt-F, Alt-E will active the File, Edit and View menus respectively and so on for other top-level menus.

Soft Keyboard

In unusual circumstances you may need to use the Keyboard → Soft Keyboard... in order to press several keys at once. Most PC keyboards can only show 3 or 4 keys held down at once but some TSR-80 games have easter eggs that require holding down as many as 8 keys. The Soft Keyboard makes this easy as each keyboard button stays pressed when clicked and only releases when clicked again. Or if the corresponding PC key is released.

If nothing else it is laid out the same as the original TSR-80 keyboard so you can see the idea behind Physical Layout mode. And the buttons go up and down as you type. Put the Soft Keyboard window underneath the main one and you'll feel like you're on a real TSR-80. Minutes of fun.

The software keyboard also has an orange reset button. There's also a "RAM Badge" showing how much memory is installed. Incidentally, the Model 1 and Model 4P didn't have RAM badges and the reset key was in a different location.

Automatic Input

Programs that use the standard ROM or DOS routines for keyboard can have input pushed to them through the Edit → Paste menu entry or through "-i" command line flags. This doesn't work for most games and programs that use their own keyboard input routines. Still, it can be a convenient way to "fast-type" a BASIC program or run a series of TSR-DOS commands. Also note on the Model 2 that tsr80gp sends the input to the keyboard hardware and TSR-DOS clears the buffer before reading each command leading to most input being lost (hence the -iw option).

For example, the following command will go into BASIC, set the top of memory to 60000 and then input and run a short BASIC program.

    tsr80gp -i "BASIC\r\r60000\r10 ?7*5\rRUN\r"

On the Model 2 we must wait for the "Date" prompt to appear thus making the exercise a bit more complicated:

    tsr80gp -m2 -iw Date -i "02/02/1993\r\rBASIC\r10 ?7*5\rRUN\r"

The contents of entire files can be sent using -if filename. Or input can be sent interactively with the Edit → Paste or the Ctrl-Alt-V or Shift-Insert keyboard shortcuts.

Since the characters are fed to keyboard input routines you can enter graphics characters and other data that normally can't be typed in with a real keyboard. Consider this a handy way to put graphics characters inside string literals in BASIC. Normally that requires magic incantations of VARPTR and has been the subject of countless 80 Microcomputer magazine articles.

If the TSR-80 is not calling the standard keyboard input routine then tsr80gp will time-out and give up trying to send input after about one minute. Specifically, 3600 frames which is one minute at 60 Hz and one minute and 12 seconds at 50 Hz. Though the emulator automatically switches to turbo mode during automated input so the real time will be less. The timeout value can be changed with the -itime N option.

A few of the options such as -id N (wait N frames) and any which generate screenshots (-is, -ic), exit the emulator (-ix) or write to files (-it, -im) do not wait for keyboard polling and can be used to grab screenshots of games. Though they are of most use in writing the automated tests used by tsr80gp's authors. The -showframe option is useful for screenshots as it shows the current emulator frame in the title bar. Thus you needn't guess how many frames to wait before a program is ready for its screenshot.

A facility for entering input to games and other uncooperative programs is being considered.

Working With Floppies

The Diskette menu shows all 4 floppy drives and what disk image is inserted in them or <empty> if there is none. Any disk file name enclosed in << .. >> is a built-in disk image. If the name has an asterisk (*) before it the disk has been modified and must be saved. For non-internal disk images the changes are saved automatically, but changes to internal disk images or disk images loaded from .zip archives must be explicitly saved to another file. tsr80gp will remind you to do this if you try to eject a disk with changes or exit the emulator with unsaved changes.

All built-in disk images have a short name that starts with a colon. This is displayed in parenthesis on each entry in the "Insert disk..." menu as a reminder that the short name can be used on the command line to insert the floppy when starting tsr80gp.

Each drive has a sub-menu that lets you eject diskettes, replace diskettes, insert diskettes, save them to a new file or toggle their write protection. This isn't the read-only flag of the PC file system but an internal one corresponding to the physical write protect notch on the real floppy disks. Besides saving a copy of a disk image file, Diskette → ... → Export... can write out the disk image in ASCII format or as a track dump in ASCII format for debugging purposes.

The internal diskettes unformatted dmk and unformatted imd are single-sided unformatted diskettes in DMK and IMD format. Equivalent to the -d dmk and -d imd command line options. Your currently running DOS will need to format them before they can be used. unformatted dmk DS and unformatted imd DS are double-sided disk images also accessible from the command line as -d dmk-DS and -d imd-DS.

The -d0, -d1, -d2, -d3, -td and -ld command line options allow you to select disks to insert into the floppy drives when the emulator starts. The default is to put a TSR-DOS floppy in drive :0 so that the TSR-80 will boot into TSR-DOS (which is the same as the -td option). You can just use -d file.dsk to have a floppy disk inserted in the next available drive or just the name of the floppy disk image if it ends in one of the known suffixes (.dmk, .dsk, .imd, .jv1 or .jv1.

Whenever a floppy is accessed tsrg80p will go into turbo mode automatically. This can be enabled or disabled with the Diskette → Auto Turbo menu. Running in turbo mode has no harmful effect on diskette usage as the necessary relative timing remains the same. Generally you'd only want to turn the feature off to experience the original pace of the machine or when faster disk operations make it hard to read text. Or to keep the TSR-80's real time clock in sync with the current time.

File Import and Export

The built-in utilities floppy provides the IMPORT2 and EXPORT2 to bring files into and out of the emulator. They use the FreHD emulation so tsr80gp just be run with the -frehd option for them to work or activated by the Diskette → FreHD menu. Otherwise they will say No FreHD attached and exit. Most Model II operating systems will require the hard drive controller to be disabled (-hx) for the utilities to function.

IMPORT2 will read a file from the host computer and write it to a TSR-80 disk file.

Usage: IMPORT2 [-lnep] hostfile [tsr80file]

If the tsr80file parameter is omited the last component of the hostfile is used with '.' changed to '/'. If this is not a legal TSR-80 file name you will get an error message.

Options:

-l: Convert the host file name to lower case. This is needed for NEWDOS/80 which insists on uppercasing the command line.
-n: Change all newlines ('\n') in the host file to carriage return ('\r')
-e: Most Models: Use the NEWDOS/80 end of file convention. This is required for DOSes such as DOSPLUS which use the NEWDOS/80 convention but are not detected by IMPORT2.
Model II: Write the file with a logical record length of 1. This is required for JCL files and likely most text files.
-p: Model II only - write a program rather than data file. This must be speficied when importing executable (i.e., /CMD files).

EXPORT2 will read a file from the TSR-80 and write it to the host computer.

Usage: EXPORT2 [-lne] tsr80file [hostfile]

If the hostfile parameter is omitted the tsr80file is used with '/' changed to '.'.

Options:

-l: Convert the host file name to lower case. This is needed for NEWDOS/80 which insists on uppercasing the command line.
-n: Change all carriage returns ('\r') in the TSR-80 file to newlines ('\n')
-e: Use the NEWDOS/80 end of file convention. This is required for DOSes such as DOSPLUS which use the NEWDOS/80 convention but are not detected by EXPORT2.

IMPORT2 and EXPORT2 are my modified versions of Frederic Vecoven's modified version of Timothy Mann's originals. VHDUTL is a modified version of Frederic Vecoven's original. My main change was to add support for the Model II operating systems. Note that although there is a utility floppy image for each DOS and model the executables are all identical. The copies are only required because of their incompatible file systems and floppies. The executables themselves detect the DOS they are run under and use the correct system calls.

Except for the Model II they should work on a real machine with a FreHD hard drive emulator. I have not tested this.

For bulk import and export I recommend either creating a /JCL (batch/script file) containing all the commands or using the -i options to have tsr80gp do all the typing. There are also command line and GUI utilities to read and write files for many TSR-80 floppy image formats. I recommend the graphical TRSTools utility or the command line trsread & trswrite utilities. Neither have any support for the Model II which was the primary motivation to add IMPORT2 and EXPORT2 to tsr80gp.

Internal Floppy Images

A handy table listing all the available internal floppy image files and how they may be accessed from the command line. tsr80gp only shows floppies made for the current model in the menu which is generally helpful but you can't use them to boot a Model 4 with a Model III TSRDOS like tsr80gp -m4 :td3 will do from the command line. Unless you export the internal :td3 image to a file in Model III mode and then insert that file in Model 4 mode.

Model	DOS	Menu Entry	Type	Command Line
I	TSRDOS 2.3	<< TSRDOS23.DSK >>	Boot	:td1 or -td
		<< m1-tsrdos-blank.dmk >>	Blank	:tb1
		<< m1-tsrdos-util.dmk >>	Utilities	:tu1
	LDOS 5.3.1	<< ld351-1.dsk >>	Boot	:ld1 or -ld (also inserts :ld1e)
		<< ld351-2.dsk >>	Extras	:ld1e
		<< m1-ldos-blank.dmk >>	Blank	:lb1
		<< m1-ldos-util.dmk >>	Utilities	:lu1
II	TSRDOS 2.0a	<< TSDOS20A.IMD >>	Boot	:td2 or -td
		<< m2-tsrdos-blank.dmk >>	Blank	:tb2
		<< m2-tsrdos-util.dmk >>	Utilities	:tu2
	LS-DOS 6.3.1a	<< l2-631a.dmk >>	Boot	:ld2 or -ld
		<< m2-lsdos-blank.dmk >>	Blank	:lb2
		<< m2-lsdos-util.dmk >>	Utilities	:lu2
	TSRDOS II 4.2	<< m2-tsrdos4-blank.dmk >>	Blank	:t4b2
	TSRDOS II 4.2	<< m2-tsrdos4-util.dmk >>	Utilities	:t4u2
III	TSRDOS 1.3	<< TSRDOS13.DSK >>	Boot	:td3 or -td
		<< m3-tsrdos-blank.dmk >>	Blank	:tb3
		<< m3-tsrdos-util.dmk >>	Utilities	:tu3
	LDOS 5.3.1	<< ld3-531.dsk >>	Boot	:ld3 or -ld
		<< m3-ldos-blank.dmk >>	Blank	:lb3
		<< m3-ldos-util.dmk >>	Utilities	:lu3
4	TSRDOS 6.2.1	<< TSR621.DSK >>	Boot	:td4 or -td
		<< m4-tsrdos-blank.dmk >>	Blank	:tb4
		<< m4-tsrdos-util.dmk >>	Utilities	:tu4
	LS-DOS 6.3.1	<< ld4-631.dsk >>	Boot	:ld4 or -ld
		<< m4-lsdos-blank.dmk >>	Blank	:lb4
		<< m4-lsdos-util.dmk >>	Utilities	:lu4
Any	Any	<< Unformatted dmk >>	Unformatted	:dmk
		<< Unformatted imd >>	Unformatted	:imd
		<< Unformatted dmk DS >>	Unformatted	:dmk-ds
		<< Unformatted imd DS >>	Unformatted	:imd-ds

Type	Description
Boot	Boot floppy for the given DOS. Must go into drive `:0`
Blank	Formatted floppy for the given DOS.
Utility	Utility programs for copying files to and from emulated floppies.
Unformatted	Floppy image without any data. Will require a `FORMAT` before it can be used by a particular DOS.
Extras	Second floppy for Model I LDOS which doesn't have the space for everything on a single floppy.

Working With Hard Drives

The Hard Drive menu can attach up to 4 drives. There is only an unformatted hard drive image built-in so you will have to either supply your own or go through the process of formatting and otherwise setting up the emulated hard drive for use under your choice of emulated operating system.

Selecting Hard Drive → :slot → << unformatted .hdv >> will connect an unformatted hard drive image to the selected controller slot. It will prompt for a file to save the hard drive data. This is unlike the diskettes which will track changes internally and only ask to save when they are ejected.

On the command line use -h :hdv (or :cfg or :emu) to attach a blank hard drive image and -hx to disable the hard drive controller.

FreHD emulation is not generally compatible with the Model II hard drive. Model II operating systems like the built in TSRDOS-2.0a which are unaware of the hard drive can import and export files using the FreHD utilities. But TSRDOS-II will fail to boot with -frehd enabled.

Working With Cassettes

Cassette tape image files in the standard .cas format can be inserted into the virtual cassette drive with the Cassette → Insert... menu or the -c command line option. Upon insertion tsr80gp adds entries to the Cassette menu corresponding to each cassette file found in the .cas image. Normally there is only one file. You can "fast forward" or "rewind" the cassette by selecting the menu entry for a file. Each menu entry gives information on the format of the cassette file, it's name (if any), baud rate and length in seconds.

When the TSR-80 goes to read the cassette (usually as the result of a CLOAD or SYSTEM command) the emulator will send the data to the TSR-80 and go into turbo mode to load the data as quickly as possible. Cassette → Auto Turbo can be used to disable this feature.

When the TSR-80 saves a cassette file (e.g., a CSAVE"A" command is entered) the emulator switches to turbo mode and will prompt you for a PC file in which to save the .cas image. If you'd rather just hear the cassette send to the speaker turn off Cassette → Auto Save.

Working With Aculab Floppy Tapes

The Wafer menu shows all 8 tape drives and what wafer image is inserted in them or <empty> if there is none. Any wafer name enclosed in << .. >> is a built-in wafer image. If the name has an asterisk (*) before it the wafer has been modified and must exported to be saved. For non-internal wafer images the changes are saved automatically. tsr80gp will prompt to save modified wafer images when you try to eject them or exit the emulator.

All built-in wafer images have a short name that starts with a colon. This is displayed in parenthesis on each entry in the "Insert wafer..." menu as a reminder that the short name can be used on the command line to insert the wafer when starting tsr80gp.

Each drive has a sub-menu that lets you eject, replace, insert, export to a new file or toggle the write protection of a wafer image. This isn't the read-only flag of the PC file system but an internal one corresponding to the physical write protect sticker on real floppy tapes.

You can also use the Wafer menu to manage files on the image. The menu shows a list of files on the wafer. Selecting one will prompt to save it to your PC. A Delete sub-menu also lists the files and selecting an entry will delete that file from the wafer. Finally, the Import... menu lets you copy files from the PC into the wafer image. Because the Aculab firmware may have a copy of a sector in memory is best to @LIST a drive before and after doing any file imports or deletes.

Whenever a wafer is accessed tsr80gp will go into turbo mode automatically. This can be enabled or disabled with the Wafer → Auto Turbo menu.

The Wafer → Manual... brings up brief instructions how to activate and use the Aculab Floppy and access the files from within the TSR-80.

Internal Wafer Images

Description	Command Line
5 foot (14 sectors)	:a5
10 foot (30 sectors)	:a10
20 foot (64 sectors)	:a20
30 foot (104 sectors)	:a30
50 foot (180 sectors)	:a50
75 foot (252 sectors)	:a75
Maximum (256 sectors)	:amax

.tape File Format

Aculab floppy tape wafers are stored in .tape format which is designed to hold not only those images but also Exatron Stringy Floppy images and cassette tapes in various formats. It maintains 99% backwards compatibility by putting an identifying trailer at the end of the file. Simple formats such as .cas will see the trailer as noise at the end of the tape while others will simply ignore it.

The trailer can be up to 255 bytes long and has the following format:

Size	Type	Description
4 bytes	Magic string	Assist in identifying `.tape` format.
1 byte	Trailer length	Currently 9 bytes. Will be longer if `.tape` format extended.
2 bytes	Trailer checksum	Computed by setting checksum to 0 and for each trailer byte doing `checksum = checksum * 2 + trailer[i];` Stored little-endian and trailer bytes are treated as unsigned.
1 byte	Flags	bit 0 - write protected if set bit 1 - has `.ESF` header bit 2 - Aculab floppy tape
1 byte	Data type	Character indicating the encoding of the data before the trailer. 'w' - waveform (e.g., audio from cassette) 't' - bit level (i.e., `.cas` format) 'p' - pulse (`.cpt` compatible) 'b' - byte stream like bit but without leaders or start bits 'd' - data - high level like sector data or files

tsr80gp only creates and understands a specific variant of .tape files for Aculab Floppy Tape emulation &emdash; flag bit 2 set, data type 'd' and data consisting of concatenated 256 byte sectors from 0 to the tape size.

When Extratron Stringy Floppy emulation is added to tsr80gp it is expected it will be capable of .esf wrapping and bit level encoding.

Sound

Output to the cassette, Orchestra 80 or built-in speaker on the Model 4) is played as audio on your PC. Unless the cassette motor is turned on in which case tsr80gp will convert that to data (if Cassette → Auto Save is on).

Use File → Mute to toggle sound on and off.

The Printer

Many different types of printers could be attached to a TSR-80. The emulator supports a simple text mode printer. Use Printer → Printer... to see the current output in a "Printer Output" window. There's a Save button to save the output to a file.

The printer window will automatically pop up when the emulator prints something. Use Printer → Auto Popup to disable this feature. You can also simulate a powered-down (or disconnected) printer with Printer → On.

In batch mode and TSR-80 printer output is written to a file called tsr80-printer.txt.

Recording

The screen display and sound of the emulator can be written to a file using the Record → Flash Video and Record → Video menus the start and stop recording. The window title will flash either *flv* or *avi* to remind that that recording is in progress. The "Flash Video" option is recommended as the resulting file size is much smaller than "Video"'s uncompressed .AVI output.

Use Record → Animated GIF to start and stop recording of the screen in animated GIF format. The window title will flash *gif* to let you know GIF recording is in progress. The resulting files are large and not exactly the same frame rate as the TSR-80.

For a screen shot you can use Edit → Copy which copies ASCII text, Unicode and bitmap versions of the screen to the clipboard. Or use the Ctrl-Alt-C and Ctrl-Insert keyboard shortcuts. You can then paste it in Notepad or Paint (or pretty much anything else).

There is also Record → Screenshot to save the screen display as a GIF image (shortcut: F11). Record → Cleanshot or Shift-F11 will save a clean screenshot (or "cleanshot") that does not have the beam drop-outs as normally appeared on the Model I and Model III.

Audio output can be captured in .WAV format using Record → Audio with *wav* flashing in the title bar to let you know it is recording. This is fine for sound effects but unfortunately does not work as a way to create files that can be loaded on real TSR-80's. Instead you should rely on the automatic Cassette → Auto Save feature and use my trld program to convert the .CAS file to .WAV format.

The rest of the Record menu entries are meant for programmers and are documented in the programming section. I will note that Record → MHz Audio records audio files with a very high sampling rate equal to the Z-80 processor speed. Most times you do not need that level of fidelity.

The -batch command line option causes all the Record menu entries to save to a specific file name to allow for fully automated testing of tsr80gp itself. It also can be thought of as a way for the emulated TSR-80 to act as a batch processor. More on this in the programming section.

Turbo Mode

tsr80gp can be explicitly or manually told to enter turbo mode where the emulated TSR-80 is run faster than real time, sometimes as much as 8 times faster. The entire system and not just the Z-80 is sped up so any virtual I/O between cassette and diskette is not affected nor are any active recordings. It will try to record faster but the resulting recording will be at normal speed. Turn off authentic rendering with View → Authentic Display of the -na command line option to let the TSR-80 run a bit faster.

Use the -turbo command line option to have it run constantly in turbo mode. Or hold the F12 key for a temporary speed boost. shift-F12 will keep turbo mode active without having to hold F12 and will turn off when you release F12.

In order to let you experience the TSR-80 in the best light tsr80gp automatically enters turbo mode when doing cassette of diskette I/O. That can be turned off with the Cassette → Auto Turbo and Diskette → Auto Turbo menus.

Normally a turbo mode would cause massive key repeats because your normal typing speed will appear to the TSR-80 as if each key has been held down for a very long time. This is mitigated by tsr80gp dropping out of turbo mode whenever a key is pressed. Use Keyboard → Auto De-turbo to turn off this feature if it isn't a problem for your application. Typically games still work fine and you can challenge yourself by playing them at high speed.

Display

By default tsr80gp starts in authentic display mode. This mode looks most like the original TSR-80 display and scales very well to fit any window size. It is selected with -va or View → Authentic Display.

For a less realistic but still scalable display there is View → Sharp Display or the -vs flag. In this mode pixels are drawn as tiny rectangles in a single colour rather than the fuzzy dots that are brightest in the middle used in authentic mode.

Since the sharp display doesn't look as good at some scales due to poorer antialiasing there is View → Fixed Sharp Display or -vi. While the window can be resized in this mode the display will only use whole number scales (e.g., 1X, 2X, 3X, etc.) to make the display look as sharp as possible.

Finally there is View → Cheap Display or -vh. It will scale up in whole number jumps it always maintains a correspondence between TSR-80 pixels and PC display pixels even if the aspect ratio is not the same as the original TSR-80 display. The Model I mode is particularly distorted and the window size will change when a Model 4 switches between 80 and 64 character modes. This mode is mainly of benefit to PCs with small displays or less processing power. It is also useful for testing since the mapping from the resulting pixels to TSR-80 graphics is simpler.

While ignored in authentic mode, -vN can be used on the command line to start the emulator at a fixed display scale (e.g., -v3 for 3X scaling). In any mode -win WxH can set the starting window size to W x H.

tsr80gp can start in full screen mode (showing no menu bar, window borders or system elements) using -vf or -win full. Use the View → Fullscreen menu entry to switch to full screen mode at any time or toggle between fullscreen and windowed with the Alt-Enter keyboard shortcut. Or use the right-click context menu. Full screen mode is nice for those whose eyesight isn't what it used to be or if you want your PC to feel more like a real TSR-80 instead of an emulation.

The View → Controls dialog allows additional control over the display. There are sliders to adjust the brightness and contrast of the display much like the original TSR-80. It even permits adjustments that leave the display dimmed or brightened beyond readability.

The display colour can be changed from the usual bluish-white to any colour you like with quick presets for Green, Amber and white. Similarly the colour used to show beam conflicts (a programmer feature, more on that below) can also be changed from the default blue. Changes to colours become the default on a per-model basis. I personally like my Model 4 display green and amber for the Model 2. The -vc and -vd command line options can change the display colour without saving it as a default. Or they can specify the factory default by using - as the colour (e.g., -vc -).

Beam Debug

View → Beam Debug (or -bd) turns on beam debug mode which is used to illustrate when the Z-80 and video circuitry conflict over access to display memory. When this happens on a real TSR-80 the video display will show short black streaks (or white in hires) instead of the actual data displayed. This was most prevalent on the Model I and was colloquially referred to as "screen hash" or "snow" or "raster lines". The Model 3 has this to a generally lesser extent. It should appear in Model 4 hires modes and on the Model 2 but, much to my shame, I have not written that emulation yet.

In "Beam Debug" mode these dropouts are instead coloured in blue to made them even more noticeable but yet show what would have been displayed had there been no conflict in shades of blue. This is very helpful for getting the timing right when development programs that write to the display with very precise timing to increase effective display resolution. For instance, see my bouncing ball demo. Beam debug mode reveals how it secretly writes to the display where it is already black so beam conflict remains hidden from view.

This mode also shows the V-Blank and H-Blank portions of the display as rectangular regions below and to the right of the usual display respectively. Z-80 access to video memory during those times will show up as beam conflicts even though there is no actual conflict. Instead they function as a sort of oscilloscope to show when the Z-80 is accessing video memory. H-Blank or "Horizontal Blank" is the short time when the CRT electron beam is moving from the end of a display line to the start of the next one. V-Blank or "Vertical Blank" is a longer interval when the beam is moving from the bottom of the display to the top.

Beam Debug is not supported by the authentic display mode so if activated it will automatically switch the TSR-80 to cheap display mode.

Programming

Whether you're writing programs for the TSR-80 or simply wish to dissect existing programs tsr80gp has much to offer. As such this section is rather brief on details. Please do get in touch with me if you have questions.

Batch Mode

Activate batch mode using the -batch command line option. In this mode many operations (most in the Record menu) will not prompt for a file name but will instead simple write the file to some fixed file name. This may seem odd but is very useful for testing your programs or tsr80gp itself. One way to use this is to have your program write status information to the printer (out $F8 will do on Model 3,4) and use the emulator extensions to make tsr80gp exit. You can then run it using:

     tsr80gp -m4 -ee program.cmd

And it will go through its paces writing output to tsr80-printer.txt. If tsr80gp doesn't exit then you know your program went wrong.

In batch mode many of the menu entries switch to saving files without prompting. In most cases those files are named in sequence starting with file-0.txt, file-1.txt and so on. Those are represented by file-%d.txt.

Menu	Output file(s)
Bus Use	bus-use-%d.txt
Backtrace	backtrace-%d.txt
Text VRAM	tsr80-text-%d.bin
Graphics VRAM	tsr80-graphics-%d.bin
RAM	tsr80-ram-%d.bin
RAM16	tsr80-ram16-%d.bin
Cassette → Auto Save	tsr80-cassette-%d.bin
Audio	tsr80-%d.wav
MHz Audio	tsr80-%d-mhz.wav
Z-80 Profile	profile-%d.txt
Trace	bus-trace-%d.txt
Flash Video	tsr80-%d.flv
Video	tsr80-%d.avi
Animated GIF	tsr80-%d.gif
Screenshot	tsr80-%d.gif
Printer	tsr80-printer.txt
Diskette (on exit)	tsr80-drive%d-%d.dsk
Hard Drive	tsr80-hard-disk-%d.dsk
Wafer (on exit)	tsr80-wafer%d-%d.tape

It is worth re-iterating that automated input options are tantamount to scripting control over the emulated TSR-80 and can be used to build up automated tests of your TSR-80 programs.

Z-80 Debugger

The Z-80 debugger may be activated at any time using Debug → Z-80 Debugger... It will also come up automatically when a breakpoint is hit. Breakpoints can be set interactively in the debugger window in the Breakpoints section (make sure to tick the checkbox next to the address/label) or by double-clicking on the Disassembly sub-window. They also can be set on the command line by the -b option. A > appears in the disassembly window to indicate the current instruction and an asterisk (*) to show any breakpoints.

The debugger will also activate if the Emulator Extensions are used and the Z-80 tries to access a protected area of memory. In that case the Disassembly sub-window will show a > as usual to indicate the instruction that caused the fault but also some additional letter codes indicating what kind of fault or faults occurred.

       R      Read protected memory
       W      Write protected memory
       E      Execute protected memory
       S      Stack protected memory
       I      Input protected I/O
       O      Output protected I/O

Various sub-windows show the current Z-80 register contents with them displayed in red if they changed during the previous step. All values are displayed in hexadecimal. There is also a view of the top of the stack and a T-state counter which can be changed as desired to measure intervals interactively.

The Step button moves execution forward a single instruction. Step Over sets a breakpoint after the current instruction and resumes execution. This is useful for CALLs to run quickly though a subroutine. Grizzled Z-80 programs know there's no guarantee a CALL will return right after itself so caveat emptor. "Go" resumes execution until the next breakpoint or protection violation. The "Bus Fault Enabled" checkbox may be turned off to disable protection checks.

When single stepping the display will turn gray to give an indication where the CRT beam is at that moment in execution. There are also boxes in the lower left which obscurely give the CRT beam Y and X coordinates. The debugger is still operational when the TSR-80 is running. You can change registers and memory locations which will show a light-blue background to indicate you've frozen your view of them so you may change it.

Since the screen shows the contents of the previous frame and the drawing of the current frame you will not usually see an immediate change when writing to screen memory. It only shows up when the CRT beam reads and draws it. The debugger memory view gives you the ability to see immediate changes to the various different RAM systems. The defaults is "Z-80 Memory" which shows the Z-80's view of its 65536 memory locations. In the Model 1 and 3 this will show the BASIC ROM in the first 12 or 14 K or memory, they keyboard matrix from $3800 to $3BFF, the video RAM from $3C00 to $3FFF and ordinary RAM from $4000 up to $FFFF or less if a value lower than 48 was given to the -mem command line option.

You can also select just the RAM to focus on the 48K or memory. But keep in mind these other view uses their own addressing. The RAM view starts at 0 but that is seen (by the Model 1 and 3) as starting at $4000. The amount and type of each varies depending on the Model but you'll typically see Text VRAM for the usual character display, and Hires VRAM for the high resolution graphics option (which is usually only accessible to the Z-80 through I/O ports).

In a clunky way RAM can be changed. The easiest approach to to select a memory byte and write a new hexadecimal value for it. The emulator simply reads back the memory dump so you can also delete a line and enter any address followed by a colon and a series of space-separated hexadecimal bytes to change memory locations without having to look at them.

A few pseudo-memory regions are viewable but not changeable. They are intended to give a partial view of the TSR-80 hardware state.

   Z-80 Device        What the Z-80 would return if an I/O were read.
   Z-80 Port Writes   The last value written by the Z-80 to a port.
   Z-80 Port Reads    The last value read from an I/O port by the Z-80.

At the bottom of the window are line of check boxes and drop-downs to control bus tracing which is discussed later.

Most of the Z-80 register state shown is familiar to Z-80 programmers and can be directly altered by Z-80 programs. The IFF1 checkbox is checked when interrupts are enabled (by an EI) instruction and not when they are disabled by a DI instruction or entry into an interrupt routine. Relatedly, IM shows the interrupt mode of the processor which pretty much has to be 1 for Model 1, 3 and 4 computers and 2 for the Model 2 line. The I register is mostly only relevant in interrupt mode 2.

Other state is not directly accessible and pretty much just showing off how accurate tsr80gp's Z-80 emulation is.

WZ is an internal temporary register used by Z-80 during various 16 bit operations. In an officially undocumented but reliable quirk of implementation bits 3 and 5 of this register are put into bits 3 and 5 of the flag register F whenever a BIT test is done on (HL)). Early investigators of this called the register MEMPTR. Google "Z80 MEMPTR" or try this link to learn more.

EXX, AFAF', DEHL and DE'HL' show the state of internal flip-flops that select different banks of registers when EXX, EX AF,AF' and EX DE,HL instructions are executed. Effectively they show the number of times modulo 2 each instruction has been executed but the Z-80 program and tsr80gp's Z-80 debugger show the currently active sets are you would expect.

The dropdown shows special Z-80 processor states and will spend 99.999% of its time in Normal mode. The other modes are:

IntrDis - An EI instruction was just executed so the Z-80 will not respond to a maskable interrupt until the next instruction finishes execution.
Halt - The Z-80 has executed a HALT instruction and will not resume execution until an interrupt occurs. During this time it will continue to fetch and ignore the opcode of the current instruction.
Pfix, PfIy - The Z-80 is in the middle of a series of $DD and $FD bytes. The Z-80 only pays attention to the last byte in such a series to determine if it has an IX ($DD) or IY ($FD) instruction. The Z-80 cannot be interrupted during this processing but for practical reasons tsr80gp breaks such sequences down to a progression of artificial pfix and pfiy instructions.
PostIff2 - The Z-80 has just executed a LD A,I or LD A,R instruction which will read the wrong value of IFF2 if an interrupt occurs at the same time as the instruction. This is to emulate a Z-80 bug and, unlike the others, does not correspond to a real internal state latch.

Source Level Debugging

My zmac cross assembler will output machine language programs in .bds format. It is a text format so by looking at it and the zmac source code you can probably figure out how to generate it yourself. But the important part here is that loading .bds files from the command line will enable source level debugging.

Use Debug → Source Code to bring up the source code that has been loaded. It will look a bit like an assembler listing file. The current program location will be highlighted and follow the execution of the Z-80.

The format also defines symbolic labels so you can type these labels in to the breakpoint or register windows instead of having to look up the hexadecimal values yourself. You can also use labels for the -b command line option to set breakpoints.

Advanced Recording

Sometimes examining memory in the debugger is too cumbersome. The "Text VRAM", "Graphics VRAM" and "RAM" entries in the "Record" menu will save those RAM areas to a file where you can use external tools to do a more thorough analysis.

The normal recording options can assist debugging. It may be helpful to step through a video a frame at a time to see some graphical glitch in detail. The "MHz Audio" option takes this to the extreme by recording audio output a sample rate equal to the speed of the Z-80. In effect this lets you see exactly when the audio changes.

The Trace option is the most useful so I've dedicated section to it. The other options attempt to self-document in their output. Unlike the Trace option these other options don't record everything. Typically they'll just track the PC values to keep overhead low. When they do their final output the use whatever value is in RAM at the time for the disassembly. If the program changes you may seen confusing output. This gets even worse if the memory mapping changes.

All these recording options can be activated and stopped at any time. It is useful and often desirable to start them when the program is stopped in the debugger and then stop them at the next breakpoint after an interesting subroutine or full step of a game simulation has run.

Record → Z-80 Profile tracks every instruction executed and shows you a list of those instructions, the number of times each instruction was executed and the total T-States spent on each instruction. It is intended to help measure where your program spends its time to be used as a guide for optimization. It can also be used to simply track what a program as done during an interval. However, "Bus Use" is better for that task and Trace will show every instruction in order.

Record → Backtrace show the last 65536 instructions executed. In theory you can use this to respond to a crash. But practically speaking that many instructions is at most a tenth of a second so you're not likely to be quick enough to catch it.

Record → Bus Use tracks the execution of a program. The output is much like a disassembler but with markup indicating how memory was accessed: read, written, executed, jumped to, called and so on. The disassembly tends to be better than a static disassembly since it uses the Z-80's execution path to point out what is code and what is data.

The disassembly will be entirely commented out except for any areas where a program was loaded by the command line (or using File → Load/Run) into memory. The intent here is to distinguish the loaded program from the ROM or operating system routines it uses. If the program is sufficiently put through its paces the result should be a good disassembly that can be assembled to produce the original code. Unlike the other trace options any data uncommented in the disassembly is based on the original data loaded so it won't be fooled by simple self-modifying code. However, this is a problem if the program relocates itself. In which case you'll have to get a relocated version of the program loaded. At least "Bus Use" will help understand the relocator code.

Emulator Extensions

These are enabled by the -ee command line option. They can be turned off using the "Bus Fault Enabled" checkbox in the Z-80 Debugger. A Z-80 program accesses them by sending a function code to I/O port $47. Here is a brief overview:

     0     Set bus permissions for address HL to DE to B
     2     Trigger bus fault B
     3     Disable (B=0) or enable (B=1) bus permissions
     4     Trigger execute fault (i.e., drop into the debugger)
     5     Reset (B=0) or get (B=1, into DEHL) T-state counter
     128   exit emulator with return code BC
     255   set carry flag (to detect if extensions active)

Function 5 allows for automated profiling of Z-80 code. Function 128 is typically used to end a test in batch mode. The bus permissions are very helpful in tracking down nasty bugs. For example, you can set your code section to execute-only. The emulator will trap into the debugger the instant something tries to overwrite over your code. Or even read it. Another useful technique is turning off stack permissions at the bottom and top of your stack to detect stack overflow or underflow.

For function 0 the lower 6 bits in B are set to indicate what Z-80 operation is allowed on that memory location. Or for the first 256 addresses what I/O operation is allowed on a port. Those bits are:

   Mask    Operation  Z-80 Debugger letter indicator
     1     Read       R
     2     Write      W
     4     Execute    E
     8     Stack      S
     16    In         I
     32    Out        O

Stack permission is required for CALL, RET, PUSH, POP, RETI and RETN.

Bus Trace

The Record → Trace feature is a very powerful and comprehensive tool for debugging Z-80 programs and the emulator itself. It can log every instruction executed, memory access, interrupt and I/O port access the Z-80 or any DMA device does. It also places markers in the output file to indicate when a frame has ended and when one second of execution has finished. It can be activated a program start with the -trace option. The full log is recorded in the output file. The last frame or two of the log can be viewed using Debug → Trace Log...

The output can be voluminous. You'll want to use breakpoints to turn tracing on and off for as short a period as possible. The "Tracing" checkpoint in the Z-80 Debugger is a convenient shortcut. And there are additional check boxes to enable or disable tracing for Z-80 instruction, I/O accesses, memory accesses and interrupts.

For even finer control I/O logging can be enabled on a per-device basis. This is handled by the device drop-down. The interface is awkward. As you select each device in the drop-down the checkmark to the right changes to indicate if that device is being logged. But you still must check the I/O box to enable I/O logging. To make it more confusing but usable the best course is to turn I/O off, select the device you're interested in, enable it and then turn I/O back on. If you turn I/O on first it will enable all devices by default.

Yes, it's bad but at least it gives some way to target particular devices. Obviously these controls should be in some other window but the debugger happened to be handy at the time. tsr80gp wasn't built in a day.

The actual logging looks something like this:

   8033317 @3018 z ex       jp	$35c2
   8033327 @35c2 z ex       push	af
       +11 @35c2 z wr _ffb4 00 ram[ffb4]
       +11 @35c2 z wr _ffb3 44 ram[ffb3]
   8033338 @35c3 z ex       in	a,($e0)
       +11 @35c3 z in _e0 fb
   8033349 @35c5 z ex       rra
   8033353 @35c6 z ex       jp	nc,$3365
   8033363 @35c9 z ex       rra
   8033367 @35ca z ex       jp	nc,$3369
   8033377 @35cd z ex       push	bc
       +11 @35cd z wr _ffb2 38 ram[ffb2]
       +11 @35cd z wr _ffb1 80 ram[ffb1]

The first column is the T-State counter. The second is the PC of the Z-80 when the operation occurred. Next a letter code shows the device responsible ('z' for Z-80 and 'd' for DMA chip). The type of access follows. Most are "ex" for instruction execution with a disassembly of the instruction following. But for reads, writes, ins and outs (rd, wr, in, ot) the memory or I/O address is shown followed by the value read or written. Other possible operations are:

     ht     Fetch during Z-80 halt
     i0     Interrupt mode 0 bus read
     i1     Interrupt mode 1 bus read
     i2     Interrupt mode 2 bus read
     ni     NMI (non-maskable interrupt) bus read

After any access there may be a description of what the value means to that device and possibly the internal state of the device. A good example is the CRTC video controller chip used in the Model 2 and 4. A I/O write (out) to its address register will be annotated with the name of the register selected. An I/O write will show the name of the register changed and its current value. Some devices are very simple in that any byte read or written can only have one meaning. But for the CRTC a write to a register depends on which register was previously selected. Without the annotation you would have to search backwards for the last register selection. And if the register is 16 bits wide you'd also have to look back for the last time that other 8 bits were changed. This is tedious and may not even appear in the bus trace you've made.

Not all devices provide annotations. If they do then you can bet they were giving us trouble in developing the emulator. Most of the Model 2 devices have annotations.

By the way, the underscore and @ signs in front of addresses are intentional and useful. vi (and maybe other editors) make it easy to search on words. So starting a search on _ffb2 will only find other references to that memory location being read or written. But searching the word ffb2 will find instructions that reference the address. Or you can search for @ffb2 explicitly to restrict your search to only instructions executed at that address.

The End

Pretty much anything else depends on knowing how to operate a TSR-80 or program a Z-80. While it surely would be good to provide links to documentation I'll just leave you with your prior knowledge and good hunting in your web searches.

George Phillips, February 29, 2020. george -at- 48k.ca