Memory

oneAPI Level Zero Specification - Version 1.18.31

Memory Functions

zesMemoryGetProperties

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesMemoryGetProperties(zes_mem_handle_t hMemory, zes_mem_properties_t *pProperties)

Get memory properties.

• The application may call this function from simultaneous threads.

• The implementation of this function should be lock-free.

Parameters:

• hMemory – [in] Handle for the component.

• pProperties – [in,out] Will contain memory properties.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hMemory

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pProperties

zesMemoryGetState

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesMemoryGetState(zes_mem_handle_t hMemory, zes_mem_state_t *pState)

Get memory state - health, allocated.

• The application may call this function from simultaneous threads.

• The implementation of this function should be lock-free.

Parameters:

• hMemory – [in] Handle for the component.

• pState – [in,out] Will contain the current health and allocated memory.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hMemory

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pState

zesMemoryGetBandwidth

Added in version 1.0

ZE_APIEXPORT ze_result_t ZE_APICALL zesMemoryGetBandwidth(zes_mem_handle_t hMemory, zes_mem_bandwidth_t *pBandwidth)

Get memory bandwidth.

• The application may call this function from simultaneous threads.

• The implementation of this function should be lock-free.

Parameters:

• hMemory – [in] Handle for the component.

• pBandwidth – [in,out] Will contain the total number of bytes read from and written to memory, as well as the current maximum bandwidth.

Returns:

• ZE_RESULT_SUCCESS

• ZE_RESULT_ERROR_UNINITIALIZED

• ZE_RESULT_ERROR_DEVICE_LOST

• ZE_RESULT_ERROR_OUT_OF_HOST_MEMORY

• ZE_RESULT_ERROR_OUT_OF_DEVICE_MEMORY

• ZE_RESULT_ERROR_INVALID_ARGUMENT

• ZE_RESULT_ERROR_UNSUPPORTED_FEATURE

• ZE_RESULT_ERROR_DEPENDENCY_UNAVAILABLE

• ZE_RESULT_ERROR_NOT_AVAILABLE

• ZE_RESULT_ERROR_DEVICE_REQUIRES_RESET

• ZE_RESULT_ERROR_DEVICE_IN_LOW_POWER_STATE

• ZE_RESULT_ERROR_UNKNOWN

• ZE_RESULT_ERROR_INVALID_NULL_HANDLE

  • nullptr == hMemory

• ZE_RESULT_ERROR_INVALID_NULL_POINTER

  • nullptr == pBandwidth

• ZE_RESULT_ERROR_INSUFFICIENT_PERMISSIONS

  • User does not have permissions to query this telemetry.

Memory Enums

zes_mem_type_t

Added in version 1.0

enum zes_mem_type_t

Memory module types.

Values:

enumerator ZES_MEM_TYPE_HBM

HBM memory.

enumerator ZES_MEM_TYPE_DDR

DDR memory.

enumerator ZES_MEM_TYPE_DDR3

DDR3 memory.

enumerator ZES_MEM_TYPE_DDR4

DDR4 memory.

enumerator ZES_MEM_TYPE_DDR5

DDR5 memory.

enumerator ZES_MEM_TYPE_LPDDR

LPDDR memory.

enumerator ZES_MEM_TYPE_LPDDR3

LPDDR3 memory.

enumerator ZES_MEM_TYPE_LPDDR4

LPDDR4 memory.

enumerator ZES_MEM_TYPE_LPDDR5

LPDDR5 memory.

enumerator ZES_MEM_TYPE_SRAM

SRAM memory.

enumerator ZES_MEM_TYPE_L1

L1 cache.

enumerator ZES_MEM_TYPE_L3

L3 cache.

enumerator ZES_MEM_TYPE_GRF

Execution unit register file.

enumerator ZES_MEM_TYPE_SLM

Execution unit shared local memory.

enumerator ZES_MEM_TYPE_GDDR4

GDDR4 memory.

enumerator ZES_MEM_TYPE_GDDR5

GDDR5 memory.

enumerator ZES_MEM_TYPE_GDDR5X

GDDR5X memory.

enumerator ZES_MEM_TYPE_GDDR6

GDDR6 memory.

enumerator ZES_MEM_TYPE_GDDR6X

GDDR6X memory.

enumerator ZES_MEM_TYPE_GDDR7

GDDR7 memory.

enumerator ZES_MEM_TYPE_LPDDR5X

LPDDR5X memory.

enumerator ZES_MEM_TYPE_HBM2

HBM2 memory. (since v1.17)

enumerator ZES_MEM_TYPE_DDR2

DDR2 memory. (since v1.17)

enumerator ZES_MEM_TYPE_HBM2E

HBM2E memory. (since v1.17)

enumerator ZES_MEM_TYPE_HBM3

HBM3 memory. (since v1.17)

