gtrace v2: RISC-V Hardware Trace Rebuilt on the Generic Trace Framework (24-Patch RFC)
On 22 October 2026, Zane Leung (liangzhen@linux.spacemit.com) posted [RFC PATCH 00/24] Add Linux RISC-V trace support via the gtrace framework to linux-riscv. It is not a v7 of the October 1 series — it is a rewrite: the earlier attempt bent RISC-V trace IP into CoreSight's device model, this one moves the topology onto gtrace, the architecture-neutral hardware-trace framework, and re-implements the CoreSight pieces as gtrace components so both can share one trace path. Diffstat: 41 files, +10,926 / −180.
What gtrace Is
gtrace (Generic Trace) lives in drivers/hwtracing/gtrace/ and provides the shared plumbing every hardware-trace implementation needs: component registration, path creation/destruction, path start/stop, and perf AUX buffer integration so trace data lands in the standard perf AUX area as PERF_RECORD_AUXTRACE.
The design is deliberately not RISC-V-only. That is the whole point of this posting: an Arm CoreSight funnel and TMC are now gtrace components too. The pitch is one kernel trace framework for both ISAs rather than two parallel subsystems — the closest thing to a successor-or-sibling to drivers/hwtracing/coresight/ anyone has posted.
What This Revision Actually Changes
| Area | Oct 1 series (v6, 14 patches) | Oct 22 RFC (24 patches) |
|---|---|---|
| Architecture | RISC-V trace IP made to conform to the CoreSight device model | Topology shifted onto gtrace; CoreSight funnel + TMC re-implemented as gtrace components |
| RISC-V components | Encoder + RAM sink | Encoder, funnel, ATB bridge, timestamp, RAM sink |
| Configuration | Device tree only | gtrace sysfs framework — per-component control, features, timestamp attributes |
| Userspace decode | 95-line stub; packet decoding "future work" | In-tree Nexus (N-Trace) decoder + gtrace AUX decoder that synthesises branch samples, incl. machine-mode instruction access |
| Data format flag | Format baked into device tree compatible | PERF_AUX_FLAG_ flag marking whether AUX data carries CoreSight framing |
| Per-CPU correlation | Not addressed | Named dependency: encoder must emit a context ID, which needs the task PID written to the RISC-V scontext CSR on context switch |
| Verification | QEMU rv-etrace model | SpacemiT K3 SoC — perf record -e gtrace// --per-thread uname produced a 1.946 MB perf.data with decodable branch records |
The 24 Patches, Grouped
Leung's own ordering is the clearest map of the work — four layers, bottom up:
- gtrace core hardening (patches 1–9, 12): connection release moved into component unregister; gtrace sysfs framework; the old single trace-format field dropped in favour of per-event parsing; PMU format attributes;
owner PIDreplaced by aperf_eventpointer insidegtrace_path; port-level start/stop callbacks; sink-specific buffer alloc/free; asetup_sysfs_bufcallback; unified default-sink selection across CPUs. - RISC-V components (10, 11, 12): trace funnel (merges N input ports into one output stream, per the RISC-V Trace Control Interface spec), timestamp component shared by encoder and funnel, and the ATB bridge.
- CoreSight as gtrace citizens (13–20): CoreSight platform core APIs (CLAIM/device registration), dynamic funnel driver (430 lines), and TMC support split across core/ETF/ETR (≈4,050 lines) — derived from the existing CoreSight drivers rather than wrapped.
- perf tooling (21–24): make the
gtracePMU listable inperf list; a Nexus (N-Trace) decoder (rvtrace-ntrace-decoder.c, +910 lines) with its owntools/arch/riscv/include/asm/insn.h; encoder metadata recorded into and parsed out ofperf.data; and an AUX decoder that reconstructs branch samples (gtrace-decoder.c, +1,283).
What the Author Actually Demonstrated
The cover letter carries the usual three-command proof, but with real numbers worth quoting:
# perf list pmu
gtrace// [Kernel PMU event]
# perf record -e gtrace// --per-thread uname
[ perf record: Woken up 1 times to write data ]
[ perf record: Captured and wrote 1.946 MB perf.data ]
# perf script
uname 767863 1 branches: ffffffff80d18b04 gtrace_poll_bit+0x34 ([kernel.kallsyms])
=> ffffffff80d18b12 gtrace_poll_bit+0x42 ([kernel.kallsyms])
uname 767863 1 branches: ffffffff80d18b4e gtrace_poll_bit+0x7e ([kernel.kallsyms])
=> ffffffff80d18b6c gtrace_poll_bit+0x9c ([kernel.kallsyms])
uname 767863 1 branches: ffffffff80d1c17a rvtrace_encoder_start+0x112 ([kernel.kallsyms])
=> ffffffff80d1c196 rvtrace_encoder_start+0x12e ([kernel.kallsyms])
Two things matter here. First, this is instruction-branch tracing on real RISC-V silicon decoded inside stock perf script — the capability RISC-V has been missing against Arm CoreSight. Second, contrast with the October 1 series: that one shipped a stub decoder and pointed at a QEMU model. Here the decoder is in the patch set and the data came off a K3 board.
What Is Still Open
| Item | Status in this RFC |
|---|---|
| Device tree | Follows the Qualcomm gtrace binding posted in August 2026, "with only the compatible properties changed" — i.e. no dedicated RISC-V binding yet |
| Per-CPU task correlation | Requires scontext CSR write on context switch; referenced as a separate patch series, not included |
| Predecessor RFC | The CoreSight-based 14-patch series is explicitly superseded — expect churn if reviewers disagree with the framework move |
| ACPI | Absent. Device tree only, despite gtrace aiming at architecture-neutral deployment |
| Upstream status | RFC, no maintainer tree, no review replies in the archive at publication of this article |
Builder Takeaways
- The strategic signal is the framework, not the driver. Putting CoreSight funnel/TMC inside gtrace is a bid to replace per-ISA trace subsystems with one. If it holds, RISC-V and Arm tracing converge on a single kernel stack — the rare cross-ISA consolidation.
- E-trace silicon now has a working reference path. K3 is a shipping RVA23 SoC; branch-level trace decoded through
perf scripton shipping silicon is a materially stronger validation than a QEMU model. - Budget for two moving parts. The gtrace framework itself may be contested in review, and the series depends on it. Vendors planning trace validation should not assume this lands as-is.
- Context ID is the next blocker for multi-task profiling. Without
scontextwiring, per-cpu trace cannot be attributed to a task — that series is the one to watch next. - Decoders are the moat. +2,100 lines of perf-side decoder work in this RFC versus a 95-line stub previously tells you where RISC-V trace tooling really is: the hardware side is arriving, the analysis side is being written now.
2026 年 10 月 22 日,Zane Leung(liangzhen@linux.spacemit.com)向 linux-riscv 提交了 [RFC PATCH 00/24] Add Linux RISC-V trace support via the gtrace framework。这不是 10 月 1 日那个系列的 v7,而是重写:上一版把 RISC-V 跟踪 IP 硬塞进 CoreSight 的设备模型,这一版把拓扑迁到架构中立的 gtrace 框架上,并把 CoreSight 的部件重新实现为 gtrace 组件,让两者共用同一条跟踪路径。总 diffstat:41 个文件,+10,926 / −180 行。
gtrace 是什么
gtrace(Generic Trace,通用跟踪)位于 drivers/hwtracing/gtrace/,提供每套硬件跟踪实现都需要的公共管道:组件注册、路径创建/销毁、路径启停,以及 perf AUX 缓冲集成 —— 跟踪数据以 PERF_RECORD_AUXTRACE 落到标准 perf AUX 区域。
该设计刻意不绑定 RISC-V,而这正是本次提交的关键:Arm CoreSight 的 funnel 与 TMC 现在也成了 gtrace 组件。目标是用一套内核跟踪框架同时服务两种 ISA,而不是维持两套并行子系统 —— 这也是目前最接近 drivers/hwtracing/coresight/ 继任者/姊妹框架的公开提案。
这一版到底改了什么
| 维度 | 10 月 1 日系列(v6,14 补丁) | 10 月 22 日 RFC(24 补丁) |
|---|---|---|
| 架构取向 | 让 RISC-V 跟踪 IP 服从 CoreSight 设备模型 | 拓扑迁到 gtrace;CoreSight funnel 与 TMC 被重新实现为 gtrace 组件 |
| RISC-V 组件 | 编码器 + RAM sink | 编码器、funnel、ATB bridge、时间戳、RAM sink |
| 配置方式 | 仅设备树 | gtrace sysfs 框架 —— 每组件 control、features、timestamp 属性 |
| 用户态解码 | 95 行桩代码,完整解码列为"后续工作" | 树内 Nexus(N-Trace)解码器 + gtrace AUX 解码器,可合成分支样本(含机器态取指) |
| 数据格式标志 | 格式固化在设备树 compatible 里 | PERF_AUX_FLAG_ 标志,标明 AUX 数据是否带 CoreSight 封装 |
| 每 CPU 任务关联 | 未涉及 | 明确列出依赖:编码器须输出 context ID,需要在上下文切换时把任务 PID 写入 RISC-V scontext CSR |
| 验证环境 | QEMU rv-etrace 模型 | SpacemiT K3 SoC 实机 —— perf record -e gtrace// --per-thread uname 生成 1.946 MB perf.data,分支记录可解码 |
24 个补丁分四层
作者自己的排序就是最清晰的工作地图,自底向上四层:
- gtrace 核心加固(1–9、12):连接释放移入组件注销流程;gtrace sysfs 框架;废弃单一 trace-format 字段,改为按 perf event 解析;新增 PMU 格式属性;
gtrace_path里用perf_event指针替代 owner PID;新增端口级 start/stop 回调;按 sink 类型分配/释放缓冲;setup_sysfs_buf回调;统一各 CPU 的默认 sink 选择。 - RISC-V 组件(10、11、12):跟踪 funnel(按 RISC-V Trace Control Interface 规范把多路输入合并为单路输出)、编码器与 funnel 共用的时间戳组件、ATB bridge。
- CoreSight 变成 gtrace 组件(13–20):CoreSight 平台核心 API(CLAIM/设备注册)、动态 funnel 驱动(430 行)、TMC 拆成 core/ETF/ETR(合计约 4,050 行)—— 是从现有 CoreSight 驱动改写而来,不是外面包一层。
- perf 工具侧(21–24):让
gtracePMU 出现在perf list;新增 Nexus(N-Trace)解码器(rvtrace-ntrace-decoder.c,+910 行)并自带tools/arch/riscv/include/asm/insn.h;把编码器元数据写入并从perf.data解析出来;AUX 解码器重建分支样本(gtrace-decoder.c,+1,283 行)。
作者给出的实测
封面信里照例给了三条命令的证据链,但这次的数字值得直接引用:
# perf list pmu
gtrace// [Kernel PMU event]
# perf record -e gtrace// --per-thread uname
[ perf record: Woken up 1 times to write data ]
[ perf record: Captured and wrote 1.946 MB perf.data ]
# perf script
uname 767863 1 branches: ffffffff80d18b04 gtrace_poll_bit+0x34 ([kernel.kallsyms])
=> ffffffff80d18b12 gtrace_poll_bit+0x42 ([kernel.kallsyms])
uname 767863 1 branches: ffffffff80d18b4e gtrace_poll_bit+0x7e ([kernel.kallsyms])
=> ffffffff80d18b6c gtrace_poll_bit+0x9c ([kernel.kallsyms])
两点值得强调。第一,这是在真实 RISC-V 芯片上做指令级分支跟踪,并在原生 perf script 里解码 —— 正是 RISC-V 相对 Arm CoreSight 长期缺失的能力。第二,与 10 月 1 日那版对比:那版只给桩解码器并指向 QEMU 模型;这次解码器就在补丁集里,数据来自 K3 板子。
仍然没解决的
| 事项 | 本 RFC 中的状态 |
|---|---|
| 设备树绑定 | 沿用 2026 年 8 月 Qualcomm 提交的 gtrace 绑定,"仅改了 compatible 属性"—— 也就是说还没有 RISC-V 专属绑定 |
| 每 CPU 任务关联 | 依赖上下文切换时写 scontext CSR,作为另一个补丁系列被引用,未包含在本系列内 |
| 前序 RFC | 基于 CoreSight 的 14 补丁系列已被明确取代 —— 若评审不认可"迁到 gtrace"这一步,还会有反复 |
| ACPI | 缺失。只有设备树,尽管 gtrace 的目标是架构中立部署 |
| 上游状态 | RFC,无维护者树;截至本文发布,存档中没有评审回复 |
开发者要点
- 战略信号在框架,不在驱动。把 CoreSight funnel/TMC 放进 gtrace,是要用一套框架取代按 ISA 划分的跟踪子系统。若成立,RISC-V 与 Arm 的跟踪将收敛到同一个内核栈 —— 罕见的跨 ISA 整合。
- E-trace 芯片现在有了可跑的参考路径。 K3 是已出货的 RVA23 SoC;在量产芯片上经
perf script解码出分支级跟踪,比 QEMU 模型是强得多的验证。 - 要为两个变量留预算。 gtrace 框架本身可能在评审中受质疑,而本系列依赖它。规划跟踪验证的厂商不宜假设它会原样合入。
- context ID 是下一个多任务剖析的卡点。 没有
scontext打通,per-cpu 跟踪无法归属到具体任务 —— 那是下一个值得盯的系列。 - 解码器才是护城河。 本 RFC 里 perf 侧解码约有 2,100 行新增,而上一版是 95 行桩代码 —— 这精确说明了 RISC-V 跟踪工具链的现状:硬件在到位,分析侧正在被补上。
Краткое содержание (RU)
22 октября 2026 года Zane Leung (SpacemiT) опубликовал RFC из 24 патчей «Add Linux RISC-V trace support via the gtrace framework». Это не v7 серии от 1 октября, а переписывание: вместо подчинения RISC-V трассировки модели CoreSight топология перенесена на архитектурно-нейтральный gtrace, а CoreSight funnel и TMC реализованы как его компоненты. 41 файл, +10 926 / −180 строк: энкодер, funnel, ATB bridge, метки времени, sysfs, PMU и встроенный декодер N-Trace. Проверено на SpacemiT K3 через perf record -e gtrace//. Не слит: это RFC, опубликованный 22 октября 2026.
Resumen (ES)
El 22 de octubre de 2026, Zane Leung (SpacemiT) publicó un RFC de 24 parches titulado «Add Linux RISC-V trace support via the gtrace framework». No es una v7 de la serie del 1 de octubre, sino una reescritura: en lugar de forzar el trazado RISC-V al modelo de dispositivo CoreSight, la topología pasa al marco neutral respecto a la arquitectura gtrace, y el funnel y el TMC de CoreSight se reimplementan como componentes gtrace. 41 archivos, +10 926 / −180 líneas: codificador, funnel, puente ATB, marcas de tiempo, sysfs, PMU y un decodificador N-Trace dentro del árbol. Verificado en un SoC SpacemiT K3 con perf record -e gtrace//. No está fusionado: es un RFC publicado el 22 de octubre de 2026.
Résumé (FR)
Le 22 octobre 2026, Zane Leung (SpacemiT) a publié un RFC de 24 patchs intitulé « Add Linux RISC-V trace support via the gtrace framework ». Ce n'est pas une v7 de la série du 1er octobre mais une réécriture : au lieu de plier le traçage RISC-V au modèle de périphérique CoreSight, la topologie passe au cadriciel gtrace, neutre quant à l'architecture, et le funnel et le TMC de CoreSight y sont réimplémentés comme composants. 41 fichiers, +10 926 / −180 lignes : encodeur, funnel, pont ATB, horodatage, sysfs, PMU et un décodeur N-Trace intégré. Vérifié sur un SoC SpacemiT K3 via perf record -e gtrace//. Non fusionné : RFC publié le 22 octobre 2026.
Kurzfassung (DE)
Am 22. Oktober 2026 veröffentlichte Zane Leung (SpacemiT) einen RFC mit 24 Patches: »Add Linux RISC-V trace support via the gtrace framework«. Es ist kein v7 der Serie vom 1. Oktober, sondern eine Neuimplementierung: Statt das RISC-V-Tracing dem CoreSight-Gerätemodell anzupassen, wandert die Topologie auf das architekturneutrale gtrace-Framework, und CoreSight-Funnel und -TMC werden als gtrace-Komponenten neu umgesetzt. 41 Dateien, +10 926 / −180 Zeilen: Encoder, Funnel, ATB-Bridge, Zeitstempel, sysfs, PMU und ein In-Tree-N-Trace-Decoder. Verifiziert auf einem SpacemiT-K3-SoC mit perf record -e gtrace//. Nicht gemerged — ein RFC vom 22. Oktober 2026.
خلاصه (FA)
در ۲۲ اکتبر ۲۰۲۶، Zane Leung از SpacemiT یک RFC ۲۴ پچی با عنوان «Add Linux RISC-V trace support via the gtrace framework» منتشر کرد. این نسخهٔ هفتم سری اول اکتبر نیست، بلکه بازنویسی است: بهجای تحمیل مدل دستگاه CoreSight به ردیابی RISC-V، توپولوژی به چارچوب مستقل از معماری gtrace منتقل شده و funnel و TMC کورسایت بهصورت مؤلفههای gtrace بازپیادهسازی شدهاند. ۴۱ فایل، +۱۰٬۹۲۶ / −۱۸۰ خط: رمزگذار، funnel، پل ATB، مهر زمانی، sysfs، PMU و رمزگشای N-Trace دروندرختی. آزمون روی SoC مدل SpacemiT K3 با perf record -e gtrace//. ادغام نشده؛ RFC منتشرشده در ۲۲ اکتبر ۲۰۲۶.
Sources / 参考来源
- linux-riscv archive — Zane Leung, "[RFC PATCH 00/24] Add Linux RISC-V trace support via the gtrace framework", Thu Oct 22 2026 20:14:41 PDT (cover letter: full patch list, diffstat, K3 perf transcript)
- linux-riscv archive — "[PATCH 10/24] gtrace: Add RISC-V trace funnel driver" (funnel driver source, Trace Control Interface reference)
- linux-riscv archive — "[PATCH 11/24] gtrace: Add RISC-V trace timestamp support"
- LKML archive — Mayuresh Chitale, "[PATCH v6 00/14] Linux RISC-V trace framework and drivers", Thu Oct 01 2026 (the superseded CoreSight-based series)
- RISC-V E-trace encapsulation specification — v1.0.0-ratified release
- RISC-V TG Nexus trace specification — 1.0 Ratified release