The android ion Memory Allocator, dmabuf is mentioned as well

From: http://blog.csdn.net/thegameisfives/article/details/7308458

What is ion?

My understanding is that Google introduced a memory manager in android4.0 to replace the previous solutions of various chip manufacturers. The following are found on the Internet:

 

It has become clear that pmem is considered obsolete and will be replaced by the ion Memory Manager. ion is a generalized Memory Manager that Google introduced in the android 4.0 ICS (ice cream sandwich) release to Address the Issue of fragmented memory management interfaces into SS different Android devices. there are at least three, probably more, pmem-like interfaces. on Android devices using NVIDIA tegra, there is "nvmap"; on Android devices using Ti OMAP, there is "cmem"; and on Android devices using Qualcomm MSM, there is "pmem ". all three SoC vendors are in the process of switching to ion. this article takes a look at ion, summarizing its interfaces to user space and to kernel-space drivers. besides being a memory pool manager, ion also enables its clients to share buffers, hence it treads the same ground as the DMA buffer sharing framework from linaro (dmabuf ). this article will end with a comparison of the two buffer sharing schemes.

 

Ion heaps

Like its pmem-like predecessors, ion manages one or more memory pools, some of which are set aside at boot time to combat fragmentation or to serve special hardware needs. GPUs, display controllers, and cameras are some of the hardware blocks that may have special memory requirements. ion presents its memory pools as ion heaps. each type of Android device can be provisioned with a different set of ion heaps according to the memory requirements of the device. the provider of an ion heap must implement the following set of callbacks:

   struct ion_heap_ops {int (*allocate) (struct ion_heap *heap, struct ion_buffer *buffer, unsigned long len, unsigned long align, unsigned long flags);void (*free) (struct ion_buffer *buffer);int (*phys) (struct ion_heap *heap, struct ion_buffer *buffer,     ion_phys_addr_t *addr, size_t *len);struct scatterlist *(*map_dma) (struct ion_heap *heap, struct ion_buffer *buffer);void (*unmap_dma) (struct ion_heap *heap,          struct ion_buffer *buffer);void * (*map_kernel) (struct ion_heap *heap,          struct ion_buffer *buffer);void (*unmap_kernel) (struct ion_heap *heap,          struct ion_buffer *buffer);int (*map_user) (struct ion_heap *heap, struct ion_buffer *buffer, struct vm_area_struct *vma);   };

Briefly,Allocate ()AndFree ()Obtain or releaseIon_bufferObject from the heap. A callPhys ()Will return the physical address and length of the buffer, but only for physically-contiguous buffers. If the heap does not provide physically contiguous buffers, it does not have to provide this callback. HereIon_phys_addr_tIs a typedefUnsigned long, And will, someday, be replacedPhys_addr_tInInclude/Linux/types. h.Map_dma ()AndUnmap_dma ()Callbacks cause the buffer to be prepared (or unprepared) for DMA.Map_kernel ()AndUnmap_kernel ()Callbacks map (or unmap) the physical memory into the kernel virtual address space. A callMap_user ()Will map the memory to user space. There is noUnmap_user ()Because the mapping is represented as a file descriptor in user space. the closing of that file descriptor will cause the memory to be unmapped from the calling process.

The default ion Driver (which can be cloned from here) offers three heaps as listed below:

   ION_HEAP_TYPE_SYSTEM:        memory allocated via vmalloc_user().   ION_HEAP_TYPE_SYSTEM_CONTIG: memory allocated via kzalloc.   ION_HEAP_TYPE_CARVEOUT:carveout memory is physically contiguous and set aside at boot.

 

Developers may choose to add more ion heaps. For example, this NVIDIA patch was submitted to add ion_heap_type_iommu for hardware blocks equipped with an iommu.

Using Ion from user space

Typically, user space device access libraries will use ion to allocate large contiguous media buffers. for example, the still camera library may allocate a capture buffer to be used by the camera device. once the buffer is fully populated with video data, the Library can pass the buffer to the kernel to be processed by a jpeg encoder hardware block.

 

A user space C/C ++ program must have been granted access to/Dev/ionDevice before it can allocate memory from ion. A callOpen ("/dev/ion", o_rdonly)Returns a file descriptor as a handle representing an ion client. Yes, one can allocate writable memory withO_rdonlyOpen. There can be no more than one client per user process. To allocate a buffer, the client needs to fill in all the fields should tHandleField in this data structure:

   struct ion_allocation_data {        size_t len;        size_t align;        unsigned int flags;        struct ion_handle *handle;   }

 

