trld - convert/combine TRS-80 executables
trld reads one or more TRS-80 programs in .cmd, .cas, .hex or .bas format and saves them as a single .cmd, .cas or .hex file. As input it supports 250, 500 and 1500 baud .cas cassette image files as well as tokenized and ASCII .bas BASIC program files. Output can be in .cmd, .cas, .hex or .wav (audio file) format.
A precompiled binary for Windows is included along with the source code which can easily be compiled on Mac and Linux systesm. These program loading routines are the same ones used in my TRS-80 Model I/III/4 emulator.
trld is a command-line tool. It takes a list of files. The last one is the output file, the rest are loaded in sequence and combined together to form the output. The format of the input files is determined automatically. The output format is chosen depending on the file suffix. For example, to convert a cassette file to a .cmd (disk executable format) you would type:
trld original.cas original.cmd
With multiple input files the program start address is taken from the last file. For ".cas" output the name of the SYSTEM file is based on the first 6 letters of the output file name. With
trld file.cmd ..\converted\out.cas
The "..\converted\out.cas" file will be called "OUT" and that's the name you must pass to the SYSTEM command. If you're using Play CAS, it tells you the tape file's name.
Option Reference
-c | Clean - don't pad .cas tail with zero bits. |
-i | Ignore checksum errors. |
-t | 250 baud output (if output is a .cas or .wav file) |
-l | 500 baud output (if output is a .cas or .wav file) |
-h | 1500 baud output (if output is a .cas or .wav file) |
-n | Put file name in .cmd output. |
-s N | Stop at stage N of relocation and/or cassette loading. "-s 1" to do nothing, "-s 0" to keep trying indefinitely. "-s 2" to do one stage of relocation/loading. |
-v | Output extra information for debugging purposes. |
-d {file} | Dumps load records from one or more files. If this option is used there is no output file. |
-inf {file} | Prints file type information for one or more files. If this option is used there is no output file. |
Output format selection
The output format will change depending on the output file name's suffix.
.cmd | TRS-DOS program data. |
.hex | Intel HEX record data. |
.cas | Cassette format at input's baud rate or 1500 if unspecified. |
.tcas .250.cas | 250 baud cassette Level I CLOAD data. |
.lcas .500.cas | 500 baud cassette SYSTEM data. |
.hcas .1500.cas | 1500 baud cassette SYSTEM data. |
.wav | Cassette audio at input's baud rate or 1500 if unspecified. |
.250.wav | 250 baud cassette SYSTEM audio. |
.500.wav | 500 baud cassette SYSTEM audio. |
.1500.wav | 1500 baud cassette Level I CLOAD audio. |
Program Relocation Handling
The "-s" option detects relocation code and cassette loaders, runs them and puts the resuls into the output file. For example, many disk executables (.cmd) start with a short block of code that copies the entire program to a different spot in memory and jumps to it. Similarly, a few games had their own custom cassette loaders. The first program on the cassette was a short loader program that would load the rest of the tape in some custom format.When "-s" detects these it runs them and puts their results in the output file. In fact, it works by running the program for a few thousand steps to see if the program ends up jumping into a place where it wrote data. With a few little tricks to distinguish between a bulk copy operation and run-of-the-mill self-modifying code.
This is mostly useful when disassembling programs. By detecting these loads and relocations you get a proper disassembly of the game itself rather than one where most of the absolute addresses are offset or where there's no game code at all but just a cassette loader.
The number given to "-s" indicates the number of times it will look for these. For example, "Time Trek" for Level 2 BASIC starts with a small loader program which auto-runs, copies itself to lower memory, loads the game from cassette and jumps to it. With "-s 1" the output will be the loader before relocation. With "-s 2" the output will be the relocated loader. With "-s 3" (or "-s 0") the output is the game itself.
Input and output files can be named ".rom" indicating they are binary dumps starting at address 0. Thus trld can convert a ".rom" file into the various output formats and also convert the various input formats into a ".rom" file. For ".rom" output the file is padded with zeros for any areas of memory not loaded into by the source file.
A caution on BASIC
While BASIC programs can be loaded, their output is in the form of an executable which will work on a cassette-based TRS-80 Model 3 as a load address is hard-coded. This is odd and unlikely to be useful to many. This can be suprising as you might expect:
trld file.bas file.cas
To output a cassette image file that you load with "CLOAD" but instead get something that loads with "SYSTEM". Converting BASIC programs between different formats is pretty easy but might best be a job for a different utility program.
George Phillips, July 29, 2018. george -at- 48k.ca