zx_sampler_create

Summary

Create a sampler session, returning an IOBuffer containing a buffer allocated for each active cpu.

Declaration

#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);

Description

zx_sampler_create() initializes a global singleton thread sampler which writes samples to the returned IOBuffer. The returned iobuffer will have a number of regions equal to the active number of cpus on the system when called. Each buffer is of the size declared in config.

The parameter options must be 0.

The parameter config must be a zx_sampler_config_t.

Config

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;

The caller may request the samples be written to the returned IOBuffer using an agreed upon iobuffer discipline. Currently, there is a single supported discipline ZX_IOB_DISCIPLINE_NONE (0) which works as follows:

After threads are attached and sampling is started, each cpu will write samples to the dedicated region. Samples will continue to be written to the buffer until either sampling stops or the buffer becomes full.

Samples are read by reading a thread's PC and attempting to walk the thread's backtrace by following frame pointers.

Samples are written as 8 bytes aligned FXT Large Blob with Metadata records where the payload contains the PCs sampled from the thread's stack. An FXT Header of 0 indicates that there is no additional data.

To safely read the data from the buffer, a read should first call zx_sampler_stop which will stop the session and return when no additional samples will be written. A reader may then map each region of the IOBuffer with zx_vmar_map_iob and access the samples.

Controlling the Session

The sampler is a global singleton and there is at most one session active at a time. The session can be controlled by passing the returned IOBuffer to the start/stop/attach calls. When the returned IOBuffer's last handle is closed the session will stop and be destroyed.

Rights

debug_resource must have resource kind ZX_RSRC_KIND_SYSTEM with base ZX_RSRC_SYSTEM_DEBUG_BASE.

Errors

ZX_ERR_NOT_SUPPORTED kernel.enable-debugging-syscalls is not set to true on the kernel command line or the experimental_thread_sampler_enabled build param is not set to true.

ZX_ERR_PERMISION_DENIED rsrc is not resource kind ZX_RSRC_KIND_SYSTEM with base ZX_RSRC_SYSTEM_DEBUG_BASE.

ZX_ERR_INVALID_ARGS - options is not 0 - The provided config is invalid. See zx_sampler_config_t for the expected config.

See also