sdk/fidl/fuchsia.sysmem2/config.fidl

// Copyright 2024 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.
library fuchsia.sysmem2;

using fuchsia.images2;

/// This type is fidl::Persist()'ed in the sysmem_config.persistent_fidl file
/// within the sysmem domain config by the assembly tool, and read by the sysmem
/// driver.
///
/// Normally json[5] would be preferable for config, but we generate this config
/// in rust using FIDL types (to avoid repetition and to take advantage of FIDL
/// rust codegen), and there's no json schema for FIDL types.
///
/// Currently there is no mechanism to change anything in this config at runtime
/// or from boot to boot. This config is static per run of the assembly tool.
///
/// See src/lib/assembly/config_schema/src/platform_config/sysmem_config.rs for
/// aspects of sysmem config which are specified directly inline in board info
/// or assembly platform config. The two parts of sysmem config don't
/// (currently) overlap. The config here is for aspects of sysmem config which
/// would be too verbose for direct inclusion in board info or assembly platform
/// config. In addition, some/most of the pixel format cost entries are
/// programmatically generated (as of this comment).
///
/// Prior to aggregation by assembly tool, there are multiple .persistent_fidl
/// files each storing its own Config instance. The board info and assembly
/// platform config lists the input persistent_fidl files, with board info
/// logically before assembly platform config. The overall list of files is
/// processed, which allows later files to override/replace info in prior files.
///
/// Because this type is only intended for use with persistent fidl, where the
/// length of a serialized instance isn't bounded, we don't bound the internal
/// vector element counts.
@available(added=23)
type Config = table {
    /// This is the ordered list of FormatCost entries which will be considered
    /// by sysmem when breaking ties among formats supported by all participants
    /// of a buffer collection.
    ///
    /// During config aggregation, if a later entry has matching FormatCostKey,
    /// the earlier entry is omitted/removed. This allows later files to
    /// override entries in earlier files, and allows files specified in
    /// assembly platform config to override entries in files specified in the
    /// board info.
    ///
    /// This vector will normally not have any two entries with matching
    /// pixel_format, pixel_format_modifier, and buffer_usage_bits in the Config
    /// instance loaded from sysmem_config.persistent_fidl by sysmem. If somehow
    /// two entries do match in those fields, sysmem can ignore all but one of
    /// the entries chosen arbitrarily.
    //
    // Unbounded length because this is a config file type not a fidl protocol
    // type.
    1: format_costs vector<FormatCostEntry>:MAX;
};

/// This is the root of the persistent fidl in a format costs file. The format
/// costs files are read by the assembly tool and merged into the single
/// sysmem_config.persistent_fidl file in the sysmem domain config (see Config
/// above).
///
/// Normally json[5] would be preferable for config, but we generate this config
/// in rust using FIDL types (to avoid repetition and to take advantage of FIDL
/// rust codegen), and there's no json schema for FIDL types.
///
/// While the resulting sysmem_config.persistent_fidl is a single file that can
/// contain multiple aspects of sysmem config, in contrast a format costs file
/// contains only format costs. We don't mind having more separate files during
/// the build, but it's nice to get sysmem's domain config down to a single file
/// on-device.
@available(added=23)
type FormatCosts = table {
    /// This is a chunk of entries that'll end up in
    /// ['fuchsia.sysmem2.Config.format_costs'] (see above) unless overriden by
    /// later entries (either in this same vector or in later-processed files
    /// during aggregation by the assembly tool).
    1: format_costs vector<FormatCostEntry>:MAX;
};

