// Copyright 2018 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.sysmem;

using zx;

// A BufferCollectionToken is not a BufferCollection, but rather a way to
// identify a potential shared BufferCollection prior to the BufferCollection
// being allocated.
//
// We use a channel for the BufferCollectionToken instead of a single eventpair
// (pair) because this way we can detect error conditions like a participant
// dying mid-create.
[Discoverable, Layout = "Simple"]
protocol BufferCollectionToken {
    // The initiator or a participant can send Duplicate() as part of creating
    // another participant-side handle to the same logical
    // BufferCollectionToken.
    //
    // This method is used to hand the logical token to all participants so all
    // participants can provide constraints to sysmem for the overall
    // BufferCollection to achieve the goal of allocating buffers compatible
    // with all participants.
    //
    // The Duplicate() message is intentionally available only on
    // BufferCollectionToken not BufferCollection.
    //
    // The token is separate from BufferCollection so that participants contact
    // sysmem directly, so that participants are only trusting their environment
    // for who sysmem is (fake token mitigation), not an initiator.  Only after
    // successful BindSharedCollection does a participant know that the token
    // was a real sysmem token.  In contrast, if we had Duplicate() directly on
    // BufferCollection, an initiator could attempt to serve the
    // BufferCollection channel itself, which would allow for some problematic
    // possibilities.
    //
    // All the BufferCollectionToken channels of a logical token must be turned
    // in via BindSharedCollection() for a BufferCollection to be successfully
    // created.  Else the BufferCollection channel will close.
    //
    // When a client calls BindSharedCollection() to turn in a
    // BufferCollectionToken, the server will process all Duplicate() messages
    // before closing down the BufferCollectionToken.  This allows the client
    // to Duplicate() and immediately turn in the BufferCollectionToken using
    // BindSharedCollection, then later transfer the client end of token_request
    // to another participant - the server will notice the existence of the
    // token_request before considering this BufferCollectionToken fully closed.
    //
    // |rights_attenuation_mask| rights bits that are zero in this mask will be
    // absent in the buffer VMO rights obtainable via the client end of
    // token_request.  This allows an initiator or intermediary participant
    // to attenuate the rights available to a participant.  This may not be the
    // only mechanism that attenuates rights on the VMO handles obtainable via
    // the client end of token_request.  This does not allow a participant
    // to gain rights that the participant doesn't already have.
    //
    // |token_request| is the server end of a BufferCollectionToken channel.
    // The client end of this channel acts as another handle to the same logical
    // BufferCollectionToken.  Typically the sender of Duplicate() will transfer
    // the client end corresponding to collection_request to a/another
    // participant running in a separate process, but it's also fine for the
    // additional logical participant to be in the same process.
    //
    // After sending one or more Duplicate() messages, and before sending the
    // created tokens to other participants (or to other Allocator2 channels),
    // the client should send a Sync() and wait for its response.  The Sync()
    // call can be made on the token, or on the BufferCollection obtained by
    // passing this token to BindSharedCollection().  Either will ensure that
    // the server knows about the tokens created via Duplicate() before the
    // other participant sends the token to the server via separate Allocator2
    // channel.  If a client is using FIDL C generated code and doesn't want to
    // block waiting for a response message, the other option is to notice
    // arrival of the BufferCollectionEvents::OnBufferCollectionCreated() event
    // after turning in this token for a BufferCollection.
    //
    // TODO(dustingreen): Consider other mechanisms to ensure the token created
    // here is recognized by the server.
    Duplicate(uint32 rights_attenuation_mask,
              request<BufferCollectionToken> token_request);

    // Ensure that previous Duplicate() messages have been received server side,
    // so that it's safe to send the client end of token_request to another
    // participant knowing the server will recognize the token when it's sent
    // into BindSharedCollection by the other participant.
    //
    // Other options include waiting for each Duplicate() to complete
    // individually, or calling Sync() on BufferCollection after this token has
    // been turned in via BindSharedCollection(), or noticing arrival of
    // BufferCollectionEvents::OnDuplicatedTokensKnownByServer().
    Sync() -> ();

    // Normally a participant will convert the token into a BufferCollection
    // view, but a particpant is also free to Close() the token (and then close
    // the channel immediately or shortly later in response to server closing
    // its end), which avoids causing LogicalBufferCollection failure.
    // Normally an unexpected token channel close will cause
    // LogicalBufferCollection failure.
    Close();
};

