Trs80gp – A TRS-80 Emulator

trs80gp primarily emulates the “gray” line of TRS-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.

Also emulated are the TRS-80 Micro Color Computer Model MC-10,
the TRS-80 DT-1 Data Terminal, TRS-80 Videotex and
the Electric Crayon external colour display.

The emulator runs on Windows from XP all the way up to Windows 10.
Included in the download are versions for MacOS, Linux and Raspberry Pi.
They may not be at full feature parity with the Windows version but the
emulator runs just fine under Wine.
It should run well on any machine produced in the past decade.

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

For older versions and checksums, please consult
the release notes.

Community

Bug reports, feature requests or other inquiries about the trs80gp emulator
are best e-mailed to me (see bottom of this page for the address). There is
a community of TRS-80 users still out there who can help with questions
operating the machines (in both emulated or physical form) and even some
amount of expertise on trs80gp itself.

I’ve recently created a
trs80gp Facebook group
and a
trs80gp Discord server
as venues for more interactive discussion. You may not find many people there
but I will keep an eye on them myself.

The most active TRS-80 forum is the
Tandy Radio Shack
section of the Vintage Computing Feduration forums. There is also a somewhat
less busy Tandy Computers
forum on AtariAge and a very lightly used
TRS-80 subreddit.
There are also a handful of facebook groups dedicated to the TRS-80 models that
trs80gp emulates.

Features

• Emulates floppy disk, hard drive, cassette, hires graphics, Orchestra 80/85/90 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.
• 6809 debugger for Videotex
• 6800 debugger for Electric Crayon
• 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. Videotex, Electric Crayon and MC-10 don’t have authentic
rendering modes.

Overview

By default trs80gp 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 “trs80gp -?” 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 TRS-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 TRS-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:

      trs80gp ball.zip

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

      trs80gp ball.zip?ball.cas

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

      trs80gp 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
• Model Selection
• The Keyboard
• Light Pen and Joystick
• Floppy Disks
• Hard Drives
• Cassette Tapes
• Aculab Floppy Tapes
• Sound
• Memory
• Printer
• Serial (RS-232) Ports
• Recording movies, pictures and audio.
• Turbo Mode
• Display
• Programming
• FreHD Emulation
• DT-1 Terminal
• TRS-80 Videotex
• Electric Crayon
• Linux Notes
• MacOS Notes

Command Line Option Summary

Model Selection

The various

-m*

options and the File → Change Model menu from
quite a wide variety of different computers, terminals and printers to emulate.
When trs80gp is run from the command line the model will default to

-m3

.
When run from a GUI the model will be whatever was selected by the menu.
In either case various preferences like display mode defaults are recalled
based on the model.

Many of the command line arguments may not be applicable vary depending on
the model. For example, printers and terminals do not have cassette or disk
storage and ignore those options. One meaningful difference is the
-r0, -r1, -r2, etc. ROM revision. The lower the revision number
the earlier the original release of that ROM. Here is a table of revisions
for each model which have more that one:

Both the Model I and Model III have Level I and Level II BASIC ROMs. The
rom revsisions only select between different Level II ROMs. There is only
one known version of the Level I ROMs for each.

Keyboard

The Keyboard menu lets you select between Logical Layout (the default)
and Physical Layout. There is also Experimental Logical Layout which is
(hopefully) temporary. It is identical to Logical Layout except for
a slight difference in handling shift key state to work better with
a custom CP/M BIOS.

Enable ghosting for a truely authentic experience. Due to the way the
keyboard matrix works on the Model 1, 3 and 4 it is possible for a 4th
key to appear pressed when 3 others are down. For example, if you press
and hold F, G and O in that order you will see
FGN on screen as those keys ghost with N.

Logical Layout means that what you see on the key is what gets sent to the TRS-80.
This is as you would expect but there are two things to keep in mind.
None of the TRS-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
which 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.

With Physical Layout the emulator is set up so TRS-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 TRS-80.
The letters, numbers, arrow keys and Enter will do what you expect and

!#$%;<>,.

are in the same spot, otherwise:

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 TRS-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. trs80gp 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.

Software Keyboard

