0
# Performance Control
1

2
Advanced performance tuning including clock control, power management, fan control, and overclocking capabilities. Most control functions require root privileges and are not supported in virtual environments.
3

4
## Capabilities
5

6
### Performance Level Control
7

8
Control GPU performance levels and operating modes.
9

10
```c { .api }
11
amdsmi_status_t amdsmi_get_gpu_perf_level(amdsmi_processor_handle processor_handle, amdsmi_dev_perf_level_t *perf);
12
amdsmi_status_t amdsmi_set_gpu_perf_level(amdsmi_processor_handle processor_handle, amdsmi_dev_perf_level_t perf_lvl);
13
```
14

15
**Parameters:**
16
- `processor_handle`: Handle to the GPU processor
17
- `perf`/`perf_lvl`: Performance level (AUTO, LOW, HIGH, MANUAL, etc.)
18

19
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
20

21
**Usage Example:**
22

23
```c
24
// Get current performance level
25
amdsmi_dev_perf_level_t current_perf;
26
amdsmi_status_t ret = amdsmi_get_gpu_perf_level(processor, &current_perf);
27
if (ret == AMDSMI_STATUS_SUCCESS) {
28
    printf("Current Performance Level: %d\n", current_perf);
29
}
30

31
// Set to high performance mode
32
ret = amdsmi_set_gpu_perf_level(processor, AMDSMI_DEV_PERF_LEVEL_HIGH);
33
if (ret == AMDSMI_STATUS_SUCCESS) {
34
    printf("Performance level set to HIGH\n");
35
}
36
```
37

38
### Determinism Mode
39

40
Enter determinism mode for consistent performance and power characteristics.
41

42
```c { .api }
43
amdsmi_status_t amdsmi_set_gpu_perf_determinism_mode(amdsmi_processor_handle processor_handle, uint64_t clkvalue);
44
```
45

46
**Parameters:**
47
- `processor_handle`: Handle to the GPU processor
48
- `clkvalue`: Clock value for deterministic operation
49

50
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
51

52
### Clock Frequency Control
53

54
Control available clock frequencies for different clock domains.
55

56
```c { .api }
57
amdsmi_status_t amdsmi_set_clk_freq(amdsmi_processor_handle processor_handle, amdsmi_clk_type_t clk_type, uint64_t freq_bitmask);
58
```
59

60
**Parameters:**
61
- `processor_handle`: Handle to the GPU processor
62
- `clk_type`: Clock type (GFX, MEMORY, SOC, etc.)
63
- `freq_bitmask`: Bitmask of allowed frequencies
64

65
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
66

67
### Clock Range Control
68

69
Set minimum and maximum clock ranges for specific clock domains.
70

71
```c { .api }
72
amdsmi_status_t amdsmi_set_gpu_clk_range(amdsmi_processor_handle processor_handle, uint64_t minclkvalue, uint64_t maxclkvalue, amdsmi_clk_type_t clkType);
73
```
74

75
**Parameters:**
76
- `processor_handle`: Handle to the GPU processor
77
- `minclkvalue`: Minimum clock value in MHz
78
- `maxclkvalue`: Maximum clock value in MHz
79
- `clkType`: Clock type to control
80

81
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
82

83
### Power Cap Control
84

85
Control power consumption limits for the GPU.
86

87
```c { .api }
88
amdsmi_status_t amdsmi_set_power_cap(amdsmi_processor_handle processor_handle, uint32_t sensor_ind, uint64_t cap);
89
```
90

91
**Parameters:**
92
- `processor_handle`: Handle to the GPU processor
93
- `sensor_ind`: 0-based sensor index (usually 0)
94
- `cap`: Power cap value in watts
95

96
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
97

98
**Usage Example:**
99

100
```c
101
// Set power cap to 200W
102
amdsmi_status_t ret = amdsmi_set_power_cap(processor, 0, 200);
103
if (ret == AMDSMI_STATUS_SUCCESS) {
104
    printf("Power cap set to 200W\n");
105
} else {
106
    printf("Failed to set power cap: %d\n", ret);
107
}
108
```
109

110
### Power Profile Control
111

112
Get and set power profile presets for different use cases.
113

114
```c { .api }
115
amdsmi_status_t amdsmi_get_gpu_power_profile_presets(amdsmi_processor_handle processor_handle, uint32_t sensor_ind, amdsmi_power_profile_status_t *status);
116
amdsmi_status_t amdsmi_set_gpu_power_profile(amdsmi_processor_handle processor_handle, uint32_t reserved, amdsmi_power_profile_preset_masks_t profile);
117
```
118

