# ktracepoint

面向内核场景的 Rust tracepoint 库，设计目标类似 Linux tracepoint：

- 用宏定义事件与字段
- 运行时按子系统/事件管理
- 支持开关、过滤表达式、回调
- 支持原始事件缓冲区与可读文本输出
- no_std 可用

## 核心能力

- 事件定义：通过 define_event_trace! 一次性生成事件元数据、调用函数、注册函数
- 事件管理：TracingEventsManager -> subsystem -> event
- 事件控制：enable/disable、format/id/filter
- 过滤表达式：基于 tp-lexer 按 schema 编译并匹配
- 输出链路：TracePipeRaw + TraceEntryParser

## 快速接入

### 1. 添加依赖

```toml
[dependencies]
ktracepoint = "*"
static-keys = "0.8"
```

### 2. 链接脚本中保留 .tracepoint 段

该库通过 __start_tracepoint / __stop_tracepoint 扫描所有事件元数据。
请将 my_section.ld 的内容并入你的链接脚本，确保 .tracepoint 段被 KEEP。

### 3. 实现 KernelTraceOps

你需要提供：

- time_now
- cpu_id
- current_pid
- trace_pipe_push_raw_record
- trace_cmdline_push
- write_kernel_text

其中 write_kernel_text 用于 static key 指令补丁。

### 4. 定义并调用事件

```rust
use ktracepoint::{define_event_trace, KernelTraceOps};

define_event_trace!(
    TEST,
    TP_lock(Mutex<()>),
    TP_kops(Kops),
    TP_system(tracepoint_test),
    TP_PROTO(a: u32, b: u32),
    TP_STRUCT__entry { a: u32, b: u32 },
    TP_fast_assign { a: a, b: b },
    TP_ident(__entry),
    TP_printk(format_args!("a={}, b={}", __entry.a, __entry.b))
);

// 生成函数: trace_TEST / register_trace_TEST / unregister_trace_TEST
trace_TEST(1, 2);
```

提示：TP_STRUCT__entry 会参与字节布局，请确保字段布局符合预期（建议 C 风格布局思路）。

### 5. 初始化管理器

```rust
use ktracepoint::global_init_events;

static_keys::global_init();
let manager = global_init_events::<Mutex<()>, Kops>()?;
```

### 6. 启用、过滤、消费输出

```rust
let subsystem = manager.get_subsystem("tracepoint_test").unwrap();
let event = subsystem.get_event("TEST").unwrap();

event.enable_file().write('1');
event.tracepoint().enable_event();
event.filter_file().write("a > 8 && b > 5").unwrap();

// 读取格式描述
let fmt = event.format_file().read();
let id = event.id_file().read();
```

## 运行示例

```bash
cd examples
cargo run --example usage
```

示例代码位于 examples/usage.rs，覆盖了：

- 事件定义与触发
- 事件启用与过滤
- 注册 event/raw 回调
- TracePipeRaw 快照读取与文本解析

## 主要公开类型

- KernelTraceOps
- TracePoint / TracePointMap
- TracingEventsManager / EventsSubsystem / EventInfo
- TracePipeRaw / TracePipeSnapshot / TracePipeOps
- TraceCmdLineCache / TraceEntryParser

## 参考项目

- DragonOS: <https://github.com/DragonOS-Community/DragonOS/blob/master/kernel/src/debug/tracing/mod.rs>
- Hermit: <https://github.com/os-module/hermit-kernel/blob/dev/src/tracepoint/mod.rs>