XRM Library C Program APIs¶

XRM provides several sets of C APIs defined in xrm.h so that applications can use these interfaces to handle the cu resource. Here are the the detailed description of the APIs.

Global Namespace¶

Overview¶

// typedefs

typedef int32_t (* xrmPluginVersionType)()
typedef int32_t (* xrmApiVersionType)()
typedef int32_t (* xrmPluginFuncType)(xrmPluginFuncParam *)
typedef void* xrmContext

// enums

enum xrmCuType
enum xrmLogLevelType

// structs

struct xrmAllocationQueryInfo
struct xrmAllocationQueryInfoV2
struct xrmCuGroupProperty
struct xrmCuGroupPropertyV2
struct xrmCuGroupResource
struct xrmCuGroupResourceV2
struct xrmCuListProperty
struct xrmCuListPropertyV2
struct xrmCuListResInforV2
struct xrmCuListResource
struct xrmCuListResourceV2
struct xrmCuPoolProperty
struct xrmCuPoolPropertyV2
struct xrmCuPoolResInforV2
struct xrmCuPoolResource
struct xrmCuPoolResourceV2
struct xrmCuProperty
struct xrmCuPropertyV2
struct xrmCuResInforV2
struct xrmCuResource
struct xrmCuResourceV2
struct xrmCuStat
struct xrmDeviceIdListPropertyV2
struct xrmDeviceListResInforV2
struct xrmPluginData
struct xrmPluginFuncParam
struct xrmReservationQueryInfoV2
struct xrmUdfCuGroupProperty
struct xrmUdfCuGroupPropertyV2
struct xrmUdfCuListProperty
struct xrmUdfCuListPropertyV2
struct xrmUdfCuProperty
struct xrmUdfCuPropertyV2

// macros

#define XRM_API_VERSION_1
#define XRM_DEVICE_INFO_CONSTRAINT_TYPE_HARDWARE_DEVICE_INDEX
#define XRM_DEVICE_INFO_CONSTRAINT_TYPE_MASK
#define XRM_DEVICE_INFO_CONSTRAINT_TYPE_NULL
#define XRM_DEVICE_INFO_CONSTRAINT_TYPE_SHIFT
#define XRM_DEVICE_INFO_CONSTRAINT_TYPE_VIRTUAL_DEVICE_INDEX
#define XRM_DEVICE_INFO_DEVICE_INDEX_MASK
#define XRM_DEVICE_INFO_DEVICE_INDEX_SHIFT
#define XRM_LOAD_GRANULARIY_1000000_MASK
#define XRM_LOAD_GRANULARIY_1000000_SHIFT
#define XRM_LOAD_GRANULARIY_100_MASK
#define XRM_LOAD_GRANULARIY_100_SHIFT
#define XRM_MEMORY_INFO_CONSTRAINT_TYPE_HARDWARE_MEMORY_INDEX
#define XRM_MEMORY_INFO_CONSTRAINT_TYPE_MASK
#define XRM_MEMORY_INFO_CONSTRAINT_TYPE_NULL
#define XRM_MEMORY_INFO_CONSTRAINT_TYPE_SHIFT
#define XRM_MEMORY_INFO_MEMORY_INDEX_MASK
#define XRM_MEMORY_INFO_MEMORY_INDEX_SHIFT
#define XRM_POLICY_INFO_CONSTRAINT_TYPE_LEAST_USED_FIRST
#define XRM_POLICY_INFO_CONSTRAINT_TYPE_MASK
#define XRM_POLICY_INFO_CONSTRAINT_TYPE_MOST_USED_FIRST
#define XRM_POLICY_INFO_CONSTRAINT_TYPE_NULL
#define XRM_POLICY_INFO_CONSTRAINT_TYPE_SHIFT

Global Functions¶

xrmCuAllocLeastUsedWithLoad¶

#include "lib/experimental/xrm_experimental.h"

int32_t xrmCuAllocLeastUsedWithLoad (
    xrmContext context,
    xrmCuProperty* cuProp,
    char* xclbinFileName,
    xrmCuResource* cuRes
    )

Allocates compute unit with a device, cu, and channel given a kernel name or alias or both and request load. This function also provides the xclbin and kernel plugin loaded on the device. If required CU is not available, this function will try to load the xclbin to one device and do the allocation again. If there are no free CUs remaining, the CU with the minimum load which supports the requested capacity will be acquired. Additionally, it strictly enforces that the allocated CU comes from a device that was loaded with the user specified xclbinFileName.

Parameters:

context	the context created through xrmCreateContext()
cuProp	the property of cu. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested. devExcl: request exclusive device usage for this client. requestLoad: request load, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: request to allocate cu from specified resource pool.
xclbinFileName	xclbin file (full path and name)
cuRes	cu resource. xclbinFileName: xclbin (path and name) attached to this device. kernelPluginFileName: kernel plugin (only name) attached to this device. kernelName: the kernel name of allocated cu. kernelAlias: the name alias of allocated cu. instanceName: the instance name of allocated cu. cuName: the name of allocated cu (kernelName:instanceName). uuid: uuid of the loaded xclbin file. deviceId: device id of this cu. cuId: cu id of this cu. channelId: channel id of this cu. cuType: type of cu, hardware kernel or soft kernel. allocServiceId: service id for this cu allocation. channelLoad: allocated load of this cu, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: id of the cu pool this cu comes from, the default pool id is 0.

