mbltml C API

mbltml C API#

mbltml: mbltml C API

mbltml Test Preview

mbltml — KR

C API provides Mobilint NPU monitoring and telemetry. More...

Classes
struct	mbltmlCoreId_t
	Composite identifier of an NPU core (cluster + core). More...
struct	mbltmlCoreInfo_t
	Per-core usage record returned by mbltmlGetCoreInfos(). More...
struct	mbltmlProcessInfo_t
	Per-process usage record returned by mbltmlGetProcessInfos(). More...

Macros
#define	MBLTML_DRIVER_VERSION_BUFFER_SIZE 80
#define	MBLTML_ON_DEVICE_DRIVER_VERSION_BUFFER_SIZE 80
#define	MBLTML_FIRMWARE_VERSION_BUFFER_SIZE 80
#define	MBLTML_NODE_NAME_BUFFER_SIZE 80

Typedefs
typedef struct mbltmlCoreId_t	mbltmlCoreId_t
	Composite identifier of an NPU core (cluster + core).
typedef struct mbltmlProcessInfo_t	mbltmlProcessInfo_t
	Per-process usage record returned by mbltmlGetProcessInfos().

Enumerations
enum	mbltmlDeviceType_t { MBLTML_DEVICE_ERROR = 0x0 , MBLTML_DEVICE_ARIES = 0x1 , MBLTML_DEVICE_REGULUS = 0x2 , MBLTML_DEVICE_REGULUS_USB = 0x4 }
	Identifier of a Mobilint NPU device family. More...
