Debugging Existing Code - Example

This chapter gives a simple example on how to use the Direct Assembler to debug and change existing code. For all details please see chapter Direct Assembler.

For this example we will use a small Studio II game written in 1802 code.

First set up the Studio II emulator with the Space Invaders game:

• Select the Studio II tab (yellow ellipse)
• Select the RCA Studio II sub-tab (orange ellipse)
• Select 'invaders.st2' as CART (blue ellipse)
• Press Start (red ellipse)

A Studio II running Space Invaders should start. Make sure to play the game a bit so most code gets executed. So move to all directions, shoot some invaders and get killed yourself. Default the keys are mapped as follows:

Left: arrow left (4 on keyboard A)
Right: arrow right (6 on keyboard A)
Fire: space (0 on keyboard B)
Restart: 0 or tab (0 on keyboard A)

Select the 'Tools' tab (yellow ellipse) and then select the 'Direct Assembler' tab (orange ellipse), this should show the direct assembler GUI. Now change address to show address 400 and onwards by using the 'Move to:' field (blue ellipse) and/or the slider (green ellipse). Address hex 0400 is the start address of all Studio II software. This address will show an ST2 instruction SYS 45D (red ellipse) in steel blue , which is a call to an 1802 code routine at address 045D. From address 0402 to 041D (magenta ellipse) data bytes should be shown in blue. After that from 041E and onwards (brown ellipse) 1802 code should be shown in black.

The Space Invaders game runs somewhere from 0400 to 07FF, so now do a manual walk thru of the code from the current address to 0800. Easiest is to use 'SHIFT arrow down' which will go one page down on every press. What you need to look out for is if all 'code' is shown as 1802 code in 'black/orange' text and 'data' is shown in blue.

Have a closer look at all blue text as that is code or data which has not been executed by the emulator. So either it is data or maybe the code isn't execute for some reason.

The following areas will probably show up in blue, possibly even more or less depending on how long you play/run the game:

• 0402 - 041D (magenta ellipse above): As this is at the start of the game we can assume it is some kind of table. However so far no proof.
• 0594/0598: Two bytes, firs one is preceded by a SEX R3 and both by an OUT 2. So obviously this is data, i.e. an OUT 2 is being done with the 04 value stored on 0594:

  

• 0668: Same as 0594:

  

• 06CB - 06CF: This must be code! As it is preceded by a BNZ D2, so the 'zero' case will execute 06CB:

  

  To manually correct this part of the code first make sure mark type is set as 1802 (yellow ellipse) and 6CB is selected as address (orange ellipse). Now press the 'Mark' button (blue ellipse) for every address. See also chapter Changing Address Usage. This should result in:

  

• 06E4 - 06E7: Same as above, mark this also as 1802 code via the 'Mark' button
• 0733 - 0737: Same as above, mark this also as 1802 code via the 'Mark' button
• 076A: Same as 0594!
• 0770 - 07F7: Looks like the end of the code so probably not used
• 07F8 - 07FF: Some table

  

Now we are ready to save the program configuration including all debug information as just collected. To do this first press 'New' then fill in a file name, e.g. invaders.bin, code start = 0400, code end 07F7, end: 0800 and press Store. You should have the following configuration:

Press 'Save' and give the configuration a name, e.g. invaders.config.

The reason why we took 07F7 as code end is because it looks like there is a table from 07F8 to 07FF. So not part of the code as such but it still needs to be saved so 'end' marks 0800 so 0400 to 0800 will be saved.

Before we make any changes to the code we do need to check if there is any code that is location specific. I did the following:

• Move to address 0402 and press 'Load V' this will list all locations that possibly do something with address 0402. The following should be shown in the message area:
  Locations loading 'value' or 'location' 0402:
  LD H-L: 047A
  LD L: 047D
  LD L: 04E3
  LD H: 04FC
  LD H: 050E
  LD H: 0518
  LD H: 05A5
  LD H: 05B4
  LD L: 06DD
  LD L: 071D
  
• Let's start with the first and easiest one: LD H-L: 047A. Move to location 047A. Here you can see 0402 being loaded into RC (yellow ellipse). Looking at the code a bit closer it also reveals that a few LDA RC instructions are done (orange ellipse) and later a check if a '0' (blue ellipse) can be found branching out of the routine. So this concludes that 0402 to 041D is indeed a data table, it also ends with a '0' on 041D.

  

  Conclusion is that we can safely 'Mark' 047A as an LDL instruction (Select 'LDL' instead of '1802' and press 'Mark'), resulting in:

  

• LD L: 047D, part of the LDL we just found on 047A.
• LD L: 04E3, on first glance nothing to do with 0402 as this load 02 in RF.0 only. To make 100% sure we could set a bookmark on address 04E3 to check what RF.1 is at this part of the code. When doing so I found: RF.1 = 08, and we can conclude it is not an address within our code but pointing at RAM. As such there is no need for further action:

  

• LD H: 04FC, here or actually starting at 04F9, RA is loaded with location 044A. After that a SEP A is done as well:

  

  So this we need to replace this with an LDRL A,044A as the code first loads RA.0 and then RA.1 (Select 'LDRL' instead of '1802' and press 'Mark'), resulting in:

  

• LD H: 050E, same as for 04FC; address 050B should be replaced by an LDRL R4,0437
• LD H: 0518, same as for 04FC; address 0515 should be replaced by an LDRL R4,041E
• LD H: 05A5, same as for 04FC; address 05A2 should be replaced by an LDRL R4,041E
• LD H: 05B4, same as for 04FC; address 05B1 should be replaced by an LDRL R4,0437
• LD L: 06DD, same as 04E3 no need to change anything
• LD L: 071D, same as 04E3 no need to change anything

After this I also printed 0400 to 0800 to a disassembly file (via 'Dis', see Disassembler) and searched for all SEP instructions. To make sure all were covered. I didn't find anymore.

Now there are some possible 'data' locations left:

• 0770: Containing D8, I pressed 'Branch' and 'Load V' on this address but couldn't find any related code. As such I'm assuming it not used
• 07F8 - 07FF: Here you will find (by using 'Load V' two locations doing something with this table: 064D and 0687. This is not easily handled automatically in the Direct Assembler so we need to note these down as locations to be changed manually if we decide we want to move the code to another location.

That's it!

In theory it should now be possible to 'insert' a byte anywhere between 041E and 07F7 and the code should still run fine. I did a few inserts on 041E and managed to play the game. Note that giving an insert will give a 'Memory warning', to get rid of that fill memory from 0770 to 07F7 with '0' as the Direct Assembler only uses that value as 'not used memory'.

Now this code could be moved, adapted and even ported to another computer (e.g. an Elf) fairly easy.