zx_sampler_create

摘要

创建一个采样器会话，返回一个 IOBuffer，其中包含为每个采样器分配的缓冲区 活跃 CPU

声明

#include <zircon/syscalls.h>

zx_status_t zx_sampler_create(zx_resource_t rsrc
                              uint64_t options,
                              zx_sampler_config_t* config,
                              size_t config_size;
                              zx_handle_t* iob_out);

说明

zx_sampler_create() 会初始化一个全局单例线程采样器，该采样器由 将样本写入返回的 IOBuffer。返回的 iobuffer 将有 等于系统上活跃 CPU 数量的区域数 调用时。每个缓冲区的大小都是 config 中声明的大小。

参数 options 必须为 0。

参数 config 必须是 zx_sampler_config_t。

配置

typedef struct {
    // How long an individual cpu core will wait in nanoseconds between
    // taking each sample. The minimum period is ZX_SAMPLER_MIN_PERIOD (10000ns).
    zx_duration_t period;

    // The requested size of the region in bytes. The size will be
    // rounded up to the next system page size boundary, as reported by
    // zx_system_get_page_size(). Use `zx_object_get_info` with topic
    // `ZX_INFO_IOB_REGIONS` on the returned handle to determine the
    // actual size of each region.
    size_t buffer_size;

    // The requested discipline of the returned iobuffer. See below for
    // valid disciplines.
    uint64_t iobuffer_discipline;
} zx_sampler_config_t;

调用方可以请求将样本写入返回的 IOBuffer 使用商定的 iobuffer 规则。目前，有一个 支持的学科ZX_IOB_DISCIPLINE_NONE (0)， 如下：

连接线程并开始采样后，每个 CPU 将写入 部署到专用区域样本将继续写入 缓冲区，直到采样停止或缓冲区填满。

通过读取线程的 PC 并尝试遍历 跟踪线程的回溯

样本以 8 个字节对齐的 FXT Large Blob with Metadata 的形式写入 记录，其中载荷包含从线程的 堆栈。FXT 标头为 0 表示没有其他数据。

要安全地从缓冲区读取数据，读取操作应首先调用 zx_sampler_stop，这将停止会话，并在没有 将编写更多示例。然后，读取者可以在地图上 使用 zx_vmar_map_iob 访问 IOBuffer，并访问示例。

控制会话

采样器是一个全局单例，并且最多只有一个会话 同时处于活动状态。会话可以通过传递返回的 IOBuffer 应用于启动/停止/附加调用。当返回的 IOBuffer 的 关闭最后一个句柄，则会话将停止并销毁。

权限

debug_resource 必须有基本的资源种类 ZX_RSRC_KIND_SYSTEM ZX_RSRC_SYSTEM_DEBUG_BASE。

错误

ZX_ERR_NOT_SUPPORTED kernel.enable-debugging-syscalls 未设置为 true （在内核命令行或 experiment_thread_sampler_enabled 下） build 参数未设为 true。

ZX_ERR_PERMISION_DENIED rsrc 不是资源种类 采用基本 ZX_RSRC_SYSTEM_DEBUG_BASE 的 ZX_RSRC_KIND_SYSTEM。

ZX_ERR_INVALID_ARGS - options 不为 0 - 提供的配置无效。请参阅 预期配置：zx_sampler_config_t。

另请参阅