debug.h File Reference

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.
#define	DEBUG_FEATURE_LOG_ISVIEWER   (1 << 1)
	Flag to activate the ISViewer logging channel.
#define	DEBUG_FEATURE_LOG_SD   (1 << 2)
	Flag to activate the logging on CompactFlash/SD card.
#define	DEBUG_FEATURE_FILE_SD   (1 << 3)
	Flag to activate filesystem access to files on CompactFlash/SD.
#define	DEBUG_FEATURE_ALL   0xFF
	Flag to activate all supported debugging features.
#define	debugf(msg, ...)   fprintf(stderr, msg, ##__VA_ARGS__)
	Write a message to the debugging channel.
#define	assertf(expr, msg, ...)
	assertf() is like assert() with an attached printf().

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.
void	debug_backtrace (void)
	Dump a backtrace (call stack) via debugf.
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.

Detailed Description

Debugging Support.

Debugging Support (C++)

Macro Definition Documentation

DEBUG_FEATURE_LOG_USB

#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:

• 64drive (rev 1 or 2)
• EverDrive64
• SC64

Compatible PC tools:

• UNFLoader (https://github.com/buu342/N64-UNFLoader)
• g64drive (https://github.com/rasky/g64drive)
• ed64 (https://github.com/anacierdem/ed64)

DEBUG_FEATURE_LOG_ISVIEWER

#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:

• cen64 (https://github.com/n64dev/cen64) - run with -is-viewer command line flag
• Ares (https://ares-emulator.github.io)
• simple64 (https://simple64.github.io)
• dgb-n64 (https://github.com/Dillonb/n64)

DEBUG_FEATURE_LOG_SD

#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:

• 64Drive HW1 and HW2
• EverDrive-64 V1, V2, V2.5, V3, X7 and X5
• ED64Plus / Super 64
• SC64

Note

This feature works only if DEBUG_FEATURE_FILE_SD is also activated.

Because of a 64drive firmware bug, the 64drive USB stack will crash if a SD command is sent while no SD card is inserted, and there is no way to detect whether a SD card is in the slot. So activating this feature without a SD card means that the USB logging will stop working.

DEBUG_FEATURE_FILE_SD

#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:

• 64Drive HW1 and HW2
• EverDrive-64 V1, V2, V2.5, V3, X7 and X5
• ED64Plus / Super 64
• SC64

DEBUG_FEATURE_ALL

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

debugf

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

assertf

#define assertf	(		expr,
			msg,
			...
	)

Value:

        ({ \
        if (!(expr)) debug_assert_func_f(__FILE__, __LINE__, __func__, #expr, msg, ##__VA_ARGS__); \
    })

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.

Function Documentation

debug_hexdump()

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

Parameters

[in]	buffer	Buffer to dump
[in]	size	Size of the buffer in bytes

debug_backtrace()

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.

See also

backtrace

backtrace_symbols