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_CU_LEAST_USED_FIRST #define XRM_POLICY_INFO_CONSTRAINT_TYPE_CU_MOST_USED_FIRST #define XRM_POLICY_INFO_CONSTRAINT_TYPE_DEV_LEAST_USED_FIRST #define XRM_POLICY_INFO_CONSTRAINT_TYPE_DEV_MOST_USED_FIRST #define XRM_POLICY_INFO_CONSTRAINT_TYPE_MASK #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 : cu most used first, only apply to cu allocation not cu list/group allocation 2 : cu least used first, only apply to cu allocation not cu list/group allocation 3 : device most used first, only apply to cu allocation not cu list/group allocation 4 : device least used first, only apply to cu allocation not cu list/group allocation 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. policyInfo set with any of (XRM_POLICY_INFO_CONSTRAINT_TYPE_CU_MOST_USED_FIRST XRM_POLICY_INFO_CONSTRAINT_TYPE_CU_LEAST_USED_FIRST XRM_POLICY_INFO_CONSTRAINT_TYPE_DEV_MOST_USED_FIRST XRM_POLICY_INFO_CONSTRAINT_TYPE_DEV_LEAST_USED_FIRST) will be cleaned and treated as no flag.
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.