1// Copyright 2018 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5library fuchsia.sysmem;
6
7using zx;
8
9// Allocates system memory buffers.
10[Discoverable, Layout = "Simple"]
11interface Allocator {
12    // Allocates a collection of buffers on behalf of a single client.
13    //
14    // |bufferCount| indicates how many buffers to allocate, between 1 and 64.
15    // |spec| describes constraints for allocating buffers of some
16    // desired form.
17    // |usage| describes how the client intends to access the buffers.
18    // |collection| provides access to the allocated buffers.
19    //
20    // Returns |ZX_OK| if successful.
21    // Returns |ZX_ERR_NO_MEMORY| if the request is valid but cannot be
22    // fulfilled due to resource exhaustion.
23    // Returns |ZX_ERR_ACCESS_DENIED| if the caller is not permitted to
24    // obtain the buffers it requested.
25    // Returns |ZX_ERR_INVALID_ARGS| if the request is malformed.
26    // Returns |ZX_ERR_NOT_SUPPORTED| if request is valid but cannot be
27    // satisfied, perhaps due to hardware limitations.
28    1: AllocateCollection(uint32 buffer_count,
29                          BufferSpec spec,
30                          BufferUsage usage)
31           -> (zx.status status, BufferCollectionInfo collection);
32
33    // Allocates a collection of buffers which will be shared among one
34    // or more clients.  This operation occurs in two phases (which may
35    // happen concurrently).
36    //
37    // |bufferCount| indicates how many buffers to allocate, between 1 and 64.
38    // |spec| describes constraints for allocating buffers of some
39    // desired form.
40    // |token_peer| is one endpoint of an eventpair which forms an association
41    // between this request and calls to |BindSharedCollection()|.
42    //
43    // In the first phase, one client acts as a coordinator.  The coordinator
44    // creates an event pair and designates one endpoint as the *token* and
45    // the other endpoint as the *token peer*. The coordinator then calls
46    // |AllocateSharedCollection()|, passing the buffer request and the token
47    // peer’s handle.  It also sends a token to each client which requires
48    // access to the buffer, duplicating the token’s handle if necessary.
49    //
50    // In the second phase, each client which received a token calls
51    // |BindSharedCollection()|, passing their usages and the token.
52    // As the buffer manager handles each request, it retrieves the token’s
53    // kernel object id (KOID) and adds it to a list to be matched up with
54    // token peers from prior or subsequent calls to
55    // |AllocateSharedCollection()|.  Once matched, the token is closed
56    // and the client’s corresponding usages are associated with the
57    // token peer.
58    //
59    // This method returns once all tokens corresponding to the |token_peer|
60    // are closed and the allocation completes successfully, or an error
61    // occurs.
62    //
63    // Returns |ZX_OK| once all of the collection’s tokens have been
64    // closed and buffer allocation has completed successfully.
65    // Returns |ZX_ERR_ACCESS_DENIED| if the caller is not permitted to
66    // obtain the buffers it requested.
67    // Returns |ZX_ERR_INVALID_ARGS| if the request is malformed.
68    // Returns |ZX_ERR_NOT_SUPPORTED| if request is valid but cannot be
69    // satisfied, perhaps due to hardware limitations.
70    2: AllocateSharedCollection(uint32 buffer_count,
71                                BufferSpec spec,
72                                handle<eventpair> token_peer)
73           -> (zx.status status);
74
75    // Enlists a client into a shared collection of buffers, taking into
76    // account how the client intends to use the buffers.
77    //
78    // |usage| describes how the client intends to access the buffers.
79    // |token| is the other endpoint of an eventpair passed to
80    // |AllocateSharedCollection()|.
81    // |collection| provides access to the allocated buffers.
82    //
83    // This method returns once all other tokens for the collection are
84    // closed and the allocation completes successfully, or an error occurs.
85    //
86    // Returns |ZX_OK| once all of the collection’s tokens have been closed
87    // and buffer allocation has completed successfully.
88    // Returns |ZX_ERR_ACCESS_DENIED| if the caller is not permitted to
89    // obtain the buffers it requested.
90    // Returns |ZX_ERR_INVALID_ARGS| if the request is malformed.
91    // Returns |ZX_ERR_NOT_SUPPORTED| if request is valid but cannot be
92    // satisfied, perhaps due to hardware limitations.
93    3: BindSharedCollection(BufferUsage usage, handle<eventpair> token)
94           -> (zx.status status, BufferCollectionInfo collection);
95};
96