| # Fuchsia trace format |
| |
| This document describes the binary format used to collect, store, and |
| transmit Fuchsia trace records. |
| You can use this document to search for detailed information |
| about each field in the Fuchsia trace format. |
| |
| Note: For information about the Fuchsia tracing system, |
| see [Fuchsia tracing system](/docs/concepts/kernel/tracing-system.md). |
| |
| ## Overview |
| |
| While a trace is running, trace providers write records into a trace buffer |
| VMO shared with the trace manager using the binary format described in this |
| document. |
| |
| The binary format is designed to introduce minimal impact upon the |
| performance of the subject under trace while writing traces. The records |
| are also written sequentially so that if a trace terminates (normally or |
| abnormally), the trace manager can still recover partial trace data already |
| stored in the trace buffer by reading everything up to the last well-formed |
| record. |
| |
| As the trace progresses, the trace manager aggregates records from all |
| trace providers participating in trace collection, and concatenates |
| them together with some special metadata records to form a trace archive. |
| |
| Once the trace completes, tools such as the `trace` command-line program |
| can read the trace records within the trace archive to visualize the results |
| or save them to a file for later consumption. |
| |
| ## Features |
| |
| - Small footprint |
| - Trace records are compact, packing information into a small number of bits. |
| - Pooling strings, processes, and threads further compacts the trace data. |
| - Memory aligned |
| - Trace records maintain an 8 byte alignment in memory to facilitate |
| writing them directly into memory mapped VMOs. |
| - Variable size records |
| - Overall record size is limited to 32 KB. |
| - Large objects may need to be broken up into multiple records. |
| - Extensible |
| - There's room to define new record types as needed. |
| - Unrecognized or malformed trace records can be skipped. |
| |
| ## Encoding primitives {#encoding-primitives} |
| |
| The Fuchsia trace format has the following encoding primitives: |
| |
| * [Atoms](#atoms) |
| * [Records](#records) |
| * [Archives](#archives) |
| * [Timestamps](#timestamps) |
| * [String references](#string-references) |
| * [Thread references](#thread-references) |
| * [Userspace object information](#userspace-object-information) |
| * [Kernel object information](#kernel-object-information) |
| * [Arguments](#arguments) |
| |
| ### Atoms {#atoms} |
| |
| Each record is constructed as a sequence of atoms. |
| |
| Each atom is written with 8 byte alignment and has a size that is also a |
| multiple of 8 bytes so as to preserve alignment. |
| |
| There are two kinds of atoms: |
| |
| - **Word**: A 64-bit value that may be further subdivided into bit fields. |
| Words are stored in machine word order (little-endian on all currently |
| supported architectures). |
| - **Stream**: A sequence of bytes padded with zeros to the next 8 byte |
| boundary. Streams are stored in byte order. Streams that are an exact |
| multiple of 8 bytes long are not padded (there is no zero terminator). |
| |
| **Fields** are subdivisions of 64-bit **Words**, denoted |
| `[<least significant bit> .. <most significant bit>]` where the first and |
| last bit positions are inclusive. All unused bits are reserved for future |
| use and must be set to 0. |
| |
| **Words** and **Fields** store unsigned integers unless otherwise specified |
| by the record format. |
| |
| **Streams** may store either UTF-8 strings or binary data, as specified by |
| the record format. |
| |
| ### Records {#records} |
| |
| A trace record is a binary encoded piece of trace information consisting of |
| a sequence of [atoms](#atoms). |
| |
| All records include a header word that contains the following basic |
| information: |
| |
| - **Record type**: A 4-bit field that identifies the type of the record |
| and the information it contains. See [Record Types](#record_types). |
| - **Record size**: Typically, a 12-bit field that indicates the number of words |
| (multiples of 8 byte units) within the record _including the record |
| header itself_. The maximum possible size of a record is 4095 words |
| (32760 bytes). Very simple records may be just 1 word (8 bytes) long. |
| Large records use a 32-bit size field and therefore have a higher |
| maximum size. |
| |
| Records are always a multiple of 8 bytes in length and are stored with |
| 8 byte alignment. |
| |
| ### Archives {#archives} |
| |
| A trace archive is a sequence of trace records, concatenated end to end, |
| which stores information collected by trace providers while a trace is |
| running together with metadata records that identify and delimit sections |
| of the trace produced by each trace provider. |
| |
| Trace archives are intended to be read sequentially since records that |
| appear earlier in the trace may influence the interpretation of records |
| which appear later in the trace. The trace system provides tools for |
| extracting information from trace archives and converting it into other |
| forms for visualization. |
| |
| ### Timestamps {#timestamps} |
| |
| Timestamps are represented as 64-bit ticks derived from a hardware counter. |
| The trace initialization record describes the number of ticks per second |
| of real time. |
| |
| By default, we assume that 1 tick equals 1 nanosecond. |
| |
| ### String references {#string-references} |
| |
| Strings are encoded as **String Refs** which are 16-bit values of the |
| following form: |
| |
| - **Empty strings**: Value is zero. |
| - **Indexed strings**: Most significant bit is zero. The lower 15 bits |
| denote an index in the **string table** which was previously assigned using a |
| **String record**. |
| - **Inline strings**: Most significant bit is one. The lower 15 bits |
| denote the length of the string in bytes. The string's content appears |
| inline in another part of the record as specified by the record format. |
| |
| To make traces more compact, frequently referenced strings, such as event |
| category and name constants, should be registered into the **string table** |
| using **string records** then referenced by index. |
| |
| There can be at most 32767 strings in the string table. If this limit is |
| reached, additional strings can be encoded by replacing existing entries |
| or by encoding strings inline. |
| |
| String content itself is stored as a UTF-8 **stream** without termination. |
| |
| The theoretical maximum length of a string is 32767 bytes but in practice this |
| will be further reduced by the space required to store the rest of the record |
| which contains it, so we set a conservative maximum string length limit of |
| 32000 bytes. |
| |
| ### Thread references {#thread-references} |
| |
| Thread and process kernel object ids (koids) are encoded as **thread refs** |
| which are 8-bit values of the following form: |
| |
| - **Inline threads**: Value is zero. The thread and process koid appears |
| inline in another part of the record as specified by the record format. |
| - **Indexed threads**: Value is non-zero. The value denotes an index in |
| the **thread table** which was previously assigned using a **thread record**. |
| |
| To make traces more compact, frequently referenced threads should be registered |
| into the **thread table** using **thread records** then referenced by index. |
| |
| There can be at most 255 threads in the string table. If this limit is |
| reached, additional threads can be encoded by replacing existing entries |
| or by encoding threads inline. |
| |
| ### Userspace object information {#userspace-object-information} |
| |
| Traces can include annotations about userspace objects (anything that can be |
| referenced using a pointer-like value such as a C++ or Dart object) in the |
| form of **userspace object records**. Trace providers typically generate |
| such records when the object is created. |
| |
| Thereafter, any **pointer arguments** which refer to the same pointer will |
| be associated with the referent's annotations. |
| |
| This makes it easy to associate human-readable labels and other information |
| with objects that appear later in the trace. |
| |
| ### Kernel object information {#kernel-object-information} |
| |
| Traces can include annotations about kernel objects (anything that can be |
| referenced using a Zircon koid such as a process, channel, or event) |
| form of **kernel object records**. Trace providers typically generate such |
| records when the object is created. |
| |
| Thereafter, any **kernel object Id arguments** which refer to the same koid will |
| be associated with the referent's annotations. |
| |
| This makes it easy to associate human-readable labels and other information |
| with objects that appear later in the trace. |
| |
| In particular, this is how the tracing system associates names with process |
| and thread koids. |
| |
| ### Arguments {#arguments} |
| |
| Arguments are typed key value pairs. |
| |
| Many record types allow up to 15 arguments to be appended to the record to |
| provide additional information from the developer. |
| |
| Arguments are size-prefixed like ordinary records so that unrecognized |
| argument types can be skipped. |
| |
| For more information, see [Argument Types](#argument-types). |
| |
| ## Extend the format {#extend-the-format} |
| |
| The trace format can be extended in the following ways: |
| |
| Note: To preserve compatibility as the trace format evolves, all extensions must be |
| documented authoritatively in this file. Currently there is no support for |
| private extensions. |
| |
| - Defining new record types. |
| - Storing new information in reserved fields of existing record types. |
| - Appending new information to existing record types (the presence of this |
| information can be detected by examining the record's size and payload). |
| - Defining new argument types. |
| |
| ## Record Types |
| |
| There are the following record types: |
| |
| Note: In the record format descriptions, each constituent atom is labeled in italics |
| followed by a bullet-point description of its contents. |
| |
| * [Record header](#record-header) |
| * [Large record header](#large-record-header) |
| * [Metadata record (record type = 0)](#metadata-record) |
| * [Initialization record (record type = 1)](#initialization-record) |
| * [String record (record type = 2)](#string-record) |
| * [Thread record (record type = 3)](#thread-record) |
| * [Event record (record type = 4)](#event-record) |
| * [Blob record (record type = 5)](#blob-record) |
| * [Userspace object record (record type = 6)](#userspace-object-record) |
| * [Kernel object record (record type = 7)](#kernel-object-record) |
| * [Scheduling record (record type = 8)](#scheduling-record) |
| * [Log record (record type = 9)](#log-record) |
| * [Large BLOB record (record type = 15, large type = 0)](#large-blob-record) |
| |
| ### Record header {#record-header} |
| |
| All records include this header that specifies the record's type and size |
| together with 48 bits of data whose usage varies by record type. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/record.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 63]`: varies by record type (must be zero if unused) |
| |
| ### Large record header {#large-record-header} |
| |
| Provides support for records larger than 32KB. Large records have a |
| 32 bit size field rather than the normal 12 bits. |
| |
| ![drawing](images/trace-format/largerecord.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (15) |
| - `[4 .. 35]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[36 .. 39]`: large record type |
| - `[40 .. 63]`: varies by large record type (must be zero if unused) |
| |
| ### Metadata record (record type = 0) {#metadata-record} |
| |
| Provides metadata about trace data that follows. |
| |
| This record type is reserved for use by the _trace manager_ when generating |
| trace archives. It must not be emitted by trace providers themselves. |
| If the trace manager encounters a **metadata record** within a trace produced |
| by a trace provider, it treats it as garbage and skips over it. |
| |
| There are several metadata record subtypes, each of which contain different |
| information. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/metadata.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (0) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 19]`: metadata type |
| - `[20 .. 63]`: varies by metadata type (must be zero if unused) |
| |
| #### Provider info metadata (metadata type = 1) {#provider-info-metadata} |
| |
| This metadata identifies a trace provider that has contributed information to |
| the trace. |
| |
| All data that follows until the next **provider section metadata** or |
| **provider info metadata** is encountered must have been collected from the |
| same provider. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/metadata1.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (0) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 19]`: metadata type (1) |
| - `[20 .. 51]`: provider id (token used to identify the provider in the trace) |
| - `[52 .. 59]`: name length in bytes |
| - `[60 .. 63]`: reserved (must be zero) |
| |
| _provider name stream_ |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| #### Provider section metadata (metadata type = 2) {#provider-section-metadata} |
| |
| This metadata delimits sections of the trace that have been obtained from |
| different providers. |
| |
| All data that follows until the next **provider section metadata** or |
| **provider info metadata** is encountered is assumed to have been collected |
| from the same provider. |
| |
| When reading a trace consisting of an accumulation of traces from different |
| trace providers, the reader must maintain state separately for each provider's |
| traces (such as the initialization data, string table, thread table, |
| userspace object table, and kernel object table) and switch contexts |
| whenever it encounters a new **provider section metadata** record. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/metadata2.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (0) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 19]`: metadata type (2) |
| - `[20 .. 51]`: provider id (token used to identify the provider in the trace) |
| - `[52 .. 63]`: reserved (must be zero) |
| |
| #### Provider event metadata (metadata type = 3) {#provider-event-metadata} |
| |
| This metadata provides running notification of events that the provider |
| wants to report. |
| |
| This record may appear anywhere in the output, and does not delimit what |
| came before it or what comes after it. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/metadata3.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (0) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 19]`: metadata type (3) |
| - `[20 .. 51]`: provider id (token used to identify the provider in the trace) |
| - `[52 .. 55]`: the event id |
| - `[56 .. 63]`: reserved (must be zero) |
| |
| ##### Events |
| |
| The following events are defined. |
| |
| - `0`: a buffer filled up, records were likely dropped |
| |
| #### Trace info metadata (metadata type = 4) {#trace-info-metadata} |
| |
| This metadata provides information about the trace as a whole. This record is |
| not associated with a particular provider. |
| |
| ##### Format |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (0) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 19]`: metadata type (4) |
| - `[20 .. 23]`: trace info type |
| - `[24 .. 63]`: varies by trace info type (must be zero if unused) |
| |
| #### Magic number record (trace info type = 0) {#magic-number-record} |
| |
| This record serves as an indicator that the binary data is in the Fuchsia |
| tracing format. Generally it should appear at the start of a trace. It carries |
| no other information. The magic number `0x16547846` is the string "FxT" |
| followed by a byte that was chosen at random. |
| |
| To allow the first eight bytes of a trace to be treated together as a magic |
| number without caring about the internal record structure, this record type is |
| _not_ extensible. The record must not contain any words other than the header |
| word, and there are no reserved fields. As an eight byte number, the entire |
| record has the value 0x0016547846040010. |
| |
| Note that the byte order of that value, and all other words in the trace, |
| depends on the endianness of the system that wrote the trace. For a little |
| endian system, the first eight bytes are 10 00 04 46 78 54 16 00. On a big |
| endian system, it will be the reverse: 00 16 54 78 46 04 00 10. |
| |
| ##### Format |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (0) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes (1) |
| - `[16 .. 19]`: metadata type (4) |
| - `[20 .. 23]`: trace info type (0) |
| - `[24 .. 55]`: the magic number 0x16547846 |
| - `[56 .. 63]`: zero |
| |
| ### Initialization record (record type = 1) {#initialization-record} |
| |
| Provides parameters needed to interpret the records that follow. In absence |
| of this record, the reader may assume that 1 tick is 1 nanosecond. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/initialization.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (1) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 63]`: reserved (must be zero) |
| |
| _tick multiplier word_ |
| |
| - `[0 .. 63]`: number of ticks per second |
| |
| ### String record (record type = 2) {#string-record} |
| |
| Registers a string in the string table, assigning it a string index in the |
| range `0x0001` to `0x7fff`. The registration replaces any prior registration |
| for the given string index when interpreting the records that follow. |
| |
| String records that attempt to set a value for string index `0x0000` must be |
| ignored since this value is reserved to represent the empty string. |
| |
| String records that contain empty strings must be tolerated but they're |
| pointless since the empty string can simply be encoded as zero in a string ref. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/string.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (2) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 30]`: string index (range 0x0001 to 0x7fff) |
| - `[31]`: always zero (0) |
| - `[32 .. 46]`: string length in bytes (range 0x0000 to 0x7fff) |
| - `[47]`: always zero (0) |
| - `[48 .. 63]`: reserved (must be zero) |
| |
| _string value stream_ |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| ### Thread record (record type = 3) {#thread-record} |
| |
| Registers a process id and thread id pair in the thread table, assigning it a |
| thread index in the range `0x01` to `0xff`. The registration replaces any |
| prior registration for the given thread index when interpreting the records |
| which follow. |
| |
| Thread index `0x00` is reserved to denote the use of an inline thread id in |
| a thread ref. Thread records that attempt to set a value for this value |
| must be ignored. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/thread.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (3) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 23]`: thread index (never 0x00) |
| - `[24 .. 63]`: reserved (must be zero) |
| |
| _process id word_ |
| |
| - `[0 .. 63]`: process koid (kernel object id) |
| |
| _thread id word_ |
| |
| - `[0 .. 63]`: thread koid (kernel object id) |
| |
| ### Event record (record type = 4) {#event-record} |
| |
| Describes a timestamped event. |
| |
| This record consists of some basic information about the event including |
| when and where it happened followed by event arguments and event subtype |
| specific data. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (4) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 19]`: event type |
| - `[20 .. 23]`: number of arguments |
| - `[24 .. 31]`: thread (thread ref) |
| - `[32 .. 47]`: category (string ref) |
| - `[48 .. 63]`: name (string ref) |
| |
| _timestamp word_ |
| |
| - `[0 .. 63]`: number of ticks |
| |
| _process id word_ (omitted unless thread ref denotes inline thread) |
| |
| - `[0 .. 63]`: process koid (kernel object id) |
| |
| _thread id word_ (omitted unless thread ref denotes inline thread) |
| |
| - `[0 .. 63]`: thread koid (kernel object id) |
| |
| _category stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _argument data_ (repeats for each argument) |
| |
| - (see below) |
| |
| _event-type specific data_ |
| |
| - Can be any of the following: |
| - [Instant event (event type = 0)](#instant-event) |
| - [Counter event (event type = 1)](#counter-event) |
| - [Duration begin event (event type = 2)](#duration-begin-event) |
| - [Duration end event (event type = 3)](#duration-end-event) |
| - [Duration complete event (event type = 4)](#duration-complete-event) |
| - [Async begin event (event type = 5)](#async-begin-event) |
| - [Async instant event (event type = 6)](#async-instant-event) |
| - [Async end event (event type = 7)](#async-end-event) |
| - [Flow begin event (event type = 8)](#flow-begin-event) |
| - [Flow step event (event type = 9)](#flow-step-event) |
| - [Flow end event (event type = 10)](#flow-end-event) |
| |
| #### Instant event (event type = 0) {#instant-event} |
| |
| Marks a moment in time on this thread. These are equivalent to Zircon |
| kernel probes. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event0.png) |
| |
| No event-type specific data required. |
| |
| #### Counter event (event type = 1) {#counter-event} |
| |
| Records sample values of each argument as data in a time series associated |
| with the counter's name and id. The values may be presented graphically as a |
| stacked area chart. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event1.png) |
| |
| _counter word_ |
| |
| - `[0 .. 63]`: counter id |
| |
| #### Duration begin event (event type = 2) {#duration-begin-event} |
| |
| Marks the beginning of an operation on a particular thread. Must be matched |
| by a **duration end event**. May be nested. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event23.png) |
| |
| No event-type specific data required. |
| |
| #### Duration end event (event type = 3) {#duration-end-event} |
| |
| Marks the end of an operation on a particular thread. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event23.png) |
| |
| No event-type specific data required. |
| |
| #### Duration complete event (event type = 4) {#duration-complete-event} |
| |
| Marks the beginning and end of an operation on a particular thread. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event4.png) |
| |
| _end time word_ |
| |
| - `[0 .. 63]`: end time number of ticks |
| |
| #### Async begin event (event type = 5) {#async-begin-event} |
| |
| Marks the beginning of an operation that may span threads. Must be matched |
| by an **async end event** using the same async correlation id. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event567.png) |
| |
| _async correlation word_ |
| |
| - `[0 .. 63]`: async correlation id |
| |
| #### Async instant Event (event type = 6) {#async-instant-event} |
| |
| Marks a moment within an operation that may span threads. Must appear |
| between **async begin event** and **async end event** using the same async |
| correlation id. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event567.png) |
| |
| _async correlation word_ |
| |
| - `[0 .. 63]`: async correlation id |
| |
| #### Async end event (event type = 7) {#async-end-event} |
| |
| Marks the end of an operation that may span threads. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event567.png) |
| |
| _async correlation word_ |
| |
| - `[0 .. 63]`: async correlation id |
| |
| #### Flow begin event (event type = 8) {#flow-begin-event} |
| |
| Marks the beginning of an operation, which results in a sequence of actions |
| that may span multiple threads or abstraction layers. Must be matched by a |
| **flow end event** using the same flow correlation id. This can be envisioned |
| as an arrow between duration events. |
| |
| The beginning of the flow is associated with the enclosing duration event |
| for this thread; it begins where the enclosing **duration event** ends. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event8910.png) |
| |
| _flow correlation word_ |
| |
| - `[0 .. 63]`: flow correlation id |
| |
| #### Flow step event (event type = 9) {#flow-step-event} |
| |
| Marks a point within a flow. |
| |
| The step is associated with the enclosing duration event for this thread; |
| the flow resumes where the enclosing duration event begins then is suspended |
| at the point where the enclosing **duration event** event ends. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event8910.png) |
| |
| _flow correlation word_ |
| |
| - `[0 .. 63]`: flow correlation id |
| |
| #### Flow end event (event type = 10) {#flow-end-event} |
| |
| Marks the end of a flow. |
| |
| The end of the flow is associated with the enclosing duration event for this |
| thread; the flow resumes where the enclosing **duration event** begins. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/event8910.png) |
| |
| _flow correlation word_ |
| |
| - `[0 .. 63]`: flow correlation id |
| |
| ### BLOB record (record type = 5) {#blob-record} |
| |
| Provides uninterpreted bulk data to be included in the trace. This can be |
| useful for embedding captured trace data in other formats. |
| |
| The blob name uniquely identifies separate blob data streams within the trace. |
| By writing multiple blob records with the same name, additional chunks of |
| data can be appended to a previously created BLOB. |
| |
| The BLOB type indicates the representation of the BLOB's content. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/blob.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (5) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: blob name (string ref) |
| - `[32 .. 46]`: blob payload size in bytes (excluding padding) |
| - `[47 .. 47]`: reserved (must be zero) |
| - `[48 .. 55]`: blob type |
| - `[56 .. 63]`: reserved (must be zero) |
| |
| _blob name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _payload stream_ (variable size) |
| |
| - binary data, padded with zeros to 8 byte alignment |
| |
| ##### Blob types |
| |
| The following blob types are defined: |
| |
| - `TRACE_BLOB_TYPE_DATA` = `0x01`: Raw untyped data. The consumer is expected to know |
| how to consume it, perhaps based on context. |
| - `TRACE_BLOB_TYPE_LAST_BRANCH` = `0x02`: Last Branch Record of Intel Performance Monitor. |
| The format is defined by the |
| [CPU performance |
| monitor](/docs/development/tracing/advanced/recording-a-cpu-performance-trace.md). |
| - `TRACE_BLOB_TYPE_PERFETTO = `0x03`: The blob contains data recorded from a |
| Perfetto speaking component. The data is encoded in [Perfetto's Proto |
| Format](https://perfetto.dev/docs/reference/trace-packet-proto). |
| |
| ### Userspace object record (record type = 6) {#userspace-object-record} |
| |
| Describes a userspace object, assigns it a label, and optionally associates |
| key/value data with it as arguments. Information about the object is added |
| to a per-process userspace object table. |
| |
| When a trace consumer encounters an event with a **pointer argument** whose |
| value matches an entry in the process's object table, it can cross-reference |
| the argument's pointer value with a prior **userspace object record** to find a |
| description of the referent. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/userspace.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (6) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 23]`: process (thread ref) |
| - `[24 .. 39]`: name (string ref) |
| - `[40 .. 43]`: number of arguments |
| - `[44 .. 63]`: reserved (must be zero) |
| |
| _pointer word_ |
| |
| - `[0 .. 63]`: pointer value |
| |
| _process id word_ (omitted unless thread ref denotes inline thread) |
| |
| - `[0 .. 63]`: process koid (kernel object id) |
| |
| _name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _argument data_ (repeats for each argument) |
| |
| - (see below) |
| |
| ### Kernel object record (record type = 7) {#kernel-object-record} |
| |
| Describes a kernel object, assigns it a label, and optionally associates |
| key/value data with it as arguments. Information about the object is added |
| to a global kernel object table. |
| |
| When a trace consumer encounters an event with a **koid argument** |
| whose value matches an entry in the kernel object table, it can |
| cross-reference the argument's koid value with a prior **kernel object record** |
| to find a description of the referent. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/kernel.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (7) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 23]`: kernel object type (one of the ZX_OBJ_TYPE_XXX constants from |
| [zircon/syscalls/types.h](/zircon/system/public/zircon/syscalls/types.h) |
| - `[24 .. 39]`: name (string ref) |
| - `[40 .. 43]`: number of arguments |
| - `[44 .. 63]`: reserved (must be zero) |
| |
| _kernel object id word_ |
| |
| - `[0 .. 63]`: koid (kernel object id) |
| |
| _name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _argument data_ (repeats for each argument) |
| |
| - (see below) |
| |
| ##### Argument Conventions |
| |
| By convention, the trace writer should include the following named arguments |
| when writing kernel object records about objects of particular types. This |
| helps trace consumers correlate relationships among kernel objects. |
| |
| Note: This information may not always be available. |
| |
| - `"process"`: for `ZX_OBJ_TYPE_THREAD` objects, specifies the koid of the |
| process that contains the thread |
| |
| ### Scheduling Record (record type = 8) {#scheduling-record} |
| |
| Describes a scheduling event such as when a thread was woken up, or a context |
| switch from one thread to another. |
| |
| ##### Format |
| |
| ``` |
| +---------(4)--------------+--------(48)--------+--(8)--+-(4)-+ |
| | scheduling record type | <type specific> | size | 8 | |
| +--------------------------+--------------------+-------+-----+ |
| ``` |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (8) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 59]`: scheduling record type specific data |
| - `[60 .. 63]`: scheduling record type |
| |
| #### Context Switch Record (scheduling event record type = 1) |
| |
| ##### Format |
| |
| ``` |
| +-(4)-+----(20)---+--------(4)-------+----(16)---+-------(4)-------+----(8)--+-(4)-+ |
| | 1 | reserved | out thread state | cpu | argument count | size | 8 | |
| +-----+-----------+------------------+-----------+-----------------+---------+-----+ |
| +---------------------------(64)------------------------------+ |
| | timestamp | |
| +-------------------------------------------------------------+ |
| +---------------------------(64)------------------------------+ |
| | outgoing thread id | |
| +-------------------------------------------------------------+ |
| +---------------------------(64)------------------------------+ |
| | incoming thread id | |
| +-------------------------------------------------------------+ |
| +--------------------------(...)------------------------------+ |
| | argument data | |
| +-------------------------------------------------------------+ |
| ``` |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (8) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 19]`: argument count |
| - `[20 .. 35]`: cpu number |
| - `[36 .. 39]`: outgoing thread state |
| - `[40 .. 59]`: reserved |
| - `[60 .. 63]`: scheduling record type (1) |
| |
| _timestamp word_ |
| |
| - `[0 .. 63]`: number of ticks |
| |
| _outoing thread id_ |
| |
| - `[0 .. 63]`: thread koid (kernel object id) |
| |
| _incoming thread id_ |
| |
| - `[0 .. 63]`: thread koid (kernel object id) |
| |
| _argument data_ (repeats of each argument) |
| |
| - (see [Arguments](#arguments) for argument format) |
| |
| ##### Argument Conventions |
| |
| By convention, the trace writer may also optionally include the following named |
| arguments when writing this record to provide additional information to trace |
| consumers. |
| |
| - `"incoming_weight"`: `Int32` describing the relative [weight](/docs/concepts/kernel/fair_scheduler.md) of the incoming |
| thread |
| - `"outgoing_weight"`: `Int32` describing the relative weight of the outgoing |
| thread |
| |
| #### Thread Wakeup Record (scheduling event record type = 2) |
| |
| ##### Format |
| |
| ``` |
| +-(4)-+----(24)---+----(16)---+-------(4)-------+----(8)--+-(4)-+ |
| | 2 | reserved | cpu | argument count | size | 8 | |
| +-----+-----------+-----------+-----------------+---------+-----+ |
| +---------------------------(64)------------------------------+ |
| | timestamp | |
| +-------------------------------------------------------------+ |
| +---------------------------(64)------------------------------+ |
| | waking thread id | |
| +-------------------------------------------------------------+ |
| +--------------------------(...)------------------------------+ |
| | argument data | |
| +-------------------------------------------------------------+ |
| ``` |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (8) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 19]`: argument count. |
| - `[20 .. 35]`: cpu number. |
| - `[60 .. 63]`: scheduling record type (2) |
| |
| _timestamp word_ |
| |
| - `[0 .. 63]`: number of ticks |
| |
| _waking thread id_ |
| |
| - `[0 .. 63]`: thread koid (kernel object id) |
| |
| _argument data_ (repeats of each argument) |
| |
| - (see [Arguments](#arguments) for argument format) |
| |
| ##### Argument Conventions |
| |
| By convention, the trace writer may also optionally include the following named |
| argument when writing this record to provide additional information to trace |
| consumers. |
| |
| - `"weight"`: `Int32` describing the relative [weight](/docs/concepts/kernel/fair_scheduler.md) of the waking thread |
| |
| #### Legacy Context Switch Record (context switch record type = 0) |
| |
| As Fuchsia's scheduling has evolved, this record is no longer an effective |
| context switch model. It remains for backwards compatibility. |
| |
| The record specifies the new state of the outgoing thread following the |
| context switch. By definition, the new state of the incoming thread is |
| "running" since it was just resumed. |
| |
| ##### Format |
| ![drawing](images/trace-format/context.png) |
| |
| - `[0 .. 3]`: record type (8) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 23]`: cpu number |
| - `[24 .. 27]`: outgoing thread state (any of the values below except "running") |
| - `[28 .. 35]`: outgoing thread (thread ref) |
| - `[36 .. 43]`: incoming thread (thread ref) |
| - `[44 .. 51]`: outgoing thread priority |
| - `[52 .. 59]`: incoming thread priority |
| - `[60 .. 63]`: scheduling record type (0) |
| |
| _timestamp word_ |
| |
| - `[0 .. 63]`: number of ticks |
| |
| _outgoing process id word_ (omitted unless outgoing thread ref denotes inline thread) |
| |
| - `[0 .. 63]`: process koid (kernel object id) |
| |
| _outgoing thread id word_ (omitted unless outgoing thread ref denotes inline thread) |
| |
| - `[0 .. 63]`: thread koid (kernel object id) |
| |
| _incoming process id word_ (omitted unless incoming thread ref denotes inline thread) |
| |
| - `[0 .. 63]`: process koid (kernel object id) |
| |
| _incoming thread id word_ (omitted unless incoming thread ref denotes inline thread) |
| |
| - `[0 .. 63]`: thread koid (kernel object id) |
| |
| ##### Thread States |
| |
| The following thread states are defined: |
| |
| - `0`: new |
| - `1`: running |
| - `2`: suspended |
| - `3`: blocked |
| - `4`: dying |
| - `5`: dead |
| |
| These values align with the `ZX_THREAD_STATE_XXX` constants from |
| [zircon/syscalls/object.h](/zircon/system/public/zircon/syscalls/object.h). |
| |
| ### Log record (record type = 9) {#log-record} |
| |
| Describes a message written to the log at a particular moment in time. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/log.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (9) |
| - `[4 .. 15]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 30]`: log message length in bytes (range 0x0000 to 0x7fff) |
| - `[31]`: always zero (0) |
| - `[32 .. 39]`: thread (thread ref) |
| - `[40 .. 63]`: reserved (must be zero) |
| |
| _timestamp word_ |
| |
| - `[0 .. 63]`: number of ticks |
| |
| _process id word_ (omitted unless thread ref denotes inline thread) |
| |
| - `[0 .. 63]`: process koid (kernel object id) |
| |
| _thread id word_ (omitted unless thread ref denotes inline thread) |
| |
| - `[0 .. 63]`: thread koid (kernel object id) |
| |
| _log message stream_ |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| ### Large BLOB record (record type = 15, large type = 0) {#large-blob-record} |
| |
| Provides large binary BLOB data to be embedded within a trace. It |
| uses the large record header. |
| |
| The large BLOB record supports a number of different formats. These |
| formats can be used for varying the types of BLOB data and metadata |
| included in the record. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/largeblob.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (15) |
| - `[4 .. 35]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[36 .. 39]`: large record type (0) |
| - `[40 .. 43]`: blob format type |
| - `[44 .. 63]`: reserved, must be zero |
| |
| #### In Band Large Blob Record With Metadata (blob format = 0) |
| |
| This type contains the blob data and metadata within the record |
| itself. The metadata includes a timestamp, thread/process |
| information, and arguments, in addition to a category and name. |
| |
| The name should be sufficient to identify the type of data contained |
| within the blob. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/largeblob0.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (15) |
| - `[4 .. 35]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[36 .. 39]`: large record type (0) |
| - `[40 .. 43]`: blob format type (0) |
| - `[44 .. 63]`: reserved, must be zero |
| |
| _format header word_ |
| |
| - `[0 .. 15]`: category (string ref) |
| - `[16 .. 31]`: name (string ref) |
| - `[32 .. 35]`: number of arguments |
| - `[36 .. 43]`: thread (thread ref) |
| - `[44 .. 63]`: reserved, must be zero |
| |
| _category stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _timestamp word_ |
| |
| - `[0 .. 63]`: number of ticks |
| |
| _process id word_ (omitted unless thread ref denotes inline thread) |
| |
| - `[0 .. 63]`: process koid (kernel object id) |
| |
| _thread id word_ (omitted unless thread ref denotes inline thread) |
| |
| - `[0 .. 63]`: thread koid (kernel object id) |
| |
| _argument data_ (repeats for each argument) |
| |
| - (see below) |
| |
| _blob size word_ |
| |
| - `[0 .. 63]`: blob payload size in bytes (excluding padding) |
| |
| _payload stream_ (variable size) |
| |
| - binary data, padded with zeros to 8 byte alignment |
| |
| #### In Band Large Blob Record No Metadata (blob format = 1) |
| |
| This type contains the blob data within the record itself, |
| but does not include metadata. The record only contains |
| a category and name. |
| |
| The name should be sufficient to identify the type of data contained |
| within the blob. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/largeblob1.png) |
| |
| _header word_ |
| |
| - `[0 .. 3]`: record type (15) |
| - `[4 .. 35]`: record size (inclusive of this word) as a multiple of 8 bytes |
| - `[36 .. 39]`: large record type (0) |
| - `[40 .. 43]`: blob format type (1) |
| - `[44 .. 63]`: reserved, must be zero |
| |
| _format header word_ |
| |
| - `[0 .. 15]`: category (string ref) |
| - `[16 .. 31]`: name (string ref) |
| - `[32 .. 63]`: reserved, must be zero |
| |
| _category stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _blob size word_ |
| |
| - `[0 .. 63]`: blob payload size in bytes (excluding padding) |
| |
| _payload stream_ (variable size) |
| |
| - binary data, padded with zeros to 8 byte alignment |
| |
| ## Argument types {#argument-types} |
| |
| Arguments associate typed key and value data records. They are used together |
| with **event record** and **userspace object record** and |
| **kernel object record**. |
| |
| Each argument consists of a one word header followed by a variable number |
| words of payload. In many cases, the header itself is sufficient to encode |
| the content of the argument. |
| |
| There are the following argument types: |
| |
| - [Argument header](#argument-header) |
| - [Null argument](#null-argument) |
| - [32-bit signed integer argument](#32-bit-signed-integer-argument) |
| - [32-bit unsigned integer argument](#32-bit-unsigned-integer-argument) |
| - [64-bit signed integer argument](#64-bit-signed-integer-argument) |
| - [64-bit unsigned integer argument](#32-bit-unsigned-integer-argument) |
| - [Double-precision floating point argument](#double-precision-floating-point-argument) |
| - [String argument](#string-argument) |
| - [Pointer argument](#pointer-argument) |
| - [Kernel object id argument](#kernel-object-id-argument) |
| - [Boolean argument](#boolean-argument) |
| |
| ### Argument header {#argument-header} |
| |
| All arguments include this header, which specifies the argument's type, |
| name, and size together with 32 bits of data whose usage varies by |
| argument type. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/argument.png) |
| |
| _argument header word_ |
| |
| - `[0 .. 3]`: argument type |
| - `[4 .. 15]`: argument size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: argument name (string ref) |
| - `[32 .. 63]`: varies (must be zero if not used) |
| |
| _argument name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| ### Null argument (argument type = 0) {#null-argument} |
| |
| Represents an argument that appears in name only, without a value. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/argument0.png) |
| |
| _argument header word_ |
| |
| - `[0 .. 3]`: argument type (0) |
| - `[4 .. 15]`: argument size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: argument name (string ref) |
| - `[32 .. 63]`: reserved (must be zero) |
| |
| _argument name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| ### 32-bit signed integer argument (argument type = 1) {#32-bit-signed-integer-argument} |
| |
| Represents a 32-bit signed integer. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/argument1.png) |
| |
| _argument header word_ |
| |
| - `[0 .. 3]`: argument type (1) |
| - `[4 .. 15]`: argument size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: argument name (string ref) |
| - `[32 .. 63]`: 32-bit signed integer |
| |
| _argument name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| ### 32-bit unsigned integer argument (argument type = 2) {#32-bit-unsigned-integer-argument} |
| |
| Represents a 32-bit unsigned integer. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/argument2.png) |
| |
| _argument header word_ |
| |
| - `[0 .. 3]`: argument type (2) |
| - `[4 .. 15]`: argument size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: argument name (string ref) |
| - `[32 .. 63]`: 32-bit unsigned integer |
| |
| _argument name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| ### 64-bit signed integer argument (argument type = 3) {#64-bit-signed-integer-argument} |
| |
| Represents a 64-bit signed integer. If a value fits in 32-bits, |
| use the **32-bit signed integer argument** type instead. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/argument3.png) |
| |
| _argument header word_ |
| |
| - `[0 .. 3]`: argument type (3) |
| - `[4 .. 15]`: argument size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: argument name (string ref) |
| - `[32 .. 63]`: reserved (must be zero) |
| |
| _argument name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _argument value word_ |
| |
| - `[0 .. 63]`: 64-bit signed integer |
| |
| ### 64-bit unsigned integer argument (argument type = 4) {#64-bit-unsigned-integer-argument} |
| |
| Represents a 64-bit unsigned integer. If a value fits in 32-bits, |
| use the **32-bit unsigned integer argument** type instead. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/argument4.png) |
| |
| _argument header word_ |
| |
| - `[0 .. 3]`: argument type (4) |
| - `[4 .. 15]`: argument size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: argument name (string ref) |
| - `[32 .. 63]`: reserved (must be zero) |
| |
| _argument name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _argument value word_ |
| |
| - `[0 .. 63]`: 64-bit unsigned integer |
| |
| ### Double-precision floating point argument (argument type = 5) {#double-precision-floating-point-argument} |
| |
| Represents a double-precision floating point number. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/argument5.png) |
| |
| _argument header word_ |
| |
| - `[0 .. 3]`: argument type (5) |
| - `[4 .. 15]`: argument size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: argument name (string ref) |
| - `[32 .. 63]`: reserved (must be zero) |
| |
| _argument name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _argument value word_ |
| |
| - `[0 .. 63]`: double-precision floating point number |
| |
| ### String argument (argument type = 6) {#string-argument} |
| |
| Represents a string value. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/argument6.png) |
| |
| _argument header word_ |
| |
| - `[0 .. 3]`: argument type (6) |
| - `[4 .. 15]`: argument size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: argument name (string ref) |
| - `[32 .. 47]`: argument value (string ref) |
| - `[48 .. 63]`: reserved (must be zero) |
| |
| _argument name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _argument value stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| ### Pointer argument (argument type = 7) {#pointer-argument} |
| |
| Represents a pointer value. Additional information about the referent can |
| be provided by a **userspace object record** associated with the same pointer. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/argument7.png) |
| |
| _argument header word_ |
| |
| - `[0 .. 3]`: argument type (7) |
| - `[4 .. 15]`: argument size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: argument name (string ref) |
| - `[32 .. 63]`: reserved (must be zero) |
| |
| _argument name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _argument value word_ |
| |
| - `[0 .. 63]`: the pointer value |
| |
| ### Kernel object id argument (argument type = 8) {#kernerl-object-id-argument} |
| |
| Represents a koid (kernel object id). Additional information about the |
| referent can be provided by a **kernel object record** associated with the |
| same koid. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/argument8.png) |
| |
| _argument header word_ |
| |
| - `[0 .. 3]`: argument type (8) |
| - `[4 .. 15]`: argument size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: argument name (string ref) |
| - `[32 .. 63]`: reserved (must be zero) |
| |
| _argument name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| _argument value word_ |
| |
| - `[0 .. 63]`: the koid (kernel object id) |
| |
| ### Boolean argument (argument type = 9) {#boolean-argument} |
| |
| Represents a boolean. |
| |
| ##### Format |
| |
| ![drawing](images/trace-format/argument9.png) |
| |
| _argument header word_ |
| |
| - `[0 .. 3]`: argument type (9) |
| - `[4 .. 15]`: argument size (inclusive of this word) as a multiple of 8 bytes |
| - `[16 .. 31]`: argument name (string ref) |
| - `[32 .. 63]`: 1 bit padded with zeros |
| |
| _argument name stream_ (omitted unless string ref denotes inline string) |
| |
| - UTF-8 string, padded with zeros to 8 byte alignment |
| |
| <!-- xrefs --> |
| |
| <!-- drawings are sourced from https://docs.google.com/document/d/19nQHHSc-TdZ1BPovkrUd5Uk5l5T3YuxTNuVl9zv0whU/edit --> |
| |