In unusual circumstances you may need to use the Keyboard → Software 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 TRS-80 games have easter eggs that
require holding down as many as 8 keys.
The software 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 TRS-80 keyboard so
you can see the idea behind Physical Layout mode. And the buttons go up and
down as you type. Put the software keyboard window underneath the main one and
you’ll feel like you’re on a real TRS-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,
“

-i

” command line flags or Edit → Paste Macro N menu entries.
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 TRS-DOS
commands. Also note on the Model 2 that trs80gp sends the input to the
keyboard hardware and TRS-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.

    trs80gp -i "BASICrr60000r10 ?7*5rRUNr"

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

    trs80gp -m2 -iw Date -i "02/02/1993rrBASICr10 ?7*5rRUNr"

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 TRS-80 is not calling the standard keyboard input routine then trs80gp
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 trs80gp’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.

Paste Macros

The Edit → Define Macro… menu allows you to create up to 10
paste shortcuts. The strings entered can be pasted either through the
Edit → Paste Macro 0 though 9 menu entires or by pressing Alt-0
though Alt-9. Each macro is automatically saved and there is a different
set of macros for each TRS-80 model.

The mechanism is exactly the same as other automatic input so you can use
escapes to enter control and graphics characters.
This is particularly useful for Xenix’s virtual console feature where
entering xFC followed by 0 though 9 will switch
to that console. For example, to have Alt-4 switch to console 4 set up
the macro to send xFCx34 or xFC4 (x hex
escapes consume at most 2 digits).

Light Pen and Joystick

The Windows version supports joystick input on the Model 1, 3 and 4 and
light pen input on the Model 1. The light pen must be enabled with the

-lp

option; the joystick can be disabled with the

-jx

option.

An Alpha products joystick is emulated using any of the standard joysticks
attached to your computer. The actual joystick was a bus hog that would
respond to reads on practically any I/O port. Most programs use port $00, $13
or $F7 so only those are mapped by trs80gp.

With the light pen enabled pressing the mouse button down will simulate the
light pen making contact with that position on screen. Releasing the mouse
button acts as if the pen were removed from the screen. Very few programs
were found that have light pen support so please report any problems you
see. We’d be very much interested to run some test programs if you have
an original light pen.

Working With Floppies

The Diskette menu shows all 4 floppy drives and what disk image is
inserted in them or

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

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 TRS-DOS floppy in drive :0 so that the
TRS-80 will boot into TRS-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,
.hfe, .jv1 or .jv3).

Whenever a floppy is accessed trsg80p 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 TRS-80’s real time clock in sync
with the current time.

Unlike actual floppy drives, the emulated drives operate in a special any-sided mode.
If a double-sided disk image is inserted, the drive will become double-sided. If the drive has a single-sided
disk image and the operating system attempts to format a track on side 2, the drive
and disk image will automatically upgrade to double-sided.

To control this behaviour, the The -dNss, -dNds and -dNas command line options
allow you to force drive N in the system to behave as single-sided, double-sided or any-sided.
Alternatively, you can enable or disable any-sided mode via the Diskette → Drive → Emulate only …
menu option.

Because of problems with CP/M auto-detecting drive sides during FORMAT,
the any-sided drive behaviour is not the default on the Model II family.
The index hole position is different between single and doubled sided 8″ diskettes.
Real 8″ double-sided disk drives use the position change to actively detect doubled-sided or single-sided diskettes.
As a result (unless -dNas is used), the emulator will signal NOT READY
from the 8″ drive in the follow cases:

• Double-sided image used in a single-sided drive
• Access the second side of single-sided image in a double-sided drive

Note that in this strict mode if you wish to format a double-sided disk image you must
insert a double-sided blank as the single-sided blank will not be promoted to double-sided.

Like the original machines, the Model II (-m2) will have single-sided 8″ drives
and the Models 12, 16, and 6000 (-m12 -m16 -m6000) will have double-sided 8″ drives.

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 trs80gp must be run with the -frehd option for
them to work or activated by the Hard Drive → 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
TRS-80 disk file.

Usage: IMPORT2 [-lnep] hostfile [trs80file]

If the

parameter is omitted the last component of the

hostfile

is used with ‘.’ changed to ‘/’. If this is not a legal
TRS-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 TRS-80 and write it to the host computer.

Usage: EXPORT2 [-lne] trs80file [hostfile]

