第 11 章 - 事件跟踪缓冲区的格式

Azure RTOS ThreadX 为所有 ThreadX 服务、线程状态更改和用户定义的事件提供内置事件跟踪支持。 若要使用事件跟踪,只需使用定义的 TX_ENABLE_EVENT_TRACE 生成 ThreadX、NetX 和 FileX 库,并通过调用 tx_trace_enable 函数启用跟踪即可 。 本章将介绍该过程。

事件跟踪格式

ThreadX 事件跟踪缓冲区的格式划分为三个部分:控制头、对象注册表和跟踪条目。 下面描述了 ThreadX 事件跟踪缓冲区的一般布局:

控制头

对象注册表条目 0

对象注册表条目“n”

事件跟踪条目 0

事件跟踪条目“n”

事件跟踪控制头

控制头定义事件跟踪缓冲区的确切布局。 这包括可以注册多少个 ThreadX 对象,以及可以记录多少个事件数。 此外,控制头将定义跟踪缓冲区的每个元素驻留在哪个位置。 以下数据结构定义了控制头:

typedef struct TX_TRACE_CONTROL_HEADER_STRUCT
{
    ULONG    tx_trace_control_header_id;
    ULONG    tx_trace_control_header_timer_valid_mask;
    ULONG    tx_trace_control_header_trace_base_address;
    ULONG    tx_trace_control_header_object_registry_start_pointer;
    USHORT   tx_trace_control_header_reserved1;
    USHORT   tx_trace_control_header_object_registry_name_size;
    ULONG    tx_trace_control_header_object_registry_end_pointer;
    ULONG    tx_trace_control_header_buffer_start_pointer;
    ULONG    tx_trace_control_header_buffer_end_pointer;
    ULONG    tx_trace_control_header_buffer_current_pointer;
    ULONG    tx_trace_control_header_reserved2;
    ULONG    tx_trace_control_header_reserved3;
    ULONG    tx_trace_control_header_reserved4;
} TX_TRACE_CONTROL_HEADER;

控制头 ID

控制头 ID 由 32 位十六进制值 0x54585442 构成,该值对应于 ASCII 字符 TXTB。 由于此值是作为 32 位无符号变量写入的,因此它还可用于检测事件跟踪缓冲区的字节序。 例如,如果内存前四个字节中的值为 0x54、0x58、0x54、0x42,则事件跟踪缓冲区是以 big endian 格式写入的。 否则,事件跟踪缓冲区是以 little endian 格式写入的。

计时器有效掩码

计时器有效掩码定义实际事件跟踪条目中有多少个时间戳位有效。 例如,如果时间戳源包含 16 位,则此字段中的值应为 0xFFFF。 32 位时间戳源的值为 0xFFFFFFFF。 此值由 tx_port.h 中的 TX_TRACE_TIME_MASK 常量定义。

跟踪基址

跟踪缓冲区基址是在 tx_trace_enable 调用中指定为应用程序跟踪缓冲区起点的地址。 此地址是保留的地址,专供分析工具用来为缓冲区中的各个元素派生缓冲区相对偏移量。 例如,只需将当前事件地址减去基址,即可计算出跟踪缓冲区中当前事件的缓冲区相对偏移量。

注册表起点和终点指针

注册表起点指针指向第一个对象注册表条目的地址,而注册表终点指针则指向紧接在最后一个注册表条目后面的地址。 这些值是在 tx_trace_enable 处理期间设置的,在整个跟踪持续时间内不会更改。

注册表名称大小

注册表名称大小定义注册表条目中每个对象名称的最大大小(以字节为单位),由符号 TX_TRACE_OBJECT_REGISTRY_NAME 定义。 默认值为 32,在 tx_trace.h 中定义。 对象名称对应于在创建对象时由应用程序指定的名称。 例如,线程的对象注册表名称是应用程序提供给 tx_thread_create 调用的名称。

缓冲区起点和终点指针

事件跟踪缓冲区起点指针指向第一个跟踪条目的地址,而注册表终点指针则指向紧接在最后一个跟踪条目后面的地址。 这些值是在 tx_trace_enable</ 处理期间设置的,在整个跟踪持续时间内不会更改。

当前缓冲区指针

事件跟踪缓冲区当前指针指向最旧跟踪条目的地址。 由于跟踪条目在一个循环列表中进行维护,因此当前缓冲区指针还表示要写入的下一个跟踪条目。 |

事件跟踪对象注册表

事件跟踪对象注册表包含对应于应用程序所创建的对象的 n 个对象注册表条目。 对象注册表的主要用途是使外部分析工具能够将实际对象名与跟踪缓冲区条目的对象地址相关联。 注册表条目的数量由应用程序在 tx_trace_enable 调用中指定。

每个对象注册表条目包含有关应用程序以前创建的特定 ThreadX 对象的信息。 以下数据结构定义每个对象注册表条目:

