When using Percepio Tracealyzer and TraceRecorder, you may have noticed that thread names show up automatically, while other kernel objects (like queues or semaphores) are only displayed as hexadecimal numbers. But in the demo traces, all kernel objects have proper names. So how do you set the names?
Most RTOS kernels have a name field in the thread structure, but typically no native support for naming other kernel object types, like queues, semaphores or mutexes. Such objects has to be named by calling the TraceRecorder API. For unnamed objects, Tracealyzer displays the object’s handle (identifier) as a hexadecimal value, which is typically the memory address of the object. For traces with many objects, such hexadecimal values can be a bit hard to follow. Fortunately it is quite easy to set more descriptive custom names for your RTOS objects.
Option 1. Using the “vTraceSet[Type]Name” functions, for example:
vTraceSetQueueName(queue, "queue name"); vTraceSetMutexName(mutex, "mutex name");
The first argument is the object pointer (i.e. the address). The exact functions (or macros) to use depends on the TraceRecorder RTOS port, so have a look in trcKernelPort.h to see which ones are available for your RTOS.
Option 2. Instead of using the type-specific functions, you may call the common function xTraceObjectSetNameWithoutHand
xTraceObjectSetNameWithoutHandle(queue, "queue name");
The “WithoutHandle” suffix means that you don’t need to provide a TraceObjectHandle_t as argument (in contrast to the related function xTraceObjectSetName).
Option 3. FreeRTOS users may use vQueueAddToRegistry(). Objects added in the queue registry are automatically picked up by TraceRecorder. Note that this is not limited to queues, as FreeRTOS implements several kernel object types based on the same “queue” data structure.
Troubleshooting
If a name still doesn’t show, then perhaps the object was created before the TraceRecorder was initialized. Invoking xTraceInitialize() before the object creation should fix that. Another cause could be that the recorder’s internal symbol table (a.k.a. entry table) is full. Try increasing the number of entry table slots in the TraceRecorder configuration, see TRC_CFG_ENTRY_SLOTS in trcConfig.h (for v4.11 and later), or in trcStreamingConfig.h (for v4.10 or earlier).
When using continuous trace streaming, it could be that the event carrying the name of the object got corrupted or wasn’t received at all. Check for “missed events” in the Live Stream window or red background color in the trace views and ensure that all events are received. Solutions depend on what streaming interface that is used. If using J-Link RTT streaming, see https://percepio.com/troubleshoot-j-link-rtt/.
