1/*
2 * Copyright 2019 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.graphics.mapper@3.0;
18
19import android.hardware.graphics.common@1.2::BufferUsage;
20import android.hardware.graphics.common@1.2::PixelFormat;
21import android.hardware.graphics.common@1.2::Rect;
22
23interface IMapper {
24    struct BufferDescriptorInfo {
25        /**
26         * The width specifies how many columns of pixels must be in the
27         * allocated buffer, but does not necessarily represent the offset in
28         * columns between the same column in adjacent rows. The rows may be
29         * padded.
30         */
31        uint32_t width;
32
33       /**
34        * The height specifies how many rows of pixels must be in the
35        * allocated buffer.
36        */
37        uint32_t height;
38
39       /**
40        * The number of image layers that must be in the allocated buffer.
41        */
42        uint32_t layerCount;
43
44        /** Buffer pixel format. */
45        PixelFormat format;
46
47        /**
48         * Buffer usage mask; valid flags can be found in the definition of
49         * BufferUsage.
50         */
51        bitfield<BufferUsage> usage;
52    };
53
54    struct Rect {
55        int32_t left;
56        int32_t top;
57        int32_t width;
58        int32_t height;
59    };
60
61    /**
62     * Creates a buffer descriptor. The descriptor can be used with IAllocator
63     * to allocate buffers.
64     *
65     * Since the buffer descriptor fully describes a buffer, any device
66     * dependent or device independent checks must be performed here whenever
67     * possible. Specifically, when layered buffers are not supported, this
68     * function must return `UNSUPPORTED` if `description.layers` is great than
69     * 1.
70     *
71     * @param description Attributes of the descriptor.
72     * @return error Error status of the call, which may be
73     *     - `NONE` upon success.
74     *     - `BAD_VALUE` if any of the specified attributes are invalid or
75     *       inconsistent.
76     *     - `NO_RESOURCES` if the creation cannot be fullfilled due to
77     *       unavailability of resources.
78     *     - `UNSUPPORTED` when any of the specified attributes are not
79     *       supported.
80     * @return descriptor Newly created buffer descriptor.
81     */
82    createDescriptor(BufferDescriptorInfo description)
83            generates (Error error,
84                       BufferDescriptor descriptor);
85
86    /**
87     * Imports a raw buffer handle to create an imported buffer handle for use
88     * with the rest of the mapper or with other in-process libraries.
89     *
90     * A buffer handle is considered raw when it is cloned (e.g., with
91     * `native_handle_clone()`) from another buffer handle locally, or when it
92     * is received from another HAL server/client or another process. A raw
93     * buffer handle must not be used to access the underlying graphic
94     * buffer. It must be imported to create an imported handle first.
95     *
96     * This function must at least validate the raw handle before creating the
97     * imported handle. It must also support importing the same raw handle
98     * multiple times to create multiple imported handles. The imported handle
99     * must be considered valid everywhere in the process, including in
100     * another instance of the mapper.
101     *
102     * Because of passthrough HALs, a raw buffer handle received from a HAL
103     * may actually have been imported in the process. importBuffer() must treat
104     * such a handle as if it is raw and must not return `BAD_BUFFER`. The
105     * returned handle is independent from the input handle as usual, and
106     * freeBuffer() must be called on it when it is no longer needed.
107     *
108     * @param rawHandle Raw buffer handle to import.
109     * @return error Error status of the call, which may be
110     *     - `NONE` upon success.
111     *     - `BAD_BUFFER` if the raw handle is invalid.
112     *     - `NO_RESOURCES` if the raw handle cannot be imported due to
113     *       unavailability of resources.
114     * @return buffer Imported buffer handle that has the type
115     *     `buffer_handle_t` which is a handle type.
116     */
117    importBuffer(handle rawHandle) generates (Error error, pointer buffer);
118
119    /**
120     * Frees a buffer handle. Buffer handles returned by importBuffer() must be
121     * freed with this function when no longer needed.
122     *
123     * This function must free up all resources allocated by importBuffer() for
124     * the imported handle. For example, if the imported handle was created
125     * with `native_handle_create()`, this function must call
126     * `native_handle_close()` and `native_handle_delete()`.
127     *
128     * @param buffer Imported buffer handle.
129     * @return error Error status of the call, which may be
130     *     - `NONE` upon success.
131     *     - `BAD_BUFFER` if the buffer is invalid.
132     */
133    freeBuffer(pointer buffer) generates (Error error);
134
135    /**
136     * Validates that the buffer can be safely accessed by a caller who assumes
137     * the specified @p description and @p stride. This must at least validate
138     * that the buffer size is large enough. Validating the buffer against
139     * individual buffer attributes is optional.
140     *
141     * @param buffer Buffer to validate against.
142     * @param description Attributes of the buffer.
143     * @param stride Stride returned by IAllocator::allocate().
144     * @return error Error status of the call, which may be
145     *     - `NONE` upon success.
146     *     - `BAD_BUFFER` if the buffer is invalid.
147     *     - `BAD_VALUE` if the buffer cannot be safely accessed.
148     */
149    validateBufferSize(pointer buffer,
150                       BufferDescriptorInfo description,
151                       uint32_t stride)
152            generates (Error error);
153
154    /**
155     * Calculates the transport size of a buffer. An imported buffer handle is a
156     * raw buffer handle with the process-local runtime data appended. This
157     * function, for example, allows a caller to omit the process-local runtime
158     * data at the tail when serializing the imported buffer handle.
159     *
160     * Note that a client might or might not omit the process-local runtime data
161     * when sending an imported buffer handle. The mapper must support both
162     * cases on the receiving end.
163     *
164     * @param buffer Buffer to get the transport size from.
165     * @return error Error status of the call, which may be
166     *     - `NONE` upon success.
167     *     - `BAD_BUFFER` if the buffer is invalid.
168     * @return numFds The number of file descriptors needed for transport.
169     * @return numInts The number of integers needed for transport.
170     */
171    getTransportSize(pointer buffer)
172            generates (Error error,
173                       uint32_t numFds,
174                       uint32_t numInts);
175
176    /**
177     * Locks the given buffer for the specified CPU usage.
178     *
179     * Locking the same buffer simultaneously from multiple threads is
180     * permitted, but if any of the threads attempt to lock the buffer for
181     * writing, the behavior is undefined, except that it must not cause
182     * process termination or block the client indefinitely. Leaving the
183     * buffer content in an indeterminate state or returning an error are both
184     * acceptable.
185     *
186     * 1D buffers (width = size in bytes, height = 1, pixel_format = BLOB) must
187     * "lock in place". The buffers must be directly accessible via mapping.
188     *
189     * The client must not modify the content of the buffer outside of
190     * @p accessRegion, and the device need not guarantee that content outside
191     * of @p accessRegion is valid for reading. The result of reading or writing
192     * outside of @p accessRegion is undefined, except that it must not cause
193     * process termination.
194     *
195     * On success, @p data must be filled with a pointer to the locked buffer
196     * memory. This address will represent the top-left corner of the entire
197     * buffer, even if @p accessRegion does not begin at the top-left corner.
198     *
199     * On success, bytesPerPixel must contain the number of bytes per pixel in
200     * the buffer. If the bytesPerPixel is unknown or variable, a value of -1
201     * should be returned. bytesPerStride must contain the bytes per stride of
202     * the buffer. If the bytesPerStride is unknown or variable, a value of -1
203     * should be returned.
204     *
205     * @param buffer Buffer to lock.
206     * @param cpuUsage CPU usage flags to request. See +ndk
207     *     libnativewindow#AHardwareBuffer_UsageFlags for possible values.
208     * @param accessRegion Portion of the buffer that the client intends to
209     *     access.
210     * @param acquireFence Handle containing a file descriptor referring to a
211     *     sync fence object, which will be signaled when it is safe for the
212     *     mapper to lock the buffer. @p acquireFence may be an empty fence if
213     *     it is already safe to lock.
214     * @return error Error status of the call, which may be
215     *     - `NONE` upon success.
216     *     - `BAD_BUFFER` if the buffer is invalid or is incompatible with this
217     *       function.
218     *     - `BAD_VALUE` if @p cpuUsage is 0, contains non-CPU usage flags, or
219     *       is incompatible with the buffer.
220     *     - `NO_RESOURCES` if the buffer cannot be locked at this time. Note
221     *       that locking may succeed at a later time.
222     * @return data CPU-accessible pointer to the buffer data.
223     * @return bytesPerPixel the number of bytes per pixel in the buffer
224     * @return bytesPerStride the number of bytes per stride of the buffer
225     */
226    lock(pointer buffer,
227         uint64_t cpuUsage,
228         Rect accessRegion,
229         handle acquireFence)
230            generates (Error error,
231                       pointer data,
232                       int32_t bytesPerPixel,
233                       int32_t bytesPerStride);
234
235    /**
236     * Locks a YCbCr buffer for the specified CPU usage.
237     *
238     * This is largely the same as lock(), except that instead of returning a
239     * pointer directly to the buffer data, it returns a `YCbCrLayout` struct
240     * describing how to access the data planes.
241     *
242     * This function must work on buffers with
243     * `AHARDWAREBUFFER_FORMAT_Y8Cb8Cr8_*` if supported by the device, as well
244     * as with any other formats requested by multimedia codecs when they are
245     * configured with a flexible-YUV-compatible color format.
246     *
247     * @param buffer Buffer to lock.
248     * @param cpuUsage CPU usage flags to request. See +ndk
249     *     libnativewindow#AHardwareBuffer_UsageFlags for possible values.
250     * @param accessRegion Portion of the buffer that the client intends to
251     *     access.
252     * @param acquireFence Handle containing a file descriptor referring to a
253     *     sync fence object, which will be signaled when it is safe for the
254     *     mapper to lock the buffer. @p acquireFence may be empty if it is
255     *     already safe to lock.
256     * @return error Error status of the call, which may be
257     *     - `NONE` upon success.
258     *     - `BAD_BUFFER` if the buffer is invalid or is incompatible with this
259     *       function.
260     *     - `BAD_VALUE` if @p cpuUsage is 0, contains non-CPU usage flags, or
261     *       is incompatible with the buffer.
262     *     - `NO_RESOURCES` if the buffer cannot be locked at this time. Note
263     *       that locking may succeed at a later time.
264     * @return layout Data layout of the locked buffer.
265     */
266    lockYCbCr(pointer buffer,
267              uint64_t cpuUsage,
268              Rect accessRegion,
269              handle acquireFence)
270            generates (Error error,
271                       YCbCrLayout layout);
272
273    /**
274     * Unlocks a buffer to indicate all CPU accesses to the buffer have
275     * completed.
276     *
277     * @param buffer Buffer to unlock.
278     * @return error Error status of the call, which may be
279     *     - `NONE` upon success.
280     *     - `BAD_BUFFER` if the buffer is invalid or not locked.
281     * @return releaseFence Handle containing a file descriptor referring to a
282     *     sync fence object. The sync fence object will be signaled when the
283     *     mapper has completed any pending work. @p releaseFence may be an
284     *     empty fence.
285     */
286    unlock(pointer buffer) generates (Error error, handle releaseFence);
287
288    /**
289     * Test whether the given BufferDescriptorInfo is allocatable.
290     *
291     * If this function returns true, it means that a buffer with the given
292     * description can be allocated on this implementation, unless resource
293     * exhaustion occurs. If this function returns false, it means that the
294     * allocation of the given description will never succeed.
295     *
296     * @param description the description of the buffer
297     * @return supported whether the description is supported
298     */
299    isSupported(BufferDescriptorInfo description)
300            generates (Error error,
301                       bool supported);
302
303};
304
305