Lib.rs

› 配置 | 开发工具 › 调试
#plugin #events #tracing #ingest #modality #protocols #trace-recorder

bin+lib modality-trace-recorder-plugin

Percepio 的 TraceRecorder 数据的 Modality 反射插件套件和摄取适配器库

作者：Jon

14 个版本 (6 个重大更新)

0.9.0 2024年2月29日
0.7.0 2024年2月21日
0.3.6 2023年5月23日
0.3.4 2023年3月8日
0.1.3 2022年7月22日

#59 in 配置

Download history 66/week @ 2024-03-13 30/week @ 2024-03-27 59/week @ 2024-04-03

每月406次下载

Apache-2.0

220KB
4.5K SLoC

modality-trace-recorder-plugin   ci crates.io

Modality 反射插件套件和摄取适配器库，用于 Percepio 的 TraceRecorder 数据。

内核端口 快照协议 流式协议 文件导入 流端口
FreeRTOS v6 v10, v12-v14 是 TCP, ITM, RTT

入门指南

  1. 将 TraceRecorder 源文件和配置添加到您的 RTOS 项目中（例如，使用 Using FreeRTOS-Plus-Trace）
  2. 使用导入器导入内存转储或流数据文件，或使用可用的流收集器从运行中的系统收集数据

适配器概念映射

以下描述了 TraceRecorder 的概念与 Modality 的概念之间的默认映射。有关更改默认行为的说明，请参阅配置部分。

  • 任务和中断服务例程对象表示为单独的 Modality 时间线
  • 初始启动任务 ('(startup)') 也表示为单独的 Modality 时间线
  • 流式标题和快照字段表示为 timeline.internal.trace_recorder 前缀下的 Modality 时间线属性。
  • 对象属性和事件上下文字段表示为 event.internal.trace_recorder 前缀下的 Modality 事件属性。
  • 事件字段属性位于根级别（例如，event.channel 用于 USER_EVENT 通道字段）。
  • 任务和中断服务例程（ISR）上下文切换将被综合为 Modality 时间线交互。

有关 Modality 概念的更多信息，请参阅 Modality 文档。

配置

所有插件都可以通过 TOML 配置文件进行配置（从 --config 选项或 MODALITY_REFLECTOR_CONFIG 环境变量）。所有配置字段都可以在命令行中进行覆盖，有关详细信息，请参阅 --help。

有关反射器配置的更多信息，请参阅 modality-reflector 配置文件文档。

常见部分

这些部分对每个插件都是相同的。

  • [ingest] —— 最高级别的摄取配置。

    • additional-timeline-attributes —— 添加到插件看到的每个时间线中的键值属性对数组。
    • override-timeline-attributes —— 覆盖插件看到的每个时间线中的键值属性对数组。
    • allow-insecure-tls —— 是否允许不安全的连接。默认为 false。
    • protocol-parent-url —— 此反射器将发送其收集数据的 URL。

  • [metadata] —— 插件配置表。

    • run-id —— 使用提供的 UUID 作为运行 ID，而不是生成一个随机的 ID。
    • time-domain —— 使用提供的 UUID 作为时间域 ID，而不是生成一个随机的 ID。
    • startup-task-name —— 使用提供的初始启动任务名称，而不是默认的 (startup)。
    • single-task-timeline —— 对所有任务使用单个时间线，而不是每个任务一个时间线。ISR 可以用它们自己的时间线表示，也可以不表示。
    • disable-task-interactions —— 当发生上下文切换时，不要综合任务和 ISR 之间的交互。
    • use-timeline-id-channel —— 通过读取 modality_timeline_id 通道（格式为 name=<obj-name>,id=<timeline-id>）上的事件来检测任务/ISR 时间线 ID。
    • deviant-event-id-base —— 使用提供的基事件 ID 解析 Deviant 自定义事件。
    • ignored-object-classes — 忽略在导入过程中处理的对象类数组（例如：[queue, semaphore]）
    • user-event-channel — 使用用户事件通道作为事件名称，而不是使用 USER_EVENT @ <task-name>，即使用 <channel> @ <task-name>。
    • user-event-format-string — 使用用户事件格式字符串作为事件名称，而不是使用 USER_EVENT @ <task-name>，即使用 <format-string> @ <task-name>。
    • [[user-event-channel-name]] — 当处理匹配通道的用户事件时，使用自定义事件名称。
      • channel— 要匹配的输入通道名称。
      • event-name— 要使用的Modality事件名称。
    • [[user-event-formatted-string-name]] — 当处理匹配格式字符串的用户事件时，使用自定义事件名称。
      • formatted-string— 要匹配的输入格式字符串。
      • event-name— 要使用的Modality事件名称。
    • [[user-event-fmt-arg-attr-keys]] — 对于匹配给定通道和格式字符串的用户事件，使用自定义属性键，而不是默认的 argN 键。
      • channel— 要匹配的输入通道名称。
      • format-string— 要匹配的输入格式字符串。
      • attribute-keys— 要使用的Modality事件属性键数组。