// BufferCollection is a connection directly from a participant to sysmem re.
// a logical BufferCollection; typically the logical BufferCollection is shared
// with other participants.  In other words, an instance of the BufferCollection
// interface is a view of a "LogicalBufferCollection".
//
// This connection exists to facilitate async indication of when the logical
// BufferCollection has been populated with buffers.
//
// Also, the channel's closure by the server is an indication to the client
// that the client should close all VMO handles that were obtained from the
// BufferCollection ASAP.
//
// Also, this interface may in future allow specifying constraints in other
// ways, and may allow for back-and-forth negotiation of constraints to some
// degree.
//
// This interface may in future allow for more than 64 VMO handles per
// BufferCollection, but currently the limit is 64.
//
// This interface may in future allow for allocating/deallocating single
// buffers.
//
// Some initiators may wait a short duration until all old logical
// BufferCollection VMO handles have closed (or until the short duration times
// out) before allocating a new BufferCollection, to help control physical
// memory fragmentation and avoid overlap of buffer allocation lifetimes for
// the old and new collections. Collections can be large enough that it's worth
// avoiding allocation overlap (in time).
[Discoverable, Layout = "Simple"]
protocol BufferCollection {
    // At least for now, the only way to get events from a BufferCollection is
    // to set a reverse BufferCollectionEvents channel.  This can be sent up to
    // once at any point during BufferCollection channel lifetime.  All events
    // are one-shot events, and will be sent immediately via |events| if the
    // one-shot event's condition has already become true (once true will stay
    // true; only goes from false to true once).
    //
    // |events| is the client end of a BufferCollectionEvents which will be sent
    // one-way messages indicating events relevant to this BufferCollection
    // channel (some may be specific to this BufferCollection channel and some
    // may be relevant to the overall logical BufferCollection).
    SetEventSink(BufferCollectionEvents events);

    // See comments on BufferCollectionToken::Sync().
    Sync() -> ();

    // Provide BufferCollectionConstraints to the logical BufferCollection.
    //
    // Participants with read but not write can only call SetConstraints() once.
    //
    // Participants with write can call SetConstraints() more than once.  The
    // initial buffer allocation will use the constraints in the first call to
    // SetConstraints().  Among other things, this allows a decoder to attempt
    // to allocate a new buffer that's larger to hold an output frame that's
    // larger.
    //
    // Sometimes the initiator is a participant only in the sense of wanting to
    // keep an eye on success/failure to populate with buffers, and zx.status on
    // failure.  In that case, |has_constraints| can be false, and |constraints|
    // will be ignored.
    //
    // VMO handles will not be provided to the client that sends null
    // constraints - that can be intentional for an initiator that doesn't need
    // VMO handles.  Not having VMO handles doesn't prevent the initator from
    // adjusting which portion of a buffer is considered valid and similar, but
    // the initiator can't hold a VMO handle open to prevent the logical
    // BufferCollection from cleaning up if the logical BufferCollection needs
    // to go away regardless of the initiator's degree of involvement for
    // whatever reason.
    //
    // For population of buffers to be attempted, all holders of a
    // BufferCollection client channel need to call SetConstraints() before
    // sysmem will attempt to allocate buffers.
    //
    // |has_constraints| if false, the constraints are effectively null, and
    // |constraints| are ignored.  The sender of null constraints won't get any
    // VMO handles in BufferCollectionInfo, but can still find out how many
    // buffers were allocated and can still refer to buffers by their
    // buffer_index.
    //
    // |constraints| are constraints on the buffer collection.
    SetConstraints(bool has_constraints,
                   BufferCollectionConstraints constraints);

    // This request completes when buffers have been allocated, responds with
    // some failure detail if allocation has been attempted but failed.
    //
    // The following must occur before buffers will be allocated:
    //   * All BufferCollectionToken(s) of the logical BufferCollectionToken
    //     must be turned in via BindSharedCollection().
    //   * All BufferCollection(s) of the logical BufferCollection must have had
    //     SetConstraints() sent to them.
    //
    // A caller using C generated FIDL code who wishes not to block a thread in
    // a zx_channel_call() for a potentially fairly long duration on this
    // message/response can use SetEventSink() and
    // BufferCollectionEvents.OnBuffersPopulated() instead.
    //
    // This method is still legal to call despite use of OnBuffersPopulated(),
    // but in that case the additional BufferCollectionInfo returned here will
    // include handles that are redundant with other handles in the
    // BufferCollectionInfo delivered via OnBuffersPopulated() (separate handle
    // but same underlying VMO objects), so most clients that bother calling
    // SetEventSink() will prefer to receive BufferCollectionInfo via
    // OnBuffersPopulated().  This method is mostly here for clients that don't
    // call SetEventSink().
    //
    // Returns |ZX_OK| if successful.
    // Returns |ZX_ERR_NO_MEMORY| if the request is valid but cannot be
    // fulfilled due to resource exhaustion.
    // Returns |ZX_ERR_ACCESS_DENIED| if the caller is not permitted to
    // obtain the buffers it requested.
    // Returns |ZX_ERR_INVALID_ARGS| if the request is malformed.
    // Returns |ZX_ERR_NOT_SUPPORTED| if request is valid but cannot be
    // satisfied, perhaps due to hardware limitations.
    //
    // |buffer_collection_info| has the VMO handles and other related info.
    WaitForBuffersAllocated()
        -> (zx.status status, BufferCollectionInfo_2 buffer_collection_info);

    // This returns the same result code as WaitForBuffersAllocated if the
    // buffer collection has been allocated or failed, or |ZX_ERR_UNAVAILABLE|
    // if WaitForBuffersAllocated would block.
    CheckBuffersAllocated() -> (zx.status status);

