Google is committed to advancing racial equity for Black communities. See how.

fuchsia.hardware.cpu.insntrace

PROTOCOLS

Controller

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

AllocateBuffer

Allocate a trace buffer. When tracing cpus, buffers are auto-assigned to cpus: the resulting trace buffer descriptor is the number of the cpu using the buffer.

Request

NameType
config BufferConfig

Response

NameType
result Controller_AllocateBuffer_Result

AssignThreadBuffer

Assign a buffer to a thread.

Request

NameType
descriptor BufferDescriptor
thread handle<thread>

Response

NameType
result Controller_AssignThreadBuffer_Result

FreeBuffer

Free a previously allocated trace buffer.

Request

NameType
descriptor BufferDescriptor

Response

NameType

GetAllocation

Return the trace allocation configuration.

Request

NameType

Response

NameType
allocation Allocation?

GetBufferConfig

Fetch a buffer's configuration.

Request

NameType
descriptor BufferDescriptor

Response

NameType
config BufferConfig?

GetBufferState

Fetch runtime information about a buffer.

Request

NameType
descriptor BufferDescriptor

Response

NameType
state BufferState?

GetChunkHandle

Fetch the handle of a chunk of a trace buffer.

Request

NameType
descriptor BufferDescriptor
chunk_num uint32

Response

NameType
buffer handle<vmo>?

Initialize

Initialize the trace. This does not include allocating space for the trace buffers, that is done later by AllocateBuffer().

Request

NameType
allocation Allocation

Response

NameType
result Controller_Initialize_Result

ReleaseThreadBuffer

Release a previously assigned buffer from a thread.

Request

NameType
descriptor BufferDescriptor
thread handle<thread>

Response

NameType
result Controller_ReleaseThreadBuffer_Result

Start

Start tracing. Must be called after Initialize() + AllocateBuffer(), with tracing off.

Request

NameType

Response

NameType

Stop

Stop tracing. May be called any time after Allocate() has been called and before Free(). If called at other times the call is ignored. May be called multiple times.

Request

NameType

Response

NameType

Terminate

Free all trace buffers and any other resources allocated for the trace. This is also done when the connection is closed (as well as stopping the trace). May be called multiple times. This can only fail when tracing in THREAD mode where tracing is terminated differently, in which case the error is ZX_ERR_BAD_STATE.

Request

NameType

Response

NameType
result Controller_Terminate_Result

STRUCTS

AddressRange

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

An address range, as [start,end].

NameTypeDescriptionDefault
start uint64 No default
end uint64 No default

Allocation

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

The allocation configuration of a trace.

NameTypeDescriptionDefault
mode Mode No default
num_traces uint16 No default

BufferConfig

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

A buffer's configuration.

NameTypeDescriptionDefault
num_chunks uint32

A "buffer" is made up of num_chunks chunks with each chunk having size 1<<chunk_order pages.

No default
chunk_order uint32

log2 of the number of pages

No default
is_circular bool

If true then use circular buffering.

No default
ctl uint64

The value of the control register.

No default
address_space_match uint64

If non-zero then the address space of the instruction must match in order for the instruction to be traced. On x86 architectures the address space is specified by CR3.

No default
address_range_0 AddressRange

If non-zero, tracing is restricted to these address ranges. TODO(dje): There's only two, and vectors don't currently work here, so spell these out individually

No default
address_range_1 AddressRange No default

BufferState

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

A buffer's runtime state.

NameTypeDescriptionDefault
capture_end uint64

This is the offset in the buffer where tracing stopped (treating all buffers as one large one). If using a circular buffer then all of the buffer may contain data, there's no current way to know if tracing wrapped without scanning records.

No default

Controller_AllocateBuffer_Response

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

NameTypeDescriptionDefault
descriptor BufferDescriptor No default

Controller_AssignThreadBuffer_Response

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

NameTypeDescriptionDefault

Controller_Initialize_Response

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

NameTypeDescriptionDefault

Controller_ReleaseThreadBuffer_Response

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

NameTypeDescriptionDefault

Controller_Terminate_Response

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

NameTypeDescriptionDefault

ENUMS

Mode

Type: uint8

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

Tracing modes

NameValueDescription
CPU 0
THREAD 1

UNIONS

Controller_AllocateBuffer_Result

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

NameTypeDescription
response Controller_AllocateBuffer_Response
err zx/status

Controller_AssignThreadBuffer_Result

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

NameTypeDescription
response Controller_AssignThreadBuffer_Response
err zx/status

Controller_Initialize_Result

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

NameTypeDescription
response Controller_Initialize_Response
err zx/status

Controller_ReleaseThreadBuffer_Result

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

NameTypeDescription
response Controller_ReleaseThreadBuffer_Response
err zx/status

Controller_Terminate_Result

Defined in fuchsia.hardware.cpu.insntrace/insntrace.fidl

NameTypeDescription
response Controller_Terminate_Response
err zx/status

CONSTANTS

NameValueTypeDescription
API_VERSION 0 uint16
MAX_NUM_ADDR_RANGES 2 uint16

The maximum number of supported address ranges.

MAX_NUM_TRACES 64 uint16

The maximum number of traces that can be collected at once. A "trace" is the instruction stream for one entity, cpu or thread.

TYPE ALIASES

NameValueDescription
BufferDescriptor uint32