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 数量相等的区域数量。每个缓冲区的大小都与配置中声明的大小相同。

参数 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_mono_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 记录写入，其中载荷包含从线程堆栈中抽样的 PC。FXT 标头为 0 表示没有其他数据。

为了安全地从缓冲区读取数据，读取操作应先调用 zx_sampler_stop，该函数会停止会话，并在没有其他样本要写入时返回。然后，读取器可以使用 zx_vmar_map_iob 映射 IOBuffer 的每个区域，并访问样本。

控制会话

抽样器是一个全局单例，一次最多只能有一个会话处于活动状态。通过将返回的 IOBuffer 传递给 start/stop/attach 调用，可以控制会话。当返回的 IOBuffer 的最后一个句柄关闭时，会话将停止并被销毁。

权限

debug_resource 必须具有资源种类 ZX_RSRC_KIND_SYSTEM，且基准为 ZX_RSRC_SYSTEM_DEBUG_BASE。

错误

ZX_ERR_NOT_SUPPORTED kernel.enable-debugging-syscalls 未在内核命令行中设置为 true，或者 experimental_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 - 提供的 config 无效。如需了解预期配置，请参阅 zx_sampler_config_t。

另请参阅