Returns:

int32_t, 0 on success or appropriate error number

xrmCuAllocLeastUsedFromDev¶

#include "lib/experimental/xrm_experimental.h"

int32_t xrmCuAllocLeastUsedFromDev (
    xrmContext context,
    int32_t deviceId,
    xrmCuProperty* cuProp,
    xrmCuResource* cuRes
    )

Allocates compute unit from specified device given a kernel name or alias or both and request load. This function also provides the xclbin and kernel plugin loaded on the device.

Parameters:

context	the context created through xrmCreateContext()
deviceId	the id of target device to allocate the cu.
cuProp	the property of requested cu. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested. devExcl: request exclusive device usage for this client. requestLoad: request load, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: request to allocate cu from specified resource pool
cuRes	the cu resource. xclbinFileName: xclbin (path and name) attached to this device. kernelPluginFileName: kernel plugin (only name) attached to this device. kernelName: the kernel name of allocated cu. kernelAlias: the name alias of allocated cu. instanceName: the instance name of allocated cu. cuName: the name of allocated cu (kernelName:instanceName). uuid: uuid of the loaded xclbin file. deviceId: device id of this cu. cuId: cu id of this cu. channelId: channel id of this cu. cuType: type of cu, hardware kernel or soft kernel. allocServiceId: service id for this cu allocation. channelLoad: allocated load of this cu, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: id of the cu pool this cu comes from, the system default pool id is 0.

Returns:

int32_t, 0 on success or appropriate error number

xrmCreateContext¶

#include "lib/xrm.h"

xrmContext xrmCreateContext (uint32_t xrmApiVersion)

Establishes a connection with the XRM daemon.

Parameters:

xrmApiVersion

the XRM API version number

Returns:

xrmContext, pointer to created context or NULL on fail

xrmDestroyContext¶

#include "lib/xrm.h"

int32_t xrmDestroyContext (xrmContext context)

Disconnects an existing connection with the XRM daemon.

Parameters:

context

the context created through xrmCreateContext()

Returns:

int32_t, 0 on success or appropriate error number

xrmIsDaemonRunning¶

#include "lib/xrm.h"

bool xrmIsDaemonRunning (xrmContext context)

To check whether the daemon is running.

Parameters:

context

the context created through xrmCreateContext()

Returns:

bool, true on running or false on NOT running

xrmEnableOneDevice¶

#include "lib/xrm.h"

int32_t xrmEnableOneDevice (
    xrmContext context,
    int32_t deviceId
    )

Enable one device.

Parameters:

context	the context created through xrmCreateContext()
deviceId	the device id to enable

Returns:

0 on success or appropriate error number

xrmDisableOneDevice¶

#include "lib/xrm.h"

int32_t xrmDisableOneDevice (
    xrmContext context,
    int32_t deviceId
    )

Disable one device.

Parameters:

context	the context created through xrmCreateContext()
deviceId	the device id to disable

Returns:

int32_t, 0 on success or appropriate error number

xrmLoadOneDevice¶

#include "lib/xrm.h"

int32_t xrmLoadOneDevice (
    xrmContext context,
    int32_t deviceId,
    char* xclbinFileName
    )

Loads xclbin to one device.

Parameters:

context	the context created through xrmCreateContext()
deviceId	the device id to load the xclbin file, -1 means to any available device
xclbinFileName	xclbin file (full path and name)

Returns:

int32_t, device id (>= 0) loaded with xclbin or appropriate error number (< 0) on fail

xrmUnloadOneDevice¶

#include "lib/xrm.h"

int32_t xrmUnloadOneDevice (
    xrmContext context,
    int32_t deviceId
    )

Unloads xclbin from one device.

Parameters:

context	the context created through xrmCreateContext()
deviceId	the device id to unload the xclbin file

Returns:

int32_t, 0 on success or appropriate error number

xrmCuAlloc¶

#include "lib/xrm.h"

int32_t xrmCuAlloc (
    xrmContext context,
    xrmCuProperty* cuProp,
    xrmCuResource* cuRes
    )

Allocates compute unit with a device, cu, and channel given a kernel name or alias or both and request load. This function also provides the xclbin and kernel plugin loaded on the device.

Parameters:

context	the context created through xrmCreateContext()
cuProp	the property of requested cu. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested. devExcl: request exclusive device usage for this client. requestLoad: request load, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: request to allocate cu from specified resource pool
cuRes	the cu resource. xclbinFileName: xclbin (path and name) attached to this device. kernelPluginFileName: kernel plugin (only name) attached to this device. kernelName: the kernel name of allocated cu. kernelAlias: the name alias of allocated cu. instanceName: the instance name of allocated cu. cuName: the name of allocated cu (kernelName:instanceName). uuid: uuid of the loaded xclbin file. deviceId: device id of this cu. cuId: cu id of this cu. channelId: channel id of this cu. cuType: type of cu, hardware kernel or soft kernel. allocServiceId: service id for this cu allocation. channelLoad: allocated load of this cu, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: id of the cu pool this cu comes from, the system default pool id is 0.

Returns:

int32_t, 0 on success or appropriate error number

