0
# AMD System Management Interface (AMD SMI) - Go Package
1

2
The AMD System Management Interface (AMD SMI) Go package provides Go bindings for AMD GPU and CPU monitoring and management in high-performance computing environments. This package offers unified access to GPU performance metrics, power monitoring, thermal sensors, and CPU management through a native Go interface.
3

4
## Package Information
5

6
- **Package Name**: goamdsmi
7
- **Package Type**: Go library  
8
- **Language**: Go
9
- **Installation**: Build with CGO linking to AMD SMI C library
10
- **Go Version Required**: 1.20 or greater
11
- **Documentation**: https://rocm.docs.amd.com/projects/amdsmi/en/latest/
12
- **Repository**: https://github.com/RadeonOpenCompute/amdsmi
13

14
## Core Imports
15

16
### Go Package Import
17

18
```go
19
import "path/to/goamdsmi"
20
```
21

22
**Note**: This is a CGO package that requires the AMD SMI C library to be installed and accessible during compilation.
23

24
## Basic Usage
25

26
### Go Interface
27

28
```go
29
package main
30

31
import (
32
    "fmt"
33
    "log"
34
)
35

36
func main() {
37
    // Initialize GPU monitoring
38
    if !goamdsmi.GO_gpu_init() {
39
        log.Fatal("Failed to initialize AMD SMI for GPU")
40
    }
41
    defer func() {
42
        if !goamdsmi.GO_gpu_shutdown() {
43
            log.Println("Warning: Failed to shutdown GPU monitoring")
44
        }
45
    }()
46

47
    // Get number of monitor devices
48
    numGPUs := goamdsmi.GO_gpu_num_monitor_devices()
49
    fmt.Printf("Found %d GPU(s)\n", numGPUs)
50

51
    if numGPUs > 0 {
52
        // Get device information for first GPU
53
        deviceName := goamdsmi.GO_gpu_dev_name_get(0)
54
        fmt.Printf("Device 0: %s\n", C.GoString(deviceName))
55
        
56
        // Get power consumption
57
        power := goamdsmi.GO_gpu_dev_power_get(0)
58
        fmt.Printf("Power: %d mW\n", power)
59
        
60
        // Get GPU utilization
61
        utilization := goamdsmi.GO_gpu_dev_gpu_busy_percent_get(0)
62
        fmt.Printf("GPU utilization: %d%%\n", utilization)
63
    }
64

65
    // Initialize CPU monitoring if needed
66
    if goamdsmi.GO_cpu_init() {
67
        defer func() {
68
            // CPU shutdown function may not be explicitly available
69
        }()
70
        
71
        numSockets := goamdsmi.GO_cpu_number_of_sockets_get()
72
        fmt.Printf("Found %d CPU socket(s)\n", numSockets)
73
    }
74
}
75
```
76

77
## Architecture
78

79
The Go AMD SMI package follows a CGO-based architecture:
80

81
- **CGO Interface**: Direct binding to AMD SMI C library using CGO
82
- **GPU Functions**: Functions prefixed with `GO_gpu_` for GPU monitoring and control
83
- **CPU Functions**: Functions prefixed with `GO_cpu_` for CPU monitoring (ESMI)
84
- **C Type Integration**: Returns C types (C.uint64_t, C.uint32_t, etc.) for direct hardware values
85
- **Driver Integration**: Communicates with amdgpu and HSMP drivers through C library
86
- **Simple Error Handling**: Boolean return values for init/shutdown, error values for data functions
87

88
The package provides a direct Go interface to AMD hardware without complex abstractions, optimized for performance monitoring applications.
89

90
## Capabilities
91

92
### Device Initialization and Discovery
93

94
Core system initialization and device enumeration for AMD GPUs and CPUs.
95

96
```go { .api }
97
func GO_gpu_init() bool
98
func GO_gpu_shutdown() bool
99
func GO_gpu_num_monitor_devices() uint
100
func GO_cpu_init() bool
101
func GO_cpu_number_of_sockets_get() uint
102
func GO_cpu_number_of_threads_get() uint
103
func GO_cpu_threads_per_core_get() uint
104
```
105

106
[Initialization and Discovery](./initialization.md)
107

108
### GPU Performance Monitoring
109

110
Real-time monitoring of GPU utilization, clock frequencies, memory usage, and performance metrics.
111