119
**Parameters:**
120
- `processor_handle`: Handle to the GPU processor
121
- `sensor_ind`: 0-based sensor index
122
- `status`: Pointer to receive power profile status
123
- `reserved`: Reserved parameter (set to 0)
124
- `profile`: Power profile preset to apply
125

126
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
127

128
### Fan Speed Control
129

130
Control GPU fan speeds manually or reset to automatic control.
131

132
```c { .api }
133
amdsmi_status_t amdsmi_set_gpu_fan_speed(amdsmi_processor_handle processor_handle, uint32_t sensor_ind, uint64_t speed);
134
amdsmi_status_t amdsmi_reset_gpu_fan(amdsmi_processor_handle processor_handle, uint32_t sensor_ind);
135
```
136

137
**Parameters:**
138
- `processor_handle`: Handle to the GPU processor
139
- `sensor_ind`: 0-based fan sensor index
140
- `speed`: Fan speed (0-255 scale or RPM depending on GPU)
141

142
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
143

144
**Usage Example:**
145

146
```c
147
// Set fan speed to 80% (approximately 204 on 0-255 scale)
148
amdsmi_status_t ret = amdsmi_set_gpu_fan_speed(processor, 0, 204);
149
if (ret == AMDSMI_STATUS_SUCCESS) {
150
    printf("Fan speed set to ~80%%\n");
151
}
152

153
// Reset fan to automatic control
154
ret = amdsmi_reset_gpu_fan(processor, 0);
155
if (ret == AMDSMI_STATUS_SUCCESS) {
156
    printf("Fan control reset to automatic\n");
157
}
158
```
159

160
### Overdrive Control
161

162
Control overdrive levels and voltage/frequency curves for advanced overclocking.
163

164
```c { .api }
165
amdsmi_status_t amdsmi_get_gpu_overdrive_level(amdsmi_processor_handle processor_handle, uint32_t *od);
166
amdsmi_status_t amdsmi_set_gpu_overdrive_level(amdsmi_processor_handle processor_handle, uint32_t od);
167
```
168

169
**Parameters:**
170
- `processor_handle`: Handle to the GPU processor
171
- `od`: Overdrive level (0-20, where 0 is disabled)
172

173
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
174

175
### Overdrive Clock and Voltage Control
176

177
Fine-tune overdrive clock and voltage settings.
178

179
```c { .api }
180
amdsmi_status_t amdsmi_set_gpu_od_clk_info(amdsmi_processor_handle processor_handle, amdsmi_freq_ind_t level, uint64_t clkvalue, amdsmi_clk_type_t clkType);
181
amdsmi_status_t amdsmi_get_gpu_od_volt_info(amdsmi_processor_handle processor_handle, amdsmi_od_volt_freq_data_t *odv);
182
amdsmi_status_t amdsmi_set_gpu_od_volt_info(amdsmi_processor_handle processor_handle, uint32_t vpoint, uint64_t clkvalue, uint64_t voltvalue);
183
```
184

185
**Parameters:**
186
- `processor_handle`: Handle to the GPU processor
187
- `level`: Frequency level index
188
- `clkvalue`: Clock value in MHz
189
- `clkType`: Clock type
190
- `odv`: Pointer to receive overdrive voltage/frequency data
191
- `vpoint`: Voltage point index
192
- `voltvalue`: Voltage value in mV
193

194
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
195

196
### GPU Reset
197

198
Reset the GPU to default state (requires root privileges).
199

200
```c { .api }
201
amdsmi_status_t amdsmi_reset_gpu(amdsmi_processor_handle processor_handle);
202
```
203

204
**Parameters:**
205
- `processor_handle`: Handle to the GPU processor
206

207
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
208

209
**Warning:** This function performs a complete GPU reset and may affect running applications.
210

211
## Python API
212

213
### Performance Level Control
214

215
```python { .api }
216
def amdsmi_get_gpu_perf_level(processor_handle):
217
    """
218
    Get current GPU performance level.
219
    
220
    Args:
221
        processor_handle: GPU processor handle
222
        
223
    Returns:
224
        AmdSmiDevPerfLevel: Current performance level
225
        
226
    Raises:
227
        AmdSmiException: If performance level query fails
228
    """
229

230
def amdsmi_set_gpu_perf_level(processor_handle, perf_level):
231
    """
232
    Set GPU performance level.
233
    
234
    Args:
235
        processor_handle: GPU processor handle
236
        perf_level (AmdSmiDevPerfLevel): Performance level to set
237
        
238
    Raises:
239
        AmdSmiException: If performance level setting fails
240
    """
241
```
242

243
### Power Control
244

