From bb79f7fe3ce0fb9642f896358f094bca9259011e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 14 Jun 2025 20:42:15 +0800 Subject: [PATCH] docs: Translation update [6b581d4d] (#1207) * Update translated documentation --------- Co-authored-by: dragonosbot --- docs/.translation_cache.json | 5 +- docs/locales/en/kernel/trace/index.rst | 5 +- docs/locales/en/kernel/trace/tracepoint.md | 74 ++++++++++++++++++++++ 3 files changed, 81 insertions(+), 3 deletions(-) create mode 100644 docs/locales/en/kernel/trace/tracepoint.md diff --git a/docs/.translation_cache.json b/docs/.translation_cache.json index fa7d207f3..984acac92 100644 --- a/docs/.translation_cache.json +++ b/docs/.translation_cache.json @@ -153,7 +153,7 @@ "hash": "aa1979d81b79f64b12962f885a6820af" }, "en:kernel/trace/index.rst": { - "hash": "944a5b865100258ec7957a4cbedd7251" + "hash": "3c466a411a5bd71514f8fa4f15d06241" }, "en:kernel/configuration/config.md": { "hash": "dff794c4f3bfb4c3d66e6d0fa8f7c495" @@ -271,5 +271,8 @@ }, "en:questions/build_errors.md": { "hash": "76bf24821bab907c28e8c8287d2895d5" + }, + "en:kernel/trace/tracepoint.md": { + "hash": "18a5f586ca3e3ffbdec6ceeac34eba9c" } } \ No newline at end of file diff --git a/docs/locales/en/kernel/trace/index.rst b/docs/locales/en/kernel/trace/index.rst index f5c9dfec4..6395f674a 100644 --- a/docs/locales/en/kernel/trace/index.rst +++ b/docs/locales/en/kernel/trace/index.rst @@ -4,7 +4,7 @@ - Source document: kernel/trace/index.rst - - Translation time: 2025-05-19 01:41:20 + - Translation time: 2025-06-14 09:35:32 - Translation model: `Qwen/Qwen3-8B` @@ -14,7 +14,7 @@ Kernel Tracing Mechanism ==================================== - The kernel tracing mechanism consists of many functionalities, such as kprobe, uprobe, tracepoint, ftrace, and eBPF, which is used to extend the observability of the kernel. The kernel currently supports kprobe and eBPF. This chapter will introduce these two mechanisms. + The kernel tracing mechanism consists of many features, such as kprobe, uprobe, tracepoint, and ftrace, as well as eBPF for extending kernel observability. The kernel currently supports kprobe and eBPF, and this chapter will introduce these two mechanisms. .. toctree:: :maxdepth: 1 @@ -22,3 +22,4 @@ Kernel Tracing Mechanism eBPF kprobe + tracepoint diff --git a/docs/locales/en/kernel/trace/tracepoint.md b/docs/locales/en/kernel/trace/tracepoint.md new file mode 100644 index 000000000..ee813ce4e --- /dev/null +++ b/docs/locales/en/kernel/trace/tracepoint.md @@ -0,0 +1,74 @@ +:::{note} +**AI Translation Notice** + +This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only. + +- Source document: kernel/trace/tracepoint.md + +- Translation time: 2025-06-14 09:36:42 + +- Translation model: `Qwen/Qwen3-8B` + +Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues) + +::: + +# Tracepoints + +> Author: Chen Linfeng +> +> Email: chenlinfeng25@outlook.com + +## Overview +Tracepoints are a tracing mechanism provided by the Linux kernel, allowing developers to insert probe points at specific locations in the kernel code to collect runtime information. Unlike kprobes, tracepoints are predefined and are typically used for collecting performance data or debugging information without modifying the kernel code. + +## Workflow +1. **Define Tracepoint**: Kernel developers define tracepoints in the code using the macro ``define_event_trace``. +2. **Trigger Tracepoint**: Developers can trigger the defined tracepoints from other parts of the code by using the functions defined with ``define_event_trace``, and pass relevant context information. For example, if the defined tracepoint is named ``my_tracepoint``, it can be triggered using ``trace_my_tracepoint()``. +3. **Collect Data**: When a tracepoint is triggered, the kernel records the related data. This data can be analyzed using user-space tools (such as ``trace-cmd`` or ``perf``). Currently, DragonOS only supports viewing the data files created by the kernel for these data. + 1. Reading the ``/sys/kernel/debug/tracing/trace`` file can view the tracepoint collected data. The buffer content will not be cleared. + 2. Reading the ``/sys/kernel/debug/tracing/trace_pipe`` file can view the tracepoint collected data. The buffer content will be cleared. If there is no content in the buffer, it will block until new data is available. + 3. Reading the ``/sys/kernel/debug/tracing/events/`` directory can view all available tracepoints. + 4. Reading the ``/sys/kernel/debug/tracing/events//format`` file can view the data format of a specific tracepoint. + 5. Writing to the ``/sys/kernel/debug/tracing/events//enable`` file can enable a specific tracepoint. + 6. Writing an empty value to ``/sys/kernel/debug/tracing/trace`` can clear the current trace data. +4. **Analyze Data**: User-space tools can read the data collected by tracepoints and generate reports or charts to help developers understand kernel behavior. + +## Interface +```rust +define_event_trace!() // 定义一个 tracepoint +``` + +```rust +// example +define_event_trace!( + sys_enter_openat, + TP_system(syscalls), + TP_PROTO(dfd: i32, path:*const u8, o_flags: u32, mode: u32), + TP_STRUCT__entry{ + dfd: i32, + path: u64, + o_flags: u32, + mode: u32, + }, + TP_fast_assign{ + dfd: dfd, + path: path as u64, + o_flags: o_flags, + mode: mode, + }, + TP_ident(__entry), + TP_printk({ + format!( + "dfd: {}, path: {:#x}, o_flags: {:?}, mode: {:?}", + __entry.dfd, + __entry.path, + __entry.o_flags, + __entry.mode + ) + }) +); +``` + +## Tracepoints For eBPF +In DragonOS, tracepoints can also be used in conjunction with eBPF to collect richer data within the kernel. eBPF programs can be attached to tracepoints to execute custom logic when a tracepoint is triggered.