异常事件

当提供 deviant-event-id-base 配置时，将解析并从TraceRecorder自定义事件映射到保留的Modality事件名称和属性，以获取与异常相关的信息。

预期事件ID偏移和数据

  • 事件：modality.mutator.announced
    • 事件ID偏移：0
    • 数据：['mutator_id']
      • mutator_id 是一个16字节UUID数组
  • 事件：modality.mutator.retired
    • 事件ID偏移：1
    • 数据：['mutator_id']
      • mutator_id 是一个16字节UUID数组
  • 事件：modality.mutation.command_communicated
    • 事件ID偏移：2
    • 数据：['mutator_id', 'mutation_id', 'mutation_success']
      • mutator_id 是一个16字节UUID数组
      • mutation_id 是一个16字节UUID数组
      • mutation_success 是一个 4 字节 (uint32_t) 的布尔值
  • 事件：modality.mutation.clear_communicated
    • 事件 ID 偏移：3
    • 数据：['mutator_id', 'mutation_id', 'mutation_success']
      • mutator_id 是一个16字节UUID数组
      • mutation_id 是一个16字节UUID数组
      • mutation_success 是一个 4 字节 (uint32_t) 的布尔值
  • 事件：modality.mutation.triggered
    • 事件 ID 偏移：4
    • 数据：['mutator_id', 'mutation_id', 'mutation_success']
      • mutator_id 是一个16字节UUID数组
      • mutation_id 是一个16字节UUID数组
      • mutation_success 是一个 4 字节 (uint32_t) 的布尔值
  • 事件：modality.mutation.injected
    • 事件 ID 偏移：5
    • 数据：['mutator_id', 'mutation_id', 'mutation_success']
      • mutator_id 是一个16字节UUID数组
      • mutation_id 是一个16字节UUID数组
      • mutation_success 是一个 4 字节 (uint32_t) 的布尔值

有关 Mutators 和 Mutations 的更多信息，请参阅 Deviant 文档。

导入器部分

这些 metadata 字段是导入器插件特有的。

请注意，各个插件配置将放在您的反射器配置文件中的特定表中，例如 [plugins.ingest.importers.trace-recorder.metadata]。

  • [metadata] —— 插件配置表。
    • protocol — 要使用的协议。可以是 streaming、snapshot 或 auto。默认值为 auto。
    • file — 要导入的文件的路径。

TCP 收集器部分

这些 metadata 字段是流式 TCP 收集器插件特有的。

请注意，各个插件配置将放在您的反射器配置文件中的特定表中，例如 [plugins.ingest.collectors.trace-recorder-tcp.metadata]。

  • [metadata] —— 插件配置表。
    • disable-control-plane — 禁止向目标发送控制平面命令。默认情况下，在启动和关闭时发送 CMD_SET_ACTIVE 以在目标上开始和停止跟踪。
    • restart — 在启动命令之前发送停止命令，以在目标上重置跟踪。
    • connect-timeout — 指定连接超时。接受类似于 "10ms" 或 "1minute 2seconds 22ms" 的持续时间。
    • remote — 要连接的远程地址和端口。默认值是 127.0.0.1:8888。