If the hostfile parameter is omitted the trs80file 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 TRS-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 trs80gp do all the typing.
There are also command line and GUI utilities to read and write files
for many TRS-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 trs80gp.

Internal Floppy Images

A handy table listing all the available internal floppy image files and
how they may be accessed from the command line. trs80gp 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 TRSDOS like

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

Working With Hard Drives

The Hard Drive menu can attach up to 4 drives.
There are only unformatted hard drive images 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 >>
(or “emu” or “DREM”) will
connect an unformatted hard drive image to the selected controller slot.
It will immediately 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 :emu or :drem)
to attach a blank hard drive image and -hx to disable the hard drive
controller.

The “drem” format is compatible with the DREM hard drive emulator available
at https://www.drem.info/. It stores
hard drive images as a pair of files. A file.cfg which gives the
geometry and other information and a file.dsk which holds the data
for all the blocks.

The “emu” format is compatible with the Gesswein MFM emulator available at
https://www.pdp8online.com/mfm/mfm.shtml.
Both the “drem” and “emu” formats allow for convenient copying of hard drive
images to or from real TRS-80’s.

FreHD emulation is not generally compatible with the Model II hard drive.
Model II operating systems like the built in TRSDOS-2.0a which are unaware
of the hard drive can import and export files using the FreHD utilities.
But TRSDOS-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 trs80gp
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 each
cassette file: counter position,
format, name (if any), baud rate and length in seconds.

When the TRS-80 goes to read the cassette (usually as the result of
a CLOAD or SYSTEM command) the emulator will send the
data to the TRS-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 TRS-80 saves a cassette file (e.g., a CSAVE"A" command
is entered) the emulator switches to turbo mode. It will prompt you for
a PC file in which to save the .cas image when the save is done.
If you’d rather just hear the cassette send to the speaker turn off
Cassette → Auto Save.

When loading a cassette file the emulator displays the cassette
counter in the title bar as Cr|123|. When writing the
title bar will show Cw|001|. If the counter stops when reading
then the emulator has reached the end of the inserted cassette tape image.
If the TRS-80 hasn’t finished loading then the load has likely failed.

Working With Aculab Floppy Tapes

The Wafer menu shows all 8 tape drives and what wafer image is inserted
in them or

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

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 trs80gp 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 TRS-80.

Internal Wafer Images

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

trs80gp only creates and understands a specific variant of .tape
files for Aculab Floppy Tape emulation — 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 trs80gp it is expected
it will be capable of .esf wrapping and bit level encoding.

Sound

Output to the cassette, Orchestra 80/85/90 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
trs80gp will convert cassette output to data (if Cassette → Auto Save is on).

Use File → Mute to toggle sound on and off.

Memory

The

-mem

option is used to set the main memory size in kilobytes.
It defaults to the maximum standard RAM for the model.
On Model 16 and 6000 systems
there is

-mem16

for the 68000 processor’s available memory. It
defaults to 1 MB as earlier versions of Xenix would crash if more memory
was available. In the Record menu and debugger memory is referred to as
RAM and

ram[]

in Bus Trace output.

The standard maximum RAM on a Model 4 was 128 KB. HyperMEM expands
that up to a megabyte with -mem hyper:1024 and is represented
as a larger RAM in the debugger, recording and trace. For memory
sizes greater than 128 K hyperMEM is assumed. -mem 256 is
equivalent to -mem hyper:256 on a Model 4.

The Model 4 also features two expansion RAMs, -mem super:1024
and -mem mega:16384. These don’t extend main memory but provide
a new tranche of banked RAM. The Record menu and the debugger refer
to them as “Expansion RAM” and accesses to it show up as expram[]
in the trace log.

The Printer

Many different types of printers could be attached to a TRS-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 can automatically pop up when the emulator prints
something. Use Printer → Auto Popup to enable this feature. You
can also simulate a powered-down (or disconnected) printer with
Printer → On.

Like the serial ports the printer port can be mapped to a TCP/IP connection.
To listen for a connection use -p @port or the “TCP/IP Listen”
option in the Printer → Connection… dialog. To make a connection
use -p host:port or “TCP/IP Connect” in the connection dialog.

To attach an emulated MX-70 printer use -p :mx70 on the command line
or use Printer → Connection… and select it from the drop-down.

