1a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/* 2a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Copyright (C) 2008 The Android Open Source Project 3a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 4a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Licensed under the Apache License, Version 2.0 (the "License"); 5a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * you may not use this file except in compliance with the License. 6a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * You may obtain a copy of the License at 7a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 8a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * http://www.apache.org/licenses/LICENSE-2.0 9a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 10a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Unless required by applicable law or agreed to in writing, software 11a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * distributed under the License is distributed on an "AS IS" BASIS, 12a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * See the License for the specific language governing permissions and 14a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * limitations under the License. 15a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 16a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 17a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 18a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#ifndef ANDROID_GRALLOC_INTERFACE_H 19a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#define ANDROID_GRALLOC_INTERFACE_H 20a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 2133c0fe022e166007547d9c7390e7e6dbba5122e7Iliyan Malchev#include <system/window.h> 2206e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray#include <system/graphics.h> 23a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#include <hardware/hardware.h> 24a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 25a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#include <stdint.h> 26a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#include <sys/cdefs.h> 27a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#include <sys/types.h> 28a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 295337b102898cfd48eda7215df15baaf3bc96521fMathias Agopian#include <cutils/native_handle.h> 305337b102898cfd48eda7215df15baaf3bc96521fMathias Agopian 315337b102898cfd48eda7215df15baaf3bc96521fMathias Agopian#include <hardware/hardware.h> 325337b102898cfd48eda7215df15baaf3bc96521fMathias Agopian#include <hardware/fb.h> 335337b102898cfd48eda7215df15baaf3bc96521fMathias Agopian 34a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian__BEGIN_DECLS 35a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 3606e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray/** 3706e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Module versioning information for the Gralloc hardware module, based on 3806e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * gralloc_module_t.common.module_api_version. 3906e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 4006e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Version History: 4106e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 4206e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * GRALLOC_MODULE_API_VERSION_0_1: 4306e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Initial Gralloc hardware module API. 4406e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 4506e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * GRALLOC_MODULE_API_VERSION_0_2: 4606e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Add support for flexible YCbCr format with (*lock_ycbcr)() method. 472e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 482e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * GRALLOC_MODULE_API_VERSION_0_3: 492e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * Add support for fence passing to/from lock/unlock. 5006e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray */ 5106e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray 5206e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray#define GRALLOC_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) 5306e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray#define GRALLOC_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) 542e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart#define GRALLOC_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) 5506e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray 5606e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray#define GRALLOC_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION(0, 1) 57e99520400f228e45b1feff28eb4105b8e5599196Erik Gilling 58a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/** 59a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * The id of this module 60a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 61a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#define GRALLOC_HARDWARE_MODULE_ID "gralloc" 62a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 63a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/** 64a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Name of the graphics device to open 65a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 66a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 67a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#define GRALLOC_HARDWARE_GPU0 "gpu0" 68a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 69a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopianenum { 70a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer is never read in software */ 7129ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_SW_READ_NEVER = 0x00000000, 72a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer is rarely read in software */ 7329ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_SW_READ_RARELY = 0x00000002, 74a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer is often read in software */ 7529ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_SW_READ_OFTEN = 0x00000003, 76a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* mask for the software read values */ 7729ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_SW_READ_MASK = 0x0000000F, 78fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza 79a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer is never written in software */ 8029ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_SW_WRITE_NEVER = 0x00000000, 81d6f7aad8de5d122d4189ecc608c749a63de4983dGreg Hackmann /* buffer is rarely written in software */ 8229ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_SW_WRITE_RARELY = 0x00000020, 83d6f7aad8de5d122d4189ecc608c749a63de4983dGreg Hackmann /* buffer is often written in software */ 8429ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_SW_WRITE_OFTEN = 0x00000030, 85a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* mask for the software write values */ 8629ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_SW_WRITE_MASK = 0x000000F0, 87a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 88a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer will be used as an OpenGL ES texture */ 8929ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_HW_TEXTURE = 0x00000100, 90a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer will be used as an OpenGL ES render target */ 9129ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_HW_RENDER = 0x00000200, 92a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer will be used by the 2D hardware blitter */ 9329ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_HW_2D = 0x00000400, 944b560d5563ee4699cd24938c2f13b4a416408273Jamie Gennis /* buffer will be used by the HWComposer HAL module */ 9529ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_HW_COMPOSER = 0x00000800, 96a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer will be used with the framebuffer device */ 9729ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_HW_FB = 0x00001000, 98fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza 99fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza /* buffer should be displayed full-screen on an external display when 100fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza * possible */ 101fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza GRALLOC_USAGE_EXTERNAL_DISP = 0x00002000, 102fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza 103fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza /* Must have a hardware-protected path to external display sink for 104fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza * this buffer. If a hardware-protected path is not available, then 105fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza * either don't composite only this buffer (preferred) to the 106fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza * external sink, or (less desirable) do not route the entire 107fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza * composition to the external sink. */ 108fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza GRALLOC_USAGE_PROTECTED = 0x00004000, 109fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza 110fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza /* buffer may be used as a cursor */ 111fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza GRALLOC_USAGE_CURSOR = 0x00008000, 112fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza 11329ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis /* buffer will be used with the HW video encoder */ 11429ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_HW_VIDEO_ENCODER = 0x00010000, 1157797d75b12a90cd03a47642c59dbb677aa4daa88Eino-Ville Talvala /* buffer will be written by the HW camera pipeline */ 1167797d75b12a90cd03a47642c59dbb677aa4daa88Eino-Ville Talvala GRALLOC_USAGE_HW_CAMERA_WRITE = 0x00020000, 1177797d75b12a90cd03a47642c59dbb677aa4daa88Eino-Ville Talvala /* buffer will be read by the HW camera pipeline */ 1187797d75b12a90cd03a47642c59dbb677aa4daa88Eino-Ville Talvala GRALLOC_USAGE_HW_CAMERA_READ = 0x00040000, 1192388a2dc91979364d96e49456b189f904f0267f3Eino-Ville Talvala /* buffer will be used as part of zero-shutter-lag queue */ 1207f8dd0ad2d3d40b57c8359971a351fd194668613Eino-Ville Talvala GRALLOC_USAGE_HW_CAMERA_ZSL = 0x00060000, 1217f8dd0ad2d3d40b57c8359971a351fd194668613Eino-Ville Talvala /* mask for the camera access values */ 1227f8dd0ad2d3d40b57c8359971a351fd194668613Eino-Ville Talvala GRALLOC_USAGE_HW_CAMERA_MASK = 0x00060000, 123a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* mask for the software usage bit-mask */ 1247797d75b12a90cd03a47642c59dbb677aa4daa88Eino-Ville Talvala GRALLOC_USAGE_HW_MASK = 0x00071F00, 12595d78bef32edd183fb8c16b7775bf0a069948420Jamie Gennis 12622423852817b19245a2134653eef3f71a39cf42aJason Sams /* buffer will be used as a RenderScript Allocation */ 12722423852817b19245a2134653eef3f71a39cf42aJason Sams GRALLOC_USAGE_RENDERSCRIPT = 0x00100000, 12822423852817b19245a2134653eef3f71a39cf42aJason Sams 129201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza /* Set by the consumer to indicate to the producer that they may attach a 130201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza * buffer that they did not detach from the BufferQueue. Will be filtered 131201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza * out by GRALLOC_USAGE_ALLOC_MASK, so gralloc modules will not need to 132201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza * handle this flag. */ 1332e3ed7e2e7fcdcf8c82b95b5156859ecc4d5b5d8Chong Zhang GRALLOC_USAGE_FOREIGN_BUFFERS = 0x00200000, 134201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza 135201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza /* Mask of all flags which could be passed to a gralloc module for buffer 136201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza * allocation. Any flags not in this mask do not need to be handled by 137201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza * gralloc modules. */ 138201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza GRALLOC_USAGE_ALLOC_MASK = ~(GRALLOC_USAGE_FOREIGN_BUFFERS), 139201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza 14095d78bef32edd183fb8c16b7775bf0a069948420Jamie Gennis /* implementation-specific private usage flags */ 14129ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_PRIVATE_0 = 0x10000000, 14229ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_PRIVATE_1 = 0x20000000, 14329ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_PRIVATE_2 = 0x40000000, 14429ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_PRIVATE_3 = 0x80000000, 14529ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis GRALLOC_USAGE_PRIVATE_MASK = 0xF0000000, 146a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian}; 147a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 148a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/*****************************************************************************/ 149a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 150a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/** 151a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 152a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * and the fields of this data structure must begin with hw_module_t 153a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * followed by module specific information. 154a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 1559d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopiantypedef struct gralloc_module_t { 156a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian struct hw_module_t common; 157a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 158988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian /* 159988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * (*registerBuffer)() must be called before a buffer_handle_t that has not 160988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * been created with (*alloc_device_t::alloc)() can be used. 161988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 162988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * This is intended to be used with buffer_handle_t's that have been 163988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * received in this process through IPC. 164988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 165988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * This function checks that the handle is indeed a valid one and prepares 166988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * it for use with (*lock)() and (*unlock)(). 167988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 168988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * It is not necessary to call (*registerBuffer)() on a handle created 169988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * with (*alloc_device_t::alloc)(). 170a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 171988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * returns an error if this buffer_handle_t is not valid. 172a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 173988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian int (*registerBuffer)(struct gralloc_module_t const* module, 174988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian buffer_handle_t handle); 175a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 176a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* 177988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * (*unregisterBuffer)() is called once this handle is no longer needed in 178988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * this process. After this call, it is an error to call (*lock)(), 179988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * (*unlock)(), or (*registerBuffer)(). 180988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 181988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * This function doesn't close or free the handle itself; this is done 182988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * by other means, usually through libcutils's native_handle_close() and 183988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * native_handle_free(). 184a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 185988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * It is an error to call (*unregisterBuffer)() on a buffer that wasn't 186988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * explicitly registered first. 187a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 188988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian int (*unregisterBuffer)(struct gralloc_module_t const* module, 189988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian buffer_handle_t handle); 190a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 191a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* 192a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * The (*lock)() method is called before a buffer is accessed for the 193a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * specified usage. This call may block, for instance if the h/w needs 194a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * to finish rendering or if CPU caches need to be synchronized. 195a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 196988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * The caller promises to modify only pixels in the area specified 197988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * by (l,t,w,h). 198a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 199a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * The content of the buffer outside of the specified area is NOT modified 200a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * by this call. 201988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 202988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * If usage specifies GRALLOC_USAGE_SW_*, vaddr is filled with the address 203988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * of the buffer in virtual memory. 204988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 20506e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Note calling (*lock)() on HAL_PIXEL_FORMAT_YCbCr_*_888 buffers will fail 20606e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * and return -EINVAL. These buffers must be locked with (*lock_ycbcr)() 20706e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * instead. 20806e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 209485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * THREADING CONSIDERATIONS: 210485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * 211485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * It is legal for several different threads to lock a buffer from 212485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * read access, none of the threads are blocked. 213485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * 214485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * However, locking a buffer simultaneously for write or read/write is 215485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * undefined, but: 216485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * - shall not result in termination of the process 217485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * - shall not block the caller 218485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * It is acceptable to return an error or to leave the buffer's content 219485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * into an indeterminate state. 220485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * 221988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * If the buffer was created with a usage mask incompatible with the 222988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * requested usage flags here, -EINVAL is returned. 223a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 224a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 225a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 226a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian int (*lock)(struct gralloc_module_t const* module, 227a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian buffer_handle_t handle, int usage, 228988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian int l, int t, int w, int h, 229988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian void** vaddr); 230a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 231a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 232a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* 233a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * The (*unlock)() method must be called after all changes to the buffer 234a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * are completed. 235a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 236a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 237a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian int (*unlock)(struct gralloc_module_t const* module, 238a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian buffer_handle_t handle); 239a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 240cd2433f3804a537aedc26f595b1c05f95a05244aMathias Agopian 241cd2433f3804a537aedc26f595b1c05f95a05244aMathias Agopian /* reserved for future use */ 242cd2433f3804a537aedc26f595b1c05f95a05244aMathias Agopian int (*perform)(struct gralloc_module_t const* module, 243cd2433f3804a537aedc26f595b1c05f95a05244aMathias Agopian int operation, ... ); 244cd2433f3804a537aedc26f595b1c05f95a05244aMathias Agopian 24506e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray /* 24606e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * The (*lock_ycbcr)() method is like the (*lock)() method, with the 24706e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * difference that it fills a struct ycbcr with a description of the buffer 24806e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * layout, and zeroes out the reserved fields. 24906e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 250811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * If the buffer format is not compatible with a flexible YUV format (e.g. 251811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * the buffer layout cannot be represented with the ycbcr struct), it 252811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * will return -EINVAL. 253811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * 254811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * This method must work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888 255811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * if supported by the device, as well as with any other format that is 256811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * requested by the multimedia codecs when they are configured with a 257811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * flexible-YUV-compatible color-format with android native buffers. 258811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * 259811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * Note that this method may also be called on buffers of other formats, 260811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * including non-YUV formats. 26106e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 26206e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Added in GRALLOC_MODULE_API_VERSION_0_2. 26306e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray */ 26406e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray 26506e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray int (*lock_ycbcr)(struct gralloc_module_t const* module, 26606e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray buffer_handle_t handle, int usage, 26706e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray int l, int t, int w, int h, 26806e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray struct android_ycbcr *ycbcr); 26906e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray 2702e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart /* 2712e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The (*lockAsync)() method is like the (*lock)() method except 2722e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * that the buffer's sync fence object is passed into the lock 2732e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * call instead of requiring the caller to wait for completion. 2742e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 2752e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The gralloc implementation takes ownership of the fenceFd and 2762e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * is responsible for closing it when no longer needed. 2772e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 2782e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * Added in GRALLOC_MODULE_API_VERSION_0_3. 2792e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart */ 2802e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart int (*lockAsync)(struct gralloc_module_t const* module, 2812e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart buffer_handle_t handle, int usage, 2822e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart int l, int t, int w, int h, 2832e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart void** vaddr, int fenceFd); 2842e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart 2852e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart /* 2862e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The (*unlockAsync)() method is like the (*unlock)() method 2872e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * except that a buffer sync fence object is returned from the 2882e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * lock call, representing the completion of any pending work 2892e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * performed by the gralloc implementation. 2902e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 2912e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The caller takes ownership of the fenceFd and is responsible 2922e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * for closing it when no longer needed. 2932e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 2942e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * Added in GRALLOC_MODULE_API_VERSION_0_3. 2952e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart */ 2962e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart int (*unlockAsync)(struct gralloc_module_t const* module, 2972e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart buffer_handle_t handle, int* fenceFd); 2982e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart 2992e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart /* 3002e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The (*lockAsync_ycbcr)() method is like the (*lock_ycbcr)() 3012e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * method except that the buffer's sync fence object is passed 3022e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * into the lock call instead of requiring the caller to wait for 3032e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * completion. 3042e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 3052e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The gralloc implementation takes ownership of the fenceFd and 3062e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * is responsible for closing it when no longer needed. 3072e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 3082e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * Added in GRALLOC_MODULE_API_VERSION_0_3. 3092e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart */ 3102e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart int (*lockAsync_ycbcr)(struct gralloc_module_t const* module, 3112e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart buffer_handle_t handle, int usage, 3122e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart int l, int t, int w, int h, 3132e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart struct android_ycbcr *ycbcr, int fenceFd); 3142e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart 3158255d9d3b62ddf90269ddbb54e6f92b29908fa75Mathias Agopian /* reserved for future use */ 3162e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart void* reserved_proc[3]; 3179d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopian} gralloc_module_t; 318a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 319a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/*****************************************************************************/ 320a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 321a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/** 322a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Every device data structure must begin with hw_device_t 323a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * followed by module specific public methods and attributes. 324a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 325a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 3269d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopiantypedef struct alloc_device_t { 327a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian struct hw_device_t common; 328a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 329a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* 330a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * (*alloc)() Allocates a buffer in graphic memory with the requested 331a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * parameters and returns a buffer_handle_t and the stride in pixels to 332a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * allow the implementation to satisfy hardware constraints on the width 333a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * of a pixmap (eg: it may have to be multiple of 8 pixels). 334a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * The CALLER TAKES OWNERSHIP of the buffer_handle_t. 3356efab252d59ceff806840111b2e6c0e478d377aeEino-Ville Talvala * 3366efab252d59ceff806840111b2e6c0e478d377aeEino-Ville Talvala * If format is HAL_PIXEL_FORMAT_YCbCr_420_888, the returned stride must be 3376efab252d59ceff806840111b2e6c0e478d377aeEino-Ville Talvala * 0, since the actual strides are available from the android_ycbcr 3386efab252d59ceff806840111b2e6c0e478d377aeEino-Ville Talvala * structure. 339a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 340a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Returns 0 on success or -errno on error. 341a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 342a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 343a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian int (*alloc)(struct alloc_device_t* dev, 344a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian int w, int h, int format, int usage, 345a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian buffer_handle_t* handle, int* stride); 346a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 347a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* 348a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * (*free)() Frees a previously allocated buffer. 349a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Behavior is undefined if the buffer is still mapped in any process, 350a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * but shall not result in termination of the program or security breaches 351a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * (allowing a process to get access to another process' buffers). 352a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * THIS FUNCTION TAKES OWNERSHIP of the buffer_handle_t which becomes 353a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * invalid after the call. 354a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 355a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Returns 0 on success or -errno on error. 356a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 357a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian int (*free)(struct alloc_device_t* dev, 358a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian buffer_handle_t handle); 359a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 360158549c89405186d9ecaefd3811cfae3949056eeErik Gilling /* This hook is OPTIONAL. 361158549c89405186d9ecaefd3811cfae3949056eeErik Gilling * 362158549c89405186d9ecaefd3811cfae3949056eeErik Gilling * If non NULL it will be caused by SurfaceFlinger on dumpsys 363158549c89405186d9ecaefd3811cfae3949056eeErik Gilling */ 364158549c89405186d9ecaefd3811cfae3949056eeErik Gilling void (*dump)(struct alloc_device_t *dev, char *buff, int buff_len); 365158549c89405186d9ecaefd3811cfae3949056eeErik Gilling 366158549c89405186d9ecaefd3811cfae3949056eeErik Gilling void* reserved_proc[7]; 3679d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopian} alloc_device_t; 368a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 369a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 370a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/** convenience API for opening and closing a supported device */ 371a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 372a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopianstatic inline int gralloc_open(const struct hw_module_t* module, 373a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian struct alloc_device_t** device) { 374a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian return module->methods->open(module, 375a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian GRALLOC_HARDWARE_GPU0, (struct hw_device_t**)device); 376a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian} 377a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 378a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopianstatic inline int gralloc_close(struct alloc_device_t* device) { 379a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian return device->common.close(&device->common); 380a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian} 381a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 382a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian__END_DECLS 383a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 384bb56a1007d80ef8165493395ac8c9b0bf05a435fGlenn Kasten#endif // ANDROID_GRALLOC_INTERFACE_H 385