0
# Initialization and Discovery
1
2
Core system initialization, device enumeration, and handle management for AMD processors. These functions must be called before using any other AMD SMI functionality.
3
4
## Capabilities
5
6
### Library Initialization
7
8
Initialize the AMD SMI library and specify which processor types to manage.
9
10
```cpp { .api }
11
amdsmi_status_t amdsmi_init(uint64_t init_flags);
12
```
13
14
**Parameters:**
15
- `init_flags`: Bitwise combination of initialization flags
16
17
**Initialization Flags:**
18
```cpp { .api }
19
typedef enum {
20
AMDSMI_INIT_ALL_PROCESSORS = 0xFFFFFFFF,
21
AMDSMI_INIT_AMD_CPUS = (1 << 0),
22
AMDSMI_INIT_AMD_GPUS = (1 << 1),
23
AMDSMI_INIT_NON_AMD_CPUS = (1 << 2),
24
AMDSMI_INIT_NON_AMD_GPUS = (1 << 3),
25
AMDSMI_INIT_AMD_APUS = (AMDSMI_INIT_AMD_CPUS | AMDSMI_INIT_AMD_GPUS)
26
} amdsmi_init_flags_t;
27
```
28
29
**Usage Example:**
30
```cpp
31
// Initialize for AMD GPUs only
32
amdsmi_status_t status = amdsmi_init(AMDSMI_INIT_AMD_GPUS);
33
if (status != AMDSMI_STATUS_SUCCESS) {
34
// Handle initialization failure
35
}
36
37
// Initialize for both AMD CPUs and GPUs
38
status = amdsmi_init(AMDSMI_INIT_AMD_APUS);
39
```
40
41
### Library Shutdown
42
43
Clean up resources and shut down the AMD SMI library.
44
45
```cpp { .api }
46
amdsmi_status_t amdsmi_shut_down(void);
47
```
48
49
**Returns:** Status code indicating success or failure
50
51
**Usage Example:**
52
```cpp
53
// Always call shutdown to clean up resources
54
amdsmi_shut_down();
55
```
56
57
### Processor Handle Discovery
58
59
Get handles to available processors for subsequent API calls.
60
61
```cpp { .api }
62
amdsmi_status_t amdsmi_get_processor_handles(amdsmi_processor_type_t processor_type,
63
amdsmi_processor_handle* processor_handles,
64
uint32_t* num_devices);
65
```
66
67
**Parameters:**
68
- `processor_type`: Type of processors to enumerate
69
- `processor_handles`: Array to store processor handles (can be NULL to query count)
70
- `num_devices`: Input: array size, Output: actual number of devices
71
72
**Processor Types:**
73
```cpp { .api }
74
typedef enum {
75
AMDSMI_PROCESSOR_TYPE_AMD_GPU,
76
AMDSMI_PROCESSOR_TYPE_AMD_CPU,
77
AMDSMI_PROCESSOR_TYPE_NON_AMD_GPU,
78
AMDSMI_PROCESSOR_TYPE_NON_AMD_CPU
79
} amdsmi_processor_type_t;
80
```
81
82
**Usage Example:**
83
```cpp
84
// First, get the number of AMD GPUs
85
uint32_t num_gpus = 0;
86
amdsmi_status_t status = amdsmi_get_processor_handles(AMDSMI_PROCESSOR_TYPE_AMD_GPU,
87
nullptr, &num_gpus);
88
89
if (status == AMDSMI_STATUS_SUCCESS && num_gpus > 0) {
90
// Allocate array for handles
91
std::vector<amdsmi_processor_handle> gpu_handles(num_gpus);
92
93
// Get the actual handles
94
status = amdsmi_get_processor_handles(AMDSMI_PROCESSOR_TYPE_AMD_GPU,
95
gpu_handles.data(), &num_gpus);
96
97
// Use the handles for subsequent API calls
98
for (const auto& handle : gpu_handles) {
99
// Perform operations on each GPU
100
}
101
}
102
```
103
104
### Processor Type Detection
105
106
Determine the type of a given processor handle.
107
108
```cpp { .api }
109
amdsmi_status_t amdsmi_get_processor_type(amdsmi_processor_handle processor_handle,
110
amdsmi_processor_type_t* processor_type);
111
```
112
113
**Parameters:**
114
- `processor_handle`: Handle to query
115
- `processor_type`: Output pointer to store processor type
116
117
**Usage Example:**
118
```cpp
119
amdsmi_processor_type_t type;
120
amdsmi_status_t status = amdsmi_get_processor_type(processor_handle, &type);
121
122
if (status == AMDSMI_STATUS_SUCCESS) {
123
switch (type) {
124
case AMDSMI_PROCESSOR_TYPE_AMD_GPU:
125
// Handle AMD GPU specific operations
126
break;
127
case AMDSMI_PROCESSOR_TYPE_AMD_CPU:
128
// Handle AMD CPU specific operations
129
break;
130
default:
131
// Handle other processor types
132
break;
133
}
134
}
135
```
136
137
### Socket Discovery
138
139
Get socket-level handles for CPU management.
140
141
```cpp { .api }
142
amdsmi_status_t amdsmi_get_socket_handles(uint32_t* num_sockets,
143
amdsmi_socket_handle* socket_handles);
144
```
145
146
**Parameters:**
147
- `num_sockets`: Input: array size, Output: actual number of sockets
148
- `socket_handles`: Array to store socket handles (can be NULL to query count)
149
150
```cpp { .api }
151
amdsmi_status_t amdsmi_get_socket_info(amdsmi_socket_handle socket_handle,
152
amdsmi_socket_info_t* socket_info);
153
```
154
155
**Socket Information Structure:**
156
```cpp { .api }
157
typedef struct {
158
uint32_t socket_id;
159
uint32_t num_cpu_cores;
160
uint32_t num_gpus;
161
} amdsmi_socket_info_t;
162
```
163
164
## Language Interface Examples
165
166
### Python
167
```python
168
import amdsmi
169
170
# Initialize library
171
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlag.AMD_GPUS)
172
173
# Get GPU handles
174
gpu_handles = amdsmi.amdsmi_get_processor_handles(amdsmi.AmdSmiProcessorType.AMD_GPU)
175
print(f"Found {len(gpu_handles)} AMD GPU(s)")
176
177
# Get socket handles for CPU management
178
socket_handles = amdsmi.amdsmi_get_socket_handles()
179
print(f"Found {len(socket_handles)} CPU socket(s)")
180
181
# Cleanup
182
amdsmi.amdsmi_shut_down()
183
```
184
185
### Go
186
187
The Go interface provides direct initialization functions for GPU and CPU monitoring:
188
189
```go { .api }
190
func GO_gpu_init() bool
191
func GO_gpu_shutdown() bool
192
func GO_gpu_num_monitor_devices() uint
193
func GO_cpu_init() bool
194
func GO_cpu_number_of_sockets_get() uint
195
func GO_cpu_number_of_threads_get() uint
196
func GO_cpu_threads_per_core_get() uint
197
```
198
199
**Usage Example:**
200
201
```go
202
package main
203
204
import (
205
"fmt"
206
"log"
207
)
208
209
func main() {
210
// Initialize for GPU monitoring
211
if !goamdsmi.GO_gpu_init() {
212
log.Fatal("Failed to initialize AMD SMI for GPUs")
213
}
214
defer func() {
215
if !goamdsmi.GO_gpu_shutdown() {
216
log.Println("Warning: Failed to shutdown GPU monitoring")
217
}
218
}()
219
220
// Get number of monitor devices
221
numGPUs := goamdsmi.GO_gpu_num_monitor_devices()
222
fmt.Printf("Found %d GPU(s) available for monitoring\n", numGPUs)
223
224
// Initialize CPU monitoring separately if needed
225
if goamdsmi.GO_cpu_init() {
226
numSockets := goamdsmi.GO_cpu_number_of_sockets_get()
227
numThreads := goamdsmi.GO_cpu_number_of_threads_get()
228
threadsPerCore := goamdsmi.GO_cpu_threads_per_core_get()
229
230
fmt.Printf("CPU Info: %d sockets, %d threads, %d threads per core\n",
231
numSockets, numThreads, threadsPerCore)
232
}
233
}
234
```
235
236
### Rust
237
```rust
238
use amdsmi::{init, shut_down, get_processor_handles, ProcessorType, InitFlag};
239
240
// Initialize library
241
init(InitFlag::AMD_GPUS)?;
242
243
// Get GPU handles
244
let gpu_handles = get_processor_handles(ProcessorType::AmdGpu)?;
245
println!("Found {} GPU(s)", gpu_handles.len());
246
247
// Cleanup
248
shut_down();
249
```
250
251
## Error Handling
252
253
All initialization functions return status codes that should be checked:
254
255
```cpp { .api }
256
typedef enum {
257
AMDSMI_STATUS_SUCCESS = 0,
258
AMDSMI_STATUS_INVAL,
259
AMDSMI_STATUS_NOT_SUPPORTED,
260
AMDSMI_STATUS_FILE_ERROR,
261
AMDSMI_STATUS_PERMISSION,
262
AMDSMI_STATUS_OUT_OF_RESOURCES,
263
AMDSMI_STATUS_INTERNAL_EXCEPTION,
264
AMDSMI_STATUS_INPUT_OUT_OF_BOUNDS,
265
AMDSMI_STATUS_INIT_ERROR,
266
AMDSMI_STATUS_NOT_YET_IMPLEMENTED,
267
AMDSMI_STATUS_NOT_FOUND,
268
AMDSMI_STATUS_INSUFFICIENT_SIZE,
269
AMDSMI_STATUS_INTERRUPT,
270
AMDSMI_STATUS_UNEXPECTED_SIZE,
271
AMDSMI_STATUS_NO_DATA,
272
AMDSMI_STATUS_UNEXPECTED_DATA,
273
AMDSMI_STATUS_BUSY,
274
AMDSMI_STATUS_REFCOUNT_OVERFLOW,
275
AMDSMI_STATUS_UNKNOWN_ERROR
276
} amdsmi_status_t;
277
```
278
279
**Common Error Conditions:**
280
- `AMDSMI_STATUS_INIT_ERROR`: Library not initialized or initialization failed
281
- `AMDSMI_STATUS_PERMISSION`: Insufficient permissions (especially for control operations)
282
- `AMDSMI_STATUS_NOT_SUPPORTED`: Feature not supported on current hardware
283
- `AMDSMI_STATUS_FILE_ERROR`: Driver files not accessible