MD Debugger and Error Handler (v.2.6 released)

Wow, I just realized I never posted version 2.x on Sonic Retro...

Let me introduce you one of the most feature-rich autonomous debuggers and error handlers for the Mega-Drive:

MD Debugger and Error Handler 2.6

NOTICE: This post was last updated on 2024-12-15 when the recent version was released



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).

Features

• 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 and SR 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.
  
  
• 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 (experimental).
  • 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 of Console.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 and KDebug.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

• 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

Version 2.5 to 2.6 migration guide
If you were already using version 2.5, migration is as simple as upgrading your Debugger.asm and ErrorHandler.asm files from the bundle for your assembler and upgrading ConvSym utility. As usual, versions are 100% backwards-compatible.

1. Download errorhandler-2.6.zip;
2. Inside this archive, find the directory that matches your assembler (e.g. asm68k for ASM68K, as for the AS Macro Assembler);
3. Replace Debugger.asm and ErrorHandler.asm files in your projects with ones from that directory;
4. Download consym-2.12.1.zip, find executable for your platform (64-bit Windows or Linux) and replace one in your project.

Version 2.0 to 2.5 migration guide

If you were already using version 2.0, migration is really simple as the new version is 100% backwards compatible.

1. Download the correct version for your project (errorhandler-as.7z or errorhandler-asm68k.7z).
2. Replace the old files; remove ErrorHandler.bin from the old installation because it's now inlined into ErrorHandler.asm.
3. Download and replace convsym utility for your platform:
   • convsym-win64.7z
   • convsym-linux64.7z
   • convsym-bsd64.7z
   • convsym-mac_x86_64.zip
4. Everything should work already, but to support features like assertions and KDebug integration you need to modify your build system to generate DEBUG builds. Just find an installation guide for your disassembly and follow the "Install ConvSym to generate debug symbols" step.

Documentation and help

Guides

• Powerful debugging techniques
• How-to add your details in exception headers
• Using KDebug integration
• Troubleshooting

References

• Debugger macro reference
• Formatted string format reference

Source code

MD Debugger and Error Handler is fully open-source. The source code is available in this monorepo: https://github.com/vladikcomper/md-modules

Version History

2024-12-15: Version 2.6 released: https://forums.sonicretro.org/index.php?posts/1088005/

2023-07-02: Version 2.5 released

2018-01-14: Version 2.0 released

2016-04-05: Version 1.0 released

 

As long as its interface is about pushing characters to some kind of port/memory address, it relatively easy to do! Debugger's core is so high-level, it actually implements buffered IO. This means that to output to different devices, be it VDP or KDebug registers, you just need to implement a "buffer flush" function.

You can take a look at this commit where I implemented `KDebug.WriteLine` for the reference: https://github.com/vladikcomper/md-modules/commit/c70c22d85b36cb7c99833f388e7a957972b9c689. Extending it can be surprisingly easy: just copy-paste the case and rewrite `@FlushBuffer` function to conform your target interface (and `_FlushLine`/`_BreakLine` optionally, if you need `.BreakLine` call).

Under the hood, both `KDebug.WriteLine` and `Console.WriteLine` use almost the same boilerplate code for setting things up: they call `FormatString` function that does buffered IO and pass their own `@FlushBuffer` callback to flush the output to the target device (`Console` or `KDebug`).

 

MD Debugger and Error Handler 2.6

- AXM68K, Psylink and GAS support, better assertions, compact error handler offsets and tons of QoL improvements!



MD Debugger 2.6 is finally out, including ~1.5 years worth of work, with tons of stability and QoL improvements! This release focuses on extending supported assemblers and improving the existing features: better asserts, compact offsets and displacements on error screens, KDebug integration is no longer experimental.

Feature highlights

• Official AXM68K and GAS support (allows SGDK integration), support for ASM68K projects using Psy-Q Linker.;
• Error handler now uses compact offsets and symbol displacements: offsets are rendered as 24-bit instead of 32-bit and displacements don't have leading zeros (+000X is now +X);
• Better assertions: you can now assign custom debuggers to failed assertions, assertion failed exception is improved and displays the received value;
• KDebug integration is no longer experimental; you can use KDebug.Write[Line] in console programs;
• Console.WriteLine, Console.Write, KDebug.WriteLine, KDebug.Write are now much faster when formatted string doesn't include any printable arguments;
• Added _Console.*, _KDebug.*, _assert macros for advanced users ("shadow macros"): they behave like the original ones, but don't save/restore CCR as an optimization;
• ASM68K version: Support projects that use "." for local labels, support projects with /o ae+ compile flag;
• AS version: Support xxx.w, (xxx).w, xxx.l and (xxx).l syntax in formatted string arguments;
• Many optimizations, bugfixes and stability improvements.

Special thanks to @OrionNavattan for contributing a few optimizations and bugfixes for this release.

See MD Debugger's version history for the detailed changelog.

Version 2.5 to 2.6 migration guide
If you were already using version 2.5, migration is as simple as upgrading your Debugger.asm and ErrorHandler.asm files from the bundle for your assembler and upgrading ConvSym utility. As usual, versions are 100% backwards-compatible.

1. Download errorhandler-2.6.zip;
2. Inside this archive, find the directory that matches your assembler (e.g. asm68k for ASM68K, as for the AS Macro Assembler);
3. Replace Debugger.asm and ErrorHandler.asm files in your projects with ones from that directory;
4. Download consym-2.12.1.zip, find executable for your platform (64-bit Windows or Linux) and replace one in your project;

Installation guides, documentation and help
MD Debugger comes with exhaustive documentation, installation guides and usage examples. See the following links for details:

• Installation guides
• Documentation and help