// 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;
};