tracing

＃将跟踪添加到设备驱动程序

本文档介绍如何向设备驱动程序添加跟踪。

##概述

请阅读[Fuchsia追踪系统设计]（../tracing/design.md）
有关跟踪的概述。

##跟踪提供者

驱动程序不必指定跟踪提供程序，devhost进程通过`libdriver.so`提供它。这里提到它是为引入主题。

##添加跟踪记录

###来源添加

通过调用`TRACE_*()`宏（`ddk/trace/event.h`），最容易添加跟踪记录。

可以发出各种跟踪记录。
有关说明，请参阅`trace/internal/event_common.h`中各种宏定义。

从内部实现文件中查找宏相关文档是暂时的情况。最终这样的文档将存在于一个更合适的地方。

例：

```c++
#include

void DoSomething(int a, std::string b) {
  TRACE_DURATION("example:example1", "DoSomething", "a", a, "b", b);

  // Do something
}
```

大多数宏的前两个参数是“类别”和事件名称。这里它们分别是“example：example1”和“DoSomething”。

跟踪类别是跟踪系统允许用户指定要收集哪些数据。如果用户未请求类别，那么将不收集任何数据。

类别不需要在驱动程序中是唯一的。
通常将一些事件分组在同一类别下。
按照惯例，类别具有格式
“:[:...]”。
驱动程序的“”通常应该是驱动程序名称。
这样做是为了避免整个系统跨类别名称的冲突。对此约定的潜在补充是所有的驱动程序类别都带上前缀“driver：”。例如，“driver：ethernet：packets”。
避免与其他跟踪提供者的命名冲突很重要，否则用户可能会请求特定类别，却获得来自不同跟踪提供者的完全不相关的数据。

包含在跟踪中的事件名称描述事件的具体内容。它通常对每个事件都是唯一的。

### Makefile添加

为了实现追踪支持，需要在驱动程序的`rules.mk`文件中添加以下内容：

```make
MODULE_STATIC_LIBS += system/ulib/trace.driver
MODULE_HEADER_DEPS += system/ulib/trace system/ulib/trace-engine
```

##使用跟踪引导

为保守起见，跟踪使用内核命令行标志来启用它：
`driver.tracing.enable = 1`。
`driver.tracing.enable = 1`是默认值。
用`driver.tracing.enable = 0`启动内核，可以禁止驱动程序在Fuchsia跟踪中的参与。

例：

第一次构建：

```sh
$ fx set $arch
$ fx build-zircon
$ fx build
```

然后启动QEMU：

```sh
$ fx run -k -N
```

或者在h/w上（增加特定于你的h/w的选项）：

```sh
$ fx serve
```

一旦跟踪支持稳定，这些额外要求将被删除。

##使用跟踪

系统启动后，您可以在目标上收集跟踪然后手动将它们复制到开发主机。
这些示例使用上述源添加中的类别。

例：

```sh
fuchsia$ trace record --categories=example:example1
host$ fx cp --to-host /data/trace.json trace.json
```

但是，在主机开发中调用`traceutil`程序更容易，它会将文件直接复制到您的主机并可以使用Chrome跟踪查看器查看。

```sh
host$ fx traceutil record --categories=example:example1
```

请参阅[跟踪使用指南]（https://fuchsia.googlesource.com/fuchsia/+/master/garnet/docs/tracing_usage_guide.md)
了解更多信息。