Debugger

From VO-EM Wiki
Jump to: navigation, search

The VO-EM debug player is the heart of this project. It provides the means to execute, test and debug software which is written for the VO-EM system. It is available on the landing page of http://vo-em.com.

At this stage, there is no 'release' player (ie, a player without debug features) available, so it is currently the only way to execute VO-EM software.

Feature overview

Screen view

The top left of the debug player shows the GPU output of the device.

FPS meter

Below the screen is a measure of the framerate. If it is lower than 60, the debug player is struggling with emulating the device at full speed.

System controls

|>

Play button - begins executing at full speed. You must click this button to start execution after loading a cartridge.

| |

Pause button. Pauses cpu execution at the current frame.

||>

Step button. Will advance the CPU one cycle. You may see the cycle counter advance many steps per click - this is because the CPU has used a "wait" command, and the debugger is skipping ahead to the next interrupt request or exception. Stepping would be very boring, otherwise.

Status text

Informs the user whether the player is paused or running. During stepping, this informs the user as to which stage of the GPU cycle the device is in (the GPU cycles once every 2400 CPU cycles).

Load Cart

Used for loading .png format cartridges.

Load dlx

Used for loading .dlx executables. Cartridge info data will be spoofed when loading in this manner. This form of loading will not be available on the release player, and is for debug only.

Debug output

The majority of the screen (entire upper right portion) is dedicated to the debugger's output. Initially displaying the welcome page before a cartridge is loaded, this section can be navigated with the number keys on your keyboard. It is organized into pages. See here for detailed information on debug pages.

Console input

Main article: Console

Always available in the bottom-right of the screen is the console input textbox. Console commands can be input here regardless of which page of the debugger is active. To see console output, switch to the console output page by pressing "`" (~).

Insert commands by pressing the enter key.

Be aware that no other hotkeys, including gamepad input, will work while the console input box has focus.

Pages

The debugger's debug pages constitute the majority of its function. They are navigated with the number row keys on your keyboard.

Console output (page `)

Main article: Console

This page displays output information from the debug console.

CPU status (page 1)

All of the CPU's current status is output here. An explanation of terms follows:

PC & IR

Shows the current contents of the PC and IR registers. A binary view of IR is also included.

TIMA & mask

Shows the CPU's tick timer and the current timer mask.

Current instruction

A real-time disassembly of the current instruction being executed is shown.

Register dump

Shows the contents of all registers from r0 to r31, in hexidecimal format.

Special register dump

Shows the contents of PSW, XBR and XAR. Also shows the current interupt queue, lined up with PSW for easy debugging. PSW and IRQ are shown in binary only, as they are to be thought of as bitfields rather than values.

GPU status (page 2)

The GPU status page shows the current settings of each layer in the GPU, as well as a visualization of the contents of sprite, tile and palette memory.

Because sprites are stored in indexed form and do not carry colour data, the entire sprite data section is colourised with one sprite palette, and the entire tile data section with one tile palette.

You can choose which palette to use for colourization. Move up and down through sprite palette data with the O and P keys, and through tile palette data with [ and ] keys.

Memory status (page 3)

Page 3 of the debugger contains a dump of device memory, showing 16 bytes per line, all in hex format. Memory values are updated in real-time. You can scroll through memory with the [ and ] keys.

Clicking on a byte in memory will insert a "poke" command with the appropriate address in the console input box. You can use this to edit memory values at runtime. Of course, values in read only memory cannot be written to, and attempting to do so may cause an IME exception, crashing your program.

The top of the screen contains a cheat sheet for memory location hotkeys. They are expanded on for clarity in the following section.

Hotkeys

Q - CART0      Cartridge bank0
W - CART1      Cartridge bank1
E - RAM        First RAM bank
R - GPU        GPU device 
T - ERAM       Extended RAM bank
Y - CARTINFO   Cartridge metadata ROM
U - HWREG      Hardware registers
N - PC         Jump to the current value of PC
-------------< The following hotkeys are all locations within GPU memory
D - SPRIMG     Sprite image data
F - TILIMG     Tile image data
G - SPRPAL     Sprite palette data
H - TILPAL     Tile palette data
J - INST       Instance data 
K - TILE       Tile map data
L - LAY        Layer control registers
C - CTRL       GPU control registers (including DMA controls)

Help (page 0)

The help page contains a list of hotkeys for the other pages.

Input

The device, of course, accepts keyboard input as gamepad input, so that games can be played. The default keys are as follows:

Arrow keys - Directional pad
z          - A button
x          - B button
s          - Select
Spacebar   - Start

Hotkey overview

` - Console output view
1 - CPU status
2 - GPU status
3 - Memory status
0 - Help message