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