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 <cutils/native_handle.h> 22 23 #include <hardware/hardware.h> 24 25 #include <stdint.h> 26 #include <sys/cdefs.h> 27 #include <sys/types.h> 28 29 __BEGIN_DECLS 30 31 /** 32 * The id of this module 33 */ 34 #define GRALLOC_HARDWARE_MODULE_ID "gralloc" 35 36 /** 37 * Name of the graphics device to open 38 */ 39 40 #define GRALLOC_HARDWARE_FB0 "fb0" 41 #define GRALLOC_HARDWARE_GPU0 "gpu0" 42 43 enum { 44 /* buffer is never read in software */ 45 GRALLOC_USAGE_SW_READ_NEVER = 0x00000000, 46 /* buffer is rarely read in software */ 47 GRALLOC_USAGE_SW_READ_RARELY = 0x00000002, 48 /* buffer is often read in software */ 49 GRALLOC_USAGE_SW_READ_OFTEN = 0x00000003, 50 /* mask for the software read values */ 51 GRALLOC_USAGE_SW_READ_MASK = 0x0000000F, 52 53 /* buffer is never written in software */ 54 GRALLOC_USAGE_SW_WRITE_NEVER = 0x00000000, 55 /* buffer is never written in software */ 56 GRALLOC_USAGE_SW_WRITE_RARELY = 0x00000020, 57 /* buffer is never written in software */ 58 GRALLOC_USAGE_SW_WRITE_OFTEN = 0x00000030, 59 /* mask for the software write values */ 60 GRALLOC_USAGE_SW_WRITE_MASK = 0x000000F0, 61 62 /* buffer will be used as an OpenGL ES texture */ 63 GRALLOC_USAGE_HW_TEXTURE = 0x00000100, 64 /* buffer will be used as an OpenGL ES render target */ 65 GRALLOC_USAGE_HW_RENDER = 0x00000200, 66 /* buffer will be used by the 2D hardware blitter */ 67 GRALLOC_USAGE_HW_2D = 0x00000400, 68 /* buffer will be used with the framebuffer device */ 69 GRALLOC_USAGE_HW_FB = 0x00001000, 70 /* mask for the software usage bit-mask */ 71 GRALLOC_USAGE_HW_MASK = 0x00001F00, 72 73 /* implementation-specific private usage flags */ 74 GRALLOC_USAGE_PRIVATE_0 = 0x10000000, 75 GRALLOC_USAGE_PRIVATE_1 = 0x20000000, 76 GRALLOC_USAGE_PRIVATE_2 = 0x40000000, 77 GRALLOC_USAGE_PRIVATE_3 = 0x80000000, 78 GRALLOC_USAGE_PRIVATE_MASK = 0xF0000000, 79 }; 80 81 /*****************************************************************************/ 82 83 typedef const native_handle* buffer_handle_t; 84 85 enum { 86 /* FIXME: this only exists to work-around some issues with 87 * the video and camera frameworks. don't implement unless 88 * you know what you're doing. 89 */ 90 GRALLOC_MODULE_PERFORM_CREATE_HANDLE_FROM_BUFFER = 0x080000001, 91 }; 92 93 /** 94 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 95 * and the fields of this data structure must begin with hw_module_t 96 * followed by module specific information. 97 */ 98 typedef struct gralloc_module_t { 99 struct hw_module_t common; 100 101 /* 102 * (*registerBuffer)() must be called before a buffer_handle_t that has not 103 * been created with (*alloc_device_t::alloc)() can be used. 104 * 105 * This is intended to be used with buffer_handle_t's that have been 106 * received in this process through IPC. 107 * 108 * This function checks that the handle is indeed a valid one and prepares 109 * it for use with (*lock)() and (*unlock)(). 110 * 111 * It is not necessary to call (*registerBuffer)() on a handle created 112 * with (*alloc_device_t::alloc)(). 113 * 114 * returns an error if this buffer_handle_t is not valid. 115 */ 116 int (*registerBuffer)(struct gralloc_module_t const* module, 117 buffer_handle_t handle); 118 119 /* 120 * (*unregisterBuffer)() is called once this handle is no longer needed in 121 * this process. After this call, it is an error to call (*lock)(), 122 * (*unlock)(), or (*registerBuffer)(). 123 * 124 * This function doesn't close or free the handle itself; this is done 125 * by other means, usually through libcutils's native_handle_close() and 126 * native_handle_free(). 127 * 128 * It is an error to call (*unregisterBuffer)() on a buffer that wasn't 129 * explicitly registered first. 130 */ 131 int (*unregisterBuffer)(struct gralloc_module_t const* module, 132 buffer_handle_t handle); 133 134 /* 135 * The (*lock)() method is called before a buffer is accessed for the 136 * specified usage. This call may block, for instance if the h/w needs 137 * to finish rendering or if CPU caches need to be synchronized. 138 * 139 * The caller promises to modify only pixels in the area specified 140 * by (l,t,w,h). 141 * 142 * The content of the buffer outside of the specified area is NOT modified 143 * by this call. 144 * 145 * If usage specifies GRALLOC_USAGE_SW_*, vaddr is filled with the address 146 * of the buffer in virtual memory. 147 * 148 * THREADING CONSIDERATIONS: 149 * 150 * It is legal for several different threads to lock a buffer from 151 * read access, none of the threads are blocked. 152 * 153 * However, locking a buffer simultaneously for write or read/write is 154 * undefined, but: 155 * - shall not result in termination of the process 156 * - shall not block the caller 157 * It is acceptable to return an error or to leave the buffer's content 158 * into an indeterminate state. 159 * 160 * If the buffer was created with a usage mask incompatible with the 161 * requested usage flags here, -EINVAL is returned. 162 * 163 */ 164 165 int (*lock)(struct gralloc_module_t const* module, 166 buffer_handle_t handle, int usage, 167 int l, int t, int w, int h, 168 void** vaddr); 169 170 171 /* 172 * The (*unlock)() method must be called after all changes to the buffer 173 * are completed. 174 */ 175 176 int (*unlock)(struct gralloc_module_t const* module, 177 buffer_handle_t handle); 178 179 180 /* reserved for future use */ 181 int (*perform)(struct gralloc_module_t const* module, 182 int operation, ... ); 183 184 /* reserved for future use */ 185 void* reserved_proc[7]; 186 } gralloc_module_t; 187 188 /*****************************************************************************/ 189 190 /** 191 * Every device data structure must begin with hw_device_t 192 * followed by module specific public methods and attributes. 193 */ 194 195 typedef struct alloc_device_t { 196 struct hw_device_t common; 197 198 /* 199 * (*alloc)() Allocates a buffer in graphic memory with the requested 200 * parameters and returns a buffer_handle_t and the stride in pixels to 201 * allow the implementation to satisfy hardware constraints on the width 202 * of a pixmap (eg: it may have to be multiple of 8 pixels). 203 * The CALLER TAKES OWNERSHIP of the buffer_handle_t. 204 * 205 * Returns 0 on success or -errno on error. 206 */ 207 208 int (*alloc)(struct alloc_device_t* dev, 209 int w, int h, int format, int usage, 210 buffer_handle_t* handle, int* stride); 211 212 /* 213 * (*free)() Frees a previously allocated buffer. 214 * Behavior is undefined if the buffer is still mapped in any process, 215 * but shall not result in termination of the program or security breaches 216 * (allowing a process to get access to another process' buffers). 217 * THIS FUNCTION TAKES OWNERSHIP of the buffer_handle_t which becomes 218 * invalid after the call. 219 * 220 * Returns 0 on success or -errno on error. 221 */ 222 int (*free)(struct alloc_device_t* dev, 223 buffer_handle_t handle); 224 225 } alloc_device_t; 226 227 228 typedef struct framebuffer_device_t { 229 struct hw_device_t common; 230 231 /* flags describing some attributes of the framebuffer */ 232 const uint32_t flags; 233 234 /* dimensions of the framebuffer in pixels */ 235 const uint32_t width; 236 const uint32_t height; 237 238 /* frambuffer stride in pixels */ 239 const int stride; 240 241 /* framebuffer pixel format */ 242 const int format; 243 244 /* resolution of the framebuffer's display panel in pixel per inch*/ 245 const float xdpi; 246 const float ydpi; 247 248 /* framebuffer's display panel refresh rate in frames per second */ 249 const float fps; 250 251 /* min swap interval supported by this framebuffer */ 252 const int minSwapInterval; 253 254 /* max swap interval supported by this framebuffer */ 255 const int maxSwapInterval; 256 257 int reserved[8]; 258 259 /* 260 * requests a specific swap-interval (same definition than EGL) 261 * 262 * Returns 0 on success or -errno on error. 263 */ 264 int (*setSwapInterval)(struct framebuffer_device_t* window, 265 int interval); 266 267 /* 268 * This hook is OPTIONAL. 269 * 270 * It is non NULL If the framebuffer driver supports "update-on-demand" 271 * and the given rectangle is the area of the screen that gets 272 * updated during (*post)(). 273 * 274 * This is useful on devices that are able to DMA only a portion of 275 * the screen to the display panel, upon demand -- as opposed to 276 * constantly refreshing the panel 60 times per second, for instance. 277 * 278 * Only the area defined by this rectangle is guaranteed to be valid, that 279 * is, the driver is not allowed to post anything outside of this 280 * rectangle. 281 * 282 * The rectangle evaluated during (*post)() and specifies which area 283 * of the buffer passed in (*post)() shall to be posted. 284 * 285 * return -EINVAL if width or height <=0, or if left or top < 0 286 */ 287 int (*setUpdateRect)(struct framebuffer_device_t* window, 288 int left, int top, int width, int height); 289 290 /* 291 * Post <buffer> to the display (display it on the screen) 292 * The buffer must have been allocated with the 293 * GRALLOC_USAGE_HW_FB usage flag. 294 * buffer must be the same width and height as the display and must NOT 295 * be locked. 296 * 297 * The buffer is shown during the next VSYNC. 298 * 299 * If the same buffer is posted again (possibly after some other buffer), 300 * post() will block until the the first post is completed. 301 * 302 * Internally, post() is expected to lock the buffer so that a 303 * subsequent call to gralloc_module_t::(*lock)() with USAGE_RENDER or 304 * USAGE_*_WRITE will block until it is safe; that is typically once this 305 * buffer is shown and another buffer has been posted. 306 * 307 * Returns 0 on success or -errno on error. 308 */ 309 int (*post)(struct framebuffer_device_t* dev, buffer_handle_t buffer); 310 311 312 /* 313 * The (*compositionComplete)() method must be called after the 314 * compositor has finished issuing GL commands for client buffers. 315 */ 316 317 int (*compositionComplete)(struct framebuffer_device_t* dev); 318 319 320 void* reserved_proc[8]; 321 322 } framebuffer_device_t; 323 324 325 /** convenience API for opening and closing a supported device */ 326 327 static inline int gralloc_open(const struct hw_module_t* module, 328 struct alloc_device_t** device) { 329 return module->methods->open(module, 330 GRALLOC_HARDWARE_GPU0, (struct hw_device_t**)device); 331 } 332 333 static inline int gralloc_close(struct alloc_device_t* device) { 334 return device->common.close(&device->common); 335 } 336 337 338 static inline int framebuffer_open(const struct hw_module_t* module, 339 struct framebuffer_device_t** device) { 340 return module->methods->open(module, 341 GRALLOC_HARDWARE_FB0, (struct hw_device_t**)device); 342 } 343 344 static inline int framebuffer_close(struct framebuffer_device_t* device) { 345 return device->common.close(&device->common); 346 } 347 348 349 __END_DECLS 350 351 #endif // ANDROID_ALLOC_INTERFACE_H 352
