aligned_malloc.h File Reference

#include <stddef.h>

Include dependency graph for aligned_malloc.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	memalign(align, size)   aligned_malloc(align, size)
	A convenience macro for the Linux API. More...

Functions
void *	aligned_malloc (size_t align, size_t size)
	Allocated aligned memory. More...
int	posix_memalign (void **memptr, size_t alignment, size_t size)
void	aligned_free (void *ptr)
	Free aligned memory. More...

Macro Definition Documentation

memalign

#define memalign	(		align,
			size
	)		aligned_malloc(align, size)

A convenience macro for the Linux API.

memalign() is simply a convenience definition which provides the commonly-used Linux API memalign. This forwards the arguments to aligned_malloc() and behaves in the same manner.

Parameters

align	Alignment of the memory block. Alignment refers to the starting address of the memory block. If 32-byte alignment is requested, the start address of the returned pointer will be 32-byte aligned. Note: Alignment must be a power of two. (1, 2, 4, 8, etc.)
size	Size of the memory allocation

Returns

Pointer to allocated memory. If memory was not successfully allocated, the function will return NULL. This can happen due to invalid input (alignment is 0, size is 0, alignment is not a power of 2) or due to insufficient memory left for the requested allocation.

Definition at line 57 of file aligned_malloc.h.

Function Documentation

aligned_free()

void aligned_free

(

void *

ptr

)

Free aligned memory.

Free memory that was allocated using aligned_malloc(). This function must not be called on memory which was not allocated with aligned_malloc().

Parameters

ptr	Pointer to the aligned_memory() block that will be freed.

aligned_free works like free(), but we work backwards from the returned pointer to find the correct offset and pointer location to return to free() Note that it is VERY BAD to call free() on an aligned_malloc() pointer.

Definition at line 74 of file aligned_malloc.c.

{
    assert(ptr);

    /*
     * Walk backwards from the passed-in pointer to get the pointer offset
     * We convert to an offset_t pointer and rely on pointer math to get the data
     */
    offset_t offset = *((offset_t*)ptr - 1);

    /*
     * Once we have the offset, we can get our original pointer and call free
     */
    void* p = (void*)((uint8_t*)ptr - offset);
    free(p);
}

References free().

aligned_malloc()

void* aligned_malloc	(	size_t	align,
		size_t	size
	)

Allocated aligned memory.

Allocate memory with at least alignment align and size size Memory which has been allocated with aligned_malloc() must be freed by calling aligned_free(). Calling free() will result in a panic or other negative effects.

Parameters

align	Alignment of the memory block. Alignment refers to the starting address of the memory block. If 32-byte alignment is requested, the start address of the returned pointer will be 32-byte aligned. Note: Alignment must be a power of two. (1, 2, 4, 8, etc.)
size	Size of the memory allocation

Returns

Pointer to allocated memory. If memory was not successfully allocated, the function will return NULL. This can happen due to invalid input (alignment is 0, size is 0, alignment is not a power of 2) or due to insufficient memory left for the requested allocation.

We will call malloc with extra bytes for our header and the offset required to guarantee the desired alignment.

Definition at line 36 of file aligned_malloc.c.

{
    void* ptr = NULL;

    // We want it to be a power of two since align_up operates on powers of two
    assert((align & (align - 1)) == 0);

    if(align && size)
    {
        /*
         * We know we have to fit an offset value
         * We also allocate extra bytes to ensure we can meet the alignment
         */
        size_t hdr_size = PTR_OFFSET_SZ + (align - 1);
        void* p = malloc(size + hdr_size);

        if(p)
        {
            /*
             * Add the offset size to malloc's pointer (we will always store that)
             * Then align the resulting value to the arget alignment
             */
            ptr = (void*)align_up(((uintptr_t)p + PTR_OFFSET_SZ), align);

            // Calculate the offset and store it behind our aligned pointer
            *((offset_t*)ptr - 1) = (offset_t)((uintptr_t)ptr - (uintptr_t)p);

        } // else NULL, could not malloc
    } // else NULL, invalid arguments

    return ptr;
}

References align_up, malloc(), and PTR_OFFSET_SZ.

Referenced by posix_memalign().

Here is the caller graph for this function:

posix_memalign()

int posix_memalign	(	void **	memptr,
		size_t	alignment,
		size_t	size
	)

Posix Memory Alignment Extension

Generated aligned memory. This function forwards the request to aligned malloc. Allocated memory must be freed with aligned_free().

Parameters

memptr	A pointer to the pointer which will store the aligned memory. The memory must be freed with aligned_free(). memptr must not be NULL.
alignment	The target alignment for the memory. Must be a power of 2.
size	The size of the allocation. Must be > 0.

Precondition

memptr is not NULL. alignment is power-of-2. size > 0.

Returns

ENOMEM if memory could not be allocated, EINVAL if alignment is not a power-of-2, and 0 on successful allocation.

Definition at line 8 of file posix_memalign.c.

{
    int r = ENOMEM;

    assert(__memptr);
    assert(__size > 0);

    // TODO: Do we need to check if __alignment is a multiple of sizeof(void *)?
    if(!IS_POWER_2(__alignment))
    {
        r = EINVAL;
    }
    else
    {
        *__memptr = aligned_malloc(__alignment, __size);

        if(*__memptr != NULL)
        {
            r = 0;
        }
    }

    return r;
}

References aligned_malloc(), and IS_POWER_2.