TheHandleField is the output parameter, while the first three fields specify the alignment, length and flags as input parameters.FlagsField is a bit mask indicating one or more ion heaps to allocate from, with the fallback ordered according to which ion heap was first added via calltoIon_device_add_heap ()During boot. In the default implementation,Ion_heap_type_carveoutIs added beforeIon_heap_type_contig. The flagsIon_heap_type_contig | ion_heap_type_carveoutIndicate the intention to allocate fromIon_heap_type_carveoutWith fallbackIon_heap_type_contig.

 

User-space clients interact with ion usingIOCTL ()System Call interface. to allocate a buffer, the client makes this call:

   int ioctl(int client_fd, ION_IOC_ALLOC, struct ion_allocation_data *allocation_data)

 

This call returns a buffer representedIon_handleWhich is not a CPU-accessible buffer pointer. The handle can only be used to obtain a file descriptor for buffer sharing as follows:

   int ioctl(int client_fd, ION_IOC_SHARE, struct ion_fd_data *fd_data);

HereClient_fdIs the file descriptor corresponding/Dev/ion, AndFd_dataIs a data structure with an inputHandleField and an outputFDField, as defined below:

   struct ion_fd_data {        struct ion_handle *handle;        int fd;   }

TheFDField is the file descriptor that can be passed around for sharing. On Android devicesBinderIPC mechanic may be used to sendFDTo another process for sharing. To obtain the shared buffer, the second user process must obtain a client handle first viaOpen ("/dev/ion", o_rdonly)System Call. ion tracks its user space clients by the PID of the process (specifically, the PID of the thread that is the "Group Leader" in the process). repeatingOpen ("/dev/ion", o_rdonly)Call in the same process will get back another file descriptor corresponding to the same client structure in the kernel.

 

To free the buffer, the second client needs to undo the effectMMAP ()With a callMunmap (), And the first client needs to close the file descriptor it obtainedIon_ioc_share, And callIon_ioc_freeAs follows:

     int ioctl(int client_fd, ION_IOC_FREE, struct ion_handle_data *handle_data);

 

HereIon_handle_dataHolds the handle as shown below:

     struct ion_handle_data {     struct ion_handle *handle;     }

TheIon_ioc_freeCommand causes the handle's reference counter to be decremented by one. When this reference counter reaches zero,Ion_handleObject gets destroyed and the affected ion bookkeeping data structure is updated.

 

User processes can also share ion buffers with a kernel driver, as explained in the next section.

 

Sharing ion buffers in the kernel

 

 

In the kernel, ion supports multiple clients, one for each driver that uses the ion functionality. A kernel driver CILS the following function to obtain an ion client handle:

 

   struct ion_client *ion_client_create(struct ion_device *dev,                    unsigned int heap_mask, const char *debug_name)

 

 

The first argument,Dev, Is the global ion device associated/Dev/ion; Why a global device is needed, and why it must be passed as a parameter, is not entirely clear. The second argument,Heap_mask, Selects one or more ion heaps in the same way asIon_allocation_data. The flagsField was covered in the previous section. For smart phone use cases involving multimedia middleware, the user process typically allocates the buffer from ion, obtains a file descriptor usingIon_ioc_shareCommand, then passes the file desciptor to a kernel driver. The kernel driver CILSIon_import_fd ()Which converts the file descriptor toIon_handleObject, as shown below:

    struct ion_handle *ion_import_fd(struct ion_client *client, int fd_from_user);

 

TheIon_handleObject is the driver's client-local reference to the shared buffer.Ion_import_fd ()Call looks up the physical address of the buffer to see whether the client has obtained a handle to the same buffer before, and if it has, this call simply increments the reference counter of the existing handle.

 

Some hardware blocks can only operate on physically-contiguous buffers with physical addresses, so affected drivers need to convertIon_handleTo a physical buffer via this call:

   int ion_phys(struct ion_client *client, struct ion_handle *handle,       ion_phys_addr_t *addr, size_t *len)

 

 

Needless to say, if the buffer is not physically contiguous, this call will fail.

When handling CILS from a client, ion always validates the input file descriptor, client and handle arguments. For example, when importing a file descriptor, ion ensures the file descriptor was indeed created byIon_ioc_shareCommand. WhenIon_phys ()Is called, ion validates whether the buffer handle belongs to the list of handles the client is allowed to access, and returns error if the handle is not on the list. this validation mechanism has CES the likelihood of unwanted accesses and inadvertent resource leaks.

