0
# Library Management
1
2
Core library initialization, shutdown, and version management functions that must be called before using other AMD SMI functionality.
3
4
## Capabilities
5
6
### Library Initialization
7
8
Initialize the AMD SMI library and internal data structures. This function must be called before using any other AMD SMI functions.
9
10
```c { .api }
11
amdsmi_status_t amdsmi_init(uint64_t init_flags);
12
```
13
14
**Parameters:**
15
- `init_flags`: Bitfield specifying which processor types to initialize. Values from `amdsmi_init_flags_t` may be OR'd together.
16
17
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
18
19
**Usage Example:**
20
21
```c
22
// Initialize for AMD GPUs only
23
amdsmi_status_t ret = amdsmi_init(AMDSMI_INIT_AMD_GPUS);
24
if (ret != AMDSMI_STATUS_SUCCESS) {
25
// Handle error
26
return ret;
27
}
28
29
// Initialize for all processor types
30
ret = amdsmi_init(AMDSMI_INIT_ALL_PROCESSORS);
31
32
// Initialize for AMD GPUs and CPUs
33
ret = amdsmi_init(AMDSMI_INIT_AMD_GPUS | AMDSMI_INIT_AMD_CPUS);
34
```
35
36
### Library Shutdown
37
38
Shutdown the AMD SMI library and perform cleanup of internal resources. This should be called when AMD SMI is no longer needed.
39
40
```c { .api }
41
amdsmi_status_t amdsmi_shut_down(void);
42
```
43
44
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
45
46
**Usage Example:**
47
48
```c
49
// Cleanup and shutdown the library
50
amdsmi_status_t ret = amdsmi_shut_down();
51
if (ret != AMDSMI_STATUS_SUCCESS) {
52
// Handle error - but continue shutdown process
53
}
54
```
55
56
### Version Information
57
58
Get the version information for the currently running AMD SMI library build.
59
60
```c { .api }
61
amdsmi_status_t amdsmi_get_lib_version(amdsmi_version_t *version);
62
```
63
64
**Parameters:**
65
- `version`: Pointer to `amdsmi_version_t` structure to receive version information
66
67
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
68
69
**Usage Example:**
70
71
```c
72
amdsmi_version_t version;
73
amdsmi_status_t ret = amdsmi_get_lib_version(&version);
74
if (ret == AMDSMI_STATUS_SUCCESS) {
75
printf("AMD SMI Library Version: %d.%d.%d.%d (%s)\n",
76
version.year, version.major, version.minor,
77
version.release, version.build);
78
}
79
```
80
81
## Python API
82
83
### Library Initialization
84
85
```python { .api }
86
def amdsmi_init(init_flags=None):
87
"""
88
Initialize the AMD SMI library.
89
90
Args:
91
init_flags (int, optional): Initialization flags from AmdSmiInitFlags
92
93
Raises:
94
AmdSmiException: If initialization fails
95
"""
96
```
97
98
### Library Shutdown
99
100
```python { .api }
101
def amdsmi_shut_down():
102
"""
103
Shutdown the AMD SMI library and cleanup resources.
104
105
Raises:
106
AmdSmiException: If shutdown fails
107
"""
108
```
109
110
### Version Information
111
112
```python { .api }
113
def amdsmi_get_lib_version():
114
"""
115
Get AMD SMI library version information.
116
117
Returns:
118
dict: Version information with keys 'year', 'major', 'minor', 'release', 'build'
119
120
Raises:
121
AmdSmiException: If version retrieval fails
122
"""
123
```
124
125
**Python Usage Example:**
126
127
```python
128
import amdsmi
129
from amdsmi import AmdSmiInitFlags
130
131
# Initialize the library
132
try:
133
amdsmi.amdsmi_init(AmdSmiInitFlags.INIT_AMD_GPUS)
134
135
# Get version information
136
version = amdsmi.amdsmi_get_lib_version()
137
print(f"AMD SMI Library Version: {version['year']}.{version['major']}.{version['minor']}.{version['release']}")
138
139
# ... use other AMD SMI functions ...
140
141
finally:
142
# Always shutdown the library
143
amdsmi.amdsmi_shut_down()
144
```
145
146
## Types
147
148
### Initialization Flags
149
150
```c { .api }
151
typedef enum {
152
AMDSMI_INIT_ALL_PROCESSORS = 0x0, // Initialize all processor types
153
AMDSMI_INIT_AMD_CPUS = (1 << 0), // Initialize AMD CPUs
154
AMDSMI_INIT_AMD_GPUS = (1 << 1), // Initialize AMD GPUs
155
AMDSMI_INIT_NON_AMD_CPUS = (1 << 2), // Initialize non-AMD CPUs
156
AMDSMI_INIT_NON_AMD_GPUS = (1 << 3) // Initialize non-AMD GPUs
157
} amdsmi_init_flags_t;
158
```
159
160
### Version Structure
161
162
```c { .api }
163
typedef struct {
164
uint32_t year; // Year of release (last 2 digits)
165
uint32_t major; // Major version number
166
uint32_t minor; // Minor version number
167
uint32_t release; // Patch/build/stepping version
168
const char *build; // Full build version string
169
} amdsmi_version_t;
170
```
171
172
### Status Codes
173
174
```c { .api }
175
typedef enum {
176
AMDSMI_STATUS_SUCCESS = 0, // Call succeeded
177
AMDSMI_STATUS_INVAL = 1, // Invalid parameters
178
AMDSMI_STATUS_NOT_SUPPORTED = 2, // Command not supported
179
AMDSMI_STATUS_NOT_YET_IMPLEMENTED = 3, // Not implemented yet
180
AMDSMI_STATUS_FAIL_LOAD_MODULE = 4, // Failed to load library
181
AMDSMI_STATUS_FAIL_LOAD_SYMBOL = 5, // Failed to load symbol
182
AMDSMI_STATUS_DRM_ERROR = 6, // Error when calling libdrm
183
AMDSMI_STATUS_API_FAILED = 7, // API call failed
184
AMDSMI_STATUS_TIMEOUT = 8, // Timeout in API call
185
AMDSMI_STATUS_RETRY = 9, // Retry operation
186
AMDSMI_STATUS_NO_PERM = 10, // Permission denied
187
AMDSMI_STATUS_INTERRUPT = 11, // Interrupt occurred during execution
188
AMDSMI_STATUS_IO = 12, // I/O Error
189
AMDSMI_STATUS_ADDRESS_FAULT = 13, // Bad address
190
AMDSMI_STATUS_FILE_ERROR = 14, // Problem accessing a file
191
AMDSMI_STATUS_OUT_OF_RESOURCES = 15, // Not enough memory
192
AMDSMI_STATUS_INTERNAL_EXCEPTION = 16, // Internal exception caught
193
AMDSMI_STATUS_INPUT_OUT_OF_BOUNDS = 17, // Input out of allowable range
194
AMDSMI_STATUS_INIT_ERROR = 18, // Error during initialization
195
AMDSMI_STATUS_REFCOUNT_OVERFLOW = 19, // Reference counter overflow
196
AMDSMI_STATUS_BUSY = 30, // Device busy
197
AMDSMI_STATUS_NOT_FOUND = 31, // Device not found
198
AMDSMI_STATUS_NOT_INIT = 32, // Device not initialized
199
AMDSMI_STATUS_NO_SLOT = 33, // No more free slot
200
AMDSMI_STATUS_NO_DATA = 40, // No data found
201
AMDSMI_STATUS_INSUFFICIENT_SIZE = 41, // Not enough resources
202
AMDSMI_STATUS_UNEXPECTED_SIZE = 42, // Unexpected amount of data
203
AMDSMI_STATUS_UNEXPECTED_DATA = 43, // Unexpected data
204
AMDSMI_STATUS_MAP_ERROR = 0xFFFFFFFE, // Internal library error mapping failed
205
AMDSMI_STATUS_UNKNOWN_ERROR = 0xFFFFFFFF // Unknown error occurred
206
} amdsmi_status_t;
207
```
208
209
## Important Notes
210
211
1. **Initialization is Required**: All AMD SMI functions except `amdsmi_get_lib_version()` require the library to be initialized first.
212
213
2. **Shutdown is Important**: Always call `amdsmi_shut_down()` to properly release resources, even if other operations fail.
214
215
3. **Processor Type Filtering**: The `init_flags` parameter controls which types of processors are discovered. Currently, only `AMDSMI_INIT_AMD_GPUS` is fully supported.
216
217
4. **Thread Safety**: The library maintains internal state, so proper initialization and shutdown should be coordinated across threads.
218
219
5. **Handle Invalidation**: All socket and processor handles become invalid after `amdsmi_shut_down()` is called.