112
```go { .api }
113
func GO_gpu_dev_gpu_busy_percent_get(i int) C.uint32_t
114
func GO_gpu_dev_gpu_memory_busy_percent_get(i int) C.uint64_t
115
func GO_gpu_dev_gpu_clk_freq_get_sclk(i int) C.uint64_t
116
func GO_gpu_dev_gpu_clk_freq_get_mclk(i int) C.uint64_t
117
func GO_gpu_dev_perf_level_get(i int) C.uint32_t
118
func GO_gpu_dev_overdrive_level_get(i int) C.uint32_t
119
func GO_gpu_dev_mem_overdrive_level_get(i int) C.uint32_t
120
```
121

122
[GPU Performance Monitoring](./gpu-performance.md)
123

124
### Power and Thermal Management
125

126
Power consumption monitoring and thermal sensors for GPU devices.
127

128
```go { .api }
129
func GO_gpu_dev_power_get(i int) C.uint64_t
130
func GO_gpu_dev_power_cap_get(i int) C.uint64_t
131
func GO_gpu_dev_temp_metric_get(i int, sensor int, metric int) C.uint64_t
132
```
133

134
[Power and Thermal Management](./power-thermal.md)
135

136
### Device Information and Properties
137

138
Hardware identification and device properties for GPU devices.
139

140
```go { .api }
141
func GO_gpu_dev_name_get(i int) *C.char
142
func GO_gpu_dev_id_get(i int) C.uint16_t
143
func GO_gpu_dev_pci_id_get(i int) C.uint64_t
144
func GO_gpu_dev_vbios_version_get(i int) *C.char
145
func GO_gpu_dev_vendor_name_get(i int) *C.char
146
```
147

148
[Device Information](./device-info.md)
149

150
### Memory Management
151

152
GPU memory usage monitoring and memory statistics.
153

154
```go { .api }
155
func GO_gpu_dev_gpu_memory_usage_get(i int) C.uint64_t
156
func GO_gpu_dev_gpu_memory_total_get(i int) C.uint64_t
157
```
158

159
[Memory Management](./memory.md)
160

161
### Performance Control
162

163
GPU frequency ranges and performance level monitoring.
164

165
```go { .api }
166
func GO_gpu_od_volt_freq_range_min_get_sclk(i int) C.uint64_t
167
func GO_gpu_od_volt_freq_range_min_get_mclk(i int) C.uint64_t
168
func GO_gpu_od_volt_freq_range_max_get_sclk(i int) C.uint64_t
169
func GO_gpu_od_volt_freq_range_max_get_mclk(i int) C.uint64_t
170
```
171

172
[Performance Control](./performance-control.md)
173

174
### System Topology and RAS
175

176
*Note: Advanced topology and RAS features are not exposed in the Go interface. This capability is primarily available through the C++ API.*
177

178
[System Topology and RAS](./topology-ras.md)
179

180
### Events and Notifications
181

182
*Note: Event and notification features are not exposed in the Go interface. This capability is primarily available through the C++ API.*
183

184
[Events and Notifications](./events.md)
185

186
### CPU Management (ESMI)
187

188
CPU socket and core monitoring for energy, power, and frequency limits.
189

190
```go { .api }
191
func GO_cpu_core_energy_get(i int) C.uint64_t
192
func GO_cpu_core_boostlimit_get(i int) C.uint32_t
193
func GO_cpu_socket_energy_get(i int) C.uint64_t
194
func GO_cpu_socket_power_get(i int) C.uint32_t
195
func GO_cpu_socket_power_cap_get(i int) C.uint32_t
196
func GO_cpu_prochot_status_get(i int) C.uint32_t
197
```
198

199
[CPU Management](./cpu-management.md)
200

201
## Error Handling
202

203
The Go interface uses simple error handling patterns:
204

205
- **Initialization functions**: Return `bool` (true for success, false for failure)
206
- **Data functions**: Return error values for failed operations:
207
  - `0xFFFF` for uint16 functions on failure
208
  - `0xFFFFFFFF` for uint32 functions on failure  
209
  - `0xFFFFFFFFFFFFFFFF` for uint64 functions on failure
210
  - `"NA"` string for char* functions on failure
211

212
## Platform Support
213

214
- **Linux**: Bare metal and virtual machine guest support
215
- **GPU Support**: AMD GPUs with amdgpu driver
216
- **CPU Support**: AMD processors with HSMP support
217
- **CGO Requirements**: Requires AMD SMI C library and proper CGO compilation flags