Ion provides debug visibility throughDebugfs. It organizes debug information under/Sys/kernel/debug/ion, With bookkeeping information in stored files associated with heaps and clients identified by symbolic names or PIDs.

 

Comparing ion and dmabuf

 

 

Ion and dmabuf share some common concepts.Dma_bufConcept is similarIon_buffer, WhileDma_buf_attachmentServes a similar purposeIon_handle. Both ion and dmabuf use anonymous file descriptors as the objects that can be passed around to provide reference-counted access to shared buffers. on the other hand, ion focuses on allocating and freeing memory from provisioned memory pools in a manner that can be shared and tracked, while dmabuf focuses more on buffer importing, exporting and synchronization in a manner that is consistent with buffer sharing solutions on non-arm ubuntures.

The following table presents a feature comparison between ion and dmabuf:

Feature	Ion	Dmabuf
Memory Manager role	Ion replaces pmem as the manager of provisioned memory pools. The list of ion heaps can be extended per device.	Dmabuf is a buffer sharing framework, designed to integrate with the memory allocators in DMA mapping frameworks, like the work-in-progress DMA-contiguous Allocator, also known as thecontiguous Memory Allocator (CMA ). dmabuf exporters have the option to implement custom allocators.
User space access control	Ion offers/Dev/ionInterface for user-space programs to allocate and share buffers. any user program with ion access can cripple the system by depleting the ion heaps. android checks user and group IDs to block unauthorized access to ion heaps.	Dmabuf offers only kernel APIs. Access control is a function of the permissions on the devices using the dmabuf feature.
Global client and buffer Database	Ion contains a device driver associated/Dev/ion. The device structure contains a database that tracks the allocated ion buffers, handles and file descriptors, all grouped by user clients and kernel clients. ion validates all client CILS according to the rules of the database. for example, there is a rule that a client cannot have two handles to the same buffer.	The DMA debug facilityimplements a global hashtable,Dma_entry_hash, To track DMA buffers, but only when the kernel was built withConfig_dma_api_debugOption.
Cross-architecture usage	Ion usage today is limited to ubuntures that run the android kernel.	Dmabuf usage is cross-architecture. The DMA mapping redesign preparation patchset modified the DMA mapping code in 9 ubuntures besides the ARM architecture.
Buffer synchronization	Ion considers buffer synchronization to be an orthogonal problem.	Dmabuf provides a pair of APIS for synchronization. The buffer-user CILSDma_buf_map_attachment ()Whenever it wants to use the buffer for DMA. Once the DMA for the current buffer-user is over, it signals 'end-of-DMA 'to the exporter via a callDma_buf_unmap_attachment ().
Delayed Buffer Allocation	Ion allocates the physical memory before the buffer is shared.	Dmabuf can defer the allocation until the first callDma_buf_map_attachment (). The exporter of DMA buffer has the opportunity to scan all client attachments, collate their buffer constraints, then choose the appropriate backing storage.

 

Ion and dmabuf can be separately integrated into multimedia applications written usingthe video4linux2 API. in the case of ion, these multimedia programs tend to use pmem now on Android devices, so switching to ion from pmem shocould have a relatively small impact.

Integrating dmabuf into video4linux2 is another story. It has taken ten patches to integrateVideobuf2Mechanic with dmabuf; In fairness, percent of these revisions were the result of changes to dmabuf as that interface stabilized. the effort shocould pay dividends in the long run because the dmabuf-based sharing mechanism is designed with DMA mapping hooks for CMA and iommu. CMA and iommu hold the promise to reduce the amount of carveout memory that it takes to build an android smart phone. inthis email, Andrew Morton was urging the completion of the patch review process so that CMA can get through the 3.4 merge window.

Even though ion and dmabuf serve similar purposes, the two are not mutually exclusive. the linaro uniied memory management team has startedto integrate CMA into ion. to reach the State where a release of the mainline kernel can boot the android user space,/Dev/ionInterface to user space must obviusly be preserved. in the kernel though, ion drivers may be able to use some of the dmabuf APIs to hook into CMA and iommu to take advantage of the capabilities offered by those subsystems. conversely, dmabuf might be able to leverage ion to present a unified interface to user space, especially to the android user space. dmabuf may also benefit from adopting some of the ion heap debugging features in order to become more developer friendly. thus far, inclusigns indicate that linaro, Google, and the kernel community are working together to bring the combined strength of ion and dmabuf to the mainline kernel.