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

@available(added=19)
type VmoBuffer = resource table {
    /// `vmo` can be un-set if a participant has only
    /// [`fuchsia.sysmem2/BufferUsage.none`] set to `NONE_USAGE` (explicitly or
    /// implicitly by [`fuchsia.sysmem2/BufferCollection.SetConstraints`]
    /// without `constraints` set).
    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.
    ///
    /// Currently sysmem will always set this field to 0, and in future, sysmem
    /// won't set this field to a non-zero value unless all participants have
    /// explicitly indicated support for non-zero vmo_usable_start (this
    /// mechanism does not exist as of this comment). A participant that hasn't
    /// explicitly indicated support for non-zero vmo_usable_start (all current
    /// clients) should implicitly assume this field is set to 0 without
    /// actually checking this field.
    2: vmo_usable_start uint64;

    /// This field is set iff `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 by the client and in
    /// that case sysmem will eventually complain loudly via syslog (currently
    /// 5s later).
    3: close_weak_asap zx.Handle:EVENTPAIR;
};

/// The maximum entries that can be in the
/// [`fuchsia.sysmem2/BufferCollectionInfo.buffers`] field.
@available(added=19)
const MAX_COUNT_BUFFER_COLLECTION_INFO_BUFFERS uint32 = 128;

/// Information about a buffer collection and its buffers.
@available(added=19)
type BufferCollectionInfo = resource table {
    /// These settings apply to all the buffers in the initial buffer
    /// allocation.
    ///
    /// This field will always be set by sysmem.
    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.
    ///
    /// This field will always be set by sysmem, even if the participant doesn't
    /// specify any buffer usage (but the [`fuchsia.sysmem2/VmoBuffer.vmo`]
    /// sub-field within this field won't be set in that case).
    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).
    ///
    /// This field will always be set by sysmem.
    3: buffer_collection_id uint64;
};

/// These settings and constraints apply to all the buffers in the collection.
@available(added=19)
type SingleBufferSettings = table {
    /// This field will always be set by sysmem.
    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.
@available(added=19)
type BufferMemorySettings = table {
    /// This field will always be set by sysmem.
    1: size_bytes uint64;
    /// This field will always be set by sysmem.
    2: is_physically_contiguous bool;
    /// This field will always be set by sysmem.
    3: is_secure bool;
    /// This field will always be set by sysmem.
    4: coherency_domain CoherencyDomain;
    /// The specific heap from which buffers are allocated.
    ///
    /// This field will always be set by sysmem.
    5: heap Heap;
};