Area Linux Implementation API¶

group aml_area_linux

Linux Implementation of AML Areas.

This building block relies on the libnuma implementation and the Linux mmap() / munmap() to provide mmap() / munmap() on NUMA host processor memory. New areas may be created to allocate a specific subset of memories. This building block also includes a static declaration of a default initialized area that can be used out-of-the-box with the abstract area API.

#include <aml/area/linux.h>

Enums

enum aml_area_linux_policy¶

Allowed policy flag for area creation.

Values:

enumerator AML_AREA_LINUX_POLICY_DEFAULT¶: Default allocation policy.

enumerator AML_AREA_LINUX_POLICY_BIND¶: Enforce binding to the specified area nodeset; fail if not possible.

enumerator AML_AREA_LINUX_POLICY_PREFERRED¶: Bind to the specified area nodeset; if not possible, fall back to other available nodes.

enumerator AML_AREA_LINUX_POLICY_INTERLEAVE¶: Bind to the specified area nodeset in a round-robin fashion.

Functions

int aml_area_linux_create(struct aml_area **area, const struct aml_bitmap *nodemask, const enum aml_area_linux_policy policy)¶

Linux area creation.

Allocates and initializes struct aml_area implemented by aml_area_linux operations.

Parameters:

area – [out] pointer to an uninitialized struct aml_area pointer to receive the new area.
nodemask – [in] list of memory nodes to use. Defaults to all allowed memory nodes if NULL.
policy – [in] The memory allocation policy to use when binding to nodeset.

Returns:

On success, returns 0 and fills “area” with a pointer to the new aml_area.

Returns:

On failure, fills “area” with NULL and returns one of AML error codes:

AML_ENOMEM if there wasn’t enough memory available.
AML_EINVAL if input flags were invalid.
AML_EDOM if the nodemask provided was out of bounds (of the allowed node set).

void aml_area_linux_destroy(struct aml_area **area)¶

Linux area destruction.

Destroys (finalizes and frees resources) struct aml_area created by aml_area_linux_create().

Parameters:: area – address of an initialized struct aml_area pointer, which will be reset to NULL on return from this call.

int aml_area_linux_mbind(struct aml_area_linux_data *bind, void *ptr, size_t size)¶

Binds memory of size “size” pointed to by “ptr” using the binding provided in “bind”. If the mbind() call was not successfull, i.e., AML_FAILURE is returned, then “errno” should be inspected for further error information.

Parameters:

bind – The requested binding. “mmap_flags” is actually unused.
ptr – The memory to bind.
size – The size of the memory pointed to by “ptr”.

Returns:

0 if successful; an error code otherwise.

int aml_area_linux_check_binding(struct aml_area_linux_data *area_data, void *ptr, size_t size)¶

Checks whether the binding of a pointer obtained with aml_area_linux_mmap() followed by aml_area_linux_mbind() matches the area settings.

Parameters:

area_data – The expected binding settings.
ptr – The supposedly bound memory.
size – The memory size.

Returns:

1 if the mapped memory binding in “ptr” matches the “area_data” binding settings, else 0.

void *aml_area_linux_mmap(const struct aml_area_data *area_data, size_t size, struct aml_area_mmap_options *opts)¶

mmap block for AML area.

This function is a wrapper around the mmap() call using arguments set in “mmap_flags” of “area_data”. This function does not perform binding, unlike what is done in areas created using aml_area_linux_create().

Parameters:

area_data – The structure containing “mmap_flags” for the mmap() call. “nodemask” and “bind_flags” fields are ignored.
size – The size to allocate.
opts – See “aml_area_linux_mmap_options”.

Returns:

a valid memory pointer, or NULL on failure. On failure, “errno” should be checked for further information.

int aml_area_linux_munmap(const struct aml_area_data *area_data, void *ptr, const size_t size)¶

munmap hook for AML area.

Unmaps memory mapped with aml_area_linux_mmap().

Parameters:

area_data – unused
ptr – The virtual memory to unmap.
size – The size of the virtual memory to unmap.

Returns:

AML_SUCCESS on success, else AML_FAILURE. On failure, “errno” should be checked for further information.

Variables

struct aml_area_ops aml_area_linux_ops¶: Contains area operations implementation for the Linux area.

struct aml_area aml_area_linux¶: Default Linux area using a private mapping and no binding. Can be used out-of-the-box with aml_area_*() functions.

struct aml_area_linux_data¶: #include <linux.h>

Implementation of aml_area_data for Linux areas.

struct aml_area_linux_mmap_options¶

#include <linux.h>

Options implementation for aml_area_linux_mmap().