| // Copyright 2023 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| @available(added=11) |
| library fuchsia.tracing; |
| |
| /// The maximum length of a provider's name. |
| const MAX_PROVIDER_NAME_LENGTH uint32 = 100; |
| |
| /// The maximum number of categories supported. |
| const MAX_NUM_ENABLED_CATEGORIES uint32 = 5000; |
| |
| /// The maximum number of categories supported. |
| const MAX_NUM_KNOWN_CATEGORIES uint32 = 5000; |
| |
| /// The maximum length of a category name. |
| const MAX_CATEGORY_NAME_LENGTH uint32 = 100; |
| |
| /// The maximum length of a category description. |
| const MAX_CATEGORY_DESCRIPTION_LENGTH uint32 = 400; |
| |
| /// aliases |
| @available(added=18) |
| alias CategoryName = string:MAX_CATEGORY_NAME_LENGTH; |
| @available(added=18) |
| alias CategoryDescription = string:MAX_CATEGORY_DESCRIPTION_LENGTH; |
| @available(added=18) |
| alias EnabledCategoryList = vector<CategoryName>:MAX_NUM_ENABLED_CATEGORIES; |
| @available(added=18) |
| alias ProviderName = string:MAX_PROVIDER_NAME_LENGTH; |
| @available(added=18) |
| alias ProviderId = uint32; |
| |
| /// The value returned by `GetKnownCategories`. |
| type KnownCategory = struct { |
| // Category name. |
| @available(replaced=18) |
| name string:MAX_CATEGORY_NAME_LENGTH; |
| @available(added=18) |
| name CategoryName; |
| // Category description. |
| @available(replaced=18) |
| description string:MAX_CATEGORY_DESCRIPTION_LENGTH; |
| @available(added=18) |
| description CategoryDescription; |
| }; |
| |
| /// Choices for clearing/retaining trace buffer contents at Start. |
| /// A brief summary of buffer contents: |
| /// The trace buffer is divided into two main pieces: durable and non-durable. |
| /// The durable portion contains things like the string and thread data for |
| /// their respective references (trace_encoded_string_ref_t and |
| /// trace_encoded_thread_ref_t). The non-durable portion contains the rest of |
| /// the trace data like events); this is the portion that, for example, is |
| /// discarded in circular buffering mode when the (non-durable) buffer fills. |
| type BufferDisposition = strict enum : uint8 { |
| /// Clear the entire buffer, including durable buffer contents. |
| /// N.B. If this is done mid-session, then string and thread references |
| /// from prior to this point will become invalid - the underlying data |
| /// will be gone. To prevent this save buffer contents before clearing. |
| /// |
| /// This is typically used when buffer contents were saved after the |
| /// preceding Stop. |
| CLEAR_ENTIRE = 1; |
| |
| /// Clear the non-durable portion of the buffer, retaining the durable |
| /// portion. |
| /// |
| /// This is typically used when buffer contents were not saved after the |
| /// preceding Stop and the current contents are to be discarded. |
| CLEAR_NONDURABLE = 2; |
| |
| /// Retain buffer contents. New trace data is added where the previous |
| /// trace run left off. |
| /// |
| /// This is typically used when buffer contents were not saved after the |
| /// preceding Stop and the current contents are to be retained. |
| RETAIN = 3; |
| }; |
| |
| /// The trace buffering mode. |
| type BufferingMode = strict enum : uint8 { |
| /// In oneshot mode there is only one buffer that is not reused. When the |
| /// buffer fills the provider just keeps dropping records, keeping a count, |
| /// and then when tracing stops the header is updated to record final |
| /// state. |
| ONESHOT = 1; |
| |
| /// In circular mode, the buffer is continually written to until tracing |
| /// stops. When the buffer fills older records are discarded as needed. |
| CIRCULAR = 2; |
| |
| /// In streaming mode, the buffer is effectively split into two pieces. |
| /// When one half of the buffer fills the provider notifies the trace |
| /// manager via the provided fifo, and then starts filling the other half |
| /// of the buffer. When the buffer is saved, the manager responds via the |
| /// provided fifo. If trace manager hasn't saved the buffer in time, and |
| /// the other buffer fills, then the provider is required to drop records |
| /// until space becomes available. |
| STREAMING = 3; |
| }; |