This chapter contains a description about how to build a TraceX event buffer and also describes the underlying format of the buffer.
ThreadX provides built-in event trace support for all ThreadX services, thread state changes, and user-defined events. The ThreadX event-trace capability is primarily designed as a post-mortem tool to analyze the last “n” activities in the application. From this information, the developer may spot problems and/or potential targets of optimization.
TraceX graphically displays the event trace buffer built by ThreadX. The following describes how to build the buffer and describes the underlying format of the buffer.
To enable event trace, define the time-stamp constants, build the ThreadX library with TX_ENABLE_EVENT_TRACE defined, and enable tracing by calling the tx_trace_enable function.
The time-stamp constants are designed to provide the developer control over the time-stamp used in the event trace entries. The two time-stamp constants and their default values are as follows:
#ifndef TX_TRACE_TIME_SOURCE
#define TX_TRACE_TIME_SOURCE ++_tx_trace_simulated_time
#endif
#ifndef TX_TRACE_TIME_MASK
#define TX_TRACE_TIME_MASK 0xFFFFFFFFUL
#endif
The above constants are defined in tx_port.h and create a “fake” time-stamp that simply increments by one on each event. The following is an example of an actual timestamp definition:
#ifndef TX_TRACE_TIME_SOURCE
#define TX_TRACE_TIME_SOURCE ((ULONG) 0x0x13000004)
#endif
#ifndef TX_TRACE_TIME_MASK
#define TX_TRACE_TIME_MASK 0xFFFFFFFFUL
#endif
The above constants specify a 32-bit timer that is obtained by reading the address 0x13000004. Most application specific time-stamps should be setup in a similar fashion.
TraceX needs the trace buffer in a binary, Intel HEX, or Motorola S-Record file format on the host. The easiest way to accomplish this is to stop the target and instruct your debugger to dump the memory area you supplied to tx_trace_enable function into a file on the host.
Warning: Be careful not to stop the target within a trace gathering code itself. Doing so can cause invalid trace information. If the program is halted within ThreadX, it is best to step over any trace insert macro before dumping the trace buffer.
Important: Appendix D shows how to dump the trace buffer from within a variety of development tools.
When ThreadX is built with TX_ENABLE_EVENT_TRACE defined, the following new event trace APIs are available to the application:
Enable event tracing
UINT tx_trace_enable (VOID *trace_buffer_start,
ULONG trace_buffer_size, ULONG registry_entries);
This service enables event tracing inside ThreadX. The trace buffer and the maximum number of ThreadX objects are supplied by the application.
Important: The ThreadX library and application must be built with TX_ENABLE_EVENT_TRACE defined in order to use event tracing.
Initialization and threads
UCHAR my_trace_buffer[64000];
/* Enable event tracing using the global "my_trace_buffer" memory and supporting a maximum of 30 ThreadX objects in the registry. */
status = tx_trace_enable (&my_trace_buffer, 64000, 30);
/* If status is TX_SUCCESS the event tracing is enabled. */
tx_trace_event_filter, tx_trace_event_unfilter, tx_trace_disable, tx_trace_isr_enter_insert, tx_trace_isr_exit_insert, tx_trace_buffer_full_notify, tx_trace_user_event_insert
Filter specified events
UINT tx_trace_event_filter (ULONG vent_filter_bits);
This service filters the specified event(s) from being inserted into the active trace buffer. Note that by default no events are filtered after tx_trace_enable is called.
Important: The ThreadX library and application must be built with TX_ENABLE_EVENT_TRACE defined in order to use event tracing.
TX_TRACE_ALL_EVENTS 0x000007FF
TX_TRACE_INTERNAL_EVENTS 0x00000001
TX_TRACE_BLOCK_POOL_EVENTS 0x00000002
TX_TRACE_BYTE_POOL_EVENTS 0x00000004
TX_TRACE_EVENT_FLAGS_EVENTS 0x00000008
TX_TRACE_INTERRUPT_CONTROL_EVENT 0x00000010
TX_TRACE_MUTEX_EVENTS 0x00000020
TX_TRACE_QUEUE_EVENTS 0x00000040
TX_TRACE_SEMAPHORE_EVENTS 0x00000080
TX_TRACE_THREAD_EVENTS 0x00000100
TX_TRACE_TIME_EVENTS 0x00000200
TX_TRACE_TIMER_EVENTS 0x00000400
FX_TRACE_ALL_EVENTS 0x00007800
FX_TRACE_INTERNAL_EVENTS 0x00000800
FX_TRACE_MEDIA_EVENTS 0x00001000
FX_TRACE_DIRECTORY_EVENTS 0x00002000
FX_TRACE_FILE_EVENTS 0x00004000
NX_TRACE_ALL_EVENTS 0x00FF8000
NX_TRACE_INTERNAL_EVENTS 0x00008000
NX_TRACE_ARP_EVENTS 0x00010000
NX_TRACE_ICMP_EVENTS 0x00020000
NX_TRACE_IGMP_EVENTS 0x00040000
NX_TRACE_IP_EVENTS 0x00080000
NX_TRACE_PACKET_EVENTS 0x00100000
NX_TRACE_RARP_EVENTS 0x00200000
NX_TRACE_TCP_EVENTS 0x00400000
NX_TRACE_UDP_EVENTS 0x00800000
UX_TRACE_ALL_EVENTS 0x7F000000
UX_TRACE_ERRORS 0x01000000
UX_TRACE_HOST_STACK_EVENTS 0x02000000
UX_TRACE_DEVICE_STACK_EVENTS 0x04000000
UX_TRACE_HOST_CONTROLLER_EVENTS 0x08000000
UX_TRACE_DEVICE_CONTROLLER_EVENTS 0x10000000
UX_TRACE_HOST_CLASS_EVENTS 0x20000000
UX_TRACE_DEVICE_CLASS_EVENTS 0x40000000
Initialization and threads
/* Filter queue and byte pool events from trace buffer. */
status = tx_trace_event_filter (TX_TRACE_QUEUE_EVENTS | TX_TRACE_BYTE_POOL_EVENTS);
/* If status is TX_SUCCESS all queue and byte pool events are filtered. */
tx_trace_enable, tx_trace_event_unfilter, tx_trace_disable, tx_trace_isr_enter_insert, tx_trace_isr_exit_insert, tx_trace_buffer_full_notify, tx_trace_user_event_insert
Unfilter specified events
UINT tx_trace_event_unfilter (ULONG event_unfilter_bits);
This service unfilters the specified event(s) such that they will be inserted into the active trace buffer.
Important: The ThreadX library and application must be built with TX_ENABLE_EVENT_TRACE defined in order to use event tracing.
TX_TRACE_ALL_EVENTS 0x000007FF
TX_TRACE_INTERNAL_EVENTS 0x00000001
TX_TRACE_BLOCK_POOL_EVENTS 0x00000002
TX_TRACE_BYTE_POOL_EVENTS 0x00000004
TX_TRACE_EVENT_FLAGS_EVENTS 0x00000008
TX_TRACE_INTERRUPT_CONTROL_EVENT 0x00000010
TX_TRACE_MUTEX_EVENTS 0x00000020
TX_TRACE_QUEUE_EVENTS 0x00000040
TX_TRACE_SEMAPHORE_EVENTS 0x00000080
TX_TRACE_THREAD_EVENTS 0x00000100
TX_TRACE_TIME_EVENTS 0x00000200
TX_TRACE_TIMER_EVENTS 0x00000400
FX_TRACE_ALL_EVENTS 0x00007800
FX_TRACE_INTERNAL_EVENTS 0x00000800
FX_TRACE_MEDIA_EVENTS 0x00001000
FX_TRACE_DIRECTORY_EVENTS 0x00002000
FX_TRACE_FILE_EVENTS 0x00004000
NX_TRACE_ALL_EVENTS 0x00FF8000
NX_TRACE_INTERNAL_EVENTS 0x00008000
NX_TRACE_ARP_EVENTS 0x00010000
NX_TRACE_ICMP_EVENTS 0x00020000
NX_TRACE_IGMP_EVENTS 0x00040000
NX_TRACE_IP_EVENTS 0x00080000
NX_TRACE_PACKET_EVENTS 0x00100000
NX_TRACE_RARP_EVENTS 0x00200000
NX_TRACE_TCP_EVENTS 0x00400000
NX_TRACE_UDP_EVENTS 0x00800000
UX_TRACE_ALL_EVENTS 0x7F000000
UX_TRACE_ERRORS 0x01000000
UX_TRACE_HOST_STACK_EVENTS 0x02000000
UX_TRACE_DEVICE_STACK_EVENTS 0x04000000
UX_TRACE_HOST_CONTROLLER_EVENTS 0x08000000
UX_TRACE_DEVICE_CONTROLLER_EVENTS 0x10000000
UX_TRACE_HOST_CLASS_EVENTS 0x20000000
UX_TRACE_DEVICE_CLASS_EVENTS 0x40000000
Initialization and threads
/* Un-filter queue and byte pool events from trace buffer. */
status =
tx_trace_event_unfilter (TX_TRACE_QUEUE_EVENTS | TX_TRACE_BYTE_POOL_EVENTS);
/* If status is TX_SUCCESS all queue and byte pool events are un-filtered. */
tx_trace_enable, tx_trace_event_filter, tx_trace_disable, tx_trace_isr_enter_insert, tx_trace_isr_exit_insert, tx_trace_buffer_full_notify, tx_trace_user_event_insert
UINT tx_trace_disable (VOID);
This service disables event tracing inside ThreadX. This can be useful if the application wants to freeze the current event trace buffer and possibly transport it externally during run-time. Once disabled, the tx_trace_enable can be called to start tracing again.
Important: The ThreadX library and application must be built with TX_ENABLE_EVENT_TRACE defined in order to use event tracing.
None.
Initialization and threads
/* Disable event tracing. */
status = tx_trace_disable ();
/* If status is TX_SUCCESS the event tracing is disabled. */
tx_trace_enable, tx_trace_event_filter, tx_trace_event_unfilter, tx_trace_isr_enter_insert, tx_trace_isr_exit_insert, tx_trace_buffer_full_notify, tx_trace_user_event_insert
VOID tx_trace_isr_enter_insert (ULONG isr_id);
This service inserts the ISR enter event into the event trace buffer. It should be called by the application at the beginning of ISR processing. The supplied parameter should identify the specific ISR to the application.
Important: The ThreadX library and application must be built with TX_ENABLE_EVENT_TRACE defined in order to use event tracing.
None
ISRs
/* Insert trace event to identify the application's ISR with an ID of 3. */
status = tx_trace_isr_enter_insert (3);
/* If status is TX_SUCCESS the ISR entry event was inserted. */
tx_trace_enable, tx_trace_event_filter, tx_trace_event_unfilter, tx_trace_disable, tx_trace_isr_exit_insert, tx_trace_buffer_full_notify, tx_trace_user_event_insert
VOID tx_trace_isr_exit_insert (ULONG isr_id);
This service inserts the ISR entry event into the event trace buffer. It should be called by the application at the beginning of ISR processing. The supplied parameter should identify the ISR to the application.
Important: The ThreadX library and application must be built with TX_ENABLE_EVENT_TRACE defined in order to use event tracing.
None
ISRs
/* Insert trace event to identify the application's ISR with an ID of 3. */
status = tx_trace_isr_exit_insert (3);
/* If status is TX_SUCCESS the ISR exit event was inserted. */
tx_trace_enable, tx_trace_event_filter, tx_trace_event_unfilter, tx_trace_disable, tx_trace_isr_enter_insert, tx_trace_buffer_full_notify, tx_trace_user_event_insert
VOID tx_trace_buffer_full_notify (VOID (*full_buffer_callback)(VOID *));
This service registers an application callback function that is called by ThreadX when the trace buffer becomes full. The application can then choose to disable tracing and/or possibly setup a new trace buffer.
Important: The ThreadX library and application must be built with TX_ENABLE_EVENT_TRACE defined in order to use event tracing.
None
ISRs
y_trace_is_full(void *trace_buffer_start)
{
/* Application specific processing goes here! */
}
/* Register the "my_trace_is_full" function to be called whenever the trace buffer fills. */
status = tx_trace_buffer_full_notify (my_trace_is_full);
/* If status is TX_SUCCESS the "my_trace_is_full" function is registered. */
tx_trace_enable, tx_trace_event_filter, tx_trace_event_unfilter, tx_trace_disable, tx_trace_isr_enter_insert, tx_trace_isr_exit_insert, tx_trace_user_event_insert
UINT tx_trace_user_event_insert (ULONG event_id,
ULONG info_field_1, ULONG info_field_2,
ULONG info_field_3, ULONG info_field_4);
This service inserts the user event into the trace buffer. User event IDs must be greater than the constant TX_TRACE_USER_EVENT_START, which is defined to be 4096. The maximum user event is defined by the constant TX_TRACE_USER_EVENT_END, which is defined to be 65535. All events within this range are available to the application. The information fields are application specific.
Important: The ThreadX library and application must be built with TX_ENABLE_EVENT_TRACE defined in order to use event tracing.
Initialization and threads
/* Insert user event 3000, with info fields of 1, 2, 3, 4. */
status = tx_trace_user_event_insert (3000, 1, 2, 3, 4);
/* If status is TX_SUCCESS the user event was inserted. */
tx_trace_enable, tx_trace_event_filter, tx_trace_event_unfilter, tx_trace_disable, tx_trace_isr_enter_insert, tx_trace_isr_exit_insert, tx_trace_buffer_full_notify