Emulicious-debugger README

The "emulicious-debugger" extension enables debugging with Emulicious in VS Code. This extension requires Emulicious (https://emulicious.net/). In Emulicious you need to have "Remote Debugging" enabled. This option can be found in Emulicious's Tools menu. For breakpoints to work you need a language extension for the language you are using.

For usage instructions see Usage.

Known issues are listed in Known Issues.

If you encounter any other issues please inform about them so they can be fixed.

If anything is unclear please also inform about that so the explainations can be improved.

Requirements

The "emulicious-debugger" extension requires Visual Studio Code (VS Code) and Emulicious (https://emulicious.net/). In Emulicious you need to have "Remote Debugging" enabled. This option can be found in Emulicious's Tools menu. For breakpoints to work you need a language extension for the language you are using. If you are using C you can for example use the C language extension that is built into VS Code. For other languages you should be able to find a corresponding language extension in VS Code's Extension Marketplace. For example if you are developing for the Game Boy (Color) with RGBDS you can find Donald Hays's RGBDS Z80 extension.

Usage

Make sure that Emulicious is running and that "Remote Debugging" (in Emulicious's Tools menu) is enabled. After that is set up, you have multiple ways to start debugging with Emulicious:

• From the command palette select "Attach to Emulicious" to attach the VS Code debugger to a running debug session of Emulicious.
• Select the ROM file in VS Code and click on Run/Debug Editor Contents in top right corner.
• Click on Run (CTRL+SHIFT+D) in the left toolbar and either click on "create a launch.json file" or on "Show". When you click "Show" you can choose from "Attach to Emulicious" and "Launch in Emulicious". That will create a launch configuration. By default that launch configuration always asks for the program to run but you can enter the name into the launch configuration. You can also add "preLaunchTask":${defaultBuildTask} if you have a default build task set up. With this setting, you make VS Code start the build task before debugging.
• If a launch configuration is already available you can press F5 to start debugging.

When building your program, make sure that debug symbols get generated. For example, when building C code with SDCC you should pass the commandline flag --debug to sdcc and the commandline flag -y to the linker. That will generate the required debug symbols in a *.cdb file.

Features

The "emulicious-debugger" extension enables source level debugging for assembler code and C code (SDCC).

Source-level Stepping

Step through your own ASM source code.

Source Breakpoints

Break on breakpoints in your ASM source code.

Callstack

Keep an eye on your callstack.

Investigate Registers

Investigate registers annotated with symbols.

Investigate Stackframes

Investigate stackframes.

Investigate System State

Investigate system state.

Inspection on Hover

Inspect symbols on hover.

Debug Console

Evaluate expressions in debug console

Disassemble

Disassemble with Emulicious and step through the disassembly in VS Code.

C-level Stepping

Step through your C source code line by line, into procedures or out of them.

C-level Breakpoints

Break on breakpoints in your C source code.

C Callstack

Keep an eye on your C callstack.

C Local Variables

Keep track of your local variables.

C Inspection of Structured Type

Inspect your C arrays and structs via Watch expressions, on hover or via the debug console.

Known Issues

Trying to start a debug session without Emulicious running or without Remote Debugging enabled yields an error message saying that the connection was refused.

If you see this error make sure that you are running Emulicious and that Remote Debugging is enabled.

Emulicious

Emulicious is a free to use multi-system emulator for Windows, Linux, Raspberry Pi OS, Mac OS(X) and any other operating system supporting Java SE.

It is focused on reverse-engineering, ROM hacking and development. For that it provides several tools such as a debugger with a smart disassembler (splitting code from data).

Emulicious emulates the Game Boy and Game Boy Color, the MSX1 and the Master System and the Game Gear.

Release Notes

1.0.4

Added description of Emulicious (https://emulicious.net/) and added gamegear keyword

1.0.3

Added some missing keywords and improved some screenshots

1.0.2

README improvements

1.0.0

Initial release of "emulicious-debugger"