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