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 2106e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray#include <system/graphics.h> 22a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#include <hardware/hardware.h> 23a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 24a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#include <stdint.h> 25a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#include <sys/cdefs.h> 26a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#include <sys/types.h> 27a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 285337b102898cfd48eda7215df15baaf3bc96521fMathias Agopian#include <cutils/native_handle.h> 295337b102898cfd48eda7215df15baaf3bc96521fMathias Agopian 305337b102898cfd48eda7215df15baaf3bc96521fMathias Agopian#include <hardware/hardware.h> 315337b102898cfd48eda7215df15baaf3bc96521fMathias Agopian#include <hardware/fb.h> 325337b102898cfd48eda7215df15baaf3bc96521fMathias Agopian 33a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian__BEGIN_DECLS 34a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 3506e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray/** 3606e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Module versioning information for the Gralloc hardware module, based on 3706e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * gralloc_module_t.common.module_api_version. 3806e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 3906e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Version History: 4006e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 4106e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * GRALLOC_MODULE_API_VERSION_0_1: 4206e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Initial Gralloc hardware module API. 4306e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 4406e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * GRALLOC_MODULE_API_VERSION_0_2: 4506e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Add support for flexible YCbCr format with (*lock_ycbcr)() method. 462e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 472e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * GRALLOC_MODULE_API_VERSION_0_3: 482e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * Add support for fence passing to/from lock/unlock. 4906e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray */ 5006e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray 5106e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray#define GRALLOC_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) 5206e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray#define GRALLOC_MODULE_API_VERSION_0_2 HARDWARE_MODULE_API_VERSION(0, 2) 532e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart#define GRALLOC_MODULE_API_VERSION_0_3 HARDWARE_MODULE_API_VERSION(0, 3) 5406e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray 5506e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray#define GRALLOC_DEVICE_API_VERSION_0_1 HARDWARE_DEVICE_API_VERSION(0, 1) 56e99520400f228e45b1feff28eb4105b8e5599196Erik Gilling 57a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/** 58a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * The id of this module 59a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 60a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#define GRALLOC_HARDWARE_MODULE_ID "gralloc" 61a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 62a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/** 63a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Name of the graphics device to open 64a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 65a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 66a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian#define GRALLOC_HARDWARE_GPU0 "gpu0" 67a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 68a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopianenum { 69a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer is never read in software */ 7092bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_SW_READ_NEVER = 0x00000000U, 71a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer is rarely read in software */ 7292bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_SW_READ_RARELY = 0x00000002U, 73a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer is often read in software */ 7492bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_SW_READ_OFTEN = 0x00000003U, 75a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* mask for the software read values */ 7692bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_SW_READ_MASK = 0x0000000FU, 77fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza 78a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer is never written in software */ 7992bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_SW_WRITE_NEVER = 0x00000000U, 80d6f7aad8de5d122d4189ecc608c749a63de4983dGreg Hackmann /* buffer is rarely written in software */ 8192bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_SW_WRITE_RARELY = 0x00000020U, 82d6f7aad8de5d122d4189ecc608c749a63de4983dGreg Hackmann /* buffer is often written in software */ 8392bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_SW_WRITE_OFTEN = 0x00000030U, 84a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* mask for the software write values */ 8592bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_SW_WRITE_MASK = 0x000000F0U, 86a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 87a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer will be used as an OpenGL ES texture */ 8892bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_HW_TEXTURE = 0x00000100U, 89a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer will be used as an OpenGL ES render target */ 9092bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_HW_RENDER = 0x00000200U, 91a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer will be used by the 2D hardware blitter */ 9292bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_HW_2D = 0x00000400U, 934b560d5563ee4699cd24938c2f13b4a416408273Jamie Gennis /* buffer will be used by the HWComposer HAL module */ 9492bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_HW_COMPOSER = 0x00000800U, 95a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* buffer will be used with the framebuffer device */ 9692bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_HW_FB = 0x00001000U, 97fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza 98fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza /* buffer should be displayed full-screen on an external display when 99fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza * possible */ 10092bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_EXTERNAL_DISP = 0x00002000U, 101fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza 102fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza /* Must have a hardware-protected path to external display sink for 103fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza * this buffer. If a hardware-protected path is not available, then 104fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza * either don't composite only this buffer (preferred) to the 105fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza * external sink, or (less desirable) do not route the entire 106fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza * composition to the external sink. */ 10792bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_PROTECTED = 0x00004000U, 108fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza 109fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza /* buffer may be used as a cursor */ 11092bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_CURSOR = 0x00008000U, 111fd2d859445d614ab3f6c4687de839097566ac317Dan Stoza 11229ead941b377cb87bcc7fe48208b96d84d649d43Jamie Gennis /* buffer will be used with the HW video encoder */ 11392bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_HW_VIDEO_ENCODER = 0x00010000U, 1147797d75b12a90cd03a47642c59dbb677aa4daa88Eino-Ville Talvala /* buffer will be written by the HW camera pipeline */ 11592bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_HW_CAMERA_WRITE = 0x00020000U, 1167797d75b12a90cd03a47642c59dbb677aa4daa88Eino-Ville Talvala /* buffer will be read by the HW camera pipeline */ 11792bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_HW_CAMERA_READ = 0x00040000U, 1182388a2dc91979364d96e49456b189f904f0267f3Eino-Ville Talvala /* buffer will be used as part of zero-shutter-lag queue */ 11992bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_HW_CAMERA_ZSL = 0x00060000U, 1207f8dd0ad2d3d40b57c8359971a351fd194668613Eino-Ville Talvala /* mask for the camera access values */ 12192bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_HW_CAMERA_MASK = 0x00060000U, 122a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* mask for the software usage bit-mask */ 12392bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_HW_MASK = 0x00071F00U, 12495d78bef32edd183fb8c16b7775bf0a069948420Jamie Gennis 12522423852817b19245a2134653eef3f71a39cf42aJason Sams /* buffer will be used as a RenderScript Allocation */ 12692bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_RENDERSCRIPT = 0x00100000U, 12722423852817b19245a2134653eef3f71a39cf42aJason Sams 128201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza /* Set by the consumer to indicate to the producer that they may attach a 129201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza * buffer that they did not detach from the BufferQueue. Will be filtered 130201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza * out by GRALLOC_USAGE_ALLOC_MASK, so gralloc modules will not need to 131201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza * handle this flag. */ 13292bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_FOREIGN_BUFFERS = 0x00200000U, 133201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza 134201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza /* Mask of all flags which could be passed to a gralloc module for buffer 135201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza * allocation. Any flags not in this mask do not need to be handled by 136201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza * gralloc modules. */ 137201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza GRALLOC_USAGE_ALLOC_MASK = ~(GRALLOC_USAGE_FOREIGN_BUFFERS), 138201c7d91b757f632bfd67ca24e6c55d0dc88a8d4Dan Stoza 13995d78bef32edd183fb8c16b7775bf0a069948420Jamie Gennis /* implementation-specific private usage flags */ 14092bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_PRIVATE_0 = 0x10000000U, 14192bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_PRIVATE_1 = 0x20000000U, 14292bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_PRIVATE_2 = 0x40000000U, 14392bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_PRIVATE_3 = 0x80000000U, 14492bba13dd1f275d3ad26f8e411036c911895905aColin Cross GRALLOC_USAGE_PRIVATE_MASK = 0xF0000000U, 145a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian}; 146a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 147a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/*****************************************************************************/ 148a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 149a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/** 150a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 151a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * and the fields of this data structure must begin with hw_module_t 152a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * followed by module specific information. 153a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 1549d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopiantypedef struct gralloc_module_t { 155a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian struct hw_module_t common; 156a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 157988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian /* 158988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * (*registerBuffer)() must be called before a buffer_handle_t that has not 159988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * been created with (*alloc_device_t::alloc)() can be used. 160988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 161988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * This is intended to be used with buffer_handle_t's that have been 162988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * received in this process through IPC. 163988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 164988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * This function checks that the handle is indeed a valid one and prepares 165988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * it for use with (*lock)() and (*unlock)(). 166988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 167988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * It is not necessary to call (*registerBuffer)() on a handle created 168988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * with (*alloc_device_t::alloc)(). 169a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 170988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * returns an error if this buffer_handle_t is not valid. 171a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 172988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian int (*registerBuffer)(struct gralloc_module_t const* module, 173988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian buffer_handle_t handle); 174a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 175a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* 176988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * (*unregisterBuffer)() is called once this handle is no longer needed in 177988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * this process. After this call, it is an error to call (*lock)(), 178988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * (*unlock)(), or (*registerBuffer)(). 179988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 180988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * This function doesn't close or free the handle itself; this is done 181988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * by other means, usually through libcutils's native_handle_close() and 182988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * native_handle_free(). 183a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 184988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * It is an error to call (*unregisterBuffer)() on a buffer that wasn't 185988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * explicitly registered first. 186a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 187988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian int (*unregisterBuffer)(struct gralloc_module_t const* module, 188988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian buffer_handle_t handle); 189a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 190a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* 191a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * The (*lock)() method is called before a buffer is accessed for the 192a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * specified usage. This call may block, for instance if the h/w needs 193a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * to finish rendering or if CPU caches need to be synchronized. 194a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 195988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * The caller promises to modify only pixels in the area specified 196988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * by (l,t,w,h). 197a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 198a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * The content of the buffer outside of the specified area is NOT modified 199a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * by this call. 200988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 201988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * If usage specifies GRALLOC_USAGE_SW_*, vaddr is filled with the address 202988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * of the buffer in virtual memory. 203988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * 20406e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Note calling (*lock)() on HAL_PIXEL_FORMAT_YCbCr_*_888 buffers will fail 20506e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * and return -EINVAL. These buffers must be locked with (*lock_ycbcr)() 20606e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * instead. 20706e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 208485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * THREADING CONSIDERATIONS: 209485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * 210485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * It is legal for several different threads to lock a buffer from 211485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * read access, none of the threads are blocked. 212485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * 213485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * However, locking a buffer simultaneously for write or read/write is 214485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * undefined, but: 215485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * - shall not result in termination of the process 216485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * - shall not block the caller 217485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * It is acceptable to return an error or to leave the buffer's content 218485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * into an indeterminate state. 219485e69809aef8bf301b6bf19c03dc2d7693aaa1aMathias Agopian * 220988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * If the buffer was created with a usage mask incompatible with the 221988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian * requested usage flags here, -EINVAL is returned. 222a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 223a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 224a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 225a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian int (*lock)(struct gralloc_module_t const* module, 226a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian buffer_handle_t handle, int usage, 227988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian int l, int t, int w, int h, 228988b8bd553180e8d71b4028ecb721f46312efe62Mathias Agopian void** vaddr); 229a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 230a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 231a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* 232a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * The (*unlock)() method must be called after all changes to the buffer 233a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * are completed. 234a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 235a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 236a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian int (*unlock)(struct gralloc_module_t const* module, 237a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian buffer_handle_t handle); 238a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 239cd2433f3804a537aedc26f595b1c05f95a05244aMathias Agopian 240cd2433f3804a537aedc26f595b1c05f95a05244aMathias Agopian /* reserved for future use */ 241cd2433f3804a537aedc26f595b1c05f95a05244aMathias Agopian int (*perform)(struct gralloc_module_t const* module, 242cd2433f3804a537aedc26f595b1c05f95a05244aMathias Agopian int operation, ... ); 243cd2433f3804a537aedc26f595b1c05f95a05244aMathias Agopian 24406e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray /* 24506e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * The (*lock_ycbcr)() method is like the (*lock)() method, with the 24606e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * difference that it fills a struct ycbcr with a description of the buffer 24706e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * layout, and zeroes out the reserved fields. 24806e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 249811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * If the buffer format is not compatible with a flexible YUV format (e.g. 250811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * the buffer layout cannot be represented with the ycbcr struct), it 251811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * will return -EINVAL. 252811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * 253811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * This method must work on buffers with HAL_PIXEL_FORMAT_YCbCr_*_888 254811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * if supported by the device, as well as with any other format that is 255811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * requested by the multimedia codecs when they are configured with a 256811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * flexible-YUV-compatible color-format with android native buffers. 257811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * 258811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * Note that this method may also be called on buffers of other formats, 259811677e68d8507efe47591dc6c2f3de7ff5dce53Lajos Molnar * including non-YUV formats. 26006e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * 26106e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray * Added in GRALLOC_MODULE_API_VERSION_0_2. 26206e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray */ 26306e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray 26406e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray int (*lock_ycbcr)(struct gralloc_module_t const* module, 26506e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray buffer_handle_t handle, int usage, 26606e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray int l, int t, int w, int h, 26706e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray struct android_ycbcr *ycbcr); 26806e3bf25660a25b417e7a2e146327b35bee5ba00Alex Ray 2692e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart /* 2702e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The (*lockAsync)() method is like the (*lock)() method except 2712e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * that the buffer's sync fence object is passed into the lock 2722e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * call instead of requiring the caller to wait for completion. 2732e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 2742e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The gralloc implementation takes ownership of the fenceFd and 2752e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * is responsible for closing it when no longer needed. 2762e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 2772e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * Added in GRALLOC_MODULE_API_VERSION_0_3. 2782e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart */ 2792e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart int (*lockAsync)(struct gralloc_module_t const* module, 2802e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart buffer_handle_t handle, int usage, 2812e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart int l, int t, int w, int h, 2822e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart void** vaddr, int fenceFd); 2832e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart 2842e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart /* 2852e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The (*unlockAsync)() method is like the (*unlock)() method 2862e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * except that a buffer sync fence object is returned from the 2872e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * lock call, representing the completion of any pending work 2882e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * performed by the gralloc implementation. 2892e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 2902e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The caller takes ownership of the fenceFd and is responsible 2912e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * for closing it when no longer needed. 2922e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 2932e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * Added in GRALLOC_MODULE_API_VERSION_0_3. 2942e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart */ 2952e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart int (*unlockAsync)(struct gralloc_module_t const* module, 2962e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart buffer_handle_t handle, int* fenceFd); 2972e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart 2982e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart /* 2992e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The (*lockAsync_ycbcr)() method is like the (*lock_ycbcr)() 3002e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * method except that the buffer's sync fence object is passed 3012e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * into the lock call instead of requiring the caller to wait for 3022e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * completion. 3032e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 3042e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * The gralloc implementation takes ownership of the fenceFd and 3052e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * is responsible for closing it when no longer needed. 3062e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * 3072e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart * Added in GRALLOC_MODULE_API_VERSION_0_3. 3082e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart */ 3092e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart int (*lockAsync_ycbcr)(struct gralloc_module_t const* module, 3102e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart buffer_handle_t handle, int usage, 3112e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart int l, int t, int w, int h, 3122e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart struct android_ycbcr *ycbcr, int fenceFd); 3132e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart 3148255d9d3b62ddf90269ddbb54e6f92b29908fa75Mathias Agopian /* reserved for future use */ 3152e49f9acbb1039a8388b070332a5e2f35cd35343Francis Hart void* reserved_proc[3]; 3169d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopian} gralloc_module_t; 317a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 318a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/*****************************************************************************/ 319a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 320a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/** 321a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Every device data structure must begin with hw_device_t 322a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * followed by module specific public methods and attributes. 323a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 324a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 3259d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopiantypedef struct alloc_device_t { 326a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian struct hw_device_t common; 327a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 328a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* 329a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * (*alloc)() Allocates a buffer in graphic memory with the requested 330a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * parameters and returns a buffer_handle_t and the stride in pixels to 331a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * allow the implementation to satisfy hardware constraints on the width 332a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * of a pixmap (eg: it may have to be multiple of 8 pixels). 333a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * The CALLER TAKES OWNERSHIP of the buffer_handle_t. 3346efab252d59ceff806840111b2e6c0e478d377aeEino-Ville Talvala * 3356efab252d59ceff806840111b2e6c0e478d377aeEino-Ville Talvala * If format is HAL_PIXEL_FORMAT_YCbCr_420_888, the returned stride must be 3366efab252d59ceff806840111b2e6c0e478d377aeEino-Ville Talvala * 0, since the actual strides are available from the android_ycbcr 3376efab252d59ceff806840111b2e6c0e478d377aeEino-Ville Talvala * structure. 338a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 339a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Returns 0 on success or -errno on error. 340a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 341a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 342a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian int (*alloc)(struct alloc_device_t* dev, 343a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian int w, int h, int format, int usage, 344a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian buffer_handle_t* handle, int* stride); 345a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 346a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian /* 347a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * (*free)() Frees a previously allocated buffer. 348a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Behavior is undefined if the buffer is still mapped in any process, 349a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * but shall not result in termination of the program or security breaches 350a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * (allowing a process to get access to another process' buffers). 351a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * THIS FUNCTION TAKES OWNERSHIP of the buffer_handle_t which becomes 352a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * invalid after the call. 353a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * 354a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian * Returns 0 on success or -errno on error. 355a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian */ 356a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian int (*free)(struct alloc_device_t* dev, 357a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian buffer_handle_t handle); 358a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 359158549c89405186d9ecaefd3811cfae3949056eeErik Gilling /* This hook is OPTIONAL. 360158549c89405186d9ecaefd3811cfae3949056eeErik Gilling * 361158549c89405186d9ecaefd3811cfae3949056eeErik Gilling * If non NULL it will be caused by SurfaceFlinger on dumpsys 362158549c89405186d9ecaefd3811cfae3949056eeErik Gilling */ 363158549c89405186d9ecaefd3811cfae3949056eeErik Gilling void (*dump)(struct alloc_device_t *dev, char *buff, int buff_len); 364158549c89405186d9ecaefd3811cfae3949056eeErik Gilling 365158549c89405186d9ecaefd3811cfae3949056eeErik Gilling void* reserved_proc[7]; 3669d82c1a447a72a2c086b9cd34c5b73b163d7acbcMathias Agopian} alloc_device_t; 367a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 368a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 369a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian/** convenience API for opening and closing a supported device */ 370a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 371a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopianstatic inline int gralloc_open(const struct hw_module_t* module, 372a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian struct alloc_device_t** device) { 373a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian return module->methods->open(module, 374cc8d9f9fcbc170dedba609a15705e838cf09218bColin Cross GRALLOC_HARDWARE_GPU0, TO_HW_DEVICE_T_OPEN(device)); 375a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian} 376a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 377a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopianstatic inline int gralloc_close(struct alloc_device_t* device) { 378a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian return device->common.close(&device->common); 379a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian} 380a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 3814cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi/** 3824cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi * map_usage_to_memtrack should be called after allocating a gralloc buffer. 3834cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi * 3844cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi * @param usage - it is the flag used when alloc function is called. 3854cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi * 3864cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi * This function maps the gralloc usage flags to appropriate memtrack bucket. 3874cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi * GrallocHAL implementers and users should make an additional ION_IOCTL_TAG 3884cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi * call using the memtrack tag returned by this function. This will help the 3894cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi * in-kernel memtack to categorize the memory allocated by different processes 3904cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi * according to their usage. 3914cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi * 3924cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi */ 3934cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoistatic inline const char* map_usage_to_memtrack(uint32_t usage) { 3944cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi usage &= GRALLOC_USAGE_ALLOC_MASK; 3954cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi 3964cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi if ((usage & GRALLOC_USAGE_HW_CAMERA_WRITE) != 0) { 3974cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi return "camera"; 3984cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi } else if ((usage & GRALLOC_USAGE_HW_VIDEO_ENCODER) != 0 || 3994cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi (usage & GRALLOC_USAGE_EXTERNAL_DISP) != 0) { 4004cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi return "video"; 4014cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi } else if ((usage & GRALLOC_USAGE_HW_RENDER) != 0 || 4024cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi (usage & GRALLOC_USAGE_HW_TEXTURE) != 0) { 4034cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi return "gl"; 4044cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi } else if ((usage & GRALLOC_USAGE_HW_CAMERA_READ) != 0) { 4054cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi return "camera"; 4064cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi } else if ((usage & GRALLOC_USAGE_SW_READ_MASK) != 0 || 4074cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi (usage & GRALLOC_USAGE_SW_WRITE_MASK) != 0) { 4084cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi return "cpu"; 4094cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi } 4104cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi return "graphics"; 4114cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi} 4124cb6c4ff1f4f4908a73354b916a91de5933f4a9fRuchi Kandoi 413a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian__END_DECLS 414a8a75166a2d3c7639a7432a67075c98796165206Mathias Agopian 415bb56a1007d80ef8165493395ac8c9b0bf05a435fGlenn Kasten#endif // ANDROID_GRALLOC_INTERFACE_H 416