Area Level Zero Implementation API¶

group aml_area_ze

Implementation of Areas with Level Zero API.

#include <aml/area/ze.h>

Implementation of Areas with Level Zero API. This building block relies on Ze implementation of host and device memory mapping to provide mmap/munmap on device memory. Additional documentation of Ze memory model can be found here:

Defines

AML_AREA_ZE_MMAP_DEVICE_FLAGS¶: Device mapping.

AML_AREA_ZE_MMAP_SHARED_FLAGS¶: Host and Device with Unified Pointer.

Functions

int aml_area_ze_device_create(struct aml_area **area, ze_device_handle_t device, uint32_t ordinal, ze_device_mem_alloc_flag_t device_flags, size_t alignment, int flags)¶

Instanciate a new area for allocating device memory using level zero backend. This area will use the first available driver handle. This area has its own context handle.

See also

zeMemAllocDevice()

Parameters:

area – [out] A pointer to the area to allocate. The resulting area is stored in this pointer and can be freed with free or aml_area_ze_destroy().
device – [in] The target device where data is to be allocated.
ordinal – [in] “ordinal of the device’s local memory to allocate from.”
device_flags – [in] Extra flag tuning device allocator behaviour.
alignment – [in] Alignment of mapped pointers. Must be a power of two.
flags – [in] The allocation type among:
- AML_AREA_ZE_MMAP_DEVICE_FLAGS
- AML_AREA_ZE_MMAP_SHARED_FLAGS

Returns:

AML_SUCCESS on success.

Returns:

-AML_ENOMEM if there was not enough memory available to satisfy this call.

Returns:

A translated ze_result_t into AML error code if calls to ze backends failed: getting drivers or context creation.

int aml_area_ze_host_create(struct aml_area **area, ze_host_mem_alloc_flag_t host_flags, size_t alignment)¶

Instanciate a new area for allocating host memory using level zero backend. This area will use the first available driver handle. This area has its own context handle.

See also

zeMemAllocHost()

Parameters:

area – [out] A pointer to the area to allocate. The resulting area is stored in this pointer and can be freed with free or aml_area_ze_destroy().
host_flags – [in] Extra flag tuning device allocator behaviour.
alignment – [in] Alignment of mapped pointers. Must be a power of two.

Returns:

AML_SUCCESS on success.

Returns:

-AML_ENOMEM if there was not enough memory available to satisfy this call.

Returns:

A translated ze_result_t into AML error code if calls to ze backends failed: getting drivers or context creation.

void aml_area_ze_destroy(struct aml_area **area)¶

Free the memory associated with an area allocated with aml_area_ze_create()

Parameters:: area – [inout] A pointer to the area to free.

void *aml_area_ze_mmap_device(const struct aml_area_data *area_data, size_t size, struct aml_area_mmap_options *options)¶

mmap() method for struct aml_area_ze_data allocating data on device.

Parameters:

area_data – [in] A pointer to a valid struct aml_area_ze_data.
size – [in] The size of the memory region to map.
options – [in] unused.

Returns:

A pointer to the mapped data on success.

Returns:

If underlying call to zeMemAllocDevice() fails with a ze_result_t the error value is translated into an AML error and stored into aml_errno while the function will returns NULL. Error codes are translated as followed:

ZE_RESULT_ERROR_UNINITIALIZED -> AML_FAILURE
ZE_RESULT_ERROR_DEVICE_LOST -> AML_FAILURE
ZE_RESULT_ERROR_INVALID_NULL_HANDLE -> AML_EINVAL
ZE_RESULT_ERROR_INVALID_NULL_POINTER -> AML_EINVAL
ZE_RESULT_ERROR_INVALID_ENUMERATION -> AML_EINVAL
ZE_RESULT_ERROR_UNSUPPORTED_SIZE -> AML_ENOTSUP
ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT -> AML_ENOTSUP
ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY -> AML_ENOMEM
ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY -> AML_ENOMEM

void *aml_area_ze_mmap_shared(const struct aml_area_data *area_data, size_t size, struct aml_area_mmap_options *options)¶

mmap() method for struct aml_area_ze_data aallocating data on device and host.

Parameters:

area_data – [in] A pointer to a valid struct aml_area_ze_data.
size – [in] The size of the memory region to map.
options – [in] unused.

Returns:

A pointer to the mapped data on success.

Returns:

If underlying call to zeMemAllocShared() fails with a ze_result_t the error value is translated into an AML error and stored into aml_errno while the function will returns NULL. Error codes are translated as followed:

ZE_RESULT_ERROR_UNINITIALIZED -> AML_FAILURE
ZE_RESULT_ERROR_DEVICE_LOST -> AML_FAILURE
ZE_RESULT_ERROR_INVALID_NULL_HANDLE -> AML_EINVAL
ZE_RESULT_ERROR_INVALID_NULL_POINTER -> AML_EINVAL
ZE_RESULT_ERROR_INVALID_ENUMERATION -> AML_EINVAL
ZE_RESULT_ERROR_UNSUPPORTED_SIZE -> AML_ENOTSUP
ZE_RESULT_ERROR_UNSUPPORTED_ALIGNMENT -> AML_ENOTSUP
ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY -> AML_ENOMEM
ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY -> AML_ENOMEM

void *aml_area_ze_mmap_host(const struct aml_area_data *area_data, size_t size, struct aml_area_mmap_options *options)¶

mmap() method for struct aml_area_ze_data aallocating data on host.

Parameters:

area_data – [in] A pointer to a valid struct aml_area_ze_data.
size – [in] The size of the memory region to map.
options – [in] unused.

Returns:

A pointer to the mapped data on success.

Returns:

If underlying call to zeMemAllocHost() fails with a ze_result_t the error value is translated into an AML error and stored into aml_errno while the function will returns NULL.

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

unmap() method for struct aml_area_ze_data to unmap data mapped with one of struct aml_area_ze_data mmap() methods:

See also

aml_area_ze_mmap_host()

See also

aml_area_ze_mmap_device()

See also

aml_area_ze_mmap_shared()

Parameters:

area_data – [in] A pointer to a valid struct aml_area_ze_data.
ptr – [inout] A pointer to the memory to unmap. This pointer must have been obtained with one of the struct aml_area_ze_data mmap() methods.
size – [in] unused.

Returns:

AML_SUCCESS or a translated ze_result_t into an aml_errno. Error codes are translated as followed:

ZE_RESULT_ERROR_UNINITIALIZED -> AML_FAILURE
ZE_RESULT_ERROR_DEVICE_LOST -> AML_FAILURE
ZE_RESULT_ERROR_INVALID_NULL_HANDLE -> AML_EINVAL
ZE_RESULT_ERROR_INVALID_NULL_POINTER -> AML_EINVAL

Variables

struct aml_area_ops aml_area_ze_ops_device¶: Operation table for the aml_area_ze on device

struct aml_area_ops aml_area_ze_ops_shared¶: Operation table for the aml_area_ze on host and device

struct aml_area_ops aml_area_ze_ops_host¶: Operation table for the aml_area_ze on host

struct aml_area *aml_area_ze_device¶

Default device mapper with cached allocation and 64 bytes alignment The driver used to obtain devices is the first returned driver.

See also

zeDeviceGet()

struct aml_area *aml_area_ze_host¶

Default hist mapper with cached allocation and 64 bytes alignment. The driver used to obtain devices is the first returned driver.

See also

zeDeviceGet()

struct aml_area_ze_data¶: #include <ze.h>

Implementation of aml_area_data.