245
```python { .api }
246
def amdsmi_set_power_cap(processor_handle, sensor_ind, cap):
247
    """
248
    Set GPU power cap.
249
    
250
    Args:
251
        processor_handle: GPU processor handle
252
        sensor_ind (int): Sensor index (usually 0)
253
        cap (int): Power cap in watts
254
        
255
    Raises:
256
        AmdSmiException: If power cap setting fails
257
    """
258

259
def amdsmi_get_gpu_power_profile_presets(processor_handle, sensor_ind):
260
    """
261
    Get available power profile presets.
262
    
263
    Args:
264
        processor_handle: GPU processor handle
265
        sensor_ind (int): Sensor index
266
        
267
    Returns:
268
        dict: Power profile status information
269
        
270
    Raises:
271
        AmdSmiException: If power profile query fails
272
    """
273
```
274

275
### Fan Control
276

277
```python { .api }
278
def amdsmi_set_gpu_fan_speed(processor_handle, sensor_ind, speed):
279
    """
280
    Set GPU fan speed.
281
    
282
    Args:
283
        processor_handle: GPU processor handle
284
        sensor_ind (int): Fan sensor index
285
        speed (int): Fan speed (0-255 scale)
286
        
287
    Raises:
288
        AmdSmiException: If fan speed setting fails
289
    """
290

291
def amdsmi_reset_gpu_fan(processor_handle, sensor_ind):
292
    """
293
    Reset GPU fan to automatic control.
294
    
295
    Args:
296
        processor_handle: GPU processor handle
297
        sensor_ind (int): Fan sensor index
298
        
299
    Raises:
300
        AmdSmiException: If fan reset fails
301
    """
302
```
303

304
**Python Usage Example:**
305

306
```python
307
import amdsmi
308
from amdsmi import AmdSmiDevPerfLevel, AmdSmiPowerProfilePresetMasks
309

310
# Initialize and get GPU handle
311
amdsmi.amdsmi_init()
312

313
try:
314
    sockets = amdsmi.amdsmi_get_socket_handles()
315
    processors = amdsmi.amdsmi_get_processor_handles(sockets[0])
316
    gpu = processors[0]
317
    
318
    # Get current performance level
319
    perf_level = amdsmi.amdsmi_get_gpu_perf_level(gpu)
320
    print(f"Current Performance Level: {perf_level}")
321
    
322
    # Set to high performance mode
323
    amdsmi.amdsmi_set_gpu_perf_level(gpu, AmdSmiDevPerfLevel.AMDSMI_DEV_PERF_LEVEL_HIGH)
324
    print("Performance level set to HIGH")
325
    
326
    # Set power cap to 250W
327
    amdsmi.amdsmi_set_power_cap(gpu, 0, 250)
328
    print("Power cap set to 250W")
329
    
330
    # Set fan speed to 70%
331
    fan_speed = int(255 * 0.7)  # Convert percentage to 0-255 scale
332
    amdsmi.amdsmi_set_gpu_fan_speed(gpu, 0, fan_speed)
333
    print(f"Fan speed set to {fan_speed} (~70%)")
334
    
335
    # Later, reset fan to automatic
336
    amdsmi.amdsmi_reset_gpu_fan(gpu, 0)
337
    print("Fan control reset to automatic")
338

339
except amdsmi.AmdSmiException as e:
340
    print(f"Control operation failed: {e}")
341

342
finally:
343
    amdsmi.amdsmi_shut_down()
344
```
345

346
## Types
347

348
### Performance Levels
349

350
```c { .api }
351
typedef enum {
352
    AMDSMI_DEV_PERF_LEVEL_AUTO = 0,        // Automatic performance scaling
353
    AMDSMI_DEV_PERF_LEVEL_LOW,             // Low performance/power mode
354
    AMDSMI_DEV_PERF_LEVEL_HIGH,            // High performance mode
355
    AMDSMI_DEV_PERF_LEVEL_MANUAL,          // Manual performance control
356
    AMDSMI_DEV_PERF_LEVEL_STABLE_STD,      // Stable standard clocks
357
    AMDSMI_DEV_PERF_LEVEL_STABLE_PEAK,     // Stable peak clocks
358
    AMDSMI_DEV_PERF_LEVEL_STABLE_MIN_MCLK, // Stable minimum memory clock
359
    AMDSMI_DEV_PERF_LEVEL_STABLE_MIN_SCLK, // Stable minimum system clock
360
    AMDSMI_DEV_PERF_LEVEL_DETERMINISM,     // Deterministic performance
361
    AMDSMI_DEV_PERF_LEVEL_UNKNOWN = 0x100  // Unknown performance level
362
} amdsmi_dev_perf_level_t;
363
```
364

365
### Power Profile Presets
366

