MAXAM is one of the best allround assembly language packages for the CPC, but it lacks some monitor functions found in other programs. Arnor has recently produced an upgraded Maxam 1.5, but despite the improvements the all-important option of stepping through machine code a command at a time hasn't been allowed for.
Program I adds to Maxam the ability to set breakpoints, single step your code, and assemble directly from Protext. Note that to make use of this facility, you MUST already have Protext and Maxam.
Type in the program, save it as ASM.BAS, then run it. It is a Basic loader which will locate the machine code close to the top of free memory. The code is then saved as a binary file to disc or tape, and two RSX commands are initialised.
Take great care when entering the data as there is no checksum value at the end of each line. Instead, a checksum t,otal is used in line 1100, and if an error does occur you'll have to check individual lines with the checksum utility.
Don't discard the Basic loader because it can be used to relocate the code to other addresses by altering line 50.
The poker takes a little while to run, but on subsequent occasions the saved binary program can be used to log in the new commands. This has a name such as ASM+STEP.&9E, where the filename extension - &9E -indicates the address where the program loads, and which therefore has to be called to initialise it. For instance, &9E gives an address of &9E00 - the last two digits are always zero.
If you choose to re-poke at an odd address, the loader will round this down to the nearest page boundary.
There are two new commands -|ASM and |STEP - which can be loaded and set up using a small routine such as:
LD MEMORY &9DFF
20 LOAD "ASH+STEP.&9E"
30 CALL &9E00
Although Maxam's editor is good, it is not a patch on Protext. I often used to write code with the word processor (in PROG mode), save it, then load it into Maxam for assembly. This fiddly process is now banished for good, as i ASM will assemble source code in Protext.
|ASM can be used from command mode, or even Basic. It works by pretending that the code has been written using Maxam, and then executing the command |ASSEMBLE.
Unfortunately, this means it will get confused if you include printer codes, block or position markers. None of these are used by Maxam, and they will be treated like an END instruction if they are present. Talking of END, your source code must have this pseudo-opcode at the bottom or an error may be generated on assembly.
|STEP adds the ability to single step through machine code one command at a time, and to view or change the contents of the registers and flags at any point. It is also possible to set a breakpoint further on in the program and let it continue without single stepping. You can even change the code by replacing one instruction with another. To step through a program starting at, for example address &XXXX, type:
The state of the registers and the first machine code command will be displayed, as shown in Figure I.
If you wish this command to be executed, press any key except Escape, Tab, Del or Enter, which all have specific functions. The instruction will then be run, and the new register contents displayed at the next command.
To carry on single-stepping without executing the current command, press Del. If you want the instruction to be carried out, but you do not want to step through a subroutine - such at the one at &A140 in the example above - press Enter. You do not need to use Enter for calls to addresses above &BB00 or below &40, as these will be carried out automatically.
The Tab key will put you in edit mode, and the display will be similar to Figure II.
The cursor is now under AF, and any of the registers or other details displayed may be changed. If you want to leave a value unchanged, pressing Enter will move the cursor to the next item, and when you've finished editing press Escape. Commands can be altered by typing in a new mnemonic under the old one.
When editing commands, you should ensure that the code doesn't change in length. For instance if we wished to change a CALL &1234 to LD A,1, we would have to place a NOP instruction in the code as well. This is because the original instruction contained three bytes, whereas the new one only has two. The NOP command, which means No OPeration, keeps the code to the same length.
To let the machine code run without single stepping through every command, set the PC to the next address at which you wish to stop the program. This address must be the first byte of a command, and it must not, of course, be an address which will be by-passed by the program.
AF BC DE HL SP IX IY PC
0000 0000 0000 0000 6FF8 0600 0000 A100 CALL &A140
Figure I: Register status and next instruction
AF BC DE HL SP IX IY PC flags:SZ-H-PNC
0000 0000 0000 0000 BFF8 0000 9000 A100 CALL &A140 00000000
Figure II: Edit mode, including flag status
The machine code being stepped through can be exited at any point by pressing Escape, and the program can be restarted at the same point and with the same register values by typing |STEP without parameters.
There are a couple of restrictions. The program will not work with interrupts disabled, so if the program contains the instruction Dl, the PC must be set to a point after the next EI. The only other commands which cannot be stepped through are RSTs 1,5,6 and 7, but these rarely occur.
This stepping function works by temporarily replacing the first byte of the command to be executed with a RST 6 instruction. This intercepts the Maxam break function, which in turn displays the register contents and disassembles the next command.
Whenever the next instruction is a CALL, JP, JR or RET, the next breakpoint is calculated accordingly, but a break is also placed immediately after the command in case it isn't carried out. For instance CALL C,addr when the carry flag is not set. After Maxam has displayed the register contents, these breakpoints are removed and new ones calculated.
In edit mode the assembling of new instructions is carried out through Maxam's ASSEM. The register values are stored independently of Maxam, which allows them to be changed in edit mode, and also the program can be resumed with |STEP. It is possible to use this function with Maxam 1.5, but because this displays the registers down the screen instead of across, and in a slightly different order, it takes a little getting used to.
With the new facilities installed Maxam is possibly the best assembler disassembler and monitor package on the market. It may take a little time to type in this program, but it will save you hours of frustration in the future.