xrmCuAllocFromDev¶

#include "lib/xrm.h"

int32_t xrmCuAllocFromDev (
    xrmContext context,
    int32_t deviceId,
    xrmCuProperty* cuProp,
    xrmCuResource* cuRes
    )

Allocates compute unit from specified device given a kernel name or alias or both and request load. This function also provides the xclbin and kernel plugin loaded on the device.

Parameters:

context	the context created through xrmCreateContext()
deviceId	the id of target device to allocate the cu.
cuProp	the property of requested cu. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested. devExcl: request exclusive device usage for this client. requestLoad: request load, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: request to allocate cu from specified resource pool
cuRes	the cu resource. xclbinFileName: xclbin (path and name) attached to this device. kernelPluginFileName: kernel plugin (only name) attached to this device. kernelName: the kernel name of allocated cu. kernelAlias: the name alias of allocated cu. instanceName: the instance name of allocated cu. cuName: the name of allocated cu (kernelName:instanceName). uuid: uuid of the loaded xclbin file. deviceId: device id of this cu. cuId: cu id of this cu. channelId: channel id of this cu. cuType: type of cu, hardware kernel or soft kernel. allocServiceId: service id for this cu allocation. channelLoad: allocated load of this cu, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: id of the cu pool this cu comes from, the system default pool id is 0.

Returns:

int32_t, 0 on success or appropriate error number

xrmCuListAlloc¶

#include "lib/xrm.h"

int32_t xrmCuListAlloc (
    xrmContext context,
    xrmCuListProperty* cuListProp,
    xrmCuListResource* cuListRes
    )

Allocates a list of compute unit resource given a list of kernels’s property with kernel name or alias or both and request load.

Parameters:

context	the context created through xrmCreateContext()
cuListProp	the property of cu list. cuProps: cu prop list to fill kernelName, devExcl and requestLoad, starting from cuProps[0], no hole. cuNum: request number of cu in this list. sameDevice: request this list of cu from same device.
cuListRes	the cu list resource. cuResources: cu resource list to fill the allocated cus infor, starting from cuResources[0], no hole. cuNum: allocated cu number in this list.

Returns:

int32_t, 0 on success or appropriate error number

xrmCuRelease¶

#include "lib/xrm.h"

bool xrmCuRelease (
    xrmContext context,
    xrmCuResource* cuRes
    )

Releases a previously allocated resource.

Parameters:

context

the context created through xrmCreateContext()

cuRes

the cu resource. xclbinFileName: xclbin (path and name) attached to this device. kernelPluginFileName: kernel plugin (only name) attached to this device. kernelName: the kernel name of allocated cu. kernelAlias: the name alias of allocated cu. instanceName: the instance name of allocated cu. cuName: the name of allocated cu (kernelName:instanceName). uuid: uuid of the loaded xclbin file. deviceId: device id of this cu. cuId: cu id of this cu. channelId: channel id of this cu. cuType: type of cu, hardware kernel or soft kernel. allocServiceId: service id for this cu allocation. channelLoad: allocated load of this cu, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: id of the cu pool this cu comes from, the system default pool id is 0.

Returns:

bool, true on success or false on fail

xrmCuListRelease¶

#include "lib/xrm.h"

bool xrmCuListRelease (
    xrmContext context,
    xrmCuListResource* cuListRes
    )

Releases a previously allocated list of resources.

Parameters:

context	the context created through xrmCreateContext()
cuListRes	the cu list resource. cuResources: cu resource list to be released, starting from cuResources[0], no hole. cuNum: number of cu in this list.

Returns:

bool, true on success or false on fail

xrmUdfCuGroupDeclare¶

#include "lib/xrm.h"

int32_t xrmUdfCuGroupDeclare (
    xrmContext context,
    xrmUdfCuGroupProperty* udfCuGroupProp,
    char* udfCuGroupName
    )

Declares user defined cu group type given the specified kernels’s property with cu name (kernelName:instanceName) and request load.

Parameters:

context	the context created through xrmCreateContext()
udfCuGroupProp	the property of user defined cu group. optionUdfCuListProps[]: option cu list property array starting from optionCuListProps[0], no hole. optionUdfCuListNum: number of option user defined cu list.
udfCuGroupName	unique user defined cu group name for the new group type declaration

Returns:

int32_t, 0 on success or appropriate error number

xrmUdfCuGroupUndeclare¶

#include "lib/xrm.h"

int32_t xrmUdfCuGroupUndeclare (
    xrmContext context,
    char* udfCuGroupName
    )

Undeclares user defined cu group type given the specified group name.

Parameters:

context	the context created through xrmCreateContext()
udfCuGroupName	user defined cu group name for the group type undeclaration

Returns:

int32_t, 0 on success or appropriate error number

xrmCuGroupAlloc¶

#include "lib/xrm.h"

int32_t xrmCuGroupAlloc (
    xrmContext context,
    xrmCuGroupProperty* cuGroupProp,
    xrmCuGroupResource* cuGroupRes
    )

Allocates a group of compute unit resource given a user defined group of kernels’s property with cu name (kernelName:instanceName) and request load.

Parameters:

