The Android ION memory allocator

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 the /dev/ion device before it can allocate memory from ION. A call to open("/dev/ion", O_RDONLY) returns a file descriptor as a handle representing an ION client. Yes, one can allocate writable memory with an O_RDONLY open. There can be no more than one client per user process. To allocate a buffer, the client needs to fill in all the fields except the handle field in this data structure:

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

The handle field is the output parameter, while the first three fields specify the alignment, length and flags as input parameters. The flags field 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 calls to ion_device_add_heap() during boot. In the default implementation,ION_HEAP_TYPE_CARVEOUT is added before ION_HEAP_TYPE_CONTIG. The flags of ION_HEAP_TYPE_CONTIG | ION_HEAP_TYPE_CARVEOUT indicate the intention to allocate from ION_HEAP_TYPE_CARVEOUT with fallback to ION_HEAP_TYPE_CONTIG.

User-space clients interact with ION using the ioctl() 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 represented by ion_handle which 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);

Here client_fd is the file descriptor corresponding to /dev/ion, and fd_data is a data structure with an input handle field and an output fd field, as defined below:

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

The fd field is the file descriptor that can be passed around for sharing. On Android devices the BINDERIPC mechanism may be used to send fd to another process for sharing. To obtain the shared buffer, the second user process must obtain a client handle first via the open("/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). Repeating the open("/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 effect of mmap() with a call to munmap(), and the first client needs to close the file descriptor it obtained via ION_IOC_SHARE, and call ION_IOC_FREE as follows:

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

Here ion_handle_data holds the handle as shown below:

     struct ion_handle_data {
	     struct ion_handle *handle;
     }

The ION_IOC_FREE command causes the handle‘s reference counter to be decremented by one. When this reference counter reaches zero, the ion_handle object 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.

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

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

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