1 /*
2  * Copyright 2015 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 
17 #ifndef ANDROID_HARDWARE_GRALLOC1_H
18 #define ANDROID_HARDWARE_GRALLOC1_H
19 
20 #include <hardware/hardware.h>
21 #include <system/window.h>
22 
23 __BEGIN_DECLS
24 
25 #define GRALLOC_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
26 #define GRALLOC_HARDWARE_MODULE_ID "gralloc"
27 
28 /*
29  * Enums
30  */
31 
32 typedef enum {
33     GRALLOC1_CAPABILITY_INVALID = 0,
34 
35     /* If this capability is supported, then the outBuffers parameter to
36      * allocate may be NULL, which instructs the device to report whether the
37      * given allocation is possible or not. */
38     GRALLOC1_CAPABILITY_TEST_ALLOCATE = 1,
39 
40     /* If this capability is supported, then the implementation supports
41      * allocating buffers with more than one image layer. */
42     GRALLOC1_CAPABILITY_LAYERED_BUFFERS = 2,
43 
44     /* If this capability is supported, then the implementation always closes
45      * and deletes a buffer handle whenever the last reference is removed.
46      *
47      * Supporting this capability is strongly recommended.  It will become
48      * mandatory in future releases. */
49     GRALLOC1_CAPABILITY_RELEASE_IMPLY_DELETE = 3,
50 
51     GRALLOC1_LAST_CAPABILITY = 3,
52 } gralloc1_capability_t;
53 
54 typedef enum {
55     GRALLOC1_CONSUMER_USAGE_NONE = 0,
56     GRALLOC1_CONSUMER_USAGE_CPU_READ_NEVER = 0,
57     /* 1ULL << 0 */
58     GRALLOC1_CONSUMER_USAGE_CPU_READ = 1ULL << 1,
59     GRALLOC1_CONSUMER_USAGE_CPU_READ_OFTEN = 1ULL << 2 |
60             GRALLOC1_CONSUMER_USAGE_CPU_READ,
61     /* 1ULL << 3 */
62     /* 1ULL << 4 */
63     /* 1ULL << 5 */
64     /* 1ULL << 6 */
65     /* 1ULL << 7 */
66     GRALLOC1_CONSUMER_USAGE_GPU_TEXTURE = 1ULL << 8,
67     /* 1ULL << 9 */
68     /* 1ULL << 10 */
69     GRALLOC1_CONSUMER_USAGE_HWCOMPOSER = 1ULL << 11,
70     GRALLOC1_CONSUMER_USAGE_CLIENT_TARGET = 1ULL << 12,
71     /* 1ULL << 13 */
72     /* 1ULL << 14 */
73     GRALLOC1_CONSUMER_USAGE_CURSOR = 1ULL << 15,
74     GRALLOC1_CONSUMER_USAGE_VIDEO_ENCODER = 1ULL << 16,
75     /* 1ULL << 17 */
76     GRALLOC1_CONSUMER_USAGE_CAMERA = 1ULL << 18,
77     /* 1ULL << 19 */
78     GRALLOC1_CONSUMER_USAGE_RENDERSCRIPT = 1ULL << 20,
79 
80     /* Indicates that the consumer may attach buffers to their end of the
81      * BufferQueue, which means that the producer may never have seen a given
82      * dequeued buffer before. May be ignored by the gralloc device. */
83     GRALLOC1_CONSUMER_USAGE_FOREIGN_BUFFERS = 1ULL << 21,
84 
85     /* 1ULL << 22 */
86     GRALLOC1_CONSUMER_USAGE_GPU_DATA_BUFFER = 1ULL << 23,
87     /* 1ULL << 24 */
88     /* 1ULL << 25 */
89     /* 1ULL << 26 */
90     /* 1ULL << 27 */
91 
92     /* Bits reserved for implementation-specific usage flags */
93     GRALLOC1_CONSUMER_USAGE_PRIVATE_0 = 1ULL << 28,
94     GRALLOC1_CONSUMER_USAGE_PRIVATE_1 = 1ULL << 29,
95     GRALLOC1_CONSUMER_USAGE_PRIVATE_2 = 1ULL << 30,
96     GRALLOC1_CONSUMER_USAGE_PRIVATE_3 = 1ULL << 31,
97 
98     /* 1ULL << 32 */
99     /* 1ULL << 33 */
100     /* 1ULL << 34 */
101     /* 1ULL << 35 */
102     /* 1ULL << 36 */
103     /* 1ULL << 37 */
104     /* 1ULL << 38 */
105     /* 1ULL << 39 */
106     /* 1ULL << 40 */
107     /* 1ULL << 41 */
108     /* 1ULL << 42 */
109     /* 1ULL << 43 */
110     /* 1ULL << 44 */
111     /* 1ULL << 45 */
112     /* 1ULL << 46 */
113     /* 1ULL << 47 */
114 
115     /* Bits reserved for implementation-specific usage flags */
116     GRALLOC1_CONSUMER_USAGE_PRIVATE_19 = 1ULL << 48,
117     GRALLOC1_CONSUMER_USAGE_PRIVATE_18 = 1ULL << 49,
118     GRALLOC1_CONSUMER_USAGE_PRIVATE_17 = 1ULL << 50,
119     GRALLOC1_CONSUMER_USAGE_PRIVATE_16 = 1ULL << 51,
120     GRALLOC1_CONSUMER_USAGE_PRIVATE_15 = 1ULL << 52,
121     GRALLOC1_CONSUMER_USAGE_PRIVATE_14 = 1ULL << 53,
122     GRALLOC1_CONSUMER_USAGE_PRIVATE_13 = 1ULL << 54,
123     GRALLOC1_CONSUMER_USAGE_PRIVATE_12 = 1ULL << 55,
124     GRALLOC1_CONSUMER_USAGE_PRIVATE_11 = 1ULL << 56,
125     GRALLOC1_CONSUMER_USAGE_PRIVATE_10 = 1ULL << 57,
126     GRALLOC1_CONSUMER_USAGE_PRIVATE_9 = 1ULL << 58,
127     GRALLOC1_CONSUMER_USAGE_PRIVATE_8 = 1ULL << 59,
128     GRALLOC1_CONSUMER_USAGE_PRIVATE_7 = 1ULL << 60,
129     GRALLOC1_CONSUMER_USAGE_PRIVATE_6 = 1ULL << 61,
130     GRALLOC1_CONSUMER_USAGE_PRIVATE_5 = 1ULL << 62,
131     GRALLOC1_CONSUMER_USAGE_PRIVATE_4 = 1ULL << 63,
132 } gralloc1_consumer_usage_t;
133 
134 typedef enum {
135     GRALLOC1_FUNCTION_INVALID = 0,
136     GRALLOC1_FUNCTION_DUMP = 1,
137     GRALLOC1_FUNCTION_CREATE_DESCRIPTOR = 2,
138     GRALLOC1_FUNCTION_DESTROY_DESCRIPTOR = 3,
139     GRALLOC1_FUNCTION_SET_CONSUMER_USAGE = 4,
140     GRALLOC1_FUNCTION_SET_DIMENSIONS = 5,
141     GRALLOC1_FUNCTION_SET_FORMAT = 6,
142     GRALLOC1_FUNCTION_SET_PRODUCER_USAGE = 7,
143     GRALLOC1_FUNCTION_GET_BACKING_STORE = 8,
144     GRALLOC1_FUNCTION_GET_CONSUMER_USAGE = 9,
145     GRALLOC1_FUNCTION_GET_DIMENSIONS = 10,
146     GRALLOC1_FUNCTION_GET_FORMAT = 11,
147     GRALLOC1_FUNCTION_GET_PRODUCER_USAGE = 12,
148     GRALLOC1_FUNCTION_GET_STRIDE = 13,
149     GRALLOC1_FUNCTION_ALLOCATE = 14,
150     GRALLOC1_FUNCTION_RETAIN = 15,
151     GRALLOC1_FUNCTION_RELEASE = 16,
152     GRALLOC1_FUNCTION_GET_NUM_FLEX_PLANES = 17,
153     GRALLOC1_FUNCTION_LOCK = 18,
154     GRALLOC1_FUNCTION_LOCK_FLEX = 19,
155     GRALLOC1_FUNCTION_UNLOCK = 20,
156     GRALLOC1_FUNCTION_SET_LAYER_COUNT = 21,
157     GRALLOC1_FUNCTION_GET_LAYER_COUNT = 22,
158     GRALLOC1_LAST_FUNCTION = 22,
159 } gralloc1_function_descriptor_t;
160 
161 typedef enum {
162     GRALLOC1_ERROR_NONE = 0,
163     GRALLOC1_ERROR_BAD_DESCRIPTOR = 1,
164     GRALLOC1_ERROR_BAD_HANDLE = 2,
165     GRALLOC1_ERROR_BAD_VALUE = 3,
166     GRALLOC1_ERROR_NOT_SHARED = 4,
167     GRALLOC1_ERROR_NO_RESOURCES = 5,
168     GRALLOC1_ERROR_UNDEFINED = 6,
169     GRALLOC1_ERROR_UNSUPPORTED = 7,
170 } gralloc1_error_t;
171 
172 typedef enum {
173     GRALLOC1_PRODUCER_USAGE_NONE = 0,
174     GRALLOC1_PRODUCER_USAGE_CPU_WRITE_NEVER = 0,
175     /* 1ULL << 0 */
176     GRALLOC1_PRODUCER_USAGE_CPU_READ = 1ULL << 1,
177     GRALLOC1_PRODUCER_USAGE_CPU_READ_OFTEN = 1ULL << 2 |
178             GRALLOC1_PRODUCER_USAGE_CPU_READ,
179     /* 1ULL << 3 */
180     /* 1ULL << 4 */
181     GRALLOC1_PRODUCER_USAGE_CPU_WRITE = 1ULL << 5,
182     GRALLOC1_PRODUCER_USAGE_CPU_WRITE_OFTEN = 1ULL << 6 |
183             GRALLOC1_PRODUCER_USAGE_CPU_WRITE,
184     /* 1ULL << 7 */
185     /* 1ULL << 8 */
186     GRALLOC1_PRODUCER_USAGE_GPU_RENDER_TARGET = 1ULL << 9,
187     /* 1ULL << 10 */
188     /* 1ULL << 11 */
189     /* 1ULL << 12 */
190     /* 1ULL << 13 */
191 
192     /* The consumer must have a hardware-protected path to an external display
193      * sink for this buffer. If a hardware-protected path is not available, then
194      * do not attempt to display this buffer. */
195     GRALLOC1_PRODUCER_USAGE_PROTECTED = 1ULL << 14,
196 
197     /* 1ULL << 15 */
198     /* 1ULL << 16 */
199     GRALLOC1_PRODUCER_USAGE_CAMERA = 1ULL << 17,
200     /* 1ULL << 18 */
201     /* 1ULL << 19 */
202     /* 1ULL << 20 */
203     /* 1ULL << 21 */
204     GRALLOC1_PRODUCER_USAGE_VIDEO_DECODER = 1ULL << 22,
205     GRALLOC1_PRODUCER_USAGE_SENSOR_DIRECT_DATA = 1ULL << 23,
206     /* 1ULL << 24 */
207     /* 1ULL << 25 */
208     /* 1ULL << 26 */
209     /* 1ULL << 27 */
210 
211     /* Bits reserved for implementation-specific usage flags */
212     GRALLOC1_PRODUCER_USAGE_PRIVATE_0 = 1ULL << 28,
213     GRALLOC1_PRODUCER_USAGE_PRIVATE_1 = 1ULL << 29,
214     GRALLOC1_PRODUCER_USAGE_PRIVATE_2 = 1ULL << 30,
215     GRALLOC1_PRODUCER_USAGE_PRIVATE_3 = 1ULL << 31,
216 
217     /* 1ULL << 32 */
218     /* 1ULL << 33 */
219     /* 1ULL << 34 */
220     /* 1ULL << 35 */
221     /* 1ULL << 36 */
222     /* 1ULL << 37 */
223     /* 1ULL << 38 */
224     /* 1ULL << 39 */
225     /* 1ULL << 40 */
226     /* 1ULL << 41 */
227     /* 1ULL << 42 */
228     /* 1ULL << 43 */
229     /* 1ULL << 44 */
230     /* 1ULL << 45 */
231     /* 1ULL << 46 */
232     /* 1ULL << 47 */
233 
234     /* Bits reserved for implementation-specific usage flags */
235     GRALLOC1_PRODUCER_USAGE_PRIVATE_19 = 1ULL << 48,
236     GRALLOC1_PRODUCER_USAGE_PRIVATE_18 = 1ULL << 49,
237     GRALLOC1_PRODUCER_USAGE_PRIVATE_17 = 1ULL << 50,
238     GRALLOC1_PRODUCER_USAGE_PRIVATE_16 = 1ULL << 51,
239     GRALLOC1_PRODUCER_USAGE_PRIVATE_15 = 1ULL << 52,
240     GRALLOC1_PRODUCER_USAGE_PRIVATE_14 = 1ULL << 53,
241     GRALLOC1_PRODUCER_USAGE_PRIVATE_13 = 1ULL << 54,
242     GRALLOC1_PRODUCER_USAGE_PRIVATE_12 = 1ULL << 55,
243     GRALLOC1_PRODUCER_USAGE_PRIVATE_11 = 1ULL << 56,
244     GRALLOC1_PRODUCER_USAGE_PRIVATE_10 = 1ULL << 57,
245     GRALLOC1_PRODUCER_USAGE_PRIVATE_9 = 1ULL << 58,
246     GRALLOC1_PRODUCER_USAGE_PRIVATE_8 = 1ULL << 59,
247     GRALLOC1_PRODUCER_USAGE_PRIVATE_7 = 1ULL << 60,
248     GRALLOC1_PRODUCER_USAGE_PRIVATE_6 = 1ULL << 61,
249     GRALLOC1_PRODUCER_USAGE_PRIVATE_5 = 1ULL << 62,
250     GRALLOC1_PRODUCER_USAGE_PRIVATE_4 = 1ULL << 63,
251 } gralloc1_producer_usage_t;
252 
253 /*
254  * Typedefs
255  */
256 
257 typedef void (*gralloc1_function_pointer_t)();
258 
259 typedef uint64_t gralloc1_backing_store_t;
260 typedef uint64_t gralloc1_buffer_descriptor_t;
261 
262 /*
263  * Device Struct
264  */
265 
266 typedef struct gralloc1_device {
267     /* Must be the first member of this struct, since a pointer to this struct
268      * will be generated by casting from a hw_device_t* */
269     struct hw_device_t common;
270 
271     /* getCapabilities(..., outCount, outCapabilities)
272      *
273      * Provides a list of capabilities (described in the definition of
274      * gralloc1_capability_t above) supported by this device. This list must not
275      * change after the device has been loaded.
276      *
277      * Parameters:
278      *   outCount - if outCapabilities was NULL, the number of capabilities
279      *       which would have been returned; if outCapabilities was not NULL,
280      *       the number of capabilities returned, which must not exceed the
281      *       value stored in outCount prior to the call
282      *   outCapabilities - a list of capabilities supported by this device; may
283      *       be NULL, in which case this function must write into outCount the
284      *       number of capabilities which would have been written into
285      *       outCapabilities
286      */
287     void (*getCapabilities)(struct gralloc1_device* device, uint32_t* outCount,
288             int32_t* /*gralloc1_capability_t*/ outCapabilities);
289 
290     /* getFunction(..., descriptor)
291      *
292      * Returns a function pointer which implements the requested description.
293      *
294      * Parameters:
295      *   descriptor - the function to return
296      *
297      * Returns either a function pointer implementing the requested descriptor
298      *   or NULL if the described function is not supported by this device.
299      */
300     gralloc1_function_pointer_t (*getFunction)(struct gralloc1_device* device,
301             int32_t /*gralloc1_function_descriptor_t*/ descriptor);
302 } gralloc1_device_t;
303 
gralloc1_open(const struct hw_module_t * module,gralloc1_device_t ** device)304 static inline int gralloc1_open(const struct hw_module_t* module,
305         gralloc1_device_t** device) {
306     return module->methods->open(module, GRALLOC_HARDWARE_MODULE_ID,
307             TO_HW_DEVICE_T_OPEN(device));
308 }
309 
gralloc1_close(gralloc1_device_t * device)310 static inline int gralloc1_close(gralloc1_device_t* device) {
311     return device->common.close(&device->common);
312 }
313 
314 /* dump(..., outSize, outBuffer)
315  * Function descriptor: GRALLOC1_FUNCTION_DUMP
316  * Must be provided by all gralloc1 devices
317  *
318  * Retrieves implementation-defined debug information, which will be displayed
319  * during, for example, `dumpsys SurfaceFlinger`.
320  *
321  * If called with outBuffer == NULL, the device should store a copy of the
322  * desired output and return its length in bytes in outSize. If the device
323  * already has a stored copy, that copy should be purged and replaced with a
324  * fresh copy.
325  *
326  * If called with outBuffer != NULL, the device should copy its stored version
327  * of the output into outBuffer and store how many bytes of data it copied into
328  * outSize. Prior to this call, the client will have populated outSize with the
329  * maximum number of bytes outBuffer can hold. The device must not write more
330  * than this amount into outBuffer. If the device does not currently have a
331  * stored copy, then it should return 0 in outSize.
332  *
333  * Any data written into outBuffer need not be null-terminated.
334  *
335  * Parameters:
336  *   outSize - if outBuffer was NULL, the number of bytes needed to copy the
337  *       device's stored output; if outBuffer was not NULL, the number of bytes
338  *       written into it, which must not exceed the value stored in outSize
339  *       prior to the call; pointer will be non-NULL
340  *   outBuffer - the buffer to write the dump output into; may be NULL as
341  *       described above; data written into this buffer need not be
342  *       null-terminated
343  */
344 typedef void (*GRALLOC1_PFN_DUMP)(gralloc1_device_t* device, uint32_t* outSize,
345         char* outBuffer);
346 
347 /*
348  * Buffer descriptor lifecycle functions
349  *
350  * All of these functions take as their first parameter a device pointer, so
351  * this parameter is omitted from the described parameter lists.
352  */
353 
354 /* createDescriptor(..., outDescriptor)
355  * Function descriptor: GRALLOC1_FUNCTION_CREATE_DESCRIPTOR
356  * Must be provided by all gralloc1 devices
357  *
358  * Creates a new, empty buffer descriptor.
359  *
360  * Parameters:
361  *   outDescriptor - the new buffer descriptor
362  *
363  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
364  *   GRALLOC1_ERROR_NO_RESOURCES - no more descriptors can currently be created
365  */
366 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_CREATE_DESCRIPTOR)(
367         gralloc1_device_t* device, gralloc1_buffer_descriptor_t* outDescriptor);
368 
369 /* destroyDescriptor(..., descriptor)
370  * Function descriptor: GRALLOC1_FUNCTION_DESTROY_DESCRIPTOR
371  * Must be provided by all gralloc1 devices
372  *
373  * Destroys an existing buffer descriptor.
374  *
375  * Parameters:
376  *   descriptor - the buffer descriptor to destroy
377  *
378  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
379  *   GRALLOC1_ERROR_BAD_DESCRIPTOR - descriptor does not refer to a valid
380  *       buffer descriptor
381  */
382 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_DESTROY_DESCRIPTOR)(
383         gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor);
384 
385 /*
386  * Buffer descriptor modification functions
387  *
388  * All of these functions take as their first two parameters a device pointer
389  * and a buffer descriptor, so these parameters are omitted from the described
390  * parameter lists.
391  */
392 
393 /* setConsumerUsage(..., usage)
394  * Function descriptor: GRALLOC1_FUNCTION_SET_CONSUMER_USAGE
395  * Must be provided by all gralloc1 devices
396  *
397  * Sets the desired consumer usage flags of the buffer.
398  *
399  * Valid usage flags can be found in the definition of gralloc1_consumer_usage_t
400  * above.
401  *
402  * Parameters:
403  *   usage - the desired consumer usage flags
404  *
405  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
406  *   GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid
407  *   GRALLOC1_ERROR_BAD_VALUE - an invalid usage flag was passed in
408  */
409 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_CONSUMER_USAGE)(
410         gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor,
411         uint64_t /*gralloc1_consumer_usage_t*/ usage);
412 
413 /* setDimensions(..., width, height)
414  * Function descriptor: GRALLOC1_FUNCTION_SET_DIMENSIONS
415  * Must be provided by all gralloc1 devices
416  *
417  * Sets the desired width and height of the buffer in pixels.
418  *
419  * The width specifies how many columns of pixels should be in the allocated
420  * buffer, but does not necessarily represent the offset in columns between the
421  * same column in adjacent rows. If this offset is required, consult getStride
422  * below.
423  *
424  * The height specifies how many rows of pixels should be in the allocated
425  * buffer.
426  *
427  * Parameters:
428  *   width - the desired width in pixels
429  *   height - the desired height in pixels
430  *
431  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
432  *   GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid
433  */
434 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_DIMENSIONS)(
435         gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor,
436         uint32_t width, uint32_t height);
437 
438 /* setFormat(..., format)
439  * Function descriptor: GRALLOC1_FUNCTION_SET_FORMAT
440  * Must be provided by all gralloc1 devices
441  *
442  * Sets the desired format of the buffer.
443  *
444  * The valid formats can be found in <system/graphics.h>.
445  *
446  * Parameters:
447  *   format - the desired format
448  *
449  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
450  *   GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid
451  *   GRALLOC1_ERROR_BAD_VALUE - format is invalid
452  */
453 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_FORMAT)(
454         gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor,
455         int32_t /*android_pixel_format_t*/ format);
456 
457 /* setLayerCount(..., layerCount)
458  * Function descriptor: GRALLOC1_FUNCTION_SET_LAYER_COUNT
459  * Must be provided by all gralloc1 devices that provide the
460  * GRALLOC1_CAPABILITY_LAYERED_BUFFERS capability.
461  *
462  * Sets the number of layers in the buffer.
463  *
464  * A buffer with multiple layers may be used as the backing store of an array
465  * texture. All layers of a buffer share the same characteristics (e.g.,
466  * dimensions, format, usage). Devices that do not support
467  * GRALLOC1_CAPABILITY_LAYERED_BUFFERS must allocate only buffers with a single
468  * layer.
469  *
470  * Parameters:
471  *   layerCount - the desired number of layers, must be non-zero
472  *
473  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
474  *   GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid
475  *   GRALLOC1_ERROR_BAD_VALUE - the layer count is invalid
476  */
477 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_LAYER_COUNT)(
478         gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor,
479         uint32_t layerCount);
480 
481 /* setProducerUsage(..., usage)
482  * Function descriptor: GRALLOC1_FUNCTION_SET_PRODUCER_USAGE
483  * Must be provided by all gralloc1 devices
484  *
485  * Sets the desired producer usage flags of the buffer.
486  *
487  * Valid usage flags can be found in the definition of gralloc1_producer_usage_t
488  * above.
489  *
490  * Parameters:
491  *   usage - the desired producer usage flags
492  *
493  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
494  *   GRALLOC1_ERROR_BAD_DESCRIPTOR - the buffer descriptor is invalid
495  *   GRALLOC1_ERROR_BAD_VALUE - an invalid usage flag was passed in
496  */
497 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_SET_PRODUCER_USAGE)(
498         gralloc1_device_t* device, gralloc1_buffer_descriptor_t descriptor,
499         uint64_t /*gralloc1_producer_usage_t*/ usage);
500 
501 /*
502  * Buffer handle query functions
503  *
504  * All of these functions take as their first two parameters a device pointer
505  * and a buffer handle, so these parameters are omitted from the described
506  * parameter lists.
507  *
508  * [1] Currently many of these functions may return GRALLOC1_ERROR_UNSUPPORTED,
509  * which means that the device is not able to retrieve the requested information
510  * from the buffer. This is necessary to enable a smooth transition from earlier
511  * versions of the gralloc HAL, but gralloc1 implementers are strongly
512  * discouraged from returning this value, as future versions of the platform
513  * code will require all of these functions to succeed given a valid handle.
514  */
515 
516 /* getBackingStore(..., outStore)
517  * Function descriptor: GRALLOC1_FUNCTION_GET_BACKING_STORE
518  * Must be provided by all gralloc1 devices
519  *
520  * Gets a value that uniquely identifies the backing store of the given buffer.
521  *
522  * Buffers which share a backing store should return the same value from this
523  * function. If the buffer is present in more than one process, the backing
524  * store value for that buffer is not required to be the same in every process.
525  *
526  * Parameters:
527  *   outStore - the backing store identifier for this buffer
528  *
529  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
530  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
531  *   GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the
532  *       backing store identifier from the buffer; see note [1] in this
533  *       section's header for more information
534  */
535 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_BACKING_STORE)(
536         gralloc1_device_t* device, buffer_handle_t buffer,
537         gralloc1_backing_store_t* outStore);
538 
539 /* getConsumerUsage(..., outUsage)
540  * Function descriptor: GRALLOC1_FUNCTION_GET_CONSUMER_USAGE
541  * Must be provided by all gralloc1 devices
542  *
543  * Gets the consumer usage flags which were used to allocate this buffer.
544  *
545  * Usage flags can be found in the definition of gralloc1_consumer_usage_t above
546  *
547  * Parameters:
548  *   outUsage - the consumer usage flags used to allocate this buffer; must be
549  *       non-NULL
550  *
551  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
552  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
553  *   GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the
554  *       dimensions from the buffer; see note [1] in this section's header for
555  *       more information
556  */
557 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_CONSUMER_USAGE)(
558         gralloc1_device_t* device, buffer_handle_t buffer,
559         uint64_t* /*gralloc1_consumer_usage_t*/ outUsage);
560 
561 /* getDimensions(..., outWidth, outHeight)
562  * Function descriptor: GRALLOC1_FUNCTION_GET_DIMENSIONS
563  * Must be provided by all gralloc1 devices
564  *
565  * Gets the width and height of the buffer in pixels.
566  *
567  * See setDimensions for more information about these values.
568  *
569  * Parameters:
570  *   outWidth - the width of the buffer in pixels, must be non-NULL
571  *   outHeight - the height of the buffer in pixels, must be non-NULL
572  *
573  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
574  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
575  *   GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the
576  *       dimensions from the buffer; see note [1] in this section's header for
577  *       more information
578  */
579 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_DIMENSIONS)(
580         gralloc1_device_t* device, buffer_handle_t buffer, uint32_t* outWidth,
581         uint32_t* outHeight);
582 
583 /* getFormat(..., outFormat)
584  * Function descriptor: GRALLOC1_FUNCTION_GET_FORMAT
585  * Must be provided by all gralloc1 devices
586  *
587  * Gets the format of the buffer.
588  *
589  * The valid formats can be found in the HAL_PIXEL_FORMAT_* enum in
590  * system/graphics.h.
591  *
592  * Parameters:
593  *   outFormat - the format of the buffer; must be non-NULL
594  *
595  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
596  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
597  *   GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the format
598  *       from the buffer; see note [1] in this section's header for more
599  *       information
600  */
601 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_FORMAT)(
602         gralloc1_device_t* device, buffer_handle_t descriptor,
603         int32_t* outFormat);
604 
605 /* getLayerCount(..., outLayerCount)
606  * Function descriptor: GRALLOC1_FUNCTION_GET_LAYER_COUNT
607  * Must be provided by all gralloc1 devices that provide the
608  * GRALLOC1_CAPABILITY_LAYERED_BUFFERS capability.
609  *
610  * Gets the number of layers of the buffer.
611  *
612  * See setLayerCount for more information about this value.
613  *
614  * Parameters:
615  *   outLayerCount - the number of layers in the image, must be non-NULL
616  *
617  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
618  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
619  *   GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the
620  *       layer count from the buffer; see note [1] in this section's header for
621  *       more information
622  */
623 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_LAYER_COUNT)(
624         gralloc1_device_t* device, buffer_handle_t buffer,
625         uint32_t* outLayerCount);
626 
627 /* getProducerUsage(..., outUsage)
628  * Function descriptor: GRALLOC1_FUNCTION_GET_PRODUCER_USAGE
629  * Must be provided by all gralloc1 devices
630  *
631  * Gets the producer usage flags which were used to allocate this buffer.
632  *
633  * Usage flags can be found in the definition of gralloc1_producer_usage_t above
634  *
635  * Parameters:
636  *   outUsage - the producer usage flags used to allocate this buffer; must be
637  *       non-NULL
638  *
639  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
640  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
641  *   GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the usage
642  *       from the buffer; see note [1] in this section's header for more
643  *       information
644  */
645 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_PRODUCER_USAGE)(
646         gralloc1_device_t* device, buffer_handle_t buffer,
647         uint64_t* /*gralloc1_producer_usage_t*/ outUsage);
648 
649 /* getStride(..., outStride)
650  * Function descriptor: GRALLOC1_FUNCTION_GET_STRIDE
651  * Must be provided by all gralloc1 devices
652  *
653  * Gets the stride of the buffer in pixels.
654  *
655  * The stride is the offset in pixel-sized elements between the same column in
656  * two adjacent rows of pixels. This may not be equal to the width of the
657  * buffer.
658  *
659  * Parameters:
660  *   outStride - the stride in pixels; must be non-NULL
661  *
662  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
663  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
664  *   GRALLOC1_ERROR_UNDEFINED - the notion of a stride is not meaningful for
665  *       this format
666  *   GRALLOC1_ERROR_UNSUPPORTED - the device is unable to retrieve the stride
667  *       from the descriptor; see note [1] in this section's header for more
668  *       information
669  */
670 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_STRIDE)(
671         gralloc1_device_t* device, buffer_handle_t buffer, uint32_t* outStride);
672 
673 /*
674  * Buffer management functions
675  */
676 
677 /* allocate(..., numDescriptors, descriptors, outBuffers)
678  * Function descriptor: GRALLOC1_FUNCTION_ALLOCATE
679  * Must be provided by all gralloc1 devices
680  *
681  * Attempts to allocate a number of buffers sharing a backing store.
682  *
683  * Each buffer will correspond to one of the descriptors passed into the
684  * function. If the device is unable to share the backing store between the
685  * buffers, it should attempt to allocate the buffers with different backing
686  * stores and return GRALLOC1_ERROR_NOT_SHARED if it is successful.
687  *
688  * If this call is successful, the client is responsible for freeing the
689  * buffer_handle_t using release() when it is finished with the buffer. It is
690  * not necessary to call retain() on the returned buffers, as they must have a
691  * reference added by the device before returning.
692  *
693  * If GRALLOC1_CAPABILITY_TEST_ALLOCATE is supported by this device, outBuffers
694  * may be NULL. In this case, the device must not attempt to allocate any
695  * buffers, but instead must return either GRALLOC1_ERROR_NONE if such an
696  * allocation is possible (ignoring potential resource contention which might
697  * lead to a GRALLOC1_ERROR_NO_RESOURCES error), GRALLOC1_ERROR_NOT_SHARED if
698  * the buffers can be allocated, but cannot share a backing store, or
699  * GRALLOC1_ERROR_UNSUPPORTED if one or more of the descriptors can never be
700  * allocated by the device.
701  *
702  * Parameters:
703  *   numDescriptors - the number of buffer descriptors, which must also be equal
704  *       to the size of the outBuffers array
705  *   descriptors - the buffer descriptors to attempt to allocate
706  *   outBuffers - the allocated buffers; must be non-NULL unless the device
707  *       supports GRALLOC1_CAPABILITY_TEST_ALLOCATE (see above), and must not be
708  *       modified by the device if allocation is unsuccessful
709  *
710  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
711  *   GRALLOC1_ERROR_BAD_DESCRIPTOR - one of the descriptors does not refer to a
712  *      valid buffer descriptor
713  *   GRALLOC1_ERROR_NOT_SHARED - allocation was successful, but required more
714  *       than one backing store to satisfy all of the buffer descriptors
715  *   GRALLOC1_ERROR_NO_RESOURCES - allocation failed because one or more of the
716  *       backing stores could not be created at this time (but this allocation
717  *       might succeed at a future time)
718  *   GRALLOC1_ERROR_UNSUPPORTED - one or more of the descriptors can never be
719  *       satisfied by the device
720  */
721 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_ALLOCATE)(
722         gralloc1_device_t* device, uint32_t numDescriptors,
723         const gralloc1_buffer_descriptor_t* descriptors,
724         buffer_handle_t* outBuffers);
725 
726 /* retain(..., buffer)
727  * Function descriptor: GRALLOC1_FUNCTION_RETAIN
728  * Must be provided by all gralloc1 devices
729  *
730  * Adds a reference to the given buffer.
731  *
732  * This function must be called when a buffer_handle_t is received from a remote
733  * process to prevent the buffer's data from being freed when the remote process
734  * releases the buffer. It may also be called to increase the reference count if
735  * two components in the same process want to interact with the buffer
736  * independently.
737  *
738  * Parameters:
739  *   buffer - the buffer to which a reference should be added
740  *
741  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
742  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
743  *   GRALLOC1_ERROR_NO_RESOURCES - it is not possible to add a reference to this
744  *       buffer at this time
745  */
746 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_RETAIN)(
747         gralloc1_device_t* device, buffer_handle_t buffer);
748 
749 /* release(..., buffer)
750  * Function descriptor: GRALLOC1_FUNCTION_RELEASE
751  * Must be provided by all gralloc1 devices
752  *
753  * Removes a reference from the given buffer.
754  *
755  * If no references remain, the buffer should be freed. When the last buffer
756  * referring to a particular backing store is freed, that backing store should
757  * also be freed.
758  *
759  * When GRALLOC1_CAPABILITY_RELEASE_IMPLY_DELETE is supported,
760  * native_handle_close and native_handle_delete must always be called by the
761  * implementation whenever the last reference is removed.  Otherwise, a call
762  * to release() will be followed by native_handle_close and native_handle_delete
763  * by the caller when the buffer is not allocated locally through allocate().
764  *
765  * Parameters:
766  *   buffer - the buffer from which a reference should be removed
767  *
768  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
769  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
770  */
771 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_RELEASE)(
772         gralloc1_device_t* device, buffer_handle_t buffer);
773 
774 /*
775  * Buffer access functions
776  *
777  * All of these functions take as their first parameter a device pointer, so
778  * this parameter is omitted from the described parameter lists.
779  */
780 
781 typedef struct gralloc1_rect {
782     int32_t left;
783     int32_t top;
784     int32_t width;
785     int32_t height;
786 } gralloc1_rect_t;
787 
788 /* getNumFlexPlanes(..., buffer, outNumPlanes)
789  * Function descriptor: GRALLOC1_FUNCTION_GET_NUM_FLEX_PLANES
790  * Must be provided by all gralloc1 devices
791  *
792  * Returns the number of flex layout planes which are needed to represent the
793  * given buffer. This may be used to efficiently allocate only as many plane
794  * structures as necessary before calling into lockFlex.
795  *
796  * If the given buffer cannot be locked as a flex format, this function may
797  * return GRALLOC1_ERROR_UNSUPPORTED (as lockFlex would).
798  *
799  * Parameters:
800  *   buffer - the buffers for which the number of planes should be queried
801  *   outNumPlanes - the number of flex planes required to describe the given
802  *       buffer; must be non-NULL
803  *
804  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
805  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
806  *   GRALLOC1_ERROR_UNSUPPORTED - the buffer's format cannot be represented in a
807  *       flex layout
808  */
809 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_GET_NUM_FLEX_PLANES)(
810         gralloc1_device_t* device, buffer_handle_t buffer,
811         uint32_t* outNumPlanes);
812 
813 /* lock(..., buffer, producerUsage, consumerUsage, accessRegion, outData,
814  *     acquireFence)
815  * Function descriptor: GRALLOC1_FUNCTION_LOCK
816  * Must be provided by all gralloc1 devices
817  *
818  * Locks the given buffer for the specified CPU usage.
819  *
820  * Exactly one of producerUsage and consumerUsage must be *_USAGE_NONE. The
821  * usage which is not *_USAGE_NONE must be one of the *_USAGE_CPU_* values, as
822  * applicable. Locking a buffer for a non-CPU usage is not supported.
823  *
824  * Locking the same buffer simultaneously from multiple threads is permitted,
825  * but if any of the threads attempt to lock the buffer for writing, the
826  * behavior is undefined, except that it must not cause process termination or
827  * block the client indefinitely. Leaving the buffer content in an indeterminate
828  * state or returning an error are both acceptable.
829  *
830  * The client must not modify the content of the buffer outside of accessRegion,
831  * and the device need not guarantee that content outside of accessRegion is
832  * valid for reading. The result of reading or writing outside of accessRegion
833  * is undefined, except that it must not cause process termination.
834  *
835  * outData must be a non-NULL pointer, the contents of which which will be
836  * filled with a pointer to the locked buffer memory. This address will
837  * represent the top-left corner of the entire buffer, even if accessRegion does
838  * not begin at the top-left corner.
839  *
840  * acquireFence is a file descriptor referring to a acquire sync fence object,
841  * which will be signaled when it is safe for the device to access the contents
842  * of the buffer (prior to locking). If it is already safe to access the buffer
843  * contents, -1 may be passed instead.
844  *
845  * Parameters:
846  *   buffer - the buffer to lock
847  *   producerUsage - the producer usage flags to request; either this or
848  *       consumerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a
849  *       CPU usage
850  *   consumerUsage - the consumer usage flags to request; either this or
851  *       producerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a
852  *       CPU usage
853  *   accessRegion - the portion of the buffer that the client intends to access;
854  *       must be non-NULL
855  *   outData - will be filled with a CPU-accessible pointer to the buffer data;
856  *       must be non-NULL
857  *   acquireFence - a sync fence file descriptor as described above
858  *
859  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
860  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
861  *   GRALLOC1_ERROR_BAD_VALUE - neither or both of producerUsage and
862  *       consumerUsage were GRALLOC1_*_USAGE_NONE, or the usage which was not
863  *       *_USAGE_NONE was not a CPU usage
864  *   GRALLOC1_ERROR_NO_RESOURCES - the buffer cannot be locked at this time, but
865  *       locking may succeed at a future time
866  *   GRALLOC1_ERROR_UNSUPPORTED - the buffer cannot be locked with the given
867  *       usage, and any future attempts at locking will also fail
868  */
869 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_LOCK)(
870         gralloc1_device_t* device, buffer_handle_t buffer,
871         uint64_t /*gralloc1_producer_usage_t*/ producerUsage,
872         uint64_t /*gralloc1_consumer_usage_t*/ consumerUsage,
873         const gralloc1_rect_t* accessRegion, void** outData,
874         int32_t acquireFence);
875 
876 /* lockFlex(..., buffer, producerUsage, consumerUsage, accessRegion,
877  *     outFlexLayout, outAcquireFence)
878  * Function descriptor: GRALLOC1_FUNCTION_LOCK_FLEX
879  * Must be provided by all gralloc1 devices
880  *
881  * This is largely the same as lock(), except that instead of returning a
882  * pointer directly to the buffer data, it returns an android_flex_layout
883  * struct describing how to access the data planes.
884  *
885  * This function must work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888 if
886  * supported by the device, as well as with any other formats requested by
887  * multimedia codecs when they are configured with a flexible-YUV-compatible
888  * color format.
889  *
890  * This function may also be called on buffers of other formats, including
891  * non-YUV formats, but if the buffer format is not compatible with a flexible
892  * representation, it may return GRALLOC1_ERROR_UNSUPPORTED.
893  *
894  * Parameters:
895  *   buffer - the buffer to lock
896  *   producerUsage - the producer usage flags to request; either this or
897  *       consumerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a
898  *       CPU usage
899  *   consumerUsage - the consumer usage flags to request; either this or
900  *       producerUsage must be GRALLOC1_*_USAGE_NONE, and the other must be a
901  *       CPU usage
902  *   accessRegion - the portion of the buffer that the client intends to access;
903  *      must be non-NULL
904  *   outFlexLayout - will be filled with the description of the planes in the
905  *       buffer
906  *   acquireFence - a sync fence file descriptor as described in lock()
907  *
908  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
909  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
910  *   GRALLOC1_ERROR_BAD_VALUE - neither or both of producerUsage and
911  *       consumerUsage were *_USAGE_NONE, or the usage which was not
912  *       *_USAGE_NONE was not a CPU usage
913  *   GRALLOC1_ERROR_NO_RESOURCES - the buffer cannot be locked at this time, but
914  *       locking may succeed at a future time
915  *   GRALLOC1_ERROR_UNSUPPORTED - the buffer cannot be locked with the given
916  *       usage, and any future attempts at locking will also fail
917  */
918 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_LOCK_FLEX)(
919         gralloc1_device_t* device, buffer_handle_t buffer,
920         uint64_t /*gralloc1_producer_usage_t*/ producerUsage,
921         uint64_t /*gralloc1_consumer_usage_t*/ consumerUsage,
922         const gralloc1_rect_t* accessRegion,
923         struct android_flex_layout* outFlexLayout, int32_t acquireFence);
924 
925 /* unlock(..., buffer, releaseFence)
926  * Function descriptor: GRALLOC1_FUNCTION_UNLOCK
927  * Must be provided by all gralloc1 devices
928  *
929  * This function indicates to the device that the client will be done with the
930  * buffer when releaseFence signals.
931  *
932  * outReleaseFence will be filled with a file descriptor referring to a release
933  * sync fence object, which will be signaled when it is safe to access the
934  * contents of the buffer (after the buffer has been unlocked). If it is already
935  * safe to access the buffer contents, then -1 may be returned instead.
936  *
937  * This function is used to unlock both buffers locked by lock() and those
938  * locked by lockFlex().
939  *
940  * Parameters:
941  *   buffer - the buffer to unlock
942  *   outReleaseFence - a sync fence file descriptor as described above
943  *
944  * Returns GRALLOC1_ERROR_NONE or one of the following errors:
945  *   GRALLOC1_ERROR_BAD_HANDLE - the buffer handle is invalid
946  */
947 typedef int32_t /*gralloc1_error_t*/ (*GRALLOC1_PFN_UNLOCK)(
948         gralloc1_device_t* device, buffer_handle_t buffer,
949         int32_t* outReleaseFence);
950 
951 __END_DECLS
952 
953 #endif
954