context	the context created through xrmCreateContext()
cuGroupProp	the property of cu group. udfCuGroupName: user defined cu group type name. poolId: id of the cu pool this group CUs come from, the system default pool id is 0.
cuGroupRes	the cu group resource. cuResources: cu resource group to fill the allocated cus infor, starting from cuResources[0], no hole. cuNum: allocated cu number in this group.

Returns:

int32_t, 0 on success or appropriate error number

xrmCuGroupRelease¶

#include "lib/xrm.h"

bool xrmCuGroupRelease (
    xrmContext context,
    xrmCuGroupResource* cuGroupRes
    )

Releases a previously allocated group of resources.

Parameters:

context	the context created through xrmCreateContext()
cuGroupRes	cu group resource. cuResources: cu resource group to be released, starting from cuResources[0], no hole. cuNum: number of cu in this group.

Returns:

bool, true on success or false on fail

xrmCuGetMaxCapacity¶

#include "lib/xrm.h"

uint64_t xrmCuGetMaxCapacity (
    xrmContext context,
    xrmCuProperty* cuProp
    )

Retrieves the maximum capacity associated with a resource.

Parameters:

context	the context created through xrmCreateContext()
cuProp	the property of cu. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested.

Returns:

uint64_t, the max capacity of the cu (> 0) or 0 if cu is not existing in system or max capacity is not described.

xrmCuCheckStatus¶

#include "lib/xrm.h"

int32_t xrmCuCheckStatus (
    xrmContext context,
    xrmCuResource* cuRes,
    xrmCuStat* cuStat
    )

To check the status of specified cu resource.

Parameters:

context	the context created through xrmCreateContext()
cuRes	the cu resource. deviceId: device id of this cu. cuId: cu id of this cu. channelId: channel id of this cu. cuType: type of cu, hardware kernel or soft kernel. allocServiceId: service id for this cu allocation.
cuStat	the status of cu. isBusy: the cu is busy or not. usedLoad: allocated load on this cu, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100)

Returns:

int32_t, 0 on success or appropriate error number

xrmAllocationQuery¶

#include "lib/xrm.h"

int32_t xrmAllocationQuery (
    xrmContext context,
    xrmAllocationQueryInfo* allocQuery,
    xrmCuListResource* cuListRes
    )

Querys the compute unit resource given the allocation service id.

Parameters:

context	the context created through xrmCreateContext()
allocQuery	the allocate query information. allocServiceId: the service id returned from allocation. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested.
cuListRes	cu list resource. cuListRes: cu resource list to fill the allocated cus infor, starting from cuResources[0], no hole. cuNum: cu number in this list.

Returns:

int32_t, 0 on success or appropriate error number

xrmCheckCuAvailableNum¶

#include "lib/xrm.h"

int32_t xrmCheckCuAvailableNum (
    xrmContext context,
    xrmCuProperty* cuProp
    )

To check the available cu num on the system given the kernels’s property with kernel name or alias or both and request load.

Parameters:

context

the context created through xrmCreateContext()

cuProp

the property of cu. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested. devExcl: request exclusive device usage for this client. requestLoad: request load, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: request to allocate cu from specified resource pool.

Returns:

int32_t, available cu num (>= 0) on success or appropriate error number (< 0).

xrmCheckCuListAvailableNum¶

#include "lib/xrm.h"

int32_t xrmCheckCuListAvailableNum (
    xrmContext context,
    xrmCuListProperty* cuListProp
    )

To check the available cu list num on the system given a list of kernels’s property with kernel name or alias or both and request load.

Parameters:

context	the context created through xrmCreateContext()
cuListProp	the property of cu list. cuProps: cu prop list to fill kernelName, devExcl and requestLoad, starting from cuProps[0], no hole cuNum: request number of cu in this list. sameDevice: request this list of cu from same device.

Returns:

int32_t, available cu list num (>= 0) on success or appropriate error number (< 0).

xrmCheckCuGroupAvailableNum¶

#include "lib/xrm.h"

int32_t xrmCheckCuGroupAvailableNum (
    xrmContext context,
    xrmCuGroupProperty* cuGroupProp
    )

To check the available group number of compute unit resource given a user defined group of kernels’s property with cu name (kernelName:instanceName) and request load.

Parameters:

context	the context created through xrmCreateContext()
cuGroupProp	the property of cu group. udfCuGroupName: user defined cu group type name. poolId: id of the cu pool this group CUs come from, the system default pool id is 0.

Returns:

int32_t, available cu group num (>= 0) on success or appropriate error number (< 0).

xrmCheckCuPoolAvailableNum¶

#include "lib/xrm.h"

int32_t xrmCheckCuPoolAvailableNum (
    xrmContext context,
    xrmCuPoolProperty* cuPoolProp
    )

To check the available cu pool num on the system given a pool of kernels’s property with kernel name or alias or both and request load.

Parameters:

context	the context created through xrmCreateContext()
cuPoolProp	the property of cu pool. cuListProp: cu list property. cuListNum: number of cu list in this pool. xclbinUuid: uuid of xclbin. xclbinNum: number of xclbin in this pool.

Returns:

int32_t, available cu pool num (>= 0) on success or appropriate error number (< 0).

xrmCuPoolReserve¶

#include "lib/xrm.h"

uint64_t xrmCuPoolReserve (
    xrmContext context,
    xrmCuPoolProperty* cuPoolProp
    )