The Electric Crayon colour display actually attaches via the printer port.
The idea was to make it easy to program. For example, a BASIC
LPRINT"ERS" will erase the screen. See the section on
the Electric Crayon for some details on how to use it.

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

Serial (RS-232) Ports

trs80gp can map serial ports to TCP/IP connections or emulate 2 and 3 button
serial mice. To have a serial port connect to a TCP/IP server use

-r host:port

or open Serial → Port A, fill in the hostname
and port and choose “TCP/IP Connect”. Or the serial port can listen on a
TCP/IP port with

-r @port

or use “TCP/IP Listen” in the serial
port dialog box. Most machines have a single serial port, the Model 2 line
has two ports accessible on the command line with

-rA

and

-rB

.

trs80gp instances can now be “wired” together through serial ports.
The ultimate setup is one trs80gp running Model 16 Xenix with two trs80gp’s
attached running DT-1 terminals. But here’s a simple example of hooking
two DT-1 terminal emulations together.

     trs80gp -mdt1 -r :4000
     trs80gp -mdt1 -r @4000

Characters typed on one of the DT-1’s will appear on the second one. Assuming
everything is working. If it does not work check the “Status” indicator of each
serial port. Both sides should note they are “connected”. But the “@” side
may only show “Listening…” or the other side “Connecting…” both indicating
no connection has been made. Or “-unbound-” if there has been some error.

To break a connection use the “None” option in the dialog box dropdown. The
other side may not see the loss of connection so you may need to manually
manage “unplugging” on both sides. trs80gp is not quite ready to be an
internet “dial-up” BBS.

The status will also show the current transmission settings of the serial port.
Baud rate, bits per word, parity and number of stop bits. These do not affect
TCP/IP connections but the emulation will limit transmit and receive speeds
based on port setup. Most original TRS-80 hardware could be set up to have
different transmit and receive speeds. That unlikely configuration will be
hidden from view. In the Model 2 line the higher baud rate settings are not
exact. trs80gp will display the exact baud rate (feature or bug? You tell me).

As a convenience trs80gp can launch DT-1 and
Videotex terminals directly from the command line
or in the serial port connection dialog. For example, you might launch a
two terminal Xenix system with:

     trs80gp -m6000 -h xenix33.cfg -rA :dt1 -rB :dt1

Or you can choose the desired terminal from the dropdown in the
serial port connection dialog. Either way, these terminals will act
as a unit with the main trs80gp emulator. If you exit the main emulator
the terminals will also be forced to exit.

There is not yet a facility to map serial ports to real serial ports on
the host machine.

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 TRS-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 TRS-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
trs80gp itself. It also can be thought of as a way for the emulated TRS-80
to act as a batch processor. More on this in the
programming section.

Turbo Mode

trs80gp can be explicitly or manually told to enter turbo mode where the
emulated TRS-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 TRS-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 TRS-80 in the best light trs80gp
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 TRS-80 as if each key has been held down
for a very long time. This is mitigated by trs80gp 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.

At the expense of graphical and timing accuracy the emulator can run up
to twice as fast as turbo mode with the -haste command line argument
(or by using the File → Haste menu item). As the old saying goes,
haste makes waste so only use this when speed is vital. Besides only
updating the display once per second, “haste” skips wait state calculations
which will throw off the timing of a program that accesses the display.
Any video capture will also be distorted.

Display

By default trs80gp starts in authentic display mode. This mode
looks most like the original TRS-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
TRS-80 pixels and PC display pixels even if the aspect ratio is not the
same as the original TRS-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 TRS-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.

trs80gp 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 TRS-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 TRS-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 -).

Under Windows trs80gp remembers the display mode and window positions for
each particular model. The windows can be set up just the way you like them
and will be in those positions the next time you run. If you run more than
one trs80gp emulator for a model at once the second and subsequent instances
will have their own set of window positions and display settings. They will
also indicate the instance as a #2, #3, etc. in the
window title bar.

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 TRS-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 TRS-80 to cheap display mode.

FreHD Emulation

Since trs80gp can emulate a
hard drive itself, FreHD emulation just means the other handy features of the
FreHD such as the real time clock and access to the host file system for
file import and export. It also means you can
experience TRS-80 video and test
your own FreHD files without needing a real TRS-80 or FreHD.