    // The CloseBuffer() doesn't immediately force all VMO handles to that
    // buffer to close, but it does close any handle held by sysmem, and does
    // notify all participants of the desire to close the buffer at which point
    // each participant that's listening may close their handle to the buffer.
    //
    // Only a particpant with write can do this.  Coordination among multiple
    // participants with write is outside of the scope of this interface.
    //
    // |buffer_index| indicates which buffer to close.  If the buffer is already
    // closed this has no effect (idempotent).
    CloseSingleBuffer(uint64 buffer_index);

    // This allocates a new buffer that is consistent with the most recent call
    // to SetConstraints(), if possible.  If not possible, this indicates the
    // failure via OnNewBufferAllocated().
    //
    // Only a participant with write can do this.  Coordination among multiple
    // participants with write is outside the scope of this interface.
    //
    // The participant is (intentionally) never informed of other participant's
    // constraints.
    AllocateSingleBuffer(uint64 buffer_index);

    // Completes when AllocateBuffer is done.  Callers who wish to avoid
    // blocking a thread while waiting can use OnAllocateSingleBufferDone()
    // instead.
    WaitForSingleBufferAllocated(uint64 buffer_index)
        -> (zx.status status, SingleBufferInfo buffer_info);

    // A participant can use this message to have sysmem verify that this
    // buffer_index exists.  This message is intentionally ignored by the
    // server if the buffer_index _does_ exist.  In that case, the client will
    // see OnAllocateSingleBufferDone() soon with status == ZX_OK (if the
    // client hasn't already seen that message).  If on the other hand the
    // buffer_index does not exist, this message causes the server to send
    // OnAllocateSingleBufferDone() with status == ZX_ERR_NOT_FOUND.  A
    // particpant will typically use this when the participant receives a new
    // buffer_index that the participant doesn't yet know about, to ensure that
    // the participant won't be waiting forever for the
    // OnAllocateSingleBufferDone() message regarding this buffer_index.
    CheckSingleBufferAllocated(uint64 buffer_index);

    // The server handles unexpected failure of a BufferCollection by failing
    // the whole LogicalBufferCollection.  Partly this is to expedite closing
    // VMO handles.  If a participant would like to cleanly close a
    // BufferCollection view without causing LogicalBufferCollection failure,
    // the participant can send Close() before closing the client end of the
    // BufferCollection channel.  If this is the last BufferCollection view, the
    // LogicalBufferCollection will still go away.
    Close();
};

// This interface intentionally doesn't include any event for
// OnOldBufferClosed(), because such an event could arrive at a participant too
// soon to be useful.  Instead, such an indication should be made in-band within
// FIDL interfaces that deliver packets to downstream participants.
[Discoverable, Layout = "Simple"]
protocol BufferCollectionEvents {
    // See comments on BufferCollectionToken::Sync().
    //
    // This message only indicates that the server has reached the point where
    // it knows about previously created tokens Duplicate()ed from the token
    // used to create this BufferCollection.
    OnDuplicatedTokensKnownByServer();

    // This event inidicates that buffer allocation is over, whether succesful
    // or failed.
    //
    // This event will eventually be sent by the server (unless the
    // BufferCollection channel closes first).
    //
    // |status|:
    // |ZX_OK| if successful.
    // |ZX_ERR_NO_MEMORY| if the request is valid but cannot be fulfilled due to
    // resource exhaustion.
    // |ZX_ERR_ACCESS_DENIED| if the caller is not permitted to obtain the
    // buffers it requested.
    // |ZX_ERR_INVALID_ARGS| if the request is malformed.
    // |ZX_ERR_NOT_SUPPORTED| if request is valid but cannot be satisfied,
    // perhaps due to hardware limitations.
    //
    // |buffer_collection_info| The buffer information, including VMO handles.
    // If |status| is not |ZX_OK|, |buffer_collection_info| is default
    // initialized and contains no meaningful information.
    OnBuffersAllocated(zx.status status,
                       BufferCollectionInfo_2 buffer_collection_info);

    // A participant can learn when a new buffer is allocated via this event.
    // The only participant that will see a failing status is the participant
    // that attempted the single buffer allocation.  Other participants will
    // only see successful single buffer allocations.
    //
    // |status|:
    //
    // |ZX_OK| if successful.  This can be seen by any participant (whether
    // sender of AllocateSingleBuffer() or not.)
    //
    // |ZX_ERR_NOT_FOUND| if the buffer_index sent via
    // CheckSingleBufferAllocated() isn't known to the server.  This can be seen
    // by any participant (whether sender of AllocateSingleBuffer() or not.)
    //
    // These error codes are only ever seen by the sender of
    // AllocateSingleBuffer():
    //
    // |ZX_ERR_NO_MEMORY| if the request is valid but cannot be fulfilled due to
    // resource exhaustion.
    // |ZX_ERR_ACCESS_DENIED| if the caller is not permitted to obtain the
    // buffers it requested.
    // |ZX_ERR_INVALID_ARGS| if the request is malformed.
    // |ZX_ERR_NOT_SUPPORTED| if request is valid but cannot be satisfied,
    // perhaps due to hardware limitations.
    OnAllocateSingleBufferDone(zx.status status,
                               SingleBufferInfo buffer_info);
};