Reserves a pool of compute unit resource given a pool of kernels’s property with kernel name or alias or both and request load.

Parameters:

context	the context created through xrmCreateContext()
cuPoolProp	the property of cu pool. cuListProp: cu prop list to fill kernelName, devExcl and requestLoad etc. information. cuListNum: request number of such cu list for this pool. xclbinUuid: request all resource in the xclbin. xclbinNum: request number of such xclbin for this pool.

Returns:

uint64_t, reserve pool id (> 0) or 0 on fail

xrmCuPoolRelinquish¶

#include "lib/xrm.h"

bool xrmCuPoolRelinquish (
    xrmContext context,
    uint64_t poolId
    )

Relinquishes a previously reserved pool of resources.

Parameters:

context	the context created through xrmCreateContext()
poolId	the reserve pool id

Returns:

bool, true on success or false on fail

xrmReservationQuery¶

#include "lib/xrm.h"

int32_t xrmReservationQuery (
    xrmContext context,
    uint64_t poolId,
    xrmCuPoolResource* cuPoolRes
    )

Querys the compute unit resource given the reservation id. NOTE: The allocServiceId, channelId and channelLoad are NOT valid in the cuPoolRes.

Parameters:

context	the context created through xrmCreateContext()
poolId	the reserve pool id
cuPoolRes	the cu pool resource. cuPoolRes: cu resource pool to fill the allocated cus infor, starting from cuPoolRes[0], no hole. cuNum: cu number in this pool.

Returns:

int32_t, 0 on success or appropriate error number

xrmExecPluginFunc¶

#include "lib/xrm.h"

int32_t xrmExecPluginFunc (
    xrmContext context,
    char* xrmPluginName,
    uint32_t funcId,
    xrmPluginFuncParam* param
    )

Execuates the function of one specified xrm plugin.

Parameters:

context	the context created through xrmCreateContext()
xrmPluginName	name of the xrm plugin
funcId	the function id within xrm plugin
param	the parameter struct for xrm plugin function

Returns:

int32_t, 0 on success or appropriate error number

xrmCuAllocWithLoad¶

#include "lib/xrm.h"

int32_t xrmCuAllocWithLoad (
    xrmContext context,
    xrmCuProperty* cuProp,
    char* xclbinFileName,
    xrmCuResource* cuRes
    )

Allocates compute unit with a device, cu, and channel given a kernel name or alias or both and request load. This function also provides the xclbin and kernel plugin loaded on the device. If required CU is not available, this function will try to load the xclbin to one device and do the allocation again.

Following APIs are NOT stable interface and may be changed in coming future.

Parameters:

context	the context created through xrmCreateContext()
cuProp	the property of cu. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested. devExcl: request exclusive device usage for this client. requestLoad: request load, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: request to allocate cu from specified resource pool.
xclbinFileName	xclbin file (full path and name)
cuRes	cu resource. xclbinFileName: xclbin (path and name) attached to this device. kernelPluginFileName: kernel plugin (only name) attached to this device. kernelName: the kernel name of allocated cu. kernelAlias: the name alias of allocated cu. instanceName: the instance name of allocated cu. cuName: the name of allocated cu (kernelName:instanceName). uuid: uuid of the loaded xclbin file. deviceId: device id of this cu. cuId: cu id of this cu. channelId: channel id of this cu. cuType: type of cu, hardware kernel or soft kernel. allocServiceId: service id for this cu allocation. channelLoad: allocated load of this cu, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: id of the cu pool this cu comes from, the default pool id is 0.

Returns:

int32_t, 0 on success or appropriate error number

xrmLoadAndAllCuAlloc¶

#include "lib/xrm.h"

int32_t xrmLoadAndAllCuAlloc (
    xrmContext context,
    char* xclbinFileName,
    xrmCuListResource* cuListRes
    )

Loads xclbin to one device, then allocates all CUs from this device.

Parameters:

context	the context created through xrmCreateContext()
xclbinFileName	xclbin file (full path and name)
cuListRes	cu list resource. cuResources: cu resource list to fill the allocated cus infor, starting from cuResources[0], no hole. cuNum: allocated cu number in this list.

Returns:

int32_t, 0 on success or appropriate error number

xrmCuBlockingAlloc¶

#include "lib/xrm.h"

int32_t xrmCuBlockingAlloc (
    xrmContext context,
    xrmCuProperty* cuProp,
    uint64_t interval,
    xrmCuResource* cuRes
    )

Blocking function of xrmCuAlloc() , this function will try to do cu allocation until success.

Parameters:

context	the context created through xrmCreateContext()
cuProp	the property of cu. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested. devExcl: request exclusive device usage for this client. requestLoad: request load, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: request to allocate cu from specified resource pool.
interval	the interval time (useconds) before re-trying, [0 - 1000000], other value is invalid.
cuRes	cu resource. xclbinFileName: xclbin (path and name) attached to this device. kernelPluginFileName: kernel plugin (only name) attached to this device. kernelName: the kernel name of allocated cu. kernelAlias: the name alias of allocated cu. instanceName: the instance name of allocated cu. cuName: the name of allocated cu (kernelName:instanceName). uuid: uuid of the loaded xclbin file. deviceId: device id of this cu. cuId: cu id of this cu. channelId: channel id of this cu. cuType: type of cu, hardware kernel or soft kernel. allocServiceId: service id for this cu allocation. channelLoad: allocated load of this cu, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: id of the cu pool this cu comes from, the default pool id is 0.