ITM 收集器部分

这些 metadata 字段是流式 ITM 收集器插件特有的。

请注意，各个插件配置将放在您的反射器配置文件中的特定表中，例如 [plugins.ingest.collectors.trace-recorder-itm.metadata]。

  • [metadata] —— 插件配置表。
    • disable-control-plane — 禁止向目标发送控制平面命令。默认情况下，在启动和关闭时发送 CMD_SET_ACTIVE 以在目标上开始和停止跟踪。
    • restart — 在启动命令之前发送停止命令，以在目标上重置跟踪。
    • elf-file — 从 ELF 文件（tz_host_command_bytes_to_read 和 tz_host_command_data）的调试符号中提取 ITM 流端口变量的内存位置。这些用于通过从探针写入控制平面命令来开始和停止跟踪。
    • command-data-addr — 使用提供的内存地址作为 ITM 流端口变量 tz_host_command_data。这些用于通过从探针写入控制平面命令来开始和停止跟踪。
    • command-len-addr — 使用提供的内存地址作为 ITM 流端口变量 tz_host_command_bytes_to_read。这些用于通过从探针写入控制平面命令来开始和停止跟踪。
    • stimulus-port — 用于跟踪记录器数据的 ITM 刺激端口。默认值为 1。
    • probe-selector — 选择特定的探针而不是打开第一个可用的探针。
    • chip — 要连接的目标芯片（例如：STM32F407VE）。
    • protocol — 连接到芯片所使用的协议。可能选项：[swd，jtag]。默认值是 swd。
    • speed — 协议速度，单位为 kHz。默认值是 4000。
    • core — 要选中的目标核心。默认值是 0。
    • clk — 为 TPIU/SWO 模块供电的时钟速度，单位为 Hz。
    • baud — 所需的 SWO 输出波特率。
    • reset — 启动时重置目标。
    • chip-description-path — 根据CMSIS Pack文件提供自定义的目标描述。有关更多信息，请参阅probe-rs目标提取部分。

RTT收集器部分

这些 metadata 字段针对流式RTT收集器插件是特定的。

请注意，每个插件配置都应放在您的反射器配置文件中的特定表中，例如：[plugins.ingest.collectors.trace-recorder-rtt.metadata]。

  • [metadata] —— 插件配置表。
    • attach-timeout — 指定目标连接超时。当提供时，插件将不断尝试连接并在目标RAM的任何位置搜索有效的RTT控制块。接受像“10ms”或“1分钟2秒22ms”这样的持续时间。有关更多信息，请参阅RTT计时部分。
    • disable-control-plane — 禁止向目标发送控制平面命令。默认情况下，在启动和关闭时发送 CMD_SET_ACTIVE 以在目标上开始和停止跟踪。
    • restart — 在启动命令之前发送停止命令，以在目标上重置跟踪。
    • up-channel — 要轮询的RTT上（目标到主机）通道号。默认值是1。
    • down-channel — 要发送启动/停止命令的RTT下（主机到目标）通道号。默认值是1。
    • probe-selector — 选择特定的探针而不是打开第一个可用的探针。
    • chip — 要连接的目标芯片（例如：STM32F407VE）。
    • protocol — 连接到芯片所使用的协议。可能选项：[swd，jtag]。默认值是 swd。
    • speed — 协议速度，单位为 kHz。默认值是 4000。
    • core — 要选中的目标核心。默认值是 0。
    • reset — 启动时重置目标。
    • chip-description-path — 根据CMSIS Pack文件提供自定义的目标描述。有关更多信息，请参阅probe-rs目标提取部分。

配置示例

以下配置示例基于导入部分，但也适用于任何收集器。

每个示例都是基于前一个示例构建的。

数据使用modality查询查询，并从以下TraceRecorder仪表（为简洁起见已截断）生成。

// logging_info will write to a channel named "info"
#define INFO(fmt, ...) logging_info(fmt, ##__VA_ARGS__)

int main(void)
{
    // ...

    INFO("System initialized");

    // ...
}

