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. 

APIs:

alloc_device_t {

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

     free

}

gralloc_module_t {

     register              -> prepare for the lock 

     unregistered       

     lock                   -> lock the buffer for specified usage, sync if required 

                                    return the virtual address the usage contains SW_XXX

     unlock                   

}

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.

Implementations

1. ashmem based.

AOSP Reference Implementation

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 ANativeWindow: dequeueBuffer/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.