enum	mbltmlHardwareVersion_t { MBLTML_HARDWARE_VERSION_ARIES_RA = 0x0000'0001 , MBLTML_HARDWARE_VERSION_REGULUS_RA = 0x0000'0002 , MBLTML_HARDWARE_VERSION_ARIES_RB = 0x0000'0003 , MBLTML_HARDWARE_VERSION_REGULUS_RB = 0x0000'0004 , MBLTML_HARDWARE_VERSION_ERROR = 0x7FFF'FFFF }
	Specific hardware revision of a Mobilint NPU. More...
enum	mbltmlStatusCode_t { MBLTML_SUCCESS = 0 , MBLTML_UNINITIALIZED = 1 , MBLTML_DRIVER_NOT_FOUND = 2 , MBLTML_INVALID_ARGUMENT = 3 , MBLTML_NOT_SUPPORTED = 4 , MBLTML_INSUFFICIENT_LENGTH = 5 }
	Status code returned by mbltml APIs. More...
enum	mbltmlExtraPmicId_t { MBLTML_EXTRA_PMIC_ID_NPU = 0 , MBLTML_EXTRA_PMIC_ID_DDR = 1 , MBLTML_EXTRA_PMIC_ID_PMIC = 2 , MBLTML_EXTRA_PMIC_ID_GOLDFINGER = 3 }
	Identifier of an extra PMIC rail. More...
enum	mbltmlCluster_t { MBLTML_CLUSTER_0 = 1 << 16 , MBLTML_CLUSTER_1 = 2 << 16 , MBLTML_CLUSTER_ERROR = 0x7FFF'0000 }
	NPU cluster identifier within a device. More...
enum	mbltmlCore_t { MBLTML_CORE_0 = 1 , MBLTML_CORE_1 = 2 , MBLTML_CORE_2 = 3 , MBLTML_CORE_3 = 4 , MBLTML_CORE_GLOBAL = 0x0000'FFFE , MBLTML_CORE_ERROR = 0x0000'FFFF }
	NPU core identifier within a cluster. More...

Functions
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlInit ()
	Initialize the mbltml library for all supported device types.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlInitDevices (unsigned int device_types)
	Initialize the mbltml library for a selected set of device types.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlShutdown ()
	Release all resources held by the mbltml library.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetDeviceCount (unsigned int *counts)
	Get the total number of devices detected by the library.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetDriverVersion (mbltmlDeviceType_t dt, char *version, unsigned int length)
	Get the driver version string for a specific device family.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetDriverRevision (mbltmlDeviceType_t dt, uint32_t *revision)
	Get the driver revision number for a specific device family.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetNodeName (int dev_no, char *name, unsigned int length)
	Get the node name of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetDeviceType (int dev_no, mbltmlDeviceType_t *device_type)
	Get the device family type of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetHardwareVersion (int dev_no, mbltmlHardwareVersion_t *version)
	Get the hardware version of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetOnDeviceDriverVersion (int dev_no, char *version, unsigned int length)
	Get the on-device driver version string of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetOnDeviceDriverRevision (int dev_no, uint32_t *revision)
	Get the on-device driver revision number of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetFirmwareVersion (int dev_no, char *version, unsigned int length)
	Get the firmware version string of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetFirmwareRevision (int dev_no, uint32_t *revision)
	Get the firmware revision number of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetFirmwareCRC (int dev_no, uint32_t *crc)
	Get the CRC of the currently-loaded firmware image.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetTemperature (int dev_no, int *temperature)
	Get the current die temperature of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetSignalType (int dev_no, uint32_t *signal_type)
	Get the current signal-type indicator reported by the device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetNPUClock (int dev_no, uint32_t *clock)
	Get the current NPU clock frequency of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetBusClock (int dev_no, uint32_t *clock)
	Get the current bus clock frequency of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetFanDuty (int dev_no, int *fan_duty)
	Get the current cooling-fan duty cycle of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetVendorId (int dev_no, uint32_t *vendor_id)
	Get the PCIe vendor ID of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetDeviceId (int dev_no, uint32_t *device_id)
	Get the PCIe device ID of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetSubVendorId (int dev_no, uint32_t *sub_vendor_id)
	Get the PCIe subsystem vendor ID of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetSubDeviceId (int dev_no, uint32_t *sub_device_id)
	Get the PCIe subsystem device ID of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetPcieGen (int dev_no, uint32_t *pcie_gen)
	Get the negotiated PCIe link generation of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetPcieLanes (int dev_no, uint32_t *pcie_lanes)
	Get the negotiated PCIe link width (in lanes) of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetPcieRev (int dev_no, uint32_t *pcie_rev)
	Get the PCIe configuration-space revision ID of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetPcieClassCode (int dev_no, uint32_t *pcie_class_code)
	Get the PCIe configuration-space class code of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetTotalPower (int dev_no, double *power)
	Get the total instantaneous power consumption of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetTotalCurrent (int dev_no, double *current)
	Get the total instantaneous current draw of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetTotalVoltage (int dev_no, double *voltage)
	Get the total instantaneous supply voltage of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetExtraPmicPower (int dev_no, double *power)
	Get the power consumption of the extra PMIC rail currently selected for the device (W).
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetExtraPmicCurrent (int dev_no, double *current)
	Get the current of the extra PMIC rail currently selected for the device (A).
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetExtraPmicVoltage (int dev_no, double *voltage)
	Get the voltage of the extra PMIC rail currently selected for the device (V).
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetExtraPmicId (int dev_no, mbltmlExtraPmicId_t *pmic_id)
	Get the extra PMIC rail currently selected for the device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetTotalUtilization (int dev_no, double *utilization)
	Get the overall NPU utilization of a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetMemoryUsage (int dev_no, int64_t *memory_usage)
	Get the amount of device memory currently in use.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetMemoryTotal (int dev_no, int64_t *memory_total)
	Get the total amount of device memory available.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetProcessInfos (int dev_no, mbltmlProcessInfo_t infos, unsigned int info_count)
	Get per-process usage information for a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlGetCoreInfos (int dev_no, mbltmlCoreInfo_t infos, unsigned int info_count)
	Get per-core usage information for a device.
MBLTML_EXPORT mbltmlStatusCode_t	mbltmlSetExtraPmicID (int dev_no, mbltmlExtraPmicId_t pmic_id)
	Select which extra PMIC rail subsequent mbltmlGetExtraPmic*() queries refer to.

Detailed Description

C API provides Mobilint NPU monitoring and telemetry.

Macro Definition Documentation

◆ MBLTML_DRIVER_VERSION_BUFFER_SIZE

#define MBLTML_DRIVER_VERSION_BUFFER_SIZE 80

Buffer size (bytes) guaranteed sufficient for mbltmlGetDriverVersion().

Definition at line 18 of file capi.h.

◆ MBLTML_ON_DEVICE_DRIVER_VERSION_BUFFER_SIZE

#define MBLTML_ON_DEVICE_DRIVER_VERSION_BUFFER_SIZE 80

Buffer size (bytes) guaranteed sufficient for mbltmlGetOnDeviceDriverVersion().

Definition at line 20 of file capi.h.

◆ MBLTML_FIRMWARE_VERSION_BUFFER_SIZE

#define MBLTML_FIRMWARE_VERSION_BUFFER_SIZE 80

Buffer size (bytes) guaranteed sufficient for mbltmlGetFirmwareVersion().

Definition at line 22 of file capi.h.

◆ MBLTML_NODE_NAME_BUFFER_SIZE

#define MBLTML_NODE_NAME_BUFFER_SIZE 80

Buffer size (bytes) guaranteed sufficient for mbltmlGetNodeName().

Definition at line 24 of file capi.h.

Typedef Documentation

◆ mbltmlProcessInfo_t

typedef struct mbltmlProcessInfo_t mbltmlProcessInfo_t

Per-process usage record returned by mbltmlGetProcessInfos().

Utilization for the process can be computed as total_npu_time_us / total_interval_us when total_interval_us is non-zero.

Enumeration Type Documentation

◆ mbltmlDeviceType_t

enum mbltmlDeviceType_t

Identifier of a Mobilint NPU device family.

Used to select a device family when calling family-scoped APIs such as mbltmlGetDriverVersion(), and to describe the family of an individual device returned by mbltmlGetDeviceType().

Enumerator
MBLTML_DEVICE_ERROR	0x0	Invalid or uninitialized value.
MBLTML_DEVICE_ARIES	0x1	Aries family.
MBLTML_DEVICE_REGULUS	0x2	Regulus (PCIe) family.
MBLTML_DEVICE_REGULUS_USB	0x4	Regulus USB-attached family.

Definition at line 25 of file type.h.

◆ mbltmlHardwareVersion_t

enum mbltmlHardwareVersion_t

Specific hardware revision of a Mobilint NPU.

Enumerator
MBLTML_HARDWARE_VERSION_ARIES_RA	0x0000'0001	aries-ra chip.
MBLTML_HARDWARE_VERSION_REGULUS_RA	0x0000'0002	regulus-ra chip.
MBLTML_HARDWARE_VERSION_ARIES_RB	0x0000'0003	aries-rb chip.
MBLTML_HARDWARE_VERSION_REGULUS_RB	0x0000'0004	regulus-rb chip.
MBLTML_HARDWARE_VERSION_ERROR	0x7FFF'FFFF	Invalid or uninitialized.

Definition at line 35 of file type.h.

◆ mbltmlStatusCode_t

enum mbltmlStatusCode_t

Status code returned by mbltml APIs.

Enumerator
MBLTML_SUCCESS	0	Operation completed successfully.
MBLTML_UNINITIALIZED	1	API used before initialization.
MBLTML_DRIVER_NOT_FOUND	2	Required driver could not be located.
MBLTML_INVALID_ARGUMENT	3	Invalid argument (NULL or out-of-range).
MBLTML_NOT_SUPPORTED	4	Feature not supported on target device.
MBLTML_INSUFFICIENT_LENGTH	5	Output buffer is too small.

Definition at line 46 of file type.h.

◆ mbltmlExtraPmicId_t

enum mbltmlExtraPmicId_t

Identifier of an extra PMIC rail.

Selects which auxiliary PMIC rail is reported by the mbltmlGetExtraPmic*() APIs. The active selection is changed with mbltmlSetExtraPmicID() and can be queried via mbltmlGetExtraPmicId().

Enumerator
MBLTML_EXTRA_PMIC_ID_NPU	0	NPU rail.
MBLTML_EXTRA_PMIC_ID_DDR	1	DDR rail.
MBLTML_EXTRA_PMIC_ID_PMIC	2	PMIC rail.
MBLTML_EXTRA_PMIC_ID_GOLDFINGER	3	Goldfinger rail.

Definition at line 62 of file type.h.

◆ mbltmlCluster_t

enum mbltmlCluster_t

NPU cluster identifier within a device.

Enumerator
MBLTML_CLUSTER_0	1 << 16	Cluster 0.
MBLTML_CLUSTER_1	2 << 16	Cluster 1.
MBLTML_CLUSTER_ERROR	0x7FFF'0000	Invalid or uninitialized state.

Definition at line 72 of file type.h.

◆ mbltmlCore_t

enum mbltmlCore_t

NPU core identifier within a cluster.

Enumerator
MBLTML_CORE_0	1	Local core 0.
MBLTML_CORE_1	2	Local core 1.
MBLTML_CORE_2	3	Local core 2.
MBLTML_CORE_3	4	Local core 3.
MBLTML_CORE_GLOBAL	0x0000'FFFE	Global (all cores aggregated).
MBLTML_CORE_ERROR	0x0000'FFFF	Invalid or uninitialized state.

Definition at line 81 of file type.h.

Function Documentation

◆ mbltmlInit()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlInit ( )

Initialize the mbltml library for all supported device types.

Equivalent to calling mbltmlInitDevices() with every bit of mbltmlDeviceType_t enabled. Must be called (directly or via mbltmlInitDevices()) before any other mbltml API.

Returns: MBLTML_SUCCESS on success, otherwise an appropriate mbltmlStatusCode_t error code.

◆ mbltmlInitDevices()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlInitDevices ( unsigned int device_types )

Initialize the mbltml library for a selected set of device types.

Parameters

[in] device_types Bitwise OR of mbltmlDeviceType_t values indicating which device families to enumerate and monitor.

Returns: MBLTML_SUCCESS on success, otherwise an appropriate mbltmlStatusCode_t error code.

◆ mbltmlShutdown()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlShutdown ( )

Release all resources held by the mbltml library.

After this call, any further API usage requires re-initialization via mbltmlInit() or mbltmlInitDevices().

Returns: MBLTML_SUCCESS on success, otherwise an appropriate mbltmlStatusCode_t error code.

◆ mbltmlGetDeviceCount()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetDeviceCount ( unsigned int * counts )

Get the total number of devices detected by the library.

Note: Supported on all device types.

Parameters

[out] counts Pointer that receives the device count.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if counts is NULL, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetDriverVersion()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetDriverVersion	(	mbltmlDeviceType_t	dt,
		char *	version,
		unsigned int	length )

Get the driver version string for a specific device family.

Note: Supported on all device types.

A buffer of MBLTML_DRIVER_VERSION_BUFFER_SIZE bytes guarantees success. The resulting string is NUL-terminated. On failure, the contents of version are left unmodified.

Parameters

[in]	dt	Device family whose driver version is queried.
[out]	version	Output buffer that receives the version string.
[in]	length	Size, in bytes, of `version`.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if version is NULL, MBLTML_INSUFFICIENT_LENGTH if length is too small, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetDriverRevision()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetDriverRevision	(	mbltmlDeviceType_t	dt,
		uint32_t *	revision )

Get the driver revision number for a specific device family.

Note: Supported on all device types.

Parameters

[in]	dt	Device family whose driver revision is queried.
[out]	revision	Pointer that receives the revision number.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if revision is NULL, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetNodeName()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetNodeName	(	int	dev_no,
		char *	name,
		unsigned int	length )

Get the node name of a device.

Note: Supported on all device types.

A buffer of MBLTML_NODE_NAME_BUFFER_SIZE bytes guarantees success. The resulting string is NUL-terminated. On failure, the contents of name are left unmodified.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	name	Output buffer that receives the node name.
[in]	length	Size, in bytes, of `name`.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if name is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, MBLTML_INSUFFICIENT_LENGTH if length is too small, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetDeviceType()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetDeviceType	(	int	dev_no,
		mbltmlDeviceType_t *	device_type )

Get the device family type of a device.

Note: Supported on all device types.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	device_type	Pointer that receives the mbltmlDeviceType_t value.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if device_type is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetHardwareVersion()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetHardwareVersion	(	int	dev_no,
		mbltmlHardwareVersion_t *	version )

Get the hardware version of a device.

Note: Supported on all device types.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	version	Pointer that receives the mbltmlHardwareVersion_t value.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if version is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetOnDeviceDriverVersion()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetOnDeviceDriverVersion	(	int	dev_no,
		char *	version,
		unsigned int	length )

Get the on-device driver version string of a device.

Note: Supported on MBLTML_DEVICE_REGULUS_USB only.

A buffer of MBLTML_ON_DEVICE_DRIVER_VERSION_BUFFER_SIZE bytes guarantees success. The resulting string is NUL-terminated. On failure, the contents of version are left unmodified.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	version	Output buffer that receives the version string.
[in]	length	Size, in bytes, of `version`.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if version is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, MBLTML_INSUFFICIENT_LENGTH if length is too small, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetOnDeviceDriverRevision()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetOnDeviceDriverRevision	(	int	dev_no,
		uint32_t *	revision )

Get the on-device driver revision number of a device.

Note: Supported on MBLTML_DEVICE_REGULUS_USB only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	revision	Pointer that receives the on-device driver revision.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if revision is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetFirmwareVersion()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetFirmwareVersion	(	int	dev_no,
		char *	version,
		unsigned int	length )

Get the firmware version string of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

A buffer of MBLTML_FIRMWARE_VERSION_BUFFER_SIZE bytes guarantees success. The resulting string is NUL-terminated. On failure, the contents of version are left unmodified.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	version	Output buffer that receives the version string.
[in]	length	Size, in bytes, of `version`.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if version is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, MBLTML_INSUFFICIENT_LENGTH if length is too small, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetFirmwareRevision()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetFirmwareRevision	(	int	dev_no,
		uint32_t *	revision )

Get the firmware revision number of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	revision	Pointer that receives the firmware revision.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if revision is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetFirmwareCRC()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetFirmwareCRC	(	int	dev_no,
		uint32_t *	crc )

Get the CRC of the currently-loaded firmware image.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	crc	Pointer that receives the firmware CRC.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if crc is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetTemperature()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetTemperature	(	int	dev_no,
		int *	temperature )

Get the current die temperature of a device.

Note: Supported on all device types.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	temperature	Pointer that receives the temperature reading.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if temperature is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetSignalType()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetSignalType	(	int	dev_no,
		uint32_t *	signal_type )

Get the current signal-type indicator reported by the device.

Note: Supported on all device types.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	signal_type	Pointer that receives the signal-type value.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if signal_type is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetNPUClock()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetNPUClock	(	int	dev_no,
		uint32_t *	clock )

Get the current NPU clock frequency of a device.

Note: Supported on all device types.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	clock	Pointer that receives the NPU clock value.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if clock is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetBusClock()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetBusClock	(	int	dev_no,
		uint32_t *	clock )

Get the current bus clock frequency of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	clock	Pointer that receives the bus clock value.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if clock is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetFanDuty()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetFanDuty	(	int	dev_no,
		int *	fan_duty )

Get the current cooling-fan duty cycle of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	fan_duty	Pointer that receives the fan duty value.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if fan_duty is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetVendorId()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetVendorId	(	int	dev_no,
		uint32_t *	vendor_id )

Get the PCIe vendor ID of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	vendor_id	Pointer that receives the vendor ID.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if vendor_id is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetDeviceId()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetDeviceId	(	int	dev_no,
		uint32_t *	device_id )

Get the PCIe device ID of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	device_id	Pointer that receives the device ID.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if device_id is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetSubVendorId()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetSubVendorId	(	int	dev_no,
		uint32_t *	sub_vendor_id )

Get the PCIe subsystem vendor ID of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	sub_vendor_id	Pointer that receives the subsystem vendor ID.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if sub_vendor_id is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetSubDeviceId()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetSubDeviceId	(	int	dev_no,
		uint32_t *	sub_device_id )

Get the PCIe subsystem device ID of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	sub_device_id	Pointer that receives the subsystem device ID.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if sub_device_id is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetPcieGen()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetPcieGen	(	int	dev_no,
		uint32_t *	pcie_gen )

Get the negotiated PCIe link generation of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	pcie_gen	Pointer that receives the PCIe generation.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if pcie_gen is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetPcieLanes()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetPcieLanes	(	int	dev_no,
		uint32_t *	pcie_lanes )

Get the negotiated PCIe link width (in lanes) of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	pcie_lanes	Pointer that receives the lane count.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if pcie_lanes is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetPcieRev()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetPcieRev	(	int	dev_no,
		uint32_t *	pcie_rev )

Get the PCIe configuration-space revision ID of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	pcie_rev	Pointer that receives the revision value.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if pcie_rev is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetPcieClassCode()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetPcieClassCode	(	int	dev_no,
		uint32_t *	pcie_class_code )

Get the PCIe configuration-space class code of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	pcie_class_code	Pointer that receives the class code.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if pcie_class_code is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetTotalPower()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetTotalPower	(	int	dev_no,
		double *	power )

Get the total instantaneous power consumption of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	power	Pointer that receives the power reading.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if power is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetTotalCurrent()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetTotalCurrent	(	int	dev_no,
		double *	current )

Get the total instantaneous current draw of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	current	Pointer that receives the current reading.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if current is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetTotalVoltage()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetTotalVoltage	(	int	dev_no,
		double *	voltage )

Get the total instantaneous supply voltage of a device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	voltage	Pointer that receives the voltage reading.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if voltage is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetExtraPmicPower()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetExtraPmicPower	(	int	dev_no,
		double *	power )

Get the power consumption of the extra PMIC rail currently selected for the device (W).

Note: Supported on MBLTML_DEVICE_ARIES only.

The selected rail is controlled by mbltmlSetExtraPmicID() and can be queried via mbltmlGetExtraPmicId().

The firmware refreshes this reading once per second. After changing the selected rail with mbltmlSetExtraPmicID(), allow up to 1 second for the new rail's value to be reported.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	power	Pointer that receives the power reading.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if power is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetExtraPmicCurrent()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetExtraPmicCurrent	(	int	dev_no,
		double *	current )

Get the current of the extra PMIC rail currently selected for the device (A).

Note: Supported on MBLTML_DEVICE_ARIES only.

The firmware refreshes this reading once per second. After changing the selected rail with mbltmlSetExtraPmicID(), allow up to 1 second for the new rail's value to be reported.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	current	Pointer that receives the current reading.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if current is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetExtraPmicVoltage()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetExtraPmicVoltage	(	int	dev_no,
		double *	voltage )