static void sensor_task(void* params)
{
    int16_t adc;
    traceString ch;

    ch = xTraceRegisterString("adc");
    while(1)
    {
        // ...
        adc = read_adc();
        vTracePrintF(ch, "%d", adc);
        // ...
    }
}

static void comms_task(void* params)
{
    traceString ch;
    wire_msg_s wire_msg = {0};

    ch = xTraceRegisterString("comms-tx");

    // ...

    INFO("Comms network ready");

    while(1)
    {
        const comms_msg_s comms_msg = comms_recv();

        // ...

        wire_msg.magic0 = WIRE_MAGIC0;
        wire_msg.magic1 = WIRE_MAGIC1;
        wire_msg.type = WIRE_TYPE_SENSOR_DATA;
        wire_msg.seqnum += 1;
        wire_msg.adc = comms_msg.adc;

        vTracePrintF(ch, "%u %u %d", wire_msg.type, wire_msg.seqnum, wire_msg.adc);

        // ...
    }
}

默认

■  ║  ║  TRACE_START @ (startup)  [1272bab3d50d491691d0abefd1bc9cc0:00]
║  ║  ║    task=(startup)
║  ║  ║    timestamp=1190400ns
║  ║  ║
■  ║  ║  USER_EVENT @ (startup)  [1272bab3d50d491691d0abefd1bc9cc0:13]
║  ║  ║    channel=info
║  ║  ║    formatted_string=System initialized
║  ║  ║    timestamp=7027200ns
║  ║  ║
║  ■  ║  USER_EVENT @ Sensor  [5528cf640e1045ea833335b809cfc02e:0130]
║  ║  ║    arg0=-128
║  ║  ║    channel=adc
║  ║  ║    formatted_string=-128
║  ║  ║    timestamp=262105600ns
║  ║  ║
║  ║  ■  USER_EVENT @ Comms  [8a0430ddb8c143299c01080926457436:04d6]
║  ║  ║    channel=info
║  ║  ║    formatted_string=Comms network ready
║  ║  ║    timestamp=2173248000ns
║  ║  ║
║  ║  ■  USER_EVENT @ Comms  [8a0430ddb8c143299c01080926457436:04d8]
║  ║  ║    arg0=240
║  ║  ║    arg1=1
║  ║  ║    arg2=-128
║  ║  ║    channel=comms-tx
║  ║  ║    formatted_string=240 1 -128
║  ║  ║    timestamp=2173299200ns

startup-task-name

[plugins.ingest.importers.trace-recorder.metadata]
startup-task-name = 'my-fw-img'

■  ║  ║  TRACE_START @ my-fw-img  [a324dcfaddb6415b878741b0238f4cf3:00]
║  ║  ║    task=(startup)
║  ║  ║    timestamp=1190400ns
║  ║  ║
■  ║  ║  USER_EVENT @ my-fw-img  [a324dcfaddb6415b878741b0238f4cf3:13]
║  ║  ║    channel=info
║  ║  ║    formatted_string=System initialized
║  ║  ║    timestamp=7027200ns
║  ║  ║
║  ■  ║  USER_EVENT @ Sensor  [8e1c7e7a3560498d932247bb100281f2:0130]
║  ║  ║    arg0=-128
║  ║  ║    channel=adc
║  ║  ║    formatted_string=-128
║  ║  ║    timestamp=262105600ns
║  ║  ║
║  ║  ■  USER_EVENT @ Comms  [ffe10d39ee5546e8aa0fc0450ee37ed0:04d6]
║  ║  ║    channel=info
║  ║  ║    formatted_string=Comms network ready
║  ║  ║    timestamp=2173248000ns
║  ║  ║
║  ║  ■  USER_EVENT @ Comms  [ffe10d39ee5546e8aa0fc0450ee37ed0:04d8]
║  ║  ║    arg0=240
║  ║  ║    arg1=1
║  ║  ║    arg2=-128
║  ║  ║    channel=comms-tx
║  ║  ║    formatted_string=240 1 -128
║  ║  ║    timestamp=2173299200ns

