trs80-tool
is a command-line tool for inspecting and
manipulating TRS-80 files, cassettes, and floppies. Its source code is
available on Github.
You can download stand-alone binaries of the latest version:
The trs80-tool
program supports these file formats:
.BAS
PRINT
are stored as a single byte), but the tool supports reading Basic programs
that are in text (non-tokenized) format. When writing a file with a .BAS
extension,
the file is always tokenized..ASC
.WAV
.CAS
.CMD
.SYS
.CMD
, but is meant to store system code
in an disk operating system..3BN
.CAS
files..L1
.JV1
.JV3
.JV1
because it can encode a mix of FM and MFM signals on the same track..DMK
.DSK
.JV1
,
.JV3
, or .DMK
file. Use the
info
command to find out..SCP
.ASM
.CMD
, .SYS
, or
.3BN
file using the disasm
command..LST
asm
or disasm
commands’
--listing
flag..ROM
.BIN
.ROM
..HEX
The tool takes a command as its first argument:
% trs80-tool COMMAND args ...
Global flags are:
--version Show the tool's version number.
--help Show the usage message.
--color=COLOR Force color mode (off, 16, 256, 16m, or auto).
By default trs80-tool
detects the color capabilities of the terminal
and sets the --color
flag automatically. You can override this, either
to turn off color (if it bothers you) or to force it on (when piping into
a pager). For example:
% trs80-tool --color=16 hexdump in.cmd | less
--trace=MODULE show trace logs for module (base, emulator, floppy).
Show tracing logs for the specified module. These log lines can reveal how the module makes various decisions, and can help debugging. This flag is mostly intended for the developer, but can help explain why (for example) a specific floppy isn't being recognized. The “base” module deals with TRS-80 file formats; the “emulator” module is the TRS-80 emulator itself; and the “floppy” module is for floppy-related messages. Repeat the option to enable tracing for multiple modules.
dir
The dir
command shows the contents of an archive file. Archives
files are those that can contain other files. These are cassette files
(in WAV or CAS format) and floppy disks (in JV1, JV3, DMK, or SCP format).
% trs80-tool dir FILE
The output format depends on the type of archive. Cassette files show baud rates, whereas floppy disks show creation date and type of file.
Normally system file are hidden, but can be shown by specifying
the --system
option.
info
The info
command takes a list of filenames and displays a one-line
description of the contents of the file, such as its type (system
program, Basic program) and, if known, the embedded filename.
% trs80-tool info in1.cmd in2.bas in3.cas in4.wav
The --verbose
flag displays some information (like floppy geometry) for
some file types:
% trs80-tool info --verbose in1.dmk in2.dsk
convert
The convert
command converts a list of input files to an output file or
directory. There are several different ways to use this command.
A single file can be converted to another format:
% trs80-tool convert in.cmd out.3bn (diskette to cassette format)
% trs80-tool convert in.bas out.asc (de-tokenize Basic program)
Several files can be put into an archive:
% trs80-tool convert in1.bas in2.3bn in3.cmd out.wav
This creates a cassette audio file containing the three files. Note that the
.CMD
file will be converted to .3BN
format.
Archive files can be extracted if the destination is a directory:
% mkdir out
% trs80-tool convert in.wav out (decode cassette and extract files)
% trs80-tool convert in.cas out
% trs80-tool convert in.dmk out
Archive files can be converted to other archive formats:
% trs80-tool convert in.dmk out.wav
% trs80-tool convert in.wav out.cas
When writing a cassette format, the baud rate of the input file will be used, if it's known:
% trs80-tool convert in1.cas in2.cas in3.cas out.wav
(The baud rate can be guessed from the .CAS
file contents.) If the
baud rate can't be guessed, 500 baud (low-speed) will be used:
% trs80-tool convert in1.bas in2.3bn out.wav
This can be overwritten using the --baud
command-line flag:
% trs80-tool convert --baud 1500 in1.cas in2.cas in3.cas out.wav
% trs80-tool convert --baud 1500 in1.bas in2.3bn out.wav
If a system program doesn't have a built-in start address, one
will be guessed by the info
command:
% trs80-tool info in.cas
in.cas: System program (VCEPRN, /17408) on a low speed cassette
The start address can be set with the --start
flag:
% trs80-tool convert --start 17408 in.cas out.cas
Wrote out.cas: System program (VCEPRN) in low speed CAS file
% trs80-tool info out.cas
out.cas: System program (VCEPRN) on a low speed cassette
The address auto
can be used to guess an appropriate start address:
% trs80-tool convert --start auto in.cas out.cas
Wrote out.cas: System program (VCEPRN) in low speed CAS file
When converting .BIN
or .ROM
files, the --start
flag specifies
both the load address and the start address:
% trs80-tool convert --start 0x1024 in.rom out.cmd
An assembly language listing disassembly file can be generated from .CMD
,
.SYS
, and .3BN
files:
% trs80-tool convert in.cmd out.asm
% trs80-tool convert in.3bn out.lst
The disassembler attempts to guess what is code and what is data. If the input program relocates itself, some entry points will be missing and code will instead be disassembled as data. You can explicitly list entry points:
% trs80-tool convert --entry 0x7059,0x7064,0x71B9,0x7263 in.cas out.lst
See also the disasm
command.
hexdump
The hexdump
command displays a hex dump of the input file, with annotations.
See the --color
flag for how to force coloring on or off.
By default the command will collapse consecutive identical lines:
% trs80-tool hexdump in.cmd
Use the --no-collapse
flag to turn off this collapsing:
% trs80-tool hexdump --no-collapse in.cmd
sectors
The sectors
command displays a table of the sectors in a floppy disk. The columns
are the sectors and the rows are the tracks. For each sector a character is displayed:
- No sector.
S Single-density sector.
D Double-density sector.
X Deleted sector.
C CRC error (ID or data).
? Missing sector.
Use the --contents
flag to also show the contents of the sectors.
The --bad
flag lists all sectors that are missing or that
have a CRC error, as well as which file (if any) is on each bad sector.
Can be combined with --contents
to also show the contents of the
bad sectors.
asm
The asm
command assembles the specified assembly language source code:
% trs80-tool asm program.asm program.cmd
It can generate .CMD
, .3BN
, .CAS
, .WAV
,
BIN
, or HEX
files. For .CAS
or
.WAV
files the default baud rate is 500, but can be set with the --baud
flag:
% trs80-tool asm --baud 1500 program.asm program.cas
A listing file can be generated with the --listing
flag:
% trs80-tool asm --listing program.lst program.asm program.cmd
disasm
The disasm
command disassembles the specified program:
% trs80-tool disasm saucer.cmd
If the program is a .CMD
, .SYS
, or .3BN
file, it is loaded into the correct place
in memory. If it's a .ROM
or .BIN
file, it is loaded at 0x0000, but this
can be change with the --org
flag:
% trs80-tool disasm --org 0x8000 file.bin
The disassembler tries to guess which bytes are code and which are data by
following the path of the program, starting with its main entry point. Additional
entry points can be specified with the --entry
flag:
% trs80-tool disasm --entry 0x0000,0x3799,0x377B model3.rom
Note that if any entry point is listed, then 0x0000 must be specified again if
applicable. The output can be controlled with --no-labels
to not create labels
for jump targets and --no-known
to not reference known ROM addresses. The
--hex-format
flag controls the format of hex numbers, which can be c
for 0x12
(the default), dollar
for $12
, or h
for 12h
.
A listing file can instead be generated with the --listing
flag:
% trs80-tool disasm --listing program.cmd
The --no-binary
flag will suppress opcode binary in the listing.
The --upper
flag will generate upper case assembly language.
run
Run a TRS-80 emulator in the shell:
% trs80-tool run
This is experimental and does not currently work well with games, and may not work at all in a Microsoft Windows shell.
Use the --model
flag to specify the model (1, 3, or 4, defaults to 3) and
the --level
flag to specify the Basic level (1 or 2, defaults to 2).
% trs80-tool run --model 1 --level 1
Specify a program or floppy to load and run directly:
% trs80-tool run tdos13a.dsk
% trs80-tool run frogger.cmd
Use the --mount
flag to specify a cassette
or floppy to mount:
% trs80-tool run --mount in.cas
Only one cassette may be mounted, but several floppies can be specified and will be assigned to consecutive drives, starting at 0:
% trs80-tool run --mount in.cas in1.dmk in2.dmk in3.dmk
If, from within the emulator, you modify the floppy, the virtual file
will be modified as well. Specify the --write-protected
option
to mount all floppies as write-protected.
The --xray
flag shows nothing in the shell but starts a web server
for the X-ray debugger. This is experimental and not yet documented.
repl
Starts an interactive session for exploring the Z80. Type help
to get
a list of commands. Type an assembly language instruction (such as ld a,5
)
to assemble it, write it to memory, explain it, execute it, and show
its effects on flags and registers. This virtual machine is not in
a TRS-80 context (it has no ROM or peripherals).
help
The help
command shows more specific information about other commands:
% trs80-tool help dir
% trs80-tool help convert
This change log covers the tool and the related web apps (My TRS-80, the IDE, and the cassette reader).
trs80-tool
:
trs80-tool
:
sectors
command has a new --bad
option
to show only missing or corrupted sectors, as well as which
file (if any) is on each bad sector. Can be combined with
--contents
to also show the contents of the
bad sectors.trs80-tool
:
run
command, if the mounted floppy is modified,
the changes will be written to the underlying virtual floppy file.
Specify the --write-protected
option to mount the floppy
write-protected.dir
command has a new --system
option
to show system files.nv
and v
for
po
and pe
flags.%
as binary
prefix. Instead of writing %1010
,
use 1010b
or 0b1010
.--upper
flag.info --version
.run
command.run
command..ASC
file)..CAS
files to avoid misdetection
of cassette headers.convert
command can go from .ROM
and .BIN
files to .CMD
and
.3BN
files. The --start
flag specifies the load and start address.repl
command.--no-labels
, --no-known
, --hex-format
, and --no-binary
flags
to the disasm
command.run
command.asm
command.sectors
command.--verbose
flag to info
command to display floppy geometry.disasm
command.hexdump
command.--entry
flag to help with disassembling programs that relocate themselves.info
command will display a guessed start address for system programs
with no specified start address.--start
flag to set the start address of system files.info
command.convert
command.