1 /*
2 * Copyright (C) 2008 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
18 #ifndef ANDROID_GRALLOC_INTERFACE_H
19 #define ANDROID_GRALLOC_INTERFACE_H
20
21 #include <system/window.h>
22 #include <system/graphics.h>
23 #include <hardware/hardware.h>
24
25 #include <stdint.h>
26 #include <sys/cdefs.h>
27 #include <sys/types.h>
28
29 #include <cutils/native_handle.h>
30
31 #include <hardware/hardware.h>
32 #include <hardware/fb.h>
33
34 __BEGIN_DECLS
35
36 /**
37 * Module versioning information for the Gralloc hardware module, based on
38 * gralloc_module_t.common.module_api_version.
39 *
40 * Version History:
41 *
42 * GRALLOC_MODULE_API_VERSION_0_1:
43 * Initial Gralloc hardware module API.
44 *
45 * GRALLOC_MODULE_API_VERSION_0_2:
46 * Add support for flexible YCbCr format with (*lock_ycbcr)() method.
47 *
48 * GRALLOC_MODULE_API_VERSION_0_3:
49 * Add support for fence passing to/from lock/unlock.
50 */
51
52 #define GRALLOC_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1)
53 #define GRALLOC_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2)
54 #define GRALLOC_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3)
55
56 #define GRALLOC_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION(0, 1)
57
58 /**
59 * The id of this module
60 */
61 #define GRALLOC_HARDWARE_MODULE_ID "gralloc"
62
63 /**
64 * Name of the graphics device to open
65 */
66
67 #define GRALLOC_HARDWARE_GPU0 "gpu0"
68
69 enum {
70 /* buffer is never read in software */
71 GRALLOC_USAGE_SW_READ_NEVER = 0x00000000,
72 /* buffer is rarely read in software */
73 GRALLOC_USAGE_SW_READ_RARELY = 0x00000002,
74 /* buffer is often read in software */
75 GRALLOC_USAGE_SW_READ_OFTEN = 0x00000003,
76 /* mask for the software read values */
77 GRALLOC_USAGE_SW_READ_MASK = 0x0000000F,
78
79 /* buffer is never written in software */
80 GRALLOC_USAGE_SW_WRITE_NEVER = 0x00000000,
81 /* buffer is rarely written in software */
82 GRALLOC_USAGE_SW_WRITE_RARELY = 0x00000020,
83 /* buffer is often written in software */
84 GRALLOC_USAGE_SW_WRITE_OFTEN = 0x00000030,
85 /* mask for the software write values */
86 GRALLOC_USAGE_SW_WRITE_MASK = 0x000000F0,
87
88 /* buffer will be used as an OpenGL ES texture */
89 GRALLOC_USAGE_HW_TEXTURE = 0x00000100,
90 /* buffer will be used as an OpenGL ES render target */
91 GRALLOC_USAGE_HW_RENDER = 0x00000200,
92 /* buffer will be used by the 2D hardware blitter */
93 GRALLOC_USAGE_HW_2D = 0x00000400,
94 /* buffer will be used by the HWComposer HAL module */
95 GRALLOC_USAGE_HW_COMPOSER = 0x00000800,
96 /* buffer will be used with the framebuffer device */
97 GRALLOC_USAGE_HW_FB = 0x00001000,
98 /* buffer will be used with the HW video encoder */
99 GRALLOC_USAGE_HW_VIDEO_ENCODER = 0x00010000,
100 /* buffer will be written by the HW camera pipeline */
101 GRALLOC_USAGE_HW_CAMERA_WRITE = 0x00020000,
102 /* buffer will be read by the HW camera pipeline */
103 GRALLOC_USAGE_HW_CAMERA_READ = 0x00040000,
104 /* buffer will be used as part of zero-shutter-lag queue */
105 GRALLOC_USAGE_HW_CAMERA_ZSL = 0x00060000,
106 /* mask for the camera access values */
107 GRALLOC_USAGE_HW_CAMERA_MASK = 0x00060000,
108 /* mask for the software usage bit-mask */
109 GRALLOC_USAGE_HW_MASK = 0x00071F00,
110
111 /* buffer will be used as a RenderScript Allocation */
112 GRALLOC_USAGE_RENDERSCRIPT = 0x00100000,
113
114 /* buffer should be displayed full-screen on an external display when
115 * possible
116 */
117 GRALLOC_USAGE_EXTERNAL_DISP = 0x00002000,
118
119 /* Must have a hardware-protected path to external display sink for
120 * this buffer. If a hardware-protected path is not available, then
121 * either don't composite only this buffer (preferred) to the
122 * external sink, or (less desirable) do not route the entire
123 * composition to the external sink.
124 */
125 GRALLOC_USAGE_PROTECTED = 0x00004000,
126
127 /* buffer may be used as a cursor */
128 GRALLOC_USAGE_CURSOR = 0x00008000,
129
130 /* implementation-specific private usage flags */
131 GRALLOC_USAGE_PRIVATE_0 = 0x10000000,
132 GRALLOC_USAGE_PRIVATE_1 = 0x20000000,
133 GRALLOC_USAGE_PRIVATE_2 = 0x40000000,
134 GRALLOC_USAGE_PRIVATE_3 = 0x80000000,
135 GRALLOC_USAGE_PRIVATE_MASK = 0xF0000000,
136 };
137
138 /*****************************************************************************/
139
140 /**
141 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
142 * and the fields of this data structure must begin with hw_module_t
143 * followed by module specific information.
144 */
145 typedef struct gralloc_module_t {
146 struct hw_module_t common;
147
148 /*
149 * (*registerBuffer)() must be called before a buffer_handle_t that has not
150 * been created with (*alloc_device_t::alloc)() can be used.
151 *
152 * This is intended to be used with buffer_handle_t's that have been
153 * received in this process through IPC.
154 *
155 * This function checks that the handle is indeed a valid one and prepares
156 * it for use with (*lock)() and (*unlock)().
157 *
158 * It is not necessary to call (*registerBuffer)() on a handle created
159 * with (*alloc_device_t::alloc)().
160 *
161 * returns an error if this buffer_handle_t is not valid.
162 */
163 int (*registerBuffer)(struct gralloc_module_t const* module,
164 buffer_handle_t handle);
165
166 /*
167 * (*unregisterBuffer)() is called once this handle is no longer needed in
168 * this process. After this call, it is an error to call (*lock)(),
169 * (*unlock)(), or (*registerBuffer)().
170 *
171 * This function doesn't close or free the handle itself; this is done
172 * by other means, usually through libcutils's native_handle_close() and
173 * native_handle_free().
174 *
175 * It is an error to call (*unregisterBuffer)() on a buffer that wasn't
176 * explicitly registered first.
177 */
178 int (*unregisterBuffer)(struct gralloc_module_t const* module,
179 buffer_handle_t handle);
180
181 /*
182 * The (*lock)() method is called before a buffer is accessed for the
183 * specified usage. This call may block, for instance if the h/w needs
184 * to finish rendering or if CPU caches need to be synchronized.
185 *
186 * The caller promises to modify only pixels in the area specified
187 * by (l,t,w,h).
188 *
189 * The content of the buffer outside of the specified area is NOT modified
190 * by this call.
191 *
192 * If usage specifies GRALLOC_USAGE_SW_*, vaddr is filled with the address
193 * of the buffer in virtual memory.
194 *
195 * Note calling (*lock)() on HAL_PIXEL_FORMAT_YCbCr_*_888 buffers will fail
196 * and return -EINVAL. These buffers must be locked with (*lock_ycbcr)()
197 * instead.
198 *
199 * THREADING CONSIDERATIONS:
200 *
201 * It is legal for several different threads to lock a buffer from
202 * read access, none of the threads are blocked.
203 *
204 * However, locking a buffer simultaneously for write or read/write is
205 * undefined, but:
206 * - shall not result in termination of the process
207 * - shall not block the caller
208 * It is acceptable to return an error or to leave the buffer's content
209 * into an indeterminate state.
210 *
211 * If the buffer was created with a usage mask incompatible with the
212 * requested usage flags here, -EINVAL is returned.
213 *
214 */
215
216 int (*lock)(struct gralloc_module_t const* module,
217 buffer_handle_t handle, int usage,
218 int l, int t, int w, int h,
219 void** vaddr);
220
221
222 /*
223 * The (*unlock)() method must be called after all changes to the buffer
224 * are completed.
225 */
226
227 int (*unlock)(struct gralloc_module_t const* module,
228 buffer_handle_t handle);
229
230
231 /* reserved for future use */
232 int (*perform)(struct gralloc_module_t const* module,
233 int operation, ... );
234
235 /*
236 * The (*lock_ycbcr)() method is like the (*lock)() method, with the
237 * difference that it fills a struct ycbcr with a description of the buffer
238 * layout, and zeroes out the reserved fields.
239 *
240 * This will only work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888, and
241 * will return -EINVAL on any other buffer formats.
242 *
243 * Added in GRALLOC_MODULE_API_VERSION_0_2.
244 */
245
246 int (*lock_ycbcr)(struct gralloc_module_t const* module,
247 buffer_handle_t handle, int usage,
248 int l, int t, int w, int h,
249 struct android_ycbcr *ycbcr);
250
251 /*
252 * The (*lockAsync)() method is like the (*lock)() method except
253 * that the buffer's sync fence object is passed into the lock
254 * call instead of requiring the caller to wait for completion.
255 *
256 * The gralloc implementation takes ownership of the fenceFd and
257 * is responsible for closing it when no longer needed.
258 *
259 * Added in GRALLOC_MODULE_API_VERSION_0_3.
260 */
261 int (*lockAsync)(struct gralloc_module_t const* module,
262 buffer_handle_t handle, int usage,
263 int l, int t, int w, int h,
264 void** vaddr, int fenceFd);
265
266 /*
267 * The (*unlockAsync)() method is like the (*unlock)() method
268 * except that a buffer sync fence object is returned from the
269 * lock call, representing the completion of any pending work
270 * performed by the gralloc implementation.
271 *
272 * The caller takes ownership of the fenceFd and is responsible
273 * for closing it when no longer needed.
274 *
275 * Added in GRALLOC_MODULE_API_VERSION_0_3.
276 */
277 int (*unlockAsync)(struct gralloc_module_t const* module,
278 buffer_handle_t handle, int* fenceFd);
279
280 /*
281 * The (*lockAsync_ycbcr)() method is like the (*lock_ycbcr)()
282 * method except that the buffer's sync fence object is passed
283 * into the lock call instead of requiring the caller to wait for
284 * completion.
285 *
286 * The gralloc implementation takes ownership of the fenceFd and
287 * is responsible for closing it when no longer needed.
288 *
289 * Added in GRALLOC_MODULE_API_VERSION_0_3.
290 */
291 int (*lockAsync_ycbcr)(struct gralloc_module_t const* module,
292 buffer_handle_t handle, int usage,
293 int l, int t, int w, int h,
294 struct android_ycbcr *ycbcr, int fenceFd);
295
296 /* reserved for future use */
297 void* reserved_proc[3];
298 } gralloc_module_t;
299
300 /*****************************************************************************/
301
302 /**
303 * Every device data structure must begin with hw_device_t
304 * followed by module specific public methods and attributes.
305 */
306
307 typedef struct alloc_device_t {
308 struct hw_device_t common;
309
310 /*
311 * (*alloc)() Allocates a buffer in graphic memory with the requested
312 * parameters and returns a buffer_handle_t and the stride in pixels to
313 * allow the implementation to satisfy hardware constraints on the width
314 * of a pixmap (eg: it may have to be multiple of 8 pixels).
315 * The CALLER TAKES OWNERSHIP of the buffer_handle_t.
316 *
317 * If format is HAL_PIXEL_FORMAT_YCbCr_420_888, the returned stride must be
318 * 0, since the actual strides are available from the android_ycbcr
319 * structure.
320 *
321 * Returns 0 on success or -errno on error.
322 */
323
324 int (*alloc)(struct alloc_device_t* dev,
325 int w, int h, int format, int usage,
326 buffer_handle_t* handle, int* stride);
327
328 /*
329 * (*free)() Frees a previously allocated buffer.
330 * Behavior is undefined if the buffer is still mapped in any process,
331 * but shall not result in termination of the program or security breaches
332 * (allowing a process to get access to another process' buffers).
333 * THIS FUNCTION TAKES OWNERSHIP of the buffer_handle_t which becomes
334 * invalid after the call.
335 *
336 * Returns 0 on success or -errno on error.
337 */
338 int (*free)(struct alloc_device_t* dev,
339 buffer_handle_t handle);
340
341 /* This hook is OPTIONAL.
342 *
343 * If non NULL it will be caused by SurfaceFlinger on dumpsys
344 */
345 void (*dump)(struct alloc_device_t *dev, char *buff, int buff_len);
346
347 void* reserved_proc[7];
348 } alloc_device_t;
349
350
351 /** convenience API for opening and closing a supported device */
352
gralloc_open(const struct hw_module_t * module,struct alloc_device_t ** device)353 static inline int gralloc_open(const struct hw_module_t* module,
354 struct alloc_device_t** device) {
355 return module->methods->open(module,
356 GRALLOC_HARDWARE_GPU0, (struct hw_device_t**)device);
357 }
358
gralloc_close(struct alloc_device_t * device)359 static inline int gralloc_close(struct alloc_device_t* device) {
360 return device->common.close(&device->common);
361 }
362
363 __END_DECLS
364
365 #endif // ANDROID_GRALLOC_INTERFACE_H
366