Skip to main content

Android UI Internal : Gralloc

Gralloc is an Android HAL module used to allocate graphic memory needed by Android multimedia subsystems, including the 3D, Camera and Video encoder/decoder.  In this this article, we will cover the gralloc APIs,  several gralloc implementations, the relationship between gralloc and ION and related framework classes. We will end the article with a sequence diagram explaining the steps of creating a GraphicBuffer, gluing together everything talked previously. 


alloc_device_t {
     alloc        ->  specify the usage (who & how), mmap the buffer, 
                           return a buffer_handle to uniquely identify a buffer 

gralloc_module_t {
     register              -> prepare for the lock 
     lock                   -> lock the buffer for specified usage, sync if required 
                                    return the virtual address the usage contains SW_XXX
The methods in alloc_device_t is referred as Allocator and those in gralloc_module_t as Mapper. It is important to note that Mapper is only used for buffers that are not allocated in the same process as they are used.  Check gralloc.h for a complete and accurate definition of those APIs.


1. ashmem based.

2. ION Based (Samsung slsi , Qcom 8974) 
Samgsung exynos5 implementation and QCom's implementation are pure ION based.

Other vendors offers Hybrid( ION + Proprietary Allocation API ) implementation. Some type of memory, determined by format and usage, will be allocated from ION while others will be allocated from proprietary allocation API.

3. Proprietary
Nothing too much to say here :)

Gralloc VS ION

Both Gralloc and ION are for memory allocations in Android but are different level and has different focus.Let's take a close look at the API for allocation.

int gralloc_alloc(struct alloc_device_t* dev,
                            int w, int h,   int format,  int usage,                  /*in parameters*/
                            buffer_handle_t* handle, int* stride);            /*out parameters*/
int ion_alloc(int fd,  
                      size_t len, size_t align, unsigned int heap_mask, unsigned int flags,   /*in parameters*/
                      ion_user_handle_t *handle)                                                               /*out parameters*/  
  • gralloc is for graphic buffer allocation (w,h,format); ION is for raw memory allocation(len).
  • gralloc specify the buffer usage, as a hint for the implementation regarding how and where the memory should be allocated ; ION API specify directly it should be allocate from. Much low-level stuff.  
  • When implementing gralloc on top of ION, beside the simple calculation of the memory size , you will also need to do the mapping between  (format, usage) set by gralloc and (heap, flags) needed by the ION API. For example, (NV12, CAMRA) can map to (ION_HEAP_TYPE_CARVEOUT_CAMERA, noCached).  How the mapping is done is vendor specific and usually need customized ION heap type.  
  • Last, gralloc is user space API while ION is more kernel level API.
Framework Classes
GraphicBufferAllocator  is wrapper to galloc_device_t  and is used to allocate/free buffers. GraphicBufferAllocator is a singleton.

GraphicBufferMapper is wrapper to gralloc_module_t and is used to register/unregistered buffers that are transported across the binder, or lock/unlock buffers for specific usage.
ANativeWindowBuffer wraps a buffer_handle_t and adds the functionality of reference counting. To get ANativeWindowBuffer, use the methods ANativeWindowdequeueBuffer/requestBuffer.

GraphicBuffer subclass ANativeWindowBuffer, and utilizes GraphicBufferAllocator to allocate/free buffer and use GraphicBufferMapper to register/lock buffer. To get GraphicBuffer, use IGraphicBufferProducer.

IGraphicBufferProducer is the interface used by Producer to dequeue and enqueue buffer. BufferQueue implements IGraphicBufferProducer as well as IGraphicBufferConsumer. BufferQueue itself deserves an article, for now just remember that a GraphicBuffer is created when you calling BufferQueue::dequeueBuffer. 

Sequence Diagram of Creating a Graphic Buffer

Following diagram describes the sequence of how a GraphicBuffer is created, with an emphasis of illustrating the relationship between various classes listed above and how the GraphicBuffer is transport across process.

Popular posts from this blog

Android Camera2 API Explained

Compared with the old camera API, the Camera2 API introduced in the L is a lot more complex: more than ten classes are involved, calls (almost always) are asynchronized, plus lots of capture controls and meta data that you feel confused about.

No worries. Let me help you out. Whenever facing a complex system need a little bit effort to understand, I usually turns to the UML class diagram to capture the big picture.

So, here is the class diagram for Camera2 API.

You are encouraged to read this Android document first and then come back to this article, with your questions. I'll expand what is said there, and list the typical steps of using camera2 API. 

1. Start from CameraManager. We use it to iterate all the cameras that are available in the system, each with a designated cameraId. Using the cameraId, we can get the properties of the specified camera device. Those properties are represented by class CameraCharacteristics. Things like "is it front or back camera", "outpu…

Java Collections Framework Cheat Sheet

Java Collections Framework (JCF) implements the Abstract Data Type  for Java platform. Every serious Java programmer should familiar himself on this topic and be able to choose the right class for specific need.  A thorough introduction to JCF is not the target of this small article and to achieve that goal you can start with this excellent tutorial . 

Instead, I'd like to
1) Provide an overview of JCF's classes ,   2) Provide a cheat sheet you can post in your cubicel for daily reference, 3) Underline the relationship between JCF's implementation and the data structure and algorithm you learned in your undergraduate course

With these goals in mind, I came up following diagram - Java Collection Cheat Sheet. You can click it to zoom in. There is no necessity for more explanation once your familiar with UML class diagram and have a basic understanding of common data structures.

Android Security: An Overview Of Application Sandbox

The Problem: Define a policy to control how various clients can access different resources. A solution: Each resource has an owner and belongs to a group.Each client has an owner but can belongs to multiple groups.Each resource has a mode stating the access permissions allowed for its owner, group members and others, respectively. In the context of operating system, or Linux specifically, the resources can be files, sockets, etc; the clients are actually processes; and we have three access permissions:read, write and execute.