user-event-channel

[plugins.ingest.importers.trace-recorder.metadata]
startup-task-name = 'my-fw-img'
user-event-channel = true

■  ║  ║  TRACE_START @ my-fw-img  [381937af8be847f7a556829770e7ba77:00]
║  ║  ║    task=(startup)
║  ║  ║    timestamp=1190400ns
║  ║  ║
■  ║  ║  info @ my-fw-img  [381937af8be847f7a556829770e7ba77:13]
║  ║  ║    channel=info
║  ║  ║    formatted_string=System initialized
║  ║  ║    timestamp=7027200ns
║  ║  ║
║  ■  ║  adc @ Sensor  [d19f58f7e235473a9799812cf7975a57:0130]
║  ║  ║    arg0=-128
║  ║  ║    channel=adc
║  ║  ║    formatted_string=-128
║  ║  ║    timestamp=262105600ns
║  ║  ║
║  ║  ■  info @ Comms  [24aa15eb92864a508ae7a962afafe9a4:04d6]
║  ║  ║    channel=info
║  ║  ║    formatted_string=Comms network ready
║  ║  ║    timestamp=2173248000ns
║  ║  ║
║  ║  ■  comms-tx @ Comms  [24aa15eb92864a508ae7a962afafe9a4:04d8]
║  ║  ║    arg0=240
║  ║  ║    arg1=1
║  ║  ║    arg2=-128
║  ║  ║    channel=comms-tx
║  ║  ║    formatted_string=240 1 -128
║  ║  ║    timestamp=2173299200ns

user-event-fmt-arg-attr-keys

[plugins.ingest.importers.trace-recorder.metadata]
startup-task-name = 'my-fw-img'
user-event-channel = true

    [[plugins.ingest.importers.trace-recorder.metadata.user-event-fmt-arg-attr-keys]]
    channel = 'comms-tx'
    format-string = '%u %u %d'
    attribute-keys = ['type', 'seqnum', 'adc']

    [[plugins.ingest.importers.trace-recorder.metadata.user-event-fmt-arg-attr-keys]]
    channel = 'adc'
    format-string = '%d'
    attribute-keys = ['measurement']

■  ║  ║  TRACE_START @ my-fw-img  [001e1d94336042e6bbbfdb3b04609ec4:00]
║  ║  ║    task=(startup)
║  ║  ║    timestamp=1190400ns
║  ║  ║
■  ║  ║  info @ my-fw-img  [001e1d94336042e6bbbfdb3b04609ec4:13]
║  ║  ║    channel=info
║  ║  ║    formatted_string=System initialized
║  ║  ║    timestamp=7027200ns
║  ║  ║
║  ■  ║  adc @ Sensor  [8245e9ef77344e3f9698adb9d45487d4:0130]
║  ║  ║    channel=adc
║  ║  ║    formatted_string=-128
║  ║  ║    measurement=-128
║  ║  ║    timestamp=262105600ns
║  ║  ║
║  ║  ■  info @ Comms  [59be714493cc4d67b15c0ee459a9fc3d:04d6]
║  ║  ║    channel=info
║  ║  ║    formatted_string=Comms network ready
║  ║  ║    timestamp=2173248000ns
║  ║  ║
║  ║  ■  comms-tx @ Comms  [59be714493cc4d67b15c0ee459a9fc3d:04d8]
║  ║  ║    channel=comms-tx
║  ║  ║    formatted_string=240 1 -128
║  ║  ║    type=240
║  ║  ║    seqnum=1
║  ║  ║    adc=-128
║  ║  ║    timestamp=2173299200ns

LICENSE

有关详细信息，请参阅LICENSE。

版权所有 2024 Auxon Corporation

在Apache License，版本2.0（“许可证”）下许可；除非根据适用法律或书面同意，否则不得使用此文件，除非遵守许可证。您可以在以下位置获得许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则在许可证下分发的软件按“原样”基础分发，不提供任何明示或暗示的保证或条件。有关许可证的具体语言规定许可和限制，请参阅许可证。

依赖项

~36–52MB
~789K SLoC