blob: c3fa131cbd82e53e52d9e97e5da9d7504cd9666d [file] [log] [blame]
// 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;
/// Allocates system memory buffers.
///
// Needs ForDeprecatedCBindings because used with "FIDL Simple C Bindings".
[Discoverable, ForDeprecatedCBindings]
protocol Allocator {
/// Allocates a BufferCollection on behalf of a single client (aka initiator)
/// who is also the only participant (from the point of view of sysmem).
///
/// This call exists mainly for temp/testing purposes. This call skips the
/// BufferCollectionToken stage, so there's no way to allow another
/// participant to specify its constraints.
///
/// Real clients are encouraged to use AllocateSharedCollection() instead,
/// and to let relevant participants directly convey their own constraints to
/// sysmem.
///
/// `collection_request` is the server end of the BufferCollection FIDL
/// channel. The client can call SetConstraints() and then
/// WaitForBuffersAllocated() on the client end of this channel to specify
/// constraints and then determine success/failure and get the
/// BufferCollectionInfo_2 for the BufferCollection. The client should also
/// keep the client end of this channel open while using the
/// BufferCollection, and should notice when this channel closes and stop
/// using the BufferCollection ASAP.
AllocateNonSharedCollection(request<BufferCollection> collection_request);
/// Creates a logical BufferCollectionToken which can be shared among
/// participants (using BufferCollectionToken.Duplicate()), and then
/// converted into a BufferCollection using BindSharedCollection().
///
/// Success/failure to populate the BufferCollection with buffers is
/// determined via the BufferCollection interface.
AllocateSharedCollection(request<BufferCollectionToken> token_request);
/// Convert a BufferCollectionToken into a connection to the logical
/// BufferCollection. The BufferCollection hasn't yet been populated with
/// buffers - the participant must first also send SetConstraints() via the
/// client end of buffer_collection.
///
/// All BufferCollectionToken(s) duplicated from a logical
/// BufferCollectionToken created via AllocateSharedCollection() must be
/// turned in via BindSharedCollection() before the logical BufferCollection
/// will be populated with buffers.
///
/// `token` the client endpoint of a channel whose server end was sent to
/// sysmem using AllocateSharedCollection or whose server end was sent to
/// sysmem using BufferCollectionToken.Duplicate(). The token is being
/// "exchanged" for a channel to the logical BufferCollection.
///
/// `buffer_collection_request` the server end of a BufferCollection
/// channel. The sender retains the client end as usual. The
/// BufferCollection channel is a single participant's connection to the
/// logical BufferCollection. There typically will be other participants
/// with their own BufferCollection channel to the logical BufferCollection.
BindSharedCollection(BufferCollectionToken token,
request<BufferCollection> buffer_collection_request);
/// Validate that a BufferCollectionToken is known to the sysmem server.
///
/// This can be used in cases where BindSharedCollection() won't be called
/// until after BufferCollectionToken.Duplicate() +
/// BufferCollectionToken.Sync(), when the client code wants to know earlier
/// whether an incoming token is valid (so far).
///
/// Calling BufferCollectionToken.Sync() on a token that isn't known to
/// sysmem risks the Sync() hanging forever.
///
/// Given that an incoming token can become invalid at any time if any
/// participant drops their BufferCollectionToken(s) or BufferCollection(s),
/// authors of client code are encouraged to consider not calling
/// ValidateBufferCollectionToken() and instead dealing with async failure
/// of the BufferCollection.Sync() after all the
/// BufferCollectionToken.Duplicate() and BindSharedCollection() (before
/// sending any duplicate tokens to other processes).
///
/// Regardless of the result of this call, this call has no effect on the
/// token with the referenced koid.
///
/// A true result from this call doesn't guarantee that the token remains
/// valid for any duration afterwards.
///
/// Client code will zx_object_get_info() on the client's token handle,
/// passing ZX_INFO_HANDLE_BASIC and getting back the related_koid
/// which then gets passed to ValidateBufferCollectionToken().
///
/// If ValidateBufferCollectionToken() returns true, the token was known at
/// the time the sysmem server processed the call, but may no longer be
/// valid/known by the time the client code receives the response.
///
/// If ValidateBufferCollectionToken() returns false, the token wasn't known
/// at the time the sysmem server processed the call, but the token may
/// become known by the time the client code receives the response. However
/// client code is not required to mitigate the possibility that the token
/// may become known late, since the source of the token should have synced
/// the token to sysmem before sending the token to the client code.
///
/// If calling ValidateBufferCollectionToken() fails in some way, there will
/// be a zx_status_t from the FIDL layer.
///
/// `token_server_koid` the koid of the server end of a channel that might
/// be a BufferCollectionToken channel. This can be obtained from
/// zx_object_get_info() ZX_INFO_HANDLE_BASIC related_koid.
ValidateBufferCollectionToken(zx.koid token_server_koid) -> (bool is_known);
/// Set information about the current client that can be used by sysmem to
/// help debug leaking memory and hangs waiting for constraints. |name| can
/// be an arbitrary string, but the current process name (see
/// fsl::GetCurrentProcessName()) is a good default. |id| can be an arbitrary
/// id, but the current process ID (see fsl::GetCurrentProcessKoid()) is a
/// good default.
/// This information is propagated to all BufferCollections created using
/// BindSharedCollection() or AllocateNonSharedCollection() from this
/// allocator. It does not affect BufferCollectionTokens, since they are
/// often passed cross-process and should have their names managed manually.
[Transitional]
SetDebugClientInfo(string:64 name, uint64 id);
};