Returns:

int32_t, 0 on success or appropriate error number

xrmCuListBlockingAlloc¶

#include "lib/xrm.h"

int32_t xrmCuListBlockingAlloc (
    xrmContext context,
    xrmCuListProperty* cuListProp,
    uint64_t interval,
    xrmCuListResource* cuListRes
    )

Blocking function of xrmCuListAlloc() , this function will try to do cu list allocation until success.

Parameters:

context	the context created through xrmCreateContext()
cuListProp	the property of cu list. cuProps: cu prop list to fill kernelName, devExcl and requestLoad, starting from cuProps[0], no hole. cuNum: request number of cu in this list. sameDevice request this list of cu from same device.
interval	the interval time (useconds) before re-trying, [0 - 1000000], other value is invalid.
cuListRes	cu list resource. cuResources: cu resource list to fill the allocated cus infor, starting from cuResources[0], no hole. cuNum: allocated cu number in this list.

Returns:

int32_t, 0 on success or appropriate error number

xrmCuGroupBlockingAlloc¶

#include "lib/xrm.h"

int32_t xrmCuGroupBlockingAlloc (
    xrmContext context,
    xrmCuGroupProperty* cuGroupProp,
    uint64_t interval,
    xrmCuGroupResource* cuGroupRes
    )

Blocking function of xrmCuGroupAlloc() , this function will try to do cu group allocation until success.

Parameters:

context	the context created through xrmCreateContext()
cuGroupProp	the property of cu group. udfCuGroupName: user defined cu group type name. poolId: id of the cu pool this group CUs come from, the system default pool id is 0.
interval	the interval time (useconds) before re-trying, [0 - 1000000], other value is invalid.
cuGroupRes	cu group resource. cuResources cu resource group to fill the allocated cus infor, starting from cuResources[0], no hole. cuNum allocated cu number in this list.

Returns:

int32_t, 0 on success or appropriate error number

xrmCuAllocV2¶

#include "lib/xrm.h"

int32_t xrmCuAllocV2 (
    xrmContext context,
    xrmCuPropertyV2* cuProp,
    xrmCuResourceV2* cuRes
    )

Allocates compute unit with a device, cu, and channel given a kernel name or alias or both and request load. This function also provides the xclbin and kernel plugin loaded on the device.

Parameters:

context	the context created through xrmCreateContext() .
cuProp	the property of requested cu. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested. devExcl: request exclusive device usage for this client. deviceInfo: resource allocation device constaint information. bit[63 - 40] reserved bit[39 - 32] constraintType 0 : no specified device constraint 1 : hardware device index. It’s used to identify hardware device index is used as the constraint. 2 : virtual device index. it’s used to descript multiple cu from same device if device index is same. It does not means from specified hardware device. This type is only valid in property of cu list. It’s not valid for single cu. others : reserved bit[31 - 0] deviceIndex memoryInfo: resource allocation memory constaint information. bit[63 - 40] reserved bit[39 - 32] constraintType 0 : no specified memory constraint 1 : hardware memory bank. It’s used to identify hardware memory bank is used as the constraint. others : reserved bit[31 - 0] memoryBankIndex policyInfo: resource allocation policy information. bit[63 - 8] reserved bit[ 7 - 0] policyType 0 : no specified policy 1 : most used first 2 : least used first others : reserved requestLoad: request load, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: request to allocate cu from specified resource pool.
cuRes	the cu resource. xclbinFileName: xclbin (path and name) attached to this device. kernelPluginFileName: kernel plugin (only name) attached to this device. kernelName: the kernel name of allocated cu. kernelAlias: the name alias of allocated cu. instanceName: the instance name of allocated cu. cuName: the name of allocated cu (kernelName:instanceName). uuid: uuid of the loaded xclbin file. deviceId: device id of this cu. cuId: cu id of this cu. channelId: channel id of this cu. cuType: type of cu, hardware kernel or soft kernel. allocServiceId: service id for this cu allocation. channelLoad: allocated load of this cu, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: id of the cu pool this cu comes from, the system default pool id is 0.

Returns:

int32_t, 0 on success or appropriate error number

xrmCuListAllocV2¶

#include "lib/xrm.h"

int32_t xrmCuListAllocV2 (
    xrmContext context,
    xrmCuListPropertyV2* cuListProp,
    xrmCuListResourceV2* cuListRes
    )

Allocates a list of compute unit resource given a list of kernels’s property with kernel name or alias or both and request load.

Parameters:

context	the context created through xrmCreateContext()
cuListProp	the property of cu list. cuProps: cu prop list to fill kernelName, devExcl and requestLoad, starting from cuProps[0], no hole. For each cu in the list: 1) if device constraint not set: allocate it from any device 2) if device constraint set with hw index: reserve it from target device 3) if device constraint set with virtual index: find all others with same virtual index, put them into one sub-list, and reserve requested CU from same device, the device id should be different from that for previous sub-lists request from virtual index. cuNum: request number of cu in this list.
cuListRes	the cu list resource. cuResources: cu resource list to fill the allocated cus infor, starting from cuResources[0], no hole. cuNum: allocated cu number in this list.

