Device statistics

Overview

These APIs are for statistics. More…

// global functions

XPUM_API xpum_result_t xpumGetStats(
    xpum_device_id_t deviceId,
    xpum_device_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    );

XPUM_API xpum_result_t xpumGetStatsEx(
    xpum_device_id_t deviceIdList[],
    uint32_t deviceCount,
    xpum_device_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    );

XPUM_API xpum_result_t xpumGetEngineStats(
    xpum_device_id_t deviceId,
    xpum_device_engine_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    );

XPUM_API xpum_result_t xpumGetEngineStatsEx(
    xpum_device_id_t deviceIdList[],
    uint32_t deviceCount,
    xpum_device_engine_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    );

XPUM_API xpum_result_t xpumGetFabricThroughputStats(
    xpum_device_id_t deviceId,
    xpum_device_fabric_throughput_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    );

XPUM_API xpum_result_t xpumGetFabricThroughputStatsEx(
    xpum_device_id_t deviceIdList[],
    uint32_t deviceCount,
    xpum_device_fabric_throughput_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    );

XPUM_API xpum_result_t xpumGetMetricsFromSysfs(
    const char** bdfs,
    uint32_t length,
    xpum_device_stats_t dataList[],
    uint32_t* count
    );

XPUM_API xpum_result_t xpumGetStatsByGroup(
    xpum_group_id_t groupId,
    xpum_device_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    );

Detailed Documentation

These APIs are for statistics. The data type is uint64_t for the APIs, the value should be divided by scale to get the real value for float or double data types. The unit of all utilization metrics types (including EU status and memory bandwidth) is percentage. The unit of power is W. The unit of energy is mJ. The unit of frequency is MHz. The unit of temperature is Celsius Degree. The unit of memory is Byte. The unit of memory read/write and link throughput is kB/s. All the RAS metrics types are numbers.

Global Functions

XPUM_API xpum_result_t xpumGetStats(
    xpum_device_id_t deviceId,
    xpum_device_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    )

Get statistics data (not including per engine utilization & fabric throughput) by device.

Support Platform: Linux

Parameters:

deviceId	IN: Device id
dataList	OUT: The arry to store statistics data for device deviceId. First pass NULL to query statistics data count. Then pass array with desired length to store statistics data.
count	IN/OUT: When dataList is NULL, count will be filled with the number of available entries, and return. When dataList is not NULL, count denotes the length of dataList, count should be equal to or larger than the number of available entries, when return, the count will store real number of entries returned by dataList
begin	OUT: Timestamp in milliseconds, the time when aggregation starts
end	OUT: Timestamp in milliseconds, the time when aggregation ends
sessionId	IN: Statistics session id. Currently XPUM only supports two statistic sessions, their session ids are 0 and 1 respectively.

Returns:

xpum_result_t

XPUM_OK if query successfully
XPUM_BUFFER_TOO_SMALL if count is smaller than needed

XPUM_API xpum_result_t xpumGetStatsEx(
    xpum_device_id_t deviceIdList[],
    uint32_t deviceCount,
    xpum_device_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    )

Get statistics data (not including per engine utilization & fabric throughput) by device list.

Support Platform: Linux

Parameters:

deviceIdList	IN: Device id list
deviceCount	IN: Device id count
dataList	OUT: The arry to store statistics data for device deviceId. First pass NULL to query statistics data count. Then pass array with desired length to store statistics data.
count	IN/OUT: When dataList is NULL, count will be filled with the number of available entries, and return. When dataList is not NULL, count denotes the length of dataList, count should be equal to or larger than the number of available entries, when return, the count will store real number of entries returned by dataList
begin	OUT: Timestamp in milliseconds, the time when aggregation starts
end	OUT: Timestamp in milliseconds, the time when aggregation ends
sessionId	IN: Statistics session id. Currently XPUM only supports two statistic sessions, their session ids are 0 and 1 respectively.

Returns:

xpum_result_t

XPUM_OK if query successfully
XPUM_BUFFER_TOO_SMALL if count is smaller than needed

XPUM_API xpum_result_t xpumGetEngineStats(
    xpum_device_id_t deviceId,
    xpum_device_engine_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    )

Get engine statistics data by device.

Support Platform: Linux

Parameters:

deviceId	IN: Device id
dataList	OUT: The arry to store statistics data for device deviceId.
count	IN/OUT: When passed in, count denotes the length of dataList, which should be equal to or larger than stats_size of this device. A device’s stats_size is 1 if no tiles exists, or 1 + count of tiles if tiles exist. When return, count will store the actual number of entries stored in dataList.
begin	OUT: Timestamp in milliseconds, the time when aggregation starts
end	OUT: Timestamp in milliseconds, the time when aggregation ends
sessionId	IN: Statistics session id. Currently XPUM only supports two statistic sessions, their session ids are 0 and 1 respectively.

Returns:

xpum_result_t

XPUM_OK if query successfully
XPUM_BUFFER_TOO_SMALL if count is smaller than needed