Get the voltage of the extra PMIC rail currently selected for the device (V).

Note: Supported on MBLTML_DEVICE_ARIES only.

The firmware refreshes this reading once per second. After changing the selected rail with mbltmlSetExtraPmicID(), allow up to 1 second for the new rail's value to be reported.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	voltage	Pointer that receives the voltage reading.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if voltage is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetExtraPmicId()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetExtraPmicId	(	int	dev_no,
		mbltmlExtraPmicId_t *	pmic_id )

Get the extra PMIC rail currently selected for the device.

Note: Supported on MBLTML_DEVICE_ARIES only.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	pmic_id	Pointer that receives the selected mbltmlExtraPmicId_t value.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if pmic_id is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetTotalUtilization()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetTotalUtilization	(	int	dev_no,
		double *	utilization )

Get the overall NPU utilization of a device.

Note: Supported on all device types.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	utilization	Pointer that receives the utilization value (typically a ratio in [0.0, 1.0] or a percentage).

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if utilization is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetMemoryUsage()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetMemoryUsage	(	int	dev_no,
		int64_t *	memory_usage )

Get the amount of device memory currently in use.

Note: Supported on all device types.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	memory_usage	Pointer that receives the in-use memory, in bytes.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if memory_usage is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetMemoryTotal()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetMemoryTotal	(	int	dev_no,
		int64_t *	memory_total )

