Direct:Debug

Direct Debug (debug.h)

Overview
Direct lib's debugging support can be compiled in or not, as decided by the DirectFB configure script. That still needs to be documented.

When debugging is compiled in, the direct D_ macros provide runtime checking. When debugging is not compiled in the same macros resolve to NOPs.

When debugging is compiled in, much of its output can be enabled/disabled at runtime in the /etc/directfbrc file. When it's disabled, there is minimal performance impact to the running code.

Messages are displayed to a log output with the format: (severity) [time] (pid) domain-name message

Domains
Domains allow debugging output to be limited to a subset of the normal output so that you can see the messages from domains being debugged and not have to wade through the noise of all the debug messages from other domains.

Domain names should have a prefix and a name, separated by a slash. If the name of a domain defined with D_DEBUG_DOMAIN includes a slash, then that domain can be enabled/disabled using either its full name or using just the prefix before the first slash. This allows enabling/disabling output for a set of related domains all at once by specifying just the prefix.

API Reference
Debugging is implemented as the following functions/macros:

direct_debug_config_domain(name, enable)

 * name: The name of the domain or prefix of domains to enable or disable (see the name parameter of D_DEBUG_DOMAIN)
 * enable: true to enable output, false to disable them

Enable or disable subsequent debugging output for a named domain or a set of domains with the named prefix.

You can put debug entries in /etc/directfbrc to automatically enable/disable domains by default when DirectFB initalizes.

D_HEAVYDEBUG(format, ...)
Don't use this

D_DEBUG_DOMAIN(identifier,name,description)

 * identifier : The name of a static variable defined by the macro to hold the context
 * name : A short name of the domain that will be used to enable/disable it.
 * description : A human-readable description of the debugging domain.

Declare/define debugging domain to be used in other  macros. The debugging domain provides a way to enable/disable messages at runtime by calling direct_debug_config_domain and/or through debug entries in /etc/directfbrc.

The name should be a general name of the library/application in which it resides followed by a slash and a more-specific area within the app/lib. This allows debugging in whole libraries or specific sections to be enabled/disabled (see D_DEBUG_AT).

D_DEBUG(format, ...)
Pass printf style arguments.

(-) is used as the severity

If debugging is globally enabled, print out a debugging message. This is generally used to report when something unexpected happens.

D_DEBUG_AT(domain, format, ...)
Pass the debugging domain and printf style arguments.

(-) is used as the severity

If the domain is enabled, print out a debugging message. This is generally used for checkpointing how far the code runs by reporting that execution is at a certain location.

Domains or domain-groups can be enabled/disabled with direct_debug_config_domain and/or debug entries in /etc/directfbrc.

If direct lib tracing is enabled in /etc/directfbrc, the message is indented depending on the call depth.

D_ASSERT(expression)
Pass an expression that is true under normal conditions.

If the expression is true, no action is taken.

If the expression is false, print out an error message indicating the asserted expression. If direct lib tracing is enabled in /etc/directfbrc a stack trace will also be displayed.

A SIGTRAP is then sent to the process group and the current application will exit with -1 status.

D_ASSUME(expression)
Pass an expression that is true under normal conditions.

If the expression is true, no action is taken.

If the expression is false, print out an error message indicating the assumed expression. If direct lib tracing is enabled in /etc/directfbrc a stack trace will also be displayed.

Execution will continue after the assumption is displayed.

D_BREAK(format, ...)
Pass printf style arguments.

(!) is used as the severity

Print out an error message indicating a break occurred. If direct lib tracing is enabled in /etc/directfbrc a stack trace will also be displayed.

A SIGTRAP is then sent to the process group and the current application will exit with -1 status.