XPUM_API xpum_result_t xpumGetEngineStatsEx(
    xpum_device_id_t deviceIdList[],
    uint32_t deviceCount,
    xpum_device_engine_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    )

Get engine statistics data by device list.

Support Platform: Linux

Parameters:

deviceIdList	IN: Device id list
deviceCount	IN: Device id count
dataList	OUT: The arry to store statistics data for device deviceId.
count	IN/OUT: When passed in, count denotes the length of dataList, which should be equal to or larger than stats_size of this device. A device’s stats_size is 1 if no tiles exists, or 1 + count of tiles if tiles exist. When return, count will store the actual number of entries stored in dataList.
begin	OUT: Timestamp in milliseconds, the time when aggregation starts
end	OUT: Timestamp in milliseconds, the time when aggregation ends
sessionId	IN: Statistics session id. Currently XPUM only supports two statistic sessions, their session ids are 0 and 1 respectively.

Returns:

xpum_result_t

XPUM_OK if query successfully
XPUM_BUFFER_TOO_SMALL if count is smaller than needed

XPUM_API xpum_result_t xpumGetFabricThroughputStats(
    xpum_device_id_t deviceId,
    xpum_device_fabric_throughput_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    )

Get Fabric throughput statistics data by device.

Support Platform: Linux

Parameters:

deviceId	IN: Device id
dataList	OUT: The arry to store statistics data for device deviceId.
count	IN/OUT: When passed in, count denotes the length of dataList, which should be equal to or larger than stats_size of this device. A device’s stats_size is 1 if no tiles exists, or 1 + count of tiles if tiles exist. When return, count will store the actual number of entries stored in dataList.
begin	OUT: Timestamp in milliseconds, the time when aggregation starts
end	OUT: Timestamp in milliseconds, the time when aggregation ends
sessionId	IN: Statistics session id. Currently XPUM only supports two statistic sessions, their session ids are 0 and 1 respectively.

Returns:

xpum_result_t

XPUM_OK if query successfully
XPUM_BUFFER_TOO_SMALL if count is smaller than needed

XPUM_API xpum_result_t xpumGetFabricThroughputStatsEx(
    xpum_device_id_t deviceIdList[],
    uint32_t deviceCount,
    xpum_device_fabric_throughput_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    )

Get Fabric throughput statistics data by device list.

Support Platform: Linux

Parameters:

deviceIdList	IN: Device id list
deviceCount	IN: Device id count
dataList	OUT: The arry to store statistics data for device deviceId.
count	IN/OUT: When passed in, count denotes the length of dataList, which should be equal to or larger than stats_size of this device. A device’s stats_size is 1 if no tiles exists, or 1 + count of tiles if tiles exist. When return, count will store the actual number of entries stored in dataList.
begin	OUT: Timestamp in milliseconds, the time when aggregation starts
end	OUT: Timestamp in milliseconds, the time when aggregation ends
sessionId	IN: Statistics session id. Currently XPUM only supports two statistic sessions, their session ids are 0 and 1 respectively.

Returns:

xpum_result_t

XPUM_OK if query successfully
XPUM_BUFFER_TOO_SMALL if count is smaller than needed

XPUM_API xpum_result_t xpumGetMetricsFromSysfs(
    const char** bdfs,
    uint32_t length,
    xpum_device_stats_t dataList[],
    uint32_t* count
    )

Get metrics data from sysfs.

Support Platform: Linux

Parameters:

bdfs	IN: The array of PCI BDF address strings
length	IN: The length of array bdfs
dataList	OUT: The array to store metrics data for device bdfs.
count	IN/OUT: When passed in, count denotes the length of dataList, which should be equal to or larger than stats size. When return, count will store the actual number of entries stored in dataList.

Returns:

xpum_result_t

XPUM_OK if query successfully
XPUM_BUFFER_TOO_SMALL if count is smaller than needed

XPUM_API xpum_result_t xpumGetStatsByGroup(
    xpum_group_id_t groupId,
    xpum_device_stats_t dataList[],
    uint32_t* count,
    uint64_t* begin,
    uint64_t* end,
    uint64_t sessionId
    )

Get statistics data by group.

Support Platform: Linux

Parameters:

groupId	IN: Group id
dataList	OUT: The arry to store statistics data for devices in group groupId. First pass NULL to query statistics data count. Then pass array with desired length to store statistics data.
count	IN/OUT: When dataList is NULL, count will be filled with the number of available entries, and return. When dataList is not NULL, count denotes the length of dataList, count should be equal to or larger than the number of available entries, when return, the count will store real number of entries returned by dataList
begin	OUT: Timestamp in milliseconds, the time when aggregation starts
end	OUT: Timestamp in milliseconds, the time when aggregation ends
sessionId	IN: Statistics session id. Currently XPUM only supports two statistic sessions, their session ids are 0 and 1 respectively.

Returns:

xpum_result_t

XPUM_OK if query successfully
XPUM_BUFFER_TOO_SMALL if count is smaller than device count of group