Get the total amount of device memory available.

Note: Supported on all device types.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	memory_total	Pointer that receives the total memory, in bytes.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if memory_total is NULL, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetProcessInfos()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetProcessInfos	(	int	dev_no,
		mbltmlProcessInfo_t *	infos,
		unsigned int *	info_count )

Get per-process usage information for a device.

Note: Supported on all device types.

This call supports the standard two-step query pattern:

Pass *info_count == 0 (with infos either NULL or unused) to learn the required entry count, which is written back to info_count.
Pass a buffer with *info_count set to its capacity to retrieve up to that many entries; the actual entry count is written back to info_count.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	infos	Output array that receives the process records. May be `NULL` when `*info_count` is `0`.
[in,out]	info_count	On input, the capacity of `infos` in entries (or `0` to query the required size). On output, the number of entries written or required.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if info_count is NULL, or if infos is NULL while *info_count is non-zero, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, MBLTML_INSUFFICIENT_LENGTH if infos is too small to hold all entries, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlGetCoreInfos()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlGetCoreInfos	(	int	dev_no,
		mbltmlCoreInfo_t *	infos,
		unsigned int *	info_count )

Get per-core usage information for a device.

Note: Supported on all device types.

The two-step query pattern documented in mbltmlGetProcessInfos() applies.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[out]	infos	Output array that receives the core records. May be `NULL` when `*info_count` is `0`.
[in,out]	info_count	On input, the capacity of `infos` in entries (or `0` to query the required size). On output, the number of entries written or required.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if info_count is NULL, or if infos is NULL while *info_count is non-zero, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, MBLTML_INSUFFICIENT_LENGTH if infos is too small to hold all entries, or another mbltmlStatusCode_t error code on failure.

