Debug Class Reference

An application debugging mechanism. See below for detailed usage. More...

#include <debug.hpp>

List of all members.

Public Member Functions
bool	update (void) const
	Called from the start of the application event handler to determine if the user has requested to view the debug output.
int	getLogLevel (void) const
	Returns the current debugging log level.
void	setLogLevel (int l)
	Sets the current debugging log level. Legal values are in the range of 0 - 3. A value of 0 disables logging. A value less than 0 results in a log level of zero, and likewise, a log level greater than three results in a log level of three.
bool	dbg_printf (const char *fmt,...)
	Parses the format and stores the resulting string into a circular buffer.
bool	debug (void) const
	Tests user input using the trigger function. When the trigger function indicates to go into debug mode, this routine saves current state information, and then takes over the interrupt handler and the screens. The current debug information is displayed to the user until they indicate they would like to exit. Then the original state information is restored, and control returns to the application.
Static Public Member Functions
Debug &	Inst (void)
	Returns a reference to the one and only Debug instance.
void	setTriggerFunc (triggerFunc trigger)
	Allows the user to set the trigger test function.
Private Member Functions
	Debug ()
	Private constructor to allow creation only by Inst.
	Debug (const Debug &)
	Private copy constructor to prevent copies of the class.
Debug &	operator= (const Debug &)
	Private operator= to prevent copies of the class.

---

Detailed Description

An application debugging mechanism. See below for detailed usage.

The Debug class provides a mechanism to aid in debugging applications, yet easily turns off debugging to prepare releases to the public. The code is not changed, so as bug reports are processed, versions of the application can be built with debugging enabled for problem determination.

To use the Debug class in your application requires only a few steps.

1. Include debug.hpp in the appropriate places, and ensure DEBUG in set.
2. In your main application, set the log level if another log level is desired. By default, the log level is set to 3.
3. Use dbg_printf, dbg_printf2, and dbg_printf3 to trace code executing in your application.
4. At the start of your event handler, test dbg_process_update;

Optionally:

• Provide a new trigger function. The default trigger function watches for the user to press the left trigger button on the NDS.
• Provide a mechanism in the application to allow the logging level to be changed on the fly.

Some example code to provide a better picture:

void interrupt_handler(void) {
  static int counter = 0;

  if (IF & IRQ_VBLANK) {
    if (!dbg_process_update) {
      ++counter;
      // normal interupt handler code.
      if ((counter % 1024) == 0) {
        dbg_printf2("counter = %d", counter);
      }
    }
    IF = IRQ_VBLANK;
  }
}

When the user requests to view debugging information, the Debug class saves the current interrupt handler and interupt event requests, and changes it to an internal handler. Screen state information is saved as well. Then control returns back to the application. Then the Debug module takes control of the screen and displays the debug log. The user can use the up/down on the D-pad to scroll the display, and the A/B buttons function as a page-up/page-down.

Pressing the Select button causes the handler to restore the previous interrupt handler and interrupt request flags as well as restoring the screen. The handler then exits allowing control to return back to the application interrupt handler.

Barring the application's use of the real-time clock for timing, ideally, the application will continue running right where it left off without any ill effects or even noticing the delay between calls to the real interrupt handler.

Some effort has been made at robustness. The desire is that even if the application is having serious problems, as long as the interrupt handler is still basically functioning, that the application should be able to get to debug mode.

Todo:

Determine if any special handling is required for various events. For example, if an alarm event arrives while processing our internal event loop, should we treat it like the user just exited the event loop, restore all of the state, and then return control back to the application using false so that the application can then process the alarm. By extension, this means that Debug must actually examine the application's interrupt event request so that it can handle unexpected events, and not change the requested events to only those the debugger is interested in.

---

Member Function Documentation

bool Debug::update (  void   )  const

Called from the start of the application event handler to determine if the user has requested to view the debug output. Return values: false  The user has not requested to view debugging information. true  The user's request for debugging information has been satisfied. Generally, don't do any input processing this time through the event loop.

void Debug::setLogLevel (  int  l  )

Sets the current debugging log level. Legal values are in the range of 0 - 3. A value of 0 disables logging. A value less than 0 results in a log level of zero, and likewise, a log level greater than three results in a log level of three. Parameters: l  The log level to set.

bool Debug::dbg_printf (  const char *  fmt, ...  )

Parses the format and stores the resulting string into a circular buffer. Note that the maximum length of the result of parsing the format statement can be no longer than MAX_DEBUG_LINE_LENGTH. Parameters: fmt  A format statement similar to what is accepted by printf. ...  Arguments to the format statement. Return values: true  Always returned.

bool Debug::debug (  void   )  const

Tests user input using the trigger function. When the trigger function indicates to go into debug mode, this routine saves current state information, and then takes over the interrupt handler and the screens. The current debug information is displayed to the user until they indicate they would like to exit. Then the original state information is restored, and control returns to the application. Return values: true  A debug event occurred and was processed. false  No debug event detected, continue with normal user input processing.

---

The documentation for this class was generated from the following file:

• debug.hpp

---