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 xrmCuGroupProperty
struct xrmCuGroupResource
struct xrmCuListProperty
struct xrmCuListResource
struct xrmCuPoolProperty
struct xrmCuPoolResource
struct xrmCuProperty
struct xrmCuResource
struct xrmCuStat
struct xrmPluginData
struct xrmPluginFuncParam
struct xrmUdfCuGroupProperty
struct xrmUdfCuListProperty
struct xrmUdfCuProperty

// macros

#define XRM_API_VERSION_1

Global Functions

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

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 (1 - 100). 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 (1 - 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 (1 - 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 (1 - 100).

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 (1 - 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 (1 - 100).

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 (1 - 100).

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.

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 (1 - 100).

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 (1 - 100). poolId: request to allocate cu from specified resource pool.

Returns:

int32_t, available cu num (>= 0) on success or appropriate error number (< 0), if available cu number is >= XRM_MAX_AVAILABLE_CU_NUM, will only return XRM_MAX_AVAILABLE_CU_NUM.

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 (1 - 100).

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), if available cu list number is >= XRM_MAX_AVAILABLE_LIST_NUM, will only return XRM_MAX_AVAILABLE_LIST_NUM.

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 (1 - 100).

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, 0 on success or appropriate error number

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 (1 - 100).

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), if available cu pool number is >= XRM_MAX_AVAILABLE_POOL_NUM, will only return XRM_MAX_AVAILABLE_POOL_NUM.

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 (1 - 100).

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 (1 - 100). 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 (1 - 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 (1 - 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 (1 - 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 (1 - 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