Handling Debug Events

Debug Event Pool

A pool is used to keep track of debugging events. This pool is made up of debug event structures where the size of the pool is specified by USBD_CFG_DBG_TRACE_NBR_EVENTS in the application configuration. Within the core, each time a new debug standard request is received, the message’s details will be set into a debug event structure and queued into the pool. Once the debug event is properly queued, a ready signal is invoked to notify the debug task handler that an event is ready to be processed.

Debug Task

An OS-dependent task is used to process debug events. The debug task handler simply pends until an event ready signal is received and obtains a pointer to the first debug event structure from the pool. The details of the debug event structure is then formatted and outputted via the application trace function. At the end of the output, the debug event structure is then subsequently freed and the debug task will pend and process the next debug event structure ready. Refer to the Processing Debug Events section for details on processing debug events.

Debug Macros

Within the core, several macros are created to set debug messages. These macros are defined in usbd_core.h and make use of the core functions USBD_Dbg() and USBD_DbgArg() that will set up a debug event structure and put the event into the debug event pool. These macros are defined in Listing - Core Level Debug Macros.

Listing - Core Level Debug Macros

#define USBD_DBG_GENERIC(msg, ep_addr, if_nbr)                    USBD_Dbg((msg),              \
                                                                          (ep_addr),           \
                                                                          (if_nbr),            \
                                                                           USBD_ERR_NONE)
 
#define USBD_DBG_GENERIC_ERR(msg, ep_addr, if_nbr, err)          USBD_Dbg((msg),               \
                                                                          (ep_addr),           \
                                                                          (if_nbr),            \
                                                                          (err))
 
#define USBD_DBG_GENERIC_ARG(msg, ep_addr, if_nbr, arg)          USBD_DbgArg((msg),            \
                                                                             (ep_addr),        \
                                                                             (if_nbr),         \
                                                                             (CPU_INT32U)(arg),\
                                                                             (USBD_ERR_NONE))
 
#define USBD_DBG_GENERIC_ARG_ERR(msg, ep_addr, if_nbr, arg, err) USBD_DbgArg((msg),            \
                                                                             (ep_addr),        \
                                                                             (if_nbr),         \
                                                                             (CPU_INT32U)(arg),\
                                                                             (err))

There are subtle yet important differences between each debug macro. The first debug macro is the most simple, specifying just the debug message, endpoint address and interface number as parameters. The second and third macros differ in the last parameter where one specifies the error and the other specifies an argument of choice. The last macro lets the caller specify all details including both error and argument.

Furthermore, core level debug macros can be further mapped to other macros to simplify the repetition of endpoint address and interface number parameters. Listing - Mapped Core Tracing Macros shows an example of a bus specific debug macro and a standard debug macro found in usbd_core.c.

Listing - Mapped Core Tracing Macros

#define  USBD_DBG_CORE_BUS(msg)             USBD_DBG_GENERIC((msg),                \
                                                              USBD_EP_ADDR_NONE,   \
                                                              USBD_IF_NBR_NONE)
 
#define  USBD_DBG_CORE_STD(msg)             USBD_DBG_GENERIC((msg),                \
                                                              0u,
                                                              USBD_IF_NBR_NONE)