There are only two FreHD features not implemented. The VHDUTIL
cannot set the clock and you cannot mount floppy disk images through the
FreHD using the special DSK/DTC device driver.

In most cases all that’s needed is to copy the contents of a FreHD SD card
to a directory (or simply mount the SD card on your PC) and run:

     trs80gp -m4 -frehd_dir frehd_file_directory

Or use the Hard Drive → FreHD → Directory… menu to
accomplish the same thing through the GUI.

FreHD setups often come with patched versions of the TRS-80 Model 1, 3 or 4
ROMs that will boot from the FreHD when the machine is powered on. Normally
they will only boot from floppy disk and require a special boot floppy that
boots with the hard drive active. Add the -frehd_patch option or
use Hard Drive → FreHD → ROM Patches to have trs80gp act the same way.

When FreHD emulation is enabled trs80gp will try to connect the image files
hard4-0, hard4-1, hard4-2 and hard4-3
in the root of the FreHD directory as hard drives 0 through 3 respectively.
But it will only do it when the respective hard drive has no image connected.

The built-in FreHD loader block can be overriden with a custom 256 byte boot
block using -frehd_load file.bin or the
Hard Drive → FreHD → Loader… menu entry.
FreHD’s auto-boot normally tries to load the FreHD menu from a
frehd.rom file in the FreHD directory.
For convenience, trs80gp has a version of the FreHD menu program built-in and
you can activate it with -frehd_menu or
Hard Drive → FreHD → Built-in Menu.

The FreHD Boot Sequence

On a real FreHD changing the loader block requires a rebuild of the firmware.
It is far easier to experiment with such changes on trs80gp. However, the
FreHD boot sequence is not widely understood so I will go over it in some
detail to help anyone debugging or developing for the FreHD.

The Model 4P is the only TRS-80 in the 1,3,4 line that has hard drive boot
code in its ROM. A properly configured hard drive image will boot on the 4P
without any FreHD auto-start patches to the 4P’s 4K ROM.

The FreHD auto-start patches do not add direct hard-drive booting to the
Model 1, 3 or 4. Instead, just before trying to boot off the floppy,
they load and execute 256 byte FreHD loader block
into RAM location $5000. If the space-bar is held the loader block will
return to the ROM and the boot will proceed normally.
Otherwise, the loader block will then try to load and
execute the frehd.rom menu program from the SD card. Despite it’s
suffix, the frehd.rom file is actually in /CMD format.

The FreHD menu program displays a nice splash screen which includes
the version number of the FreHD firmware (as determined by querying the
FreHD itself). It then uses the FreHDs extended facilities to list
available hard drive images to boot. When the user selects one it
instructs the FreHD to mount that hard drive image and proceeds to
boot it.

Booting is mostly a matter of loading the second sector from the hard drive
into $4300 (or $4200 on the Model 1) and executing it. Before doing so
the FreHD menu will write the current time and date into a few locations.
Most TRS-80 operating systems will check for a valid date in these locations
when they boot and not prompt for one.

Here is where I am not entirely clear on the exact operation for the FreHD
menu program. It will also try to make patches to the boot block and perhaps
even the operating system itself. I believe the intent of these patches it
to allow certain TRS-80 operating system to accept the pre-initialized
time and date. There may well be other purposes.

Boot Sequence in Depth

Note that you could write your own frehd.rom menu program. And
in the general sense it could do anything you want. It could just be a
game that auto-boots on the FreHD. But if you aim to improve the menu
or even make a different loader block then you’ll want to
consult the source code.
And continue reading as I have a few more details on how it all hangs
together.

On the Model 3 a fairly short sequence of ROM BASIC commands can be used to mimic
the auto-start ROM patch:

     POKE 16912,16
     10 OUT 197,3
     20 IF INP(196)254 THEN PRINT"No frehd":END
     30 FORI=0TO255:POKE20480+I,INP(196):NEXT
     RUN
     SYSTEM
     /20480

The same code will work on the Model 4, just change line 10 to output 4.
And on the Model 1 don’t do the initial

POKE

and change line 10
to output 1. The initial poke turns on

EXTIO