Returns:

int32_t, 0 on success or appropriate error number.

xrmCuReleaseV2¶

#include "lib/xrm.h"

bool xrmCuReleaseV2 (
    xrmContext context,
    xrmCuResourceV2* cuRes
    )

Releases a previously allocated resource.

Parameters:

context

the context created through xrmCreateContext() .

cuRes

the cu resource. xclbinFileName: xclbin (path and name) attached to this device. kernelPluginFileName: kernel plugin (only name) attached to this device. kernelName: the kernel name of allocated cu. kernelAlias: the name alias of allocated cu. instanceName: the instance name of allocated cu. cuName: the name of allocated cu (kernelName:instanceName). uuid: uuid of the loaded xclbin file. deviceId: device id of this cu. cuId: cu id of this cu. channelId: channel id of this cu. cuType: type of cu, hardware kernel or soft kernel. allocServiceId: service id for this cu allocation. channelLoad: allocated load of this cu, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: id of the cu pool this cu comes from, the system default pool id is 0.

Returns:

bool, true on success or false on fail.

xrmCuListReleaseV2¶

#include "lib/xrm.h"

bool xrmCuListReleaseV2 (
    xrmContext context,
    xrmCuListResourceV2* cuListRes
    )

Releases a previously allocated list of resources.

Parameters:

context	the context created through xrmCreateContext() .
cuListRes	the cu list resource. cuResources: cu resource list to be released, starting from cuResources[0], no hole. cuNum: number of cu in this list.

Returns:

bool, true on success or false on fail.

xrmUdfCuGroupDeclareV2¶

#include "lib/xrm.h"

int32_t xrmUdfCuGroupDeclareV2 (
    xrmContext context,
    xrmUdfCuGroupPropertyV2* udfCuGroupProp,
    char* udfCuGroupName
    )

Declares user defined cu group type given the specified kernels’s property with cu name (kernelName:instanceName) and request load.

Parameters:

context	the context created through xrmCreateContext() .
udfCuGroupProp	the property of user defined cu group. optionUdfCuListProps[]: option cu list property array starting from optionCuListProps[0], no hole. optionUdfCuListNum: number of option user defined cu list.
udfCuGroupName	unique user defined cu group name for the new group type declaration.

Returns:

int32_t, 0 on success or appropriate error number.

xrmUdfCuGroupUndeclareV2¶

#include "lib/xrm.h"

int32_t xrmUdfCuGroupUndeclareV2 (
    xrmContext context,
    char* udfCuGroupName
    )

Undeclares user defined cu group type given the specified group name.

Parameters:

context	the context created through xrmCreateContext() .
udfCuGroupName	user defined cu group name for the group type undeclaration.

Returns:

int32_t, 0 on success or appropriate error number.

xrmCuGroupAllocV2¶

#include "lib/xrm.h"

int32_t xrmCuGroupAllocV2 (
    xrmContext context,
    xrmCuGroupPropertyV2* cuGroupProp,
    xrmCuGroupResourceV2* cuGroupRes
    )

Allocates a group of compute unit resource given a user defined group of kernels’s property with cu name (kernelName:instanceName) and request load.

Parameters:

context	the context created through xrmCreateContext() .
cuGroupProp	the property of cu group. udfCuGroupName: user defined cu group type name. poolId: id of the cu pool this group CUs come from, the system default pool id is 0.
cuGroupRes	the cu group resource. cuResources: cu resource group to fill the allocated cus infor, starting from cuResources[0], no hole. cuNum: allocated cu number in this group.

Returns:

int32_t, 0 on success or appropriate error number.

xrmCuGroupReleaseV2¶

#include "lib/xrm.h"

bool xrmCuGroupReleaseV2 (
    xrmContext context,
    xrmCuGroupResourceV2* cuGroupRes
    )

Releases a previously allocated group of resources.

Parameters:

context	the context created through xrmCreateContext() .
cuGroupRes	cu group resource. cuResources: cu resource group to be released, starting from cuResources[0], no hole. cuNum: number of cu in this group.

Returns:

bool, true on success or false on fail.

xrmAllocationQueryV2¶

#include "lib/xrm.h"

int32_t xrmAllocationQueryV2 (
    xrmContext context,
    xrmAllocationQueryInfoV2* allocQuery,
    xrmCuListResourceV2* cuListRes
    )

Querys the compute unit resource given the allocation service id.

Parameters:

context	the context created through xrmCreateContext() .
allocQuery	the allocate query information. allocServiceId: the service id returned from allocation. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested.
cuListRes	cu list resource. cuListRes: cu resource list to fill the allocated cus infor, starting from cuResources[0], no hole. cuNum: cu number in this list.

Returns:

int32_t, 0 on success or appropriate error number.

xrmCheckCuAvailableNumV2¶

#include "lib/xrm.h"

int32_t xrmCheckCuAvailableNumV2 (
    xrmContext context,
    xrmCuPropertyV2* cuProp
    )

To check the available cu num on the system given the kernels’s property with kernel name or alias or both and request load.

Parameters:

context

the context created through xrmCreateContext()

cuProp

