|
libdragon
|
Debugging Support. More...
Go to the source code of this file.
Macros | |
| #define | DEBUG_FEATURE_LOG_USB (1 << 0) |
| Flag to activate the USB logging channel. More... | |
| #define | DEBUG_FEATURE_LOG_ISVIEWER (1 << 1) |
| Flag to activate the ISViewer logging channel. More... | |
| #define | DEBUG_FEATURE_LOG_SD (1 << 2) |
| Flag to activate the logging on CompactFlash/SD card. More... | |
| #define | DEBUG_FEATURE_FILE_SD (1 << 3) |
| Flag to activate filesystem access to files on CompactFlash/SD. More... | |
| #define | DEBUG_FEATURE_ALL 0xFF |
| Flag to activate all supported debugging features. More... | |
| #define | debugf(msg, ...) fprintf(stderr, msg, ##__VA_ARGS__) |
| Write a message to the debugging channel. More... | |
| #define | assertf(expr, msg, ...) |
| assertf() is like assert() with an attached printf(). More... | |
Functions | |
| bool | debug_init_usblog (void) |
| Initialize USB logging. | |
| bool | debug_init_isviewer (void) |
| Initialize ISViewer logging. | |
| bool | debug_init_sdlog (const char *fn, const char *openfmt) |
| Initialize SD logging. | |
| bool | debug_init_sdfs (const char *prefix, int npart) |
| Initialize SD filesystem. | |
| void | debug_close_sdfs (void) |
| Shutdown SD filesystem. | |
| void | debug_hexdump (const void *buffer, int size) |
| Do a hexdump of the specified buffer via debugf. More... | |
| void | debug_backtrace (void) |
| Dump a backtrace (call stack) via debugf. More... | |
| void | debug_assert_func_f (const char *file, int line, const char *func, const char *failedexpr, const char *msg,...) |
| Underlying implementation function for assert() and assertf. | |
Debugging Support.
Debugging Support (C++)
| #define DEBUG_FEATURE_LOG_USB (1 << 0) |
Flag to activate the USB logging channel.
The USB logging channel is supported on several different development cartridges, using a compatible tool to acquire data on the PC side.
Logging can be done by writing to stderr. You can use the debugf() macro as a simple wrapper over fprintf(stderr) that can be disabled when building the final ROM through the NDEBUG macro.
Supported development cartridges:
Compatible PC tools:
| #define DEBUG_FEATURE_LOG_ISVIEWER (1 << 1) |
Flag to activate the ISViewer logging channel.
ISViewer was a real development cartridge that was used in the 90s to debug N64 development. It is emulated by a few emulators to ease the work of homebrew developers.
Logging can be done by writing to stderr. You can use the debugf() macro as a simple wrapper over fprintf(stderr) that can be disabled when building the final ROM through the NDEBUG macro.
Supported emulators:
| #define DEBUG_FEATURE_LOG_SD (1 << 2) |
Flag to activate the logging on CompactFlash/SD card.
When this feature is activated, and assuming a SD card is inserted into the cartridge slot and its read-only physical switch is disabled, libdragon will write the logging stream to a file called "libdragon.log" on the root of the card. If the file already exists, logging will be appended to it.
The SD card must be formatted in either FAT16, FAT32 or ExFat.
Logging can be done by writing to stderr. You can use the debugf() macro as a simple wrapper over fprintf(stderr) that can be disabled when building the final ROM through the NDEBUG macro.
Supported development cartridges:
| #define DEBUG_FEATURE_FILE_SD (1 << 3) |
Flag to activate filesystem access to files on CompactFlash/SD.
This flag activates a feature that allows direct read/write access to the SD card / CompactFlash filesystem, available on a development cartridge.
To access the files on the SD card, simply open them prefixing their name using the "sd:/" prefix in front of filenames.
The SD card must be formatted in either FAT16, FAT32 or ExFat. Long filenames are supported.
Supported development cartridges:
| #define DEBUG_FEATURE_ALL 0xFF |
Flag to activate all supported debugging features.
This flag can be passed to debug_init() to activate all supported debugging features. It is a good default for development, and should be used unless there are strong constraints on ROM size. In fact, disabling unused debugging features will decrease the ROM size because the unused code will not be linked.
| #define debugf | ( | msg, | |
| ... | |||
| ) | fprintf(stderr, msg, ##__VA_ARGS__) |
Write a message to the debugging channel.
This macro is a simple wrapper over fprintf(stderr), to write a debugging message through all the activated debugging channels.
Writing directly to stderr is perfectly supported; this macro only simplifies disabling all debugging features, because it is disabled when compiling with NDEBUG.
| #define assertf | ( | expr, | |
| msg, | |||
| ... | |||
| ) |
assertf() is like assert() with an attached printf().
assertf() behaves exactly like assert(), but allows for a better debugging experience because it is possible to attach a formatted string that will be displayed in case the assert triggers.
Assertion in general are supported by libdragon even without this debugging library: they abort execution displaying a console screen with the error message. Moreover, the assertion is also printed on stderr, so when using this debug library, it can be read on PC using one of the supported debugging channel.
| void debug_hexdump | ( | const void * | buffer, |
| int | size | ||
| ) |
Do a hexdump of the specified buffer via debugf.
This is useful to dump a binary buffer for debugging purposes. The hexdump shown contains both the hexadecimal and ASCII values, similar to what hex editors do.
Sample output:
0000 80 80 80 80 80 80 80 80 80 80 80 80 80 80 80 80 |................| 0010 45 67 cd ef aa aa aa aa aa aa aa aa aa aa aa aa |Eg..............| 0020 9a bc 12 34 80 80 80 80 80 80 80 80 80 80 80 80 |...4............| 0030 aa aa aa aa aa aa aa aa ef 01 67 89 aa aa aa aa |..........g.....| 0040 80 80 80 80 80 80 80 80 00 00 00 00 80 80 80 80 |................|
| [in] | buffer | Buffer to dump |
| [in] | size | Size of the buffer in bytes |
| void debug_backtrace | ( | void | ) |
Dump a backtrace (call stack) via debugf.
This function will dump the current call stack to the debugging channel. It is useful to understand where the program is currently executing, and to understand the context of an error.
The implementation of this function relies on the lower level backtrace and backtrace_symbols functions, which are implemented in libdragon itself via a symbol table embedded in the ROM. See backtrace_symbols for more information.
1.9.4