in the shadow register
of port $EC. Without that the FreHD will not see accesses to it.
Note that the program will not work in Disk BASIC since the POKEs will
scramble the extra code loaded by Disk BASIC and crash the program.

Notice that the loader block must start with $FE or it will be ignored by
the auto-start patch. That’s so the auto-start patch has no effect when
there is no FreHD attached. It is actually bytes 1 through 255 of loader
block that are put into RAM $5000 (20480). The last byte at $50FF is the
first byte which is $FE. The initial OUT to port 197 ($C5) serves
two purposes. It tells the FreHD to start feeding byte 0 and on of the
load block when reads come in on port 196 ($C4). And it outputs that
value as byte 2 of the loader block. Since execution begins at byte 1
the loader block must put an instruction there which effectively skips
byte 2. As such, loader blocks have byte 1 set to $FE which is the
Z-80 CP A,n instruction.

This byte is used by the auto-start patch to indicate to the FreHD menu
program what type of TRS-80 it is running on. Hence the 1 for Model 2,
3 for Model 3 and 4 for Model 4. The Model 4P auto-start patch puts in a 5.

If the loader block cannot find a frehd.rom file on the SD card
it will simply return and the TRS-80 will boot as normal.

Once the FreHD menu program is loaded it will load the model number from
location $5001. Initially it uses the model number to decide if it should
use the ROM routine to read the keyboard (1, 2, 3, 4) or its own keyboard
scanning for model 5, the 4P. It then scans the root directory of the SD
card looking for hard drive image files in
HDV format.
A file must start with the bytes $56 $CB, have bit 0 of byte 8 set (indicating
autoboot) and byte 11, the OS type must be one of:

     0 for LS-DOS 6.3.1
     1 for LDOS 5.3.1
     2 for CP/M
     3 for Newdos 2.5
     4 for Model I LDOS 5.3.1
     5 for Model I NEWDOS 2.5

trs80gp’s built-in FreHD menu also experimentally accepts 6 for MULTIDOS.
Files meeting these criteria will be listed for the user to select but with
one more condition for model number 5 (Model 4P). An OS type of 1 or 3
will only be listed if a ‘modela.iii’ is on the SD card. That’s because
those are Model III OS’s and will only work on the 4P if the ROM image
has been loaded.

As mentioned before, once an image is selected it will be mounted as hard
drive 0 and the menu will kick off the boot by loading sector 2 from the
hard drive into $4300 (or $4200 if the model number is 1).

It will also write the current date and time into one or more memory locations
depending on the model number and OS type. This will make most TRS-80
operating systems skip prompting of the date and time as they are already
initalized.

Before executing the boot block the FreHD menu system may patch the hard
drive boot block (or even, I think, some of the code loaded by the boot
block) for unclear purposes. I suspect it is to allow some of the
OS’s to accept an initialized date. And maybe even patch the OS to load
from the hard drive instead of diskette.
The menu will also load the modeala.iii
from the SD card on the Model 4P if the OS type is 1 or 3 so those Model 3
operating systems will work on a 4P which does not have the necessary
BASIC ROM to support them.

After that the FreHD system is out of the picture and the operating systems
boots as it would off a regular hard drive.

The diligent programmer can make use of the various memory locations
and I/O ports to set breakpoints to inspect the boot process at any point
in its various steps. Special FreHD operations such as opening and reading
files on the SD card are recognized and displayed clearly in the
bus trace allowing a high level view of what a
program is doing with the FreHD.

Programming

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

Running Programs

Normally on a TRS-80 programs are run either as

/CMD

files at the
TRS-DOS prompt or loaded from cassette with CLOAD or SYSTEM commands.
This is the best way to test programs you write but only needs to be done as a
final test. For development trs80gp will directly load programs from
the command line or via the File → Run… menu or via drag and drop.
This is largely similar to standard procedure but does has its differences.
Existing TRS-80 games often work well when run directly but there’s no guarantee.

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 trs80gp
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 trs80gp exit. You can then
run it using:

     trs80gp -m4 -ee program.cmd

And it will go through its paces writing output to

trs80-printer.txt

.
If trs80gp 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.

