Basic ASM Code Debugging and Analysis for the Beginner Coder
Basic ASM Code Debugging and Analysis for the Beginner Coder

Chapter 1: Intro

After learning how to make very basic ASM Codes, the beginner coder may have trouble progressing to a higher skill level. Analyzing other already made ASM codes is one of the best ways to improve your ASM coding skills. Dolphin comes with many features to assist you.

Chapter 2: Setting up Hot Keys & Info About Other Features

Hotkeys (keyboard button shortcuts) are very useful for quick debugging. Open up your Dolphin Emulator. Under Options, select Hotkey Settings. There's basically only 2 hotkeys that are useful for debugging. In the general tab, there is a hotkey setting for 'Toggle Pause'. Set that to whatever keyboard button you desire, I just use the '9' button. Sometimes debugging codes requires constant pausing/resuming of emulation, thus its very helpful to have that feature as a hotkey.

For the next hotkey, go to the Debugging tab. There is a hotkey setting for 'Step-In'. This is by far the most important feature of debugging anything in Dolphin, and you will be using this hotkey a ton. Set this to w/e suits you, I use the 'M' button.

What is Step In?

'Step In' is to make Dolphin execute just one ASM instruction normally when the emulation is paused. 'Step In' is usually called 'stepping' by coders. When a coder says 'step by step' the code, they mean to debug the code utilizing the 'Step In' feature of Dolphin.

Chapter 3: Understanding How the Gecko Code Handler implements ASM Codes into Memory

According to the Gecko Documentation HERE, ASM Codes (C2 type) have the name of 'Insert ASM'. This name is misleading as it's impossible to insert within memory itself. What actually happens is this...

1. At the code's address, a branch instruction (replacing the default instruction) is placed in by the code handler (a backwards branch)
2. The branch instruction jumps to the first instruction of the ASM code (of the source) where the code's instructions are placed into memory by the code handler (codes dumped usually around 0x800022xx thru 0x800023xx)
3. The amount to jump for the branch instruction itself is auto calculated by the code handler
4. The code instructions are thus executed. After the last instruction of the source, a branch instruction (also auto added by the code handler) will automatically jump back to the address right after the code's address, thus continuing the game's instructions.

For example let's take a look at the ever so known shared item code (PAL version, with 00 for the WW value) -

C27BA164 00000002
38600000 90770020
60000000 00000000

Here's what actually happens in the game when the ASM code gets executed...

Address    Instruction
807BA164  b => 0x80002348
80002348  li r3, 0
8000234C  stw r3, 0x0020 (r23)
80002350  nop
80002354  b => 0x807BA168

NOTE: The address that the branch jumps back to (where the ASM source is) will vary, but as mentioned before it's usually around the 0x800022XX thru 0x800023XX range)

The '00000000' word of the compiled code is read by the code handler and the code handler knows to replace it with a branch (to address after code's address) instruction after the last instruction of the ASM source.

Chapter 4. Debugging/Analyzing ASM Codes

First apply w/e code you want to debug/analyze. If the code's address gets executed during boot or is executed every frame, we need to adjust a dolphin setting (unless you don't mind the address+code getting executed multiple times before analyzing the code). At the top of the Dolphin main menu, click Options. Select 'Boot to Pause'. This will cause the game to halt when it executes its very first instruction.

Open up your Breakpoint tab/window. Set an Instruction Breakpoint using the value for the code's address. Once set, un-pause the emulation if it was paused if you used 'Boot to Pause'. After Dolphin pauses from the BP being hit, take a look at the Code View. You will be at the code's address and you will see the branch-back instruction that was mentioned earlier.

Remember the Hotkey you configured for Stepping? Use that hotkey to make the code execute one instruction at a time at w/e pace you like. When you execute the first instruction, the branch backwards jump will be preformed, and you will be at the beginning of the ASM code's instructions.

Take notes of register and memory values when stepping. Use this time to take a look at how advanced instructions are executed. Whenever a value in any register gets modified after a step, that register will turn red. The red register will go back to black if it's not modified if you decide to step again. Btw, on your first BP hit after launching Dolphin for the first time during a session, any registers not zero will start off as red color.

Chapter 5: More Tips

To quickly set a BP on an address (only useful for Instruction BPs), simply left click to the immedaite left of the Address value in code view. A grey dot will appear signaling a BP has been set for the address.

Need to quickly copy an address value? Right click on the address in Code View, select Copy Address.

You can also use this right-click method to quickly replace instructions. Right click on an address, you will see shortcuts to quicly replace the address's instruction with a nop or a blr. The nop feature can be really handy for beginner coders. You may not know what a blr is. If not, don't worry about that til you get to the point of learning about function calls. Or even better, use this guide on a code that has a blr instruction and analyze it to understand what it does.

You can also edit in any custom valid PPC instruction you want with the 'Replace Instruction' feature, but you will need to enter in the compiled form. If you set in a custom instruction of any kind, or a quick nop/blr, you can use the 'Restore Instruction' feature to bring back the address's original instruction.

Need to edit register values by hand? Easy to to do. Simply double click within the register you need to edit, and type in the custom value.

Btw, on the left side of the Code view is the call stack. It's a trace back of function calls. Once again, if you are a beginner coder, you don't need to worry about this as this deals with function calls.

Chapter 6. Conclusion

As I always tell person after person, the best way to get better at coding, is to take other ppl's codes (that are a little above your own skill level) and analyze them on Dolphin. Set the BPs, step by step necessary instructions, and take plenty of notes. Happy coding!
If you want, I can write out/post something like this for advanced users so you and I can both work on it
Super Mario Eclipse, what Super Mario Sunshine could've been.
Feel free, since this thread is here now I will be updating some of my more advanced threads. Such as in the Calling Function threads, including how to set BPs to allow a function to execute w/o a stepping thru the entire thing (which a beginner might try to do, lol).

One thread we need is something about working with the call stack. Another thread the site needs is anything that will cover advanced work w/ Floats.The only thread I've done on floats is basic conversion to integers.

A small quick thread on the condition register could help too, but advanced work for the CR is very rare in MKWii codes.
I will help contribute then Smile
Super Mario Eclipse, what Super Mario Sunshine could've been.

Forum Jump:

Users browsing this thread: 1 Guest(s)