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_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 傳遞至開始/停止/附加呼叫，藉此控制工作階段。當傳回的 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 建構參數未設為 true。

ZX_ERR_PERMISION_DENIED rsrc 不是資源種類， ZX_RSRC_KIND_SYSTEM 且以 ZX_RSRC_SYSTEM_DEBUG_BASE 為基礎。

ZX_ERR_INVALID_ARGS - options 不是 0 - 提供的 config 無效。如需預期設定，請參閱 zx_sampler_config_t。

另請參閱