MD Debugger and Error Handler (or simply "MD Debugger", also known as "The Advanced Error Handler and Debugger") is a ready-to-use error handler that comes with a powerful integrated debugger. It aims to provide robust and extensible debugging tools built-in directly into the Mega-Drive ROM, that can be used anywhere (from emulators to the real hardware).
Currently, it targets The AS Macroassembler and ASM68K assemblers. It has installation instructions and full support for the mainline Sonic disassemblies, but it can be integrated into any AS or ASM68K project (both the error handler and debugger) or even any pre-existing ROM (error handler only in a binary form).
-
Debug symbol support.
- It can extract symbols from AS and ASM68K at build time and bundle them with the ROM;
- Debug symbols are efficiently compressed to save space and stored in custom database-like format; they are not visible as plain-text.
- Error dumps will display symbols from your source code instead of raw offsets, making debugging crashes times more easier;
-
Backtrace support, caller guessing and more.
- Press the B button on the exception screen to display the backtrace and see the full call chain that led to the exception;
- Press the A button to display which symbols address registers point to;
- Generic exception screen displays a caller out-of-the box.
-
Detailed and informative exceptions.
- Generic exception screen is as detailed and informative as possible;
- See exception location, caller address, all the main CPU registers, stack dump and more;
- Additional details can be displayed like VInt and HInt addresses (if dynamic) as well as
USP
andSR
registers.
-
Easily write your own debuggers with "high-level" macros.
- Write your own debug programs to display what you need;
- Use "high-level" macros that debugger environment provides, like
Console.Write "My d0 is %<.w d0 hex>"
; - Formatted string syntax in the debugger is extremely powerful: display any value from any memory location as: hexadecimal, decimal, binary, signed, unsigned, symbol or even a null-terminated ASCII string. Control output by modifying colors or adding line breaks.
-
Throw custom exceptions and customize error handling.
- You can throw custom exceptions at any time using
RaiseError
macro; - Use your own debug programs in exceptions if needed;
- Customize generic exception screen showing or hiding some less frequently used exception details;
- Map your debug programs to buttons on the exception screen.
- You can throw custom exceptions at any time using
-
Assertions.
- Use one of the most powerful debugging techniques and take advantage of self-testing code!
- Assertions, widely adopted by many high-level languages, are provided by the debugger out-of-the box;
- Use
assert
pseudo-instruction that is only compiled in DEBUG builds. This means zero run-time cost for your final (RELEASE) builds to implement self-testing code.
-
KDebug integration for logging, breakpoints and cycle-counting.
- Display formatted strings at any point straight in your emulator's debug console!
- Use a similar "high-level" macro interface as in console programs (
KDebug.WriteLine
instead ofConsole.WriteLine
), but without interrupting your programs; - Currently, the only emulators to support KDebug are Gens KMod and Blastem-nightly;
- Create manual breakpoints with
KDebug.BreakPoint
; - Measure your code performance using
KDebug.StartTimer
andKDebug.EndTimer
.
-
Easy to install and extremely lightweight.
- Error handler blob is below 3 KiB, which is quite small for the number of features it provides; optional debugger extensions take a few hundreds of bytes each;
- It's quite easy to install, with installation instructions and ready configurations provided for the most mainline Sonic disassemblies.
Installation instructions are provided for:
- Sonic 1 GitHub Disassembly (AS version)
- Sonic 1 GitHub Disassembly (ASM68K version)
- Sonic 1 Hivebrain 2005 Disassembly
- Sonic 1 Hivebrain 2022 Disassembly
- Sonic 2 GitHub Disassembly
If you'd like to contribute new installation instructions or update the existing ones, feel free to open a Pull Request: https://github.com/vladikcomper/md-modules/pulls
- Powerful debugging techniques
- How-to add your details in exception headers
- Using KDebug intergration
- Troubleshooting
Currently, the MD Debugger and Error Handler supports integration with the following assemblers:
- ASM68K (
bundle-asm68k
)- AXM68K, a hacked ASM68K usually bundled with macros for Z80 assembly support (
bundle-axm68k
)
- AXM68K, a hacked ASM68K usually bundled with macros for Z80 assembly support (
- The AS Macroassembler v.1.42 Bld 55 and above (
bundle-as
)
Warning
The AS Macroassembler version has limited support for some features
- Introduced debugger extensions and the following new built-in debuggers:
- Backtrace debugger (mapped to the B button by default);
- Address register debugger (mapped to the A button by default).
- Upgraded ConvSym from version 2.0 to 2.9.1. The adds the following major features for debug symbol generation:
- Stable AS support;
- Improve symbol data compression by force-converting your symbols to upper or lowecase;
- Support for multiple labels on the same offset;
- Support for symbols in RAM section (must be properly implemented in your project);
- Advanced offset transformations: mask, upper/bottom boundary, add/subtract base address;
- Added
assert
macro. - Implemented
KDebug
integration with the following new macros:KDebug.WriteLine
KDebug.Write
KDebug.BreakLine
KDebug.BreakPoint
KDebug.StartTimer
KDebug.EndTimer
- Added additional
Console.*
macros:Console.Clear
Console.Pause
Console.Sleep
- Improve readability of offsets and symbols in the exception header;
- Renamed "Module:" field in exception header to "Offset:" for clarity;
- ASM68K version: Support "case-sensitive" compile-flag;
- AS version: Most of the M68K addressing modes are now supported in formatted strings. The following examples now work:
%<.w #1234>
%<.w #SomeSymbolAsValue>
%<.l $FF0000>
%<.b 1(a0)>
%<.b something(a0)>
%<.b SomeLabel(pc)>
- AS version: Add a workaround for an assembler bug in older builds of AS which may cause some instructions to be misaligned;
- AS version: Macro invocations (
Console.*
,RaiseError
) no longer break local labels if placed in-between them; - AS version: Prefer
!align
instead ofalign
to avoid issues if it's overridden in the project; - AS version: Support "case-sensitive" compile flag;
- Support full address range for stack pointer (previous version only correctly worked with $FF8000-$FFFFFF range due to optimizations);
- Introduce "External symbol table" bundles for both AS and ASM68K versions, which uses a reference to the symbol table instead of expecting it right after the Error Handler blob;
- Fixed a rare case of buffer overflow when displaying offset as a symbol with displacement;
- Code-size optimizations, minor bugfixes and stability improvements.
The original version 2.x release