enumerator ZES_MEM_TYPE_HBM3E

HBM3E memory. (since v1.17)

enumerator ZES_MEM_TYPE_HBM4

HBM4 memory. (since v1.17)

enumerator ZES_MEM_TYPE_LPDDR6

LPDDR6 memory. (since v1.17)

enumerator ZES_MEM_TYPE_FORCE_UINT32

Value marking end of ZES_MEM_TYPE_* ENUMs.

zes_mem_loc_t

Added in version 1.0

enum zes_mem_loc_t

Memory module location.

Values:

enumerator ZES_MEM_LOC_SYSTEM

System memory.

enumerator ZES_MEM_LOC_DEVICE

On board local device memory.

enumerator ZES_MEM_LOC_FORCE_UINT32

Value marking end of ZES_MEM_LOC_* ENUMs.

zes_mem_health_t

Added in version 1.0

enum zes_mem_health_t

Memory health.

Values:

enumerator ZES_MEM_HEALTH_UNKNOWN

The memory health cannot be determined.

enumerator ZES_MEM_HEALTH_OK

All memory channels are healthy.

enumerator ZES_MEM_HEALTH_DEGRADED

Excessive correctable errors have been detected on one or more channels. Device should be reset.

enumerator ZES_MEM_HEALTH_CRITICAL

Operating with reduced memory to cover banks with too many uncorrectable errors.

enumerator ZES_MEM_HEALTH_REPLACE

Device should be replaced due to excessive uncorrectable errors.

enumerator ZES_MEM_HEALTH_FORCE_UINT32

Value marking end of ZES_MEM_HEALTH_* ENUMs.

Memory Structures

zes_mem_properties_t

Added in version 1.0

struct zes_mem_properties_t

Memory properties. To get the memory vendor ID and memory vendor name, pNext member of this structure should point to an instance of zes_memory_vendor_info_ext_properties_t with its stype set to ZES_STRUCTURE_TYPE_MEMORY_VENDOR_INFO_EXT_PROPERTIES.

Public Members

zes_structure_type_t stype

[in] type of this structure

void *pNext

[in,out][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

zes_mem_type_t type

[out] The memory type

ze_bool_t onSubdevice

[out] True if this resource is located on a sub-device; false means that the resource is on the device of the calling Sysman handle

uint32_t subdeviceId

[out] If onSubdevice is true, this gives the ID of the sub-device

zes_mem_loc_t location

[out] Location of this memory (system, device)

uint64_t physicalSize

[out] Physical memory capacity in bytes. A value of 0 indicates that this property is not known. However, a call to zesMemoryGetState() will return the available free physical memory.

int32_t busWidth

[out] Width of the memory bus. A value of -1 means that this property is unknown.

int32_t numChannels

[out] The number of memory channels. A value of -1 means that this property is unknown.

zes_mem_state_t

Added in version 1.0

struct zes_mem_state_t

Memory state - health, allocated.

• Percent free is given by 100 * free / physical mem size.

Public Members

zes_structure_type_t stype

[in] type of this structure

const void *pNext

[in][optional] must be null or a pointer to an extension-specific structure (i.e. contains stype and pNext).

zes_mem_health_t health

[out] Indicates the health of the memory

uint64_t free

[out] The free physical memory in bytes

uint64_t size

[out] The total allocatable memory in bytes (can be less than the physicalSize member of zes_mem_properties_t). DEPRECATED This member can no longer track the allocatable memory reliably. Clients depending on this information can use the zeDeviceGetProperties with ze_device_usablemem_size_ext_properties_t extension to get information of the available usable memory.

zes_mem_bandwidth_t

Added in version 1.0

struct zes_mem_bandwidth_t

Memory bandwidth.

• Percent bandwidth is calculated by taking two snapshots (s1, s2) and using the equation: bw = 10^6 * ((s2.readCounter - s1.readCounter) + (s2.writeCounter - s1.writeCounter)) / (s2.maxBandwidth * (s2.timestamp - s1.timestamp))

• Counter can roll over and rollover needs to be handled by comparing the current read against the previous read

• Counter is a 32 byte transaction count, which means the calculated delta (delta = current_value - previous_value or delta = 2^32 - previous_value + current_value in case of rollover) needs to be multiplied by 32 to get delta between samples in actual byte count

Public Members

uint64_t readCounter

[out] Total bytes read from memory

uint64_t writeCounter

[out] Total bytes written to memory

uint64_t maxBandwidth

[out] Current maximum bandwidth in units of bytes/sec

uint64_t timestamp

[out] The timestamp in microseconds when these measurements were sampled. This timestamp should only be used to calculate delta time between snapshots of this structure. Never take the delta of this timestamp with the timestamp from a different structure since they are not guaranteed to have the same base. The absolute value of the timestamp is only valid during within the application and may be different on the next execution.