typedef struct TX_TRACE_OBJECT_REGISTRY_ENTRY_STRUCT
{
    UCHAR    tx_trace_object_registry_entry_object_available**;
    UCHAR    tx_trace_object_registry_entry_object_type**;
    UCHAR    tx_trace_object_registry_entry_object_reserved1;
    UCHAR    tx_trace_object_registry_entry_object_reserved2;
    ULONG    tx_trace_thread_registry_entry_object_pointer;
    ULONG    tx_trace_object_registry_entry_object_parameter_1;
    ULONG    tx_trace_object_registry_entry_object_parameter_2;
    UCHAR    tx_trace_thread_registry_entry_object_name[TX_TRACE_OBJECT_REGISTRY_NAME];

} TX_TRACE_OBJECT_REGISTRY_ENTRY;

对象可用标志

如果对象注册表条目可用,则对象可用标志将设置为 1。 否则,如果值不为 1,则表示对象注册表条目不可用。 请注意,即使该条目可用,它也仍可能包含有效信息。

对象条目类型

对象条目类型标识此条目中的对象类型。 下面是有效对象类型的列表:

“对象类型”
0 无效
1 线程
2 计时器
3 队列
4 Semaphore
5 Mutex
6 事件标志组
7 块池
8 字节池
9 ../media
10 文件
11 IP
12 数据包池
13 TCP 套接字
14 UDP 套接字
15-20 保留
21 USB 主机堆栈设备
22 USB 主机堆栈接口
23 USB 主机终结点
24 USB 主机类
25 USB 设备
26 USB 设备接口
27 USB 设备终结点
28 USB 设备类

对象指针

对象指针指定用于通过 ThreadX API 访问对象的对象地址。

对象保留字段

对于除线程以外的所有对象,这些保留字段应为 0。 对于线程,将线程输入到注册表时该线程的优先级会放入到这两个保留字段中。

对象参数

对象参数包含有关对象的补充信息。 下面描述了每个 ThreadX 对象的补充信息:

“对象类型” 参数 1 参数 2
线程 堆栈起点 堆栈大小
计时器 初始时钟周期 重新计划时钟周期
队列 队列大小 消息大小
Semaphore 初始实例 -
Mutex 继承标志 -
事件标志组 - -
块池 总块数 块大小
字节池 字节数总计 -
../media FAT 缓存大小 扇区缓存大小
文件 - -
IP 堆栈起点 堆栈大小
数据包池 Packet Size 数据包数
TCP 套接字 IP 地址 窗口大小
UDP 套接字 IP 地址 RX 队列最大值

对象名称

对象名称包含 ThreadX 对象的名称。 该名称是创建对象时提供给 ThreadX 的名称。 默认情况下,对象名称最多包含 32 个字符。 超过 32 个字符的实际名称将被截断。

事件跟踪条目

事件跟踪条目位于事件跟踪缓冲区的底部部分。 这些条目在一个循环列表中进行维护,其当前入口指针指向最旧的条目。 列表中的条目数是通过 tx_trace_enable 调用来计算的

每个对象注册表条目包含有关特定 ThreadX 跟踪事件的信息。 以下数据结构定义每个跟踪事件条目:

typedef struct TX_TRACE_BUFFER_ENTRY_STRUCT
{
    ULONG     tx_trace_buffer_entry_thread_pointer;
    ULONG     tx_trace_buffer_entry_thread_priority;
    ULONG     tx_trace_buffer_entry_event_id;
    ULONG     tx_trace_buffer_entry_time_stamp;
    ULONG     tx_trace_buffer_entry_information_field_1;
    ULONG     tx_trace_buffer_entry_information_field_2;
    ULONG     tx_trace_buffer_entry_information_field_3;
    ULONG     tx_trace_buffer_entry_information_field_4;
} TX_TRACE_BUFFER_ENTRY;

线程指针

线程指针包含发生此事件时运行的线程的地址。 如果该事件是在初始化期间发生的(未运行线程),则此指针的值为 0xF0F0F0F0。 如果该事件是在运行中断服务例程 (ISR) 期间发生的,则此指针的值为 0xFFFFFFFF。 如果该条目尚未使用,则此指针的值为 0。

线程优先级

线程优先级字段包含发生此事件时运行的线程的线程优先级和抢占阈值。 如果存在中断上下文(线程指针为 0xFFFFFFFF),则此字段的值不是优先级,而是发生该事件时 _tx_thread_current_ptr的值。 否则,此字段的值为 0。

事件 ID

事件 ID 指定发生的事件。 有效 ThreadX 跟踪事件 ID 的范围为 1 到 1024。 1025 及更大的值是为用户特定的事件保留的。 有关 ThreadX 事件 ID 的完整定义,请参阅 tx_trace.h 文件

信息字段 (1-4)

信息字段包含有关特定事件的其他信息。 有关定义的每个 ThreadX 事件 ID 的信息字段完整说明,请参阅 tx_trace.h 文件