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. It supports 250, 500 and 1500 baud .cas cassette image files as well as tokenized and ASCII .bas BASIC program files. Source code for Windows is included; only small changes will be required for other operating systems. These program loading routines are the same ones used in my TRS-80 Model I/III 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 high-speed (1500 baud) 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.
|Ignore checksum errors.|
|Low baud output (if output is a .cas file)|
|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.|
|Output extra information for debugging purposes.|
|Dumps load records from one or more files. If this option is used there is no output file.|
If the output file ends in ".lcas" it will be saved as a low-baud (500) cassette image. If it ends in ".hcas" it will be saved as a high-baud (1500) file (the default if ".cas").
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, August 23, 2015. gp2000 -at- shaw.ca