◆ mbltmlSetExtraPmicID()

MBLTML_EXPORT mbltmlStatusCode_t mbltmlSetExtraPmicID	(	int	dev_no,
		mbltmlExtraPmicId_t	pmic_id )

Select which extra PMIC rail subsequent mbltmlGetExtraPmic*() queries refer to.

Note: Supported on aries-rb hardware (MBLTML_HARDWARE_VERSION_ARIES_RB) only.

The underlying readings are refreshed by firmware once per second; allow up to 1 second after this call before mbltmlGetExtraPmicPower(), mbltmlGetExtraPmicCurrent() and mbltmlGetExtraPmicVoltage() reflect the newly selected rail.

Parameters

[in]	dev_no	Device index. See mbltmlGetDeviceCount() for the count.
[in]	pmic_id	Identifier of the extra PMIC rail to select.

Returns: MBLTML_SUCCESS on success, MBLTML_INVALID_ARGUMENT if dev_no is out of range of the device count, or another mbltmlStatusCode_t error code on failure.

mbltml C API

mbltml C API#

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MBLTML_DRIVER_VERSION_BUFFER_SIZE

◆ MBLTML_ON_DEVICE_DRIVER_VERSION_BUFFER_SIZE

◆ MBLTML_FIRMWARE_VERSION_BUFFER_SIZE

