include/hardware/gralloc.h

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