/// A FormatCostEntry can be used to influence which PixelFormatAndModifier is
/// chosen for a buffer collection, optionally taking BufferUsage into account.
///
/// The default cost is f32::MAX, so any specified cost with a non-MAX value
/// will prefer the specified format over any formats that don't have any
/// FormatCost entry.
///
/// Entries which have the same pixel_format, pixel_format_modifier, and
/// required_usage_bits as a previous entry will override that previous entry.
/// For matching purposes, an absent pixel_format_modifier matches LINEAR, and
/// an absent required_buffer_usage_bits matches all-0 usage bits.
///
/// Board info sysmem_defaults entries are logically before platform sysmem
/// entries.
///
/// Sysmem uses the resulting aggregated list of FormatCostEntry(s) when
/// breaking ties among the set of formats which are supported by all
/// participants of a buffer collection. For each mutually-supported format,
/// entries with non-matching format are ignored, and entries with extra
/// buffer_usage_bits set are ignored. Among the remaining entries, the entry
/// with the most usage bits in common with the aggregated participant usages is
/// selected to determine the cost (if a tie, the later entry wins). Then the
/// format with the lowest cost is chosen. If it's still a tie (equal cost), the
/// tie is broken arbitrarily but not randomly.
///
/// This is not intended as a mechanism to disallow selection of a format that
/// is supported by all participants of a buffer collection. If a participant
/// claims support for a format but fails to handle that format correctly, it
/// should be fixed to handle that format correctly or changed to stop claiming
/// support for that format.
///
/// This mechanism is intended to influence format selection toward more
/// efficient formats with better performance, lower memory bandwidth usage,
/// etc, for a given set of usage bits, taking into account quirks that may be
/// unique to a given board or overall platform config.
@available(added=23)
type FormatCostEntry = table {
    /// Must be set. If two entries have logically equal key (after field
    /// defaults are applied), the later entry will override the earlier entry.
    1: key FormatCostKey;

    /// Must be set. Lower costs win, but see also FormatCostKey fields re.
    /// filtering entries by format and usage bits first.
    ///
    /// When two entries (each with format supported by all the participants of
    /// a buffer collection) have different costs, the lower cost entry (and its
    /// format) is chosen.
    ///
    /// For non-test scenarios, only use cost values > 0.0 (typically at least
    /// 1.0 as of this comment), with 0.0 and negative values reserved for
    /// testing.
    2: cost float32;
};

/// Entries which have the same pixel_format, pixel_format_modifier, and
/// required_usage_bits as a previous entry will override that previous entry.
/// For matching purposes, an absent pixel_format_modifier matches LINEAR, and
/// an absent required_buffer_usage_bits matches all-0 usage bits.
@available(added=23)
type FormatCostKey = table {
    /// The pixel_format and pixel_format_modifier are the format to which this
    /// FormatCost entry applies.
    ///
    /// Must be set.
    1: pixel_format fuchsia.images2.PixelFormat;

    /// The pixel_format and pixel_format_modifier are the format to which this
    /// FormatCost entry applies.
    ///
    /// Un-set is equivalent to LINEAR.
    2: pixel_format_modifier fuchsia.images2.PixelFormatModifier;

    /// If set, this entry is only considered if the buffer collection has at
    /// least these usage bits set.
    ///
    /// The buffer collection has an aggregated BufferUsage which is the union
    /// of per-participant BufferUsage bits. FormatCost entries with additional
    /// set bits are ignored. Among the rest, the one with matching format and
    /// the most usage bits set determines the cost of that format for that
    /// buffer collection.
    ///
    /// Then the lowest-cost format is chosen for that buffer collection among
    /// the formats that are mutually suppored by all the participants of that
    /// buffer collection.
    ///
    /// The main intent of this field is to allow "waving off" a format that
    /// works, but doesn't perform well, for a particular combination of usages.
    /// In that case the cost can be set high when the problematic combination
    /// of usage bits is set. The format will still be chosen if this format is
    /// the only mutually-supported format among the participants of the buffer
    /// collection.
    ///
    /// Un-set is equivalent to zero usage bits set, meaning the entry applies
    /// to the format unless another entry with more specific usage applies.
    ///
    /// It can be reasonable in some cases for all entries to omit this field,
    /// when/if format selection based on format cost alone, ignoring usage, is
    /// sufficient.
    3: buffer_usage_bits BufferUsage;
};