◆ MBLTML_NODE_NAME_BUFFER_SIZE

Typedef Documentation

◆ mbltmlProcessInfo_t

Enumeration Type Documentation

◆ mbltmlDeviceType_t

◆ mbltmlHardwareVersion_t

◆ mbltmlStatusCode_t

◆ mbltmlExtraPmicId_t

◆ mbltmlCluster_t

◆ mbltmlCore_t

Function Documentation

◆ mbltmlInit()

◆ mbltmlInitDevices()

◆ mbltmlShutdown()

◆ mbltmlGetDeviceCount()

◆ mbltmlGetDriverVersion()

◆ mbltmlGetDriverRevision()

◆ mbltmlGetNodeName()

◆ mbltmlGetDeviceType()

◆ mbltmlGetHardwareVersion()

◆ mbltmlGetOnDeviceDriverVersion()

◆ mbltmlGetOnDeviceDriverRevision()

◆ mbltmlGetFirmwareVersion()

◆ mbltmlGetFirmwareRevision()

◆ mbltmlGetFirmwareCRC()

◆ mbltmlGetTemperature()

◆ mbltmlGetSignalType()

◆ mbltmlGetNPUClock()

◆ mbltmlGetBusClock()

◆ mbltmlGetFanDuty()

◆ mbltmlGetVendorId()

◆ mbltmlGetDeviceId()

◆ mbltmlGetSubVendorId()

◆ mbltmlGetSubDeviceId()

◆ mbltmlGetPcieGen()

◆ mbltmlGetPcieLanes()

◆ mbltmlGetPcieRev()

◆ mbltmlGetPcieClassCode()

◆ mbltmlGetTotalPower()

◆ mbltmlGetTotalCurrent()

◆ mbltmlGetTotalVoltage()

◆ mbltmlGetExtraPmicPower()

◆ mbltmlGetExtraPmicCurrent()

◆ mbltmlGetExtraPmicVoltage()

◆ mbltmlGetExtraPmicId()

◆ mbltmlGetTotalUtilization()

◆ mbltmlGetMemoryUsage()

◆ mbltmlGetMemoryTotal()

◆ mbltmlGetProcessInfos()

◆ mbltmlGetCoreInfos()

◆ mbltmlSetExtraPmicID()