1#pragma once
2
3// DISCLAIMER:
4// THIS FILE IS CREATED FROM SCRATCH, BY READING THE OFFICIAL MTML API
5// DOCUMENTATION REFERENCED BELOW, IN ORDER TO MAKE FASTFETCH MIT COMPLIANT.
6
7#define MTML_DEVICE_PCI_SBDF_BUFFER_SIZE 32
8#define MTML_DEVICE_NAME_BUFFER_SIZE 32
9
10/**
11 * Return values for MTML API calls.
12 */
13typedef enum {
14 MTML_SUCCESS = 0,
15} MtmlReturn;
16
17/**
18 * The brand of the device.
19 */
20typedef enum {
21 MTML_BRAND_MTT = 0, //!< MTT series.
22} MtmlBrandType;
23
24typedef struct MtmlLibrary MtmlLibrary;
25typedef struct MtmlSystem MtmlSystem;
26typedef struct MtmlDevice MtmlDevice;
27typedef struct MtmlGpu MtmlGpu;
28typedef struct MtmlMemory MtmlMemory;
29
30/**
31 * PCI information about a device.
32 */
33typedef struct
34{
35 char sbdf[MTML_DEVICE_PCI_SBDF_BUFFER_SIZE]; //!< The tuple segment:bus:device.function PCI identifier (& nullptr terminator).
36 unsigned int segment; //!< The PCI segment group(domain) on which the device's bus resides, 0 to 0xffffffff.
37 unsigned int bus; //!< The bus on which the device resides, 0 to 0xff.
38 unsigned int device; //!< The device ID on the bus, 0 to 31.
39 unsigned int pciDeviceId; //!< The combined 16-bit device ID and 16-bit vendor ID.
40 unsigned int pciSubsystemId; //!< The 32-bit sub system device ID.
41 unsigned int busWidth; //!< @deprecated This value set to zero.
42 float pciMaxSpeed; //!< The maximum link speed (transfer rate per lane) of the device. The unit is GT/s.
43 float pciCurSpeed; //!< The current link speed (transfer rate per lane) of the device. The unit is GT/s.
44 unsigned int pciMaxWidth; //!< The maximum link width of the device.
45 unsigned int pciCurWidth; //!< The current link width of the device.
46 unsigned int pciMaxGen; //!< The maximum supported generation of the device.
47 unsigned int pciCurGen; //!< The current generation of the device.
48 int rsvd[6]; //!< Reserved for future extension.
49} MtmlPciInfo;
50
51// Retrieves the number of cores of a device.
52MtmlReturn mtmlDeviceCountGpuCores(const MtmlDevice* device, unsigned int* numCores);
53// Retrieves the brand of a device.
54MtmlReturn mtmlDeviceGetBrand(const MtmlDevice* dev, MtmlBrandType* type);
55// Retrieves the index associated with the specified device.
56MtmlReturn mtmlDeviceGetIndex(const MtmlDevice* dev, unsigned int* index);
57// Retrieves the name of a device.
58MtmlReturn mtmlDeviceGetName(const MtmlDevice* dev, char* name, unsigned int length);
59// Retrieves the PCI attributes of a device.
60MtmlReturn mtmlDeviceGetPciInfo(const MtmlDevice* dev, MtmlPciInfo* pci);
61/**
62 * Retrieves the UUID of a specified device. The UUID is a hexadecimal string in the
63 * form of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where each 'x' is an ASCII character that represents a hexadecimal
64 * digit. The UUID is globally unique for every single device thus can be used to identify different devices
65 * physically.
66 */
67MtmlReturn mtmlDeviceGetUUID(const MtmlDevice* dev, char* uuid, unsigned int length);
68// Initializes a GPU opaque object to represent a specific graphic core on the target device that is designated by its index.
69MtmlReturn mtmlDeviceInitGpu(const MtmlDevice* dev, MtmlGpu** gpu);
70// Initializes a memory opaque object to represent the memory on the target device.
71MtmlReturn mtmlDeviceInitMemory(const MtmlDevice* dev, MtmlMemory** mem);
72
73// Retrieves the maximum supported clock speed for the device's graphic core.
74MtmlReturn mtmlGpuGetMaxClock(const MtmlGpu* gpu, unsigned int* clockMhz);
75// Retrieves the current temperature readings for the device's graphic core, in degrees Celsius.
76MtmlReturn mtmlGpuGetTemperature(const MtmlGpu* gpu, unsigned int* temp);
77// Retrieves the current utilization rate for the device's graphic core.
78MtmlReturn mtmlGpuGetUtilization(const MtmlGpu* gpu, unsigned int* utilization);
79
80// Retrieves the number of devices that can be accessed by the library opaque object.
81MtmlReturn mtmlLibraryCountDevice(const MtmlLibrary* lib, unsigned int* count);
82/**
83 * Initializes a device opaque object to represent a device that is designated by its index.
84 * The index ranges from (0) to (deviceCount - 1), where deviceCount is retrieved from \ref mtmlLibraryCountDevice().
85 */
86MtmlReturn mtmlLibraryInit(MtmlLibrary** lib);
87/**
88 * Initializes a device opaque object to represent a device that is designated by its index.
89 * The index ranges from (0) to (deviceCount - 1), where deviceCount is retrieved from \ref mtmlLibraryCountDevice().
90 */
91MtmlReturn mtmlLibraryInitDeviceByIndex(const MtmlLibrary* lib, unsigned int index, MtmlDevice** dev);
92/**
93 * Initializes a device opaque object to represent a device that is designated by its PCI Sbdf.
94 * The PCI Sbdf format like 00000000:3a:00.0 refer to \ref MtmlPciInfo::sbdf.
95 */
96MtmlReturn mtmlLibraryInitDeviceByPciSbdf(const MtmlLibrary* lib, const char* pciSbdf, MtmlDevice** dev);
97// Initializes a MtmlSystem opaque pointer that is bound to a library opaque object.
98MtmlReturn mtmlLibraryInitSystem(const MtmlLibrary* lib, MtmlSystem** sys);
99/**
100 * Shuts down the library opaque object that is previously initialized by \ref mtmlLibraryInit() and releases its resources.
101 * The \a lib pointer cannot be used anymore after this function returns.
102 */
103MtmlReturn mtmlLibraryShutDown(MtmlLibrary* lib);
104
105// Retrieves the amount of total memory available on the device, in bytes.
106MtmlReturn mtmlMemoryGetTotal(const MtmlMemory* mem, unsigned long long* total);
107// Retrieves the amount of used memory on the device, in bytes.
108MtmlReturn mtmlMemoryGetUsed(const MtmlMemory* mem, unsigned long long* used);
109// Retrieves the current memory utilization rate for the device.
110MtmlReturn mtmlMemoryGetUtilization(const MtmlMemory* mem, unsigned int* utilization);