It is worth re-iterating that automated input options
are tantamount to scripting control over the emulated TRS-80 and can be used
to build up automated tests of your TRS-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 section just below
the “Go” button. Breakpoints cover a range of addresses from the value
in the left box to the one in the right which will be filled in semi-automatically
to specify a single address. Make sure to tick the checkbox next to the
start address/label to enable the breakpoint. PC breakpoints can also
be set by double-clicking on the Disassembly sub-window.

You may set up to 4 breakpoints of each type. A “PC Breakpoint” is the
traditional kind which is triggered whenever a program executes in the given
address range. Other types trigger whenever memory is read or written in
the range or I/O is performed. These types are useful to find when particular
variables are changed or accessed and finding when devices are accessed.
Breakpoints may also be set on the command
line by the -b, -bm, -bio and related options.

A > appears in the disassembly window to indicate the next
instruction to execute and an asterisk (*) to show any active
PC breakpoints.

Memory and I/O breakpoints (or if the Z-80 has set breakpoints using the
the Emulator Extensions) show extra information in the
debug window when they are triggered.
The Disassembly sub-window will show a ! to indicate
the instruction that caused the fault and additional letter codes
indicating what kind of fault or faults occurred. The > will
point to the next instruction to execute as usual.

       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 except for the T-state and cycles counters.
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 programmers 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 “Emulator Extensions” 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 give the CRT beam raster Y and X coordinates. The debugger
is still operational when the TRS-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, the 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. There may be no memory for some
of the address space (e.g., $3000 .. $37FF on the Model I). Such regions
will display as ~ff (or ~00 on the Model II) and cannot
be changed.

You can also select just the RAM to focus on the 48K of memory. But keep
in mind these other views use 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).

You can search through memory by typing a string into the search box.
The usual backslash escapes can be used for control and graphics characters:
n, r, t and HH for any hexadecimal value.
If the string starts with $ then the rest is taken to be
hexadecimal digits with spaces ignored.
The < and > buttons cycle through the matches
which are highlighted in the memory window below.

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 TRS-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 trs80gp'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 trs80gp'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 trs80gp 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.

The debugger also provides a sub-window for watching expressions.
For each expression you choose what result to show: The memory byte or word
at the calculated value, or the value itself (or the high/or low byte of the value)

Expressions use C-like syntax consisting of:

• Decimal constants (use $ or 0x to prefix hexadecimal constants)
• Parenthesis to control order of evaluation
• C number operations: + - * / %
• C bit operations: ! ~ << >> & ^ |
• C comparisons: == != < > <= >=
• C logical and/or: && ||
• Register names: e.g. A B C AF HL IX AF'
• Register flags: e.g. F.C, F.N
• Source code symbol values (if loaded)

There is a special syntax for reading memory inside an expression.
The expressions

(expr)b

and

(expr)w

return the
value of the byte or word at the memory location inside the expression.

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
and other command line option to set breakpoints.

In certain situations you may want to have symbols available for a program
but don't wish to load it into memory. The -ls command line option
and File → Load Symbols... menu entry are used to only load the symbols
from a .bds file. Doing so allows you to use symbolic names in
the debugger but does not alter RAM contents in case the program is already
underway.

Disk Viewer

Under the Debug menu there is a Disk Viewer which allows you to browse
through all the floppy and hard drive images inserted and examine their data.
There is a search feature to look for strings or binary data.
The usual backslash escapes can be used for control and graphics characters:

n

,

r

,

t

and

HH

for any hexadecimal value.
If the string starts with

$

then the rest is taken to be
hexadecimal digits with spaces ignored.
The

<

and

>

buttons will cycle through all the matches.

Use the drop downs to select disk images, sides, tracks and sectors. The
sector dropdown presents both the physical and logical sector numbers. The
logical number is the value written on the disk and is what is used when
we generically refer to reading or writing sector N. The physical number
is the relative position of the sector in the track.

Device Map

The debug menu also features the somewhat experimental "Device Map" feature.
It gives you a quick overview of the current mappings of Z-80 address and
I/O space to RAM and devices. In short, something like the typical memory
map seen in programmer guides. Do keep in mind that it shows the mapping
when it was brought up. If the program subsequently switches memory maps
the window will not be updated.

The feature is experimental mainly because it doesn't yet display all
the emulator implicitly knows about the address space. For example,
the Model I does not have any memory mapped from $3000 to $36FF but the
map will display that as read-only RAM. And it says nothing at all about
the memory mapped printer and floppy disk devices accessible in the
$3700 - $37FF range. In other words, the map can be incomplete or misleading.
But it seems more handy having it around even with its current shortcomings.

