sdk/fidl/fuchsia.sysmem2/results.fidl

// Copyright 2020 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 zx;

type VmoBuffer = resource table {
    /// The same VMO can be used by more than one CodecBuffer (only of the same
    /// buffer_lifetime_ordinal), but each vmo handle must be a separate handle.
    ///
    /// |vmo| can be un-set if a participant has no usage which requires a
    /// VMO handle.
    1: vmo zx.Handle:VMO;

    /// Offset within the VMO of the first usable byte.  Must be < the VMO's
    /// size in bytes, and leave sufficient room for
    /// BufferMemorySettings.size_bytes before the end of the VMO.
    2: vmo_usable_start uint64;

    /// This field is set iff the |vmo| is a sysmem weak VMO handle. The client
    /// must keep |close_weak_asap| around for as long as |vmo|, and must notice
    /// ZX_EVENTPAIR_PEER_CLOSED; if that signal occurs, the client must close
    /// |vmo| asap. Not doing so is considered a VMO leak and in that case
    /// sysmem will eventually complain loudly via syslog (currently 5s later).
    3: close_weak_asap zx.Handle:EVENTPAIR;
};

const MAX_COUNT_BUFFER_COLLECTION_INFO_BUFFERS uint32 = 128;

/// Information about a buffer collection and its buffers.
// TODO(fxbug.dev/32119): provide a way for clients to receive this table instead of the
// struct fuchsia.sysmem.BufferCollectionInfo_2.
type BufferCollectionInfo = resource table {
    /// These settings apply to all the buffers in the initial buffer allocation.
    /// This must be set.
    1: settings SingleBufferSettings;

    /// VMO handles (and vmo_usable_start offset) for each buffer in the
    /// collection.
    ///
    /// The size of this vector is the buffer_count (buffer_count is not sent
    /// separately).
    ///
    /// All buffer VMO handles have identical size and access rights.  The size
    /// is in settings.buffer_settings.size_bytes.
    ///
    /// The VMO access rights are determined based on the usages which the
    /// client specified when allocating the buffer collection.  For example,
    /// a client which expressed a read-only usage will receive VMOs without
    /// write rights.  In addition, the rights can be attenuated by the
    /// parameter to BufferCollectionToken.Duplicate() calls.
    ///
    /// This field will always have VmoBuffer(s) in it, even if the participant
    /// specifies usage whieh does not require VMO handles.  This permits such
    /// a participant to know the vmo_usable_start values, in case that's of any
    /// use to the participant.
    2: buffers vector<VmoBuffer>:MAX_COUNT_BUFFER_COLLECTION_INFO_BUFFERS;

    /// This number is unique among all logical buffer collections per boot.
    ///
    /// This ID number will be the same for all BufferCollectionToken(s),
    /// BufferCollection(s), and BufferCollectionTokenGroup(s) associated with
    /// the same logical buffer collection (derived from the same root token
    /// created with fuchsia.sysmem2.Allocator.CreateSharedCollection, or with
    /// CreateNonSharedCollection).
    ///
    /// The same ID can be retrieved from a BufferCollectionToken,
    /// BufferCollection, or BufferCollectionTokenGroup using
    /// GetBufferCollectionId (at the cost of a round-trip to sysmem and back).
    3: buffer_collection_id uint64;
};

/// These settings and constraints apply to all the buffers in the collection.
type SingleBufferSettings = table {
    1: buffer_settings BufferMemorySettings;

    /// Buffers holding data that is not uncompressed image data will not have
    /// this field set.  Buffers holding data that is uncompressed image data
    /// _may_ have this field set.
    ///
    /// At least for now, changing the PixelFormat requires re-allocating
    /// buffers.
    ///
    /// If un-set, there are no image format constraints.
    2: image_format_constraints ImageFormatConstraints;
};

/// These are memory-related settings for all buffers of a buffer collection.
type BufferMemorySettings = table {
    1: size_bytes uint64;
    2: is_physically_contiguous bool;
    3: is_secure bool;
    4: coherency_domain CoherencyDomain;
    /// The specific heap from which buffers are allocated.
    /// See above in this file for heap identifier values.
    5: heap HeapType;
};