the property of cu. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested. devExcl: request exclusive device usage for this client. requestLoad: request load, only one type granularity at one time. bit[31 - 28] reserved bit[27 - 8] granularity of 1000000 (0 - 1000000) bit[ 7 - 0] granularity of 100 (0 - 100) poolId: request to allocate cu from specified resource pool.

Returns:

int32_t, available cu num (>= 0) on success or appropriate error number (< 0).

xrmCheckCuListAvailableNumV2¶

#include "lib/xrm.h"

int32_t xrmCheckCuListAvailableNumV2 (
    xrmContext context,
    xrmCuListPropertyV2* cuListProp
    )

To check the available cu list num on the system given a list of kernels’s property with kernel name or alias or both and request load.

Parameters:

context

the context created through xrmCreateContext() .

cuListProp

the property of cu list. cuProps: cu prop list to fill kernelName, devExcl and requestLoad, starting from cuProps[0], no hole For each cu in the list: 1) if device constraint not set: allocate it from any device 2) if device constraint set with hw index: reserve it from target device 3) if device constraint set with virtual index: find all others with same virtual index, put them into one sub-list, and reserve requested CU from same device, the device id should be different from that for previous sub-lists request from virtual index. cuNum: request number of cu in this list.

Returns:

int32_t, available cu list num (>= 0) on success or appropriate error number (< 0).

xrmCheckCuGroupAvailableNumV2¶

#include "lib/xrm.h"

int32_t xrmCheckCuGroupAvailableNumV2 (
    xrmContext context,
    xrmCuGroupPropertyV2* cuGroupProp
    )

To check the available group number of compute unit resource given a user defined group of kernels’s property with cu name (kernelName:instanceName) and request load.

Parameters:

context	the context created through xrmCreateContext() .
cuGroupProp	the property of cu group. udfCuGroupName: user defined cu group type name. poolId: id of the cu pool this group CUs come from, the system default pool id is 0.

Returns:

int32_t, available cu group num (>= 0) on success or appropriate error number (< 0).

xrmCheckCuPoolAvailableNumV2¶

#include "lib/xrm.h"

int32_t xrmCheckCuPoolAvailableNumV2 (
    xrmContext context,
    xrmCuPoolPropertyV2* cuPoolProp
    )

To check the available cu pool num on the system given a pool of kernels’s property with kernel name or alias or both and request load.

Parameters:

context	the context created through xrmCreateContext() .
cuPoolProp	the property of cu pool. cuListProp: cu list property. cuListNum: number of cu list in this pool. xclbinUuid: uuid of xclbin. xclbinNum: number of xclbin in this pool.

Returns:

int32_t, available cu pool num (>= 0) on success or appropriate error number (< 0).

xrmCuPoolReserveV2¶

#include "lib/xrm.h"

uint64_t xrmCuPoolReserveV2 (
    xrmContext context,
    xrmCuPoolPropertyV2* cuPoolProp,
    xrmCuPoolResInforV2* cuPoolResInfor
    )

Reserves a pool of compute unit resource given a pool of kernels’s property with kernel name or alias or both and request load.

Parameters:

context	the context created through xrmCreateContext() .
cuPoolProp	the property of cu pool. cuListProp: cu prop list to fill kernelName, devExcl and requestLoad etc. information. For each cu in the list: 1) if device constraint not set: reserve it from any device 2) if device constraint set with hw index: reserve it from target device 3) if device constraint set with virtual index: find all others with same virtual index, put them into one sub-list, and reserve requested CU from same device, the device id should be different from that for previous sub-lists request from virtual index. cuListNum: request number of such cu list for this pool. xclbinUuid: request all resource in the xclbin. xclbinNum: request number of such xclbin for this pool. deviceIdListProp: device id list
cuPoolResInfor	the return information of cu pool. cuListResInfor: cu list resource information. cuListNum: number of cu list for this pool. xclbinResInfor: resource information of the xclbin. xclbinNum: number of xclbin for this pool.

Returns:

uint64_t, reserve pool id (> 0) or 0 on fail.

xrmCuPoolRelinquishV2¶

#include "lib/xrm.h"

bool xrmCuPoolRelinquishV2 (
    xrmContext context,
    uint64_t poolId
    )

Relinquishes a previously reserved pool of resources.

Parameters:

context	the context created through xrmCreateContext() .
poolId	the reserve pool id.

Returns:

bool, true on success or false on fail.

xrmReservationQueryV2¶

#include "lib/xrm.h"

int32_t xrmReservationQueryV2 (
    xrmContext context,
    xrmReservationQueryInfoV2* reserveQueryInfo,
    xrmCuPoolResourceV2* cuPoolRes
    )

Querys the compute unit resource given the reservation id. NOTE: The allocServiceId, channelId and channelLoad are NOT valid in the cuPoolRes.

Parameters:

context	the context created through xrmCreateContext() .
reserveQueryInfo	the reservation query information. poolId: reservation pool id. kernelName: the kernel name requested. kernelAlias: the alias of kernel name requested.
cuPoolRes	the cu pool resource. cuPoolRes: cu resource pool to fill the allocated cus infor, starting from cuPoolRes[0], no hole. cuNum: cu number in this pool.

Returns:

int32_t, 0 on success or appropriate error number.