367
```c { .api }
368
typedef enum {
369
    AMDSMI_PWR_PROF_PRST_CUSTOM_MASK = 0x1,        // Custom profile
370
    AMDSMI_PWR_PROF_PRST_VIDEO_MASK = 0x2,         // Video profile
371
    AMDSMI_PWR_PROF_PRST_POWER_SAVING_MASK = 0x4,  // Power saving profile
372
    AMDSMI_PWR_PROF_PRST_COMPUTE_MASK = 0x8,       // Compute profile
373
    AMDSMI_PWR_PROF_PRST_VR_MASK = 0x10,          // VR profile
374
    AMDSMI_PWR_PROF_PRST_3D_FULL_SCREEN_MASK = 0x20, // 3D full screen profile
375
    AMDSMI_PWR_PROF_PRST_BOOTUP_DEFAULT = 0x40,    // Bootup default profile
376
    AMDSMI_PWR_PROF_PRST_LAST = AMDSMI_PWR_PROF_PRST_BOOTUP_DEFAULT
377
} amdsmi_power_profile_preset_masks_t;
378
```
379

380
### Frequency Indices
381

382
```c { .api }
383
typedef enum {
384
    AMDSMI_FREQ_IND_MIN = 0,      // Minimum frequency
385
    AMDSMI_FREQ_IND_MAX = 1,      // Maximum frequency
386
    AMDSMI_FREQ_IND_INVALID = 0xFFFFFFFF
387
} amdsmi_freq_ind_t;
388
```
389

390
### Overdrive Voltage/Frequency Data
391

392
```c { .api }
393
typedef struct {
394
    uint32_t num_regions;                                        // Number of voltage curve regions
395
    struct {
396
        uint32_t freq_range_max;                                // Maximum frequency for region
397
        uint32_t freq_range_min;                                // Minimum frequency for region  
398
        uint32_t volt_range_max;                                // Maximum voltage for region
399
        uint32_t volt_range_min;                                // Minimum voltage for region
400
    } curve_regions[AMDSMI_NUM_VOLTAGE_CURVE_POINTS];
401
    uint32_t reserved[8];                                       // Reserved
402
} amdsmi_od_volt_freq_data_t;
403
```
404

405
### Power Profile Status
406

407
```c { .api }
408
typedef struct {
409
    uint32_t available_profiles;          // Available profile mask
410
    uint32_t current_profile;            // Current active profile
411
    uint32_t num_profiles;               // Number of available profiles
412
    uint32_t reserved[5];                // Reserved
413
} amdsmi_power_profile_status_t;
414
```
415

416
## Constants
417

418
```c { .api }
419
#define AMDSMI_NUM_VOLTAGE_CURVE_POINTS 3     // Number of voltage curve points  
420
#define AMDSMI_MAX_FAN_SPEED 255              // Maximum fan speed value
421
```
422

423
### GPU Reset
424

425
Perform a soft reset of the GPU processor.
426

427
```c { .api }
428
amdsmi_status_t amdsmi_reset_gpu(amdsmi_processor_handle processor_handle);
429
```
430

431
**Parameters:**
432
- `processor_handle`: Handle to the GPU processor to reset
433

434
**Returns:** `amdsmi_status_t` - AMDSMI_STATUS_SUCCESS on success, error code on failure
435

436
**Usage Example:**
437

438
```c
439
// Reset the GPU (requires root privileges)
440
amdsmi_status_t ret = amdsmi_reset_gpu(processor);
441
if (ret == AMDSMI_STATUS_SUCCESS) {
442
    printf("GPU reset successfully\n");
443
} else {
444
    printf("GPU reset failed: %d\n", ret);
445
}
446
```
447

448
**Warning:** GPU reset will interrupt all running GPU processes and may cause data loss.
449

450
## Important Notes
451

452
1. **Root Privileges Required**: Most control functions require root/administrator privileges.
453

454
2. **Virtual Machine Limitations**: Control functions are typically not supported in virtual environments.
455

456
3. **Hardware Dependency**: Available features depend on specific GPU model and driver version.
457

458
4. **Safety Considerations**: 
459
   - Incorrect settings can cause system instability or hardware damage
460
   - Always monitor temperatures when adjusting performance settings
461
   - Overdrive settings can void warranty
462

463
5. **Performance Levels**:
464
   - **AUTO**: Let the driver manage performance automatically
465
   - **HIGH**: Maximum performance for demanding workloads
466
   - **LOW**: Reduced performance for power saving
467
   - **MANUAL**: Full manual control over frequencies
468

469
6. **Power Profiles**: Pre-configured settings optimized for specific use cases like gaming, compute, or power saving.
470

471
7. **Fan Control**: Manual fan control overrides automatic thermal management; monitor temperatures carefully.
472

473
8. **Overdrive**: Advanced overclocking features that may not be available on all GPUs.
474

475
9. **Persistence**: Settings may not persist across reboots or driver restarts.