README for tpasm assembler tools by Chris Williams Introduction ------------ The tpasm assembler is a very nice assembler, containing many useful features an assembly programmer needs. It works nicely for making TI-86 ASM programs, but it can't create .86p files (it doesn't know how). That is why I wrote a couple little utilities to help create .86p files from any stage in the compilation process - from the hex output file of the assembler to the raw binary object file. I also wrote a useful shell script which automates the entire process (OK, so it can't write programs for you!). I have tested and use these programs regularly for my own assembly programming, so I think they work pretty well. That doesn't mean they're perfect, but they're not cheap junk (much). :-D Description of the Utilities ---------------------------- The ihxtobin utility converts a file in Intel hex format to a binary file. The tpasm outputs in the (among others) Intel hex format, so this program is needed to get a raw binary file from the Intel hex file. ihxtobin creates a binary file of the smallest size that still contains all of the data. That is, offset zero (0) of the file (the first byte) is the lowest address found in the Intel hex file, and the last byte is the highest address. The mk86p utility creates a .86p program variable file from any other file (raw binary or even text). It can be used to create any machine-language or BASIC program variable. It can make the program variable locked, unlocked, tokenized, or untokenized. It also allows you to specify the on-calc variable name as well as a comment which goes in the .86p file. The mk86asm.sh script ties tpasm, ihxtobin, and mk86p together to create program variables from one or more assembly-language source files and does so in a robust manner. It can process any number of separate assembly programs with one invocation, so you don't have to run it for every assembly program you want to compile (e.g., you can run "mk86asm.sh *.asm *.z80" to compile every .asm and .z80 file in the current directory). How to Use the Utilities ------------------------ The simplest and easiest way to create a .86p file from an assembly program is to invoke mk86asm.sh with the name of the .asm (or .z80 or whatever) file as the only argument. A TI-86 program variable with the same name as the .asm file is created. mk86asm.sh will inform you if the program does not start at _asm_exec_ram (0xD748), so it helps you to avoid simple errors like forgetting to write "org _asm_exec_ram" in your program. If you want to specify the on-calc variable name (different from the .asm filename, for example), simply supply a "-n " or "-n=" (without quotes) *before* the .asm filename. If you specify a variable name, it applies only to the next .asm file. For more sophisticated uses, you could create a .86p file from any arbitrary file. For example, you could write a TI-BASIC program on your computer, using the text editor of your choice, and then create a .86p file from that program (caveat: some characters like newline are different). I can't really think of any useful uses for this, but the possibilities are there! The ihxtobin program can be used outside of TI assembly programming. Other (usually embedded or microcontroller) assembly programming and memory flashing typically use files in Intel hex format to describe memory state. If you have such a need to convert Intel hex files to raw binary files, then ihxtobin is the answer (I might be able to use it for a 68HC11 assembly programming class, for example). To use tpasm, read the README.TXT file found in the tpasm.tgz file. Other Considerations -------------------- The tpasm, ihxtobin, and mk86p programs must be compiled before they can be used. Just compile ihxtobin with "make" (without quotes) in the ihxtobin directory and mk86p with "make" in the mk86p directory. To make tpasm, first untar tpasm.tgz with "tar -xzf tpasm.tgz", enter the tpasm directory, and then "make" (read the documentation that comes with tpasm for full instructions). The programs I wrote were written without any platform-specific features (they should compile and run on any POSIX- and/or ANSI C-compliant system), so you shouldn't experience any problems. If you do, however, please send me (via email) any diagnostic messages you receive and a fix if you can make one. The mk86p program, for example, has a debugging mode by defining DEBUG during compile (with "-DDEBUG"). In debug mode mk86p displays some helpful messages. All of these programs (ihxtobin, mk86p, as well as tpasm) must be in your PATH env variable for mk86asm.sh to work correctly. I have a ~/bin directory which contains a symlink to mk86asm.sh called mk86asm (among other symlinks), and ~/bin is in my PATH, so I can invoke "mk86asm" from any directory. You can obtain the newest version of tpasm from http://www.sqrt.com. Read the README.TXT file in the tpasm.tgz file. Acknowledgments --------------- Texas Instruments, for great calculators (TI-86, 89, and 92+, of course!). Todd Squires (and others) for the nice tpasm assembler