Advanced Recording

Sometimes examining memory in the debugger is too cumbersome. The
"Text VRAM", "Graphics VRAM", "RAM", "RAM16" and "Expansion 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 "Emulator Extensions" 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
     6     Control recording
              B=$41 - toggle audio recording
              B=$4D - toggle Mhz Audio recording
              B=$47 - toggle animated GIF recording
              B=$46 - toggle Flash video recording
              B=$56 - toggle video recording
              B=$53 - take screenshot
              B=$47 - take cleanshot
   64..127 Set parameter (see below)
     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 7 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
     64    DMA        D

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

For BASIC where OUT is readily available but controller register
contents is difficult there a way to trigger any function with just OUT
commands.

OUT 71,32+n will trigger function n using whatever parameters
were previously set. A parameter is set by first doing an OUT 71,64+p
where p is the parameter number and then doing OUT 71,x to
set the value. If a command requires a register then the parameter triggered
version of the command will read parameter 2 for register B, parameter 3 for
register C, parameter 8 for H and so on. Or put another way, you select
the parameter for register R by sending the ascii value of the register letter.

For example, this will toggle animated GIF recording:

    OUT 71,66:OUT 71,71:OUT 71,32+6

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. trs80gp 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. An 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.

DT-1 Terminal

The TRS-80 DT-1 (Data Terminal 1) is not a computer but a terminal and as
such can do very little without being connected to a computer. It does have
a built-in SET-UP screen that needs the
DT-1 User's Manual
to be understood. Do note that you must press Page-Up on trs80gp to access
the setup screen as Ctrl+Shift+Enter will not work. And if you're in the
setup screen use Page-Down to active the "KL" easter egg rather than
pressing Ctrl+Shift-4.

The trs80gp Setup menu provides all the functionality of the DT-1 SET-UP screen
in a somewhat more descriptive format. It will also change the SET-UP screen
if you're in it so you can learn the cryptic settings. Use Setup →
Duplex → Half to put the DT-1 into a mode where you will see each
character you type. If you're feeling really adventurous type
G2BlinkingG0text to see some blinking text.

trs80gp's DT-1 emulation is missing a few features of the original. There's
no way to attach a printer, not all input keycodes can be generated, there's
no half-intensity text mode and no beep. If you have a real DT-1 please get
in touch as a few tests could go along way to implementing the missing features.

TRS-80 Videotex

The TRS-80 Videotex terminal was an early foray into online information
access. It had a 300 baud modem allowing it
to get the latest news and information.
The built-in software is very minimal and trs80gp itself hasn't been
polished enough yet to help round off the rough edges.

The Videotex could run in offline mode. It lets you enter pages of text
and it was possible to later upload that data to an online service.
To experience this, run trs80gp -mv or use
File → Change Model → Videotex. Press almost any key
(except backspace) and you'll be entering text in the offline mode.
Take time to be amazed that it word-wraps text as you type.

If you press backspace (which is a physical mapping of the BREAK key;
sorry about that) it will then prompt you with "PLACE CALL". On the
real machine you'd pick up your phone, dial the information service.
When in answered you'd put the phone down and press ENTER to let it
know you're connected.

When you hung up the phone (or the server hung up) the terminal will
print OFF LINE indicating this. There was also an LED, I gather.
There must be some way to proceed from this point but either I don't
know what it is or trs80gp doesn't quite emulate it yet. You can reset
the emulator if necessary.

       trs80gp -mec -i "A 10 4 HELLO WORLDr"

    Graphics Modes:

    0	alphanumerics and semigraphics-4
    1	2 x 3 semigraphics-6
    2	 64 x  64 x 4 graphics
    3	128 x  64 x 2 graphics
    4	128 x  64 x 4 graphics
    5	128 x  96 x 2 graphics
    6	128 x  96 x 4 graphics
    7	128 x 192 x 2 graphics
    8	128 x 192 x 4 graphics
    9	256 x 192 x 2 graphics

    open trs80gp.app --args -m1 -pcg-80

    trs80gp.app/Contents/MacOS/trs80gp -m2 -turbo