tessl/pypi-amdsmi
Python library for monitoring and managing AMD GPUs and CPUs with programmatic hardware metrics access
cpu-monitoring.mddocs/reference/
CPU Monitoring
Monitoring functions for AMD CPU hardware metrics including power consumption, temperature, energy usage, frequency limits, and system information. These functions provide comprehensive visibility into CPU performance and health status.
Note: Most CPU monitoring functions require the ESMI (Embedded System Management Interface) library to be installed and supported by the CPU. Functions that don't require ESMI are noted in their descriptions.
Capabilities
CPU Handle Discovery
Get handles for CPU sockets and cores to use with monitoring functions.
def amdsmi_get_cpusocket_handles() -> List[processor_handle]:
"""
Get list of CPU socket handles.
Returns handles for all CPU sockets in the system. These handles are used
with other CPU monitoring functions.
Requires: ESMI library support
Parameters:
- None
Returns:
- List[processor_handle]: List of CPU socket handles
Raises:
- AmdSmiLibraryException: On query failure or if ESMI is not available
Example:
```python
import amdsmi
# Initialize for CPU monitoring
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
sockets = amdsmi.amdsmi_get_cpusocket_handles()
print(f"Found {len(sockets)} CPU socket(s)")
for i, socket in enumerate(sockets):
print(f"Socket {i}: {socket}")
finally:
amdsmi.amdsmi_shut_down()
```
"""def amdsmi_get_cpucore_handles(socket_handle: processor_handle) -> List[processor_handle]:
"""
Get list of CPU core handles for a specific socket.
Returns handles for all CPU cores within the specified socket. Core handles
are used for per-core monitoring functions.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- List[processor_handle]: List of CPU core handles for the socket
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
sockets = amdsmi.amdsmi_get_cpusocket_handles()
for socket in sockets:
cores = amdsmi.amdsmi_get_cpucore_handles(socket)
print(f"Socket {socket} has {len(cores)} cores")
finally:
amdsmi.amdsmi_shut_down()
```
"""def amdsmi_get_processor_info(processor_handle: processor_handle) -> str:
"""
Get processor information string.
Returns a descriptive string containing information about the processor
(CPU socket or core).
Requires: ESMI library support
Parameters:
- processor_handle: Handle for the target CPU socket or core
Returns:
- str: Processor information string
Raises:
- AmdSmiParameterException: If processor_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
sockets = amdsmi.amdsmi_get_cpusocket_handles()
for socket in sockets:
info = amdsmi.amdsmi_get_processor_info(socket)
print(f"Processor Info: {info}")
finally:
amdsmi.amdsmi_shut_down()
```
"""Power Monitoring
Monitor CPU socket power consumption and manage power limits.
def amdsmi_get_cpu_socket_power(socket_handle: processor_handle) -> str:
"""
Get current power consumption for a CPU socket.
Returns the current power draw for the specified CPU socket in milliwatts.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- str: Power consumption formatted as "{value} mW" (e.g., "45000 mW")
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
sockets = amdsmi.amdsmi_get_cpusocket_handles()
for socket in sockets:
power_str = amdsmi.amdsmi_get_cpu_socket_power(socket)
# Parse the value (e.g., "45000 mW")
power_mw = int(power_str.split()[0])
power_w = power_mw / 1000
print(f"Socket Power: {power_w:.2f} W")
finally:
amdsmi.amdsmi_shut_down()
```
"""def amdsmi_get_cpu_socket_power_cap(socket_handle: processor_handle) -> str:
"""
Get power cap (limit) for a CPU socket.
Returns the current power cap setting for the specified CPU socket. The power
cap limits the maximum power the socket can consume.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- str: Power cap formatted as "{value} mW" (e.g., "65000 mW")
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
cap_str = amdsmi.amdsmi_get_cpu_socket_power_cap(socket)
cap_mw = int(cap_str.split()[0])
cap_w = cap_mw / 1000
print(f"Power Cap: {cap_w:.2f} W")
finally:
amdsmi.amdsmi_shut_down()
```
"""def amdsmi_get_cpu_socket_power_cap_max(socket_handle: processor_handle) -> str:
"""
Get maximum power cap limit for a CPU socket.
Returns the maximum allowed power cap value for the specified CPU socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- str: Maximum power cap formatted as "{value} mW"
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
max_cap_str = amdsmi.amdsmi_get_cpu_socket_power_cap_max(socket)
max_cap_mw = int(max_cap_str.split()[0])
print(f"Maximum power cap: {max_cap_mw / 1000:.2f} W")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_set_cpu_socket_power_cap(socket_handle: processor_handle, power_cap: int) -> None:
"""
Set power cap (limit) for a CPU socket.
Sets the maximum power consumption limit for the specified CPU socket. This can
be used to constrain power usage for thermal or power budget reasons.
Requires: ESMI library support and appropriate privileges
Parameters:
- socket_handle: Handle for the target CPU socket
- power_cap (int): Power cap value in milliwatts (mW)
Returns:
- None
Raises:
- AmdSmiParameterException: If socket_handle or power_cap is invalid
- AmdSmiLibraryException: On operation failure (may require root privileges)
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Set power cap to 65W (65000 mW)
new_cap_mw = 65000
amdsmi.amdsmi_set_cpu_socket_power_cap(socket, new_cap_mw)
print(f"Power cap set to {new_cap_mw / 1000:.2f} W")
# Verify the new setting
cap_str = amdsmi.amdsmi_get_cpu_socket_power_cap(socket)
print(f"Current power cap: {cap_str}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_pwr_svi_telemetry_all_rails(socket_handle: processor_handle) -> Dict[str, int]:
"""
Get SVI-based telemetry for all power rails.
Returns power telemetry data from the Serial VID Interface (SVI) for all voltage
rails on the CPU socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- Dict[str, int]: Dictionary containing power rail telemetry with power values in milliwatts
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
telemetry = amdsmi.amdsmi_get_cpu_pwr_svi_telemetry_all_rails(socket)
print("Power Rail Telemetry:")
for rail, power in telemetry.items():
print(f" {rail}: {power / 1000:.2f} W")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_set_cpu_pwr_efficiency_mode(socket_handle: processor_handle, mode: int) -> None:
"""
Set power efficiency mode for a CPU socket.
Configures the power efficiency mode to optimize power consumption characteristics.
Requires: ESMI library support and appropriate privileges
Parameters:
- socket_handle: Handle for the target CPU socket
- mode (int): Power efficiency mode value
Returns:
- None
Raises:
- AmdSmiParameterException: If socket_handle or mode is invalid
- AmdSmiLibraryException: On operation failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
amdsmi.amdsmi_set_cpu_pwr_efficiency_mode(socket, 1)
print("Power efficiency mode set")
finally:
amdsmi.amdsmi_shut_down()
```
"""Temperature Monitoring
Monitor CPU socket temperature and PROCHOT status.
def amdsmi_get_cpu_socket_temperature(socket_handle: processor_handle) -> str:
"""
Get temperature for a CPU socket.
Returns the current temperature reading for the specified CPU socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- str: Temperature formatted as "{value} Degrees C" (e.g., "45 Degrees C")
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
sockets = amdsmi.amdsmi_get_cpusocket_handles()
for i, socket in enumerate(sockets):
temp_str = amdsmi.amdsmi_get_cpu_socket_temperature(socket)
# Parse the value (e.g., "45 Degrees C")
temp_c = int(temp_str.split()[0])
print(f"Socket {i} Temperature: {temp_c}°C")
# Warning check
if temp_c > 80:
print(f" WARNING: High temperature!")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_prochot_status(socket_handle: processor_handle) -> int:
"""
Get PROCHOT status for a CPU socket.
Returns the current PROCHOT (processor hot) status, which indicates thermal
throttling conditions. PROCHOT is asserted when the processor reaches thermal limits.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- int: PROCHOT status value (0 = not asserted, non-zero = asserted)
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
prochot = amdsmi.amdsmi_get_cpu_prochot_status(socket)
if prochot:
print("WARNING: PROCHOT asserted - CPU is thermal throttling!")
else:
print("CPU temperature within normal range")
finally:
amdsmi.amdsmi_shut_down()
```
"""Energy Monitoring
Monitor energy consumption for CPU sockets and cores.
def amdsmi_get_cpu_core_energy(core_handle: processor_handle) -> str:
"""
Get energy consumption for a CPU core.
Returns the accumulated energy consumption for the specified CPU core. This
counter accumulates over time and can be used to calculate energy usage over
intervals by taking multiple readings.
Requires: ESMI library support
Parameters:
- core_handle: Handle for the target CPU core
Returns:
- str: Energy consumption formatted as "{value} J" (joules)
Raises:
- AmdSmiParameterException: If core_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
import time
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
cores = amdsmi.amdsmi_get_cpucore_handles(socket)
core = cores[0]
# Take initial reading
energy1_str = amdsmi.amdsmi_get_cpu_core_energy(core)
energy1_j = float(energy1_str.split()[0])
time.sleep(1)
# Take second reading
energy2_str = amdsmi.amdsmi_get_cpu_core_energy(core)
energy2_j = float(energy2_str.split()[0])
# Calculate energy consumed in 1 second
energy_consumed = energy2_j - energy1_j
print(f"Core energy consumed: {energy_consumed:.4f} J")
print(f"Core average power: {energy_consumed:.4f} W")
finally:
amdsmi.amdsmi_shut_down()
```
"""def amdsmi_get_cpu_socket_energy(socket_handle: processor_handle) -> str:
"""
Get energy consumption for a CPU socket.
Returns the accumulated energy consumption for the specified CPU socket,
representing the total energy used by all cores and components in the socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- str: Energy consumption formatted as "{value} J" (joules)
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
import time
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Monitor socket energy over 5 seconds
energy1_str = amdsmi.amdsmi_get_cpu_socket_energy(socket)
energy1_j = float(energy1_str.split()[0])
time.sleep(5)
energy2_str = amdsmi.amdsmi_get_cpu_socket_energy(socket)
energy2_j = float(energy2_str.split()[0])
# Calculate consumption
energy_consumed = energy2_j - energy1_j
avg_power = energy_consumed / 5.0
print(f"Socket energy consumed: {energy_consumed:.2f} J over 5 seconds")
print(f"Average socket power: {avg_power:.2f} W")
finally:
amdsmi.amdsmi_shut_down()
```
"""Frequency Management
Monitor and control CPU core and socket frequency limits.
def amdsmi_get_cpu_fclk_mclk(socket_handle: processor_handle) -> Dict[str, str]:
"""
Get fabric clock (FCLK) and memory clock (MCLK) frequencies.
Returns the current FCLK and MCLK frequencies for the CPU socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- Dict[str, str]: Dictionary with 'fclk' and 'mclk' keys, values formatted as "{value} MHz"
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
clocks = amdsmi.amdsmi_get_cpu_fclk_mclk(socket)
print(f"Fabric Clock: {clocks['fclk']}")
print(f"Memory Clock: {clocks['mclk']}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_cclk_limit(socket_handle: processor_handle) -> str:
"""
Get core clock (CCLK) frequency limit.
Returns the current core clock frequency limit for the CPU socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- str: Core clock limit formatted as "{value} MHz"
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
cclk = amdsmi.amdsmi_get_cpu_cclk_limit(socket)
print(f"Core Clock Limit: {cclk}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_socket_current_active_freq_limit(socket_handle: processor_handle) -> Dict[str, str]:
"""
Get currently active frequency limit and source.
Returns the current active frequency limit for the socket along with information
about what is causing the limit (thermal, power, etc.).
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- Dict[str, str]: Dictionary with 'freq' and 'freq_src' keys
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
freq_info = amdsmi.amdsmi_get_cpu_socket_current_active_freq_limit(socket)
print(f"Active Frequency Limit: {freq_info['freq']}")
print(f"Limit Source: {freq_info['freq_src']}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_socket_freq_range(socket_handle: processor_handle) -> Dict[str, str]:
"""
Get frequency range for a CPU socket.
Returns the minimum and maximum frequency range for the socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- Dict[str, str]: Dictionary with 'max_socket_freq' and 'min_socket_freq' keys
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
freq_range = amdsmi.amdsmi_get_cpu_socket_freq_range(socket)
print(f"Max Frequency: {freq_range['max_socket_freq']}")
print(f"Min Frequency: {freq_range['min_socket_freq']}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_core_current_freq_limit(core_handle: processor_handle) -> str:
"""
Get current frequency limit for a CPU core.
Returns the current frequency limit for the specified core.
Requires: ESMI library support
Parameters:
- core_handle: Handle for the target CPU core
Returns:
- str: Frequency limit formatted as "{value} MHz"
Raises:
- AmdSmiParameterException: If core_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
cores = amdsmi.amdsmi_get_cpucore_handles(socket)
core = cores[0]
freq_limit = amdsmi.amdsmi_get_cpu_core_current_freq_limit(core)
print(f"Core Frequency Limit: {freq_limit}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_core_boostlimit(core_handle: processor_handle) -> str:
"""
Get boost frequency limit for a CPU core.
Returns the maximum boost frequency the specified CPU core can reach. This
represents the highest clock speed the core can achieve under boost conditions.
Requires: ESMI library support
Parameters:
- core_handle: Handle for the target CPU core
Returns:
- str: Boost limit formatted as "{value} MHz" (megahertz)
Raises:
- AmdSmiParameterException: If core_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
cores = amdsmi.amdsmi_get_cpucore_handles(socket)
print("Core Boost Limits:")
for i, core in enumerate(cores):
boost_str = amdsmi.amdsmi_get_cpu_core_boostlimit(core)
boost_mhz = int(boost_str.split()[0])
boost_ghz = boost_mhz / 1000
print(f" Core {i}: {boost_ghz:.2f} GHz")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_set_cpu_core_boostlimit(
core_handle: processor_handle,
boostlimit: int
) -> None:
"""
Set boost frequency limit for a CPU core.
Configures the maximum boost frequency limit for the specified CPU core.
Requires: ESMI library support and appropriate privileges
Parameters:
- core_handle: Handle for the target CPU core
- boostlimit: Boost frequency limit in MHz
Raises:
- AmdSmiParameterException: If core_handle or boostlimit are invalid
- AmdSmiLibraryException: On configuration failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
cores = amdsmi.amdsmi_get_cpucore_handles(socket)
# Set core boost limit to 4000 MHz
amdsmi.amdsmi_set_cpu_core_boostlimit(cores[0], 4000)
print("Core boost limit set to 4000 MHz")
finally:
amdsmi.amdsmi_shut_down()
```
"""HSMP Metrics Table
Access comprehensive CPU metrics via the HSMP (Host System Management Port) interface.
def amdsmi_get_hsmp_metrics_table(socket_handle: processor_handle) -> Dict[str, Any]:
"""
Get HSMP metrics table for a CPU socket.
Returns a comprehensive dictionary of CPU metrics from the HSMP metrics table.
This provides detailed information about power, temperatures, frequencies, and
other performance metrics in a single query.
The metrics table contains numerous fields including accumulator values, power
consumption, clock frequencies, temperature readings, C-state residency, and
various performance metrics. Available fields depend on the CPU model and HSMP
version.
Requires: ESMI library support with HSMP protocol
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- dict: Dictionary containing HSMP metrics including:
- accumulation_counter (int): Metrics accumulation counter
- max_socket_temperature (float): Maximum socket temperature in °C
- max_vr_temperature (float): Maximum voltage regulator temperature in °C
- max_hbm_temperature (float): Maximum HBM temperature in °C
- socket_power_limit (float): Socket power limit in watts
- max_socket_power_limit (float): Maximum socket power limit in watts
- socket_power (float): Current socket power in watts
- timestamp (int): Timestamp of metrics
- socket_energy_acc (float): Accumulated socket energy
- ccd_energy_acc (float): Accumulated CCD energy
- xcd_energy_acc (float): Accumulated XCD energy
- aid_energy_acc (float): Accumulated AID energy
- hbm_energy_acc (float): Accumulated HBM energy
- cclk_frequency_limit (int): Core clock frequency limit in MHz
- gfxclk_frequency_limit (int): Graphics clock frequency limit in MHz
- fclk_frequency (int): Fabric clock frequency in MHz
- uclk_frequency (int): Memory clock frequency in MHz
- socclk_frequency (List[int]): SoC clock frequencies in MHz
- vclk_frequency (List[int]): Video clock frequencies in MHz
- dclk_frequency (List[int]): Display clock frequencies in MHz
- lclk_frequency (List[int]): Link clock frequencies in MHz
- gfxclk_frequency_acc (List[int]): Graphics clock frequency accumulators
- cclk_frequency_acc (int): Core clock frequency accumulator
- max_cclk_frequency (int): Maximum core clock frequency in MHz
- min_cclk_frequency (int): Minimum core clock frequency in MHz
- max_gfxclk_frequency (int): Maximum graphics clock frequency in MHz
- min_gfxclk_frequency (int): Minimum graphics clock frequency in MHz
- fclk_frequency_table (List[int]): Fabric clock frequency table in MHz
- uclk_frequency_table (List[int]): Memory clock frequency table in MHz
- socclk_frequency_table (List[int]): SoC clock frequency table in MHz
- vclk_frequency_table (List[int]): Video clock frequency table in MHz
- dclk_frequency_table (List[int]): Display clock frequency table in MHz
- lclk_frequency_table (List[int]): Link clock frequency table in MHz
- max_lclk_dpm_range (int): Maximum LCLK DPM range
- min_lclk_dpm_range (int): Minimum LCLK DPM range
- xgmi_width (int): XGMI link width
- xgmi_bitrate (int): XGMI bitrate
- xgmi_read_bandwidth_acc (List[int]): XGMI read bandwidth accumulators
- xgmi_write_bandwidth_acc (List[int]): XGMI write bandwidth accumulators
- socket_c0_residency (int): Socket C0 residency percentage
- socket_gfx_busy (int): Socket graphics busy percentage
- dram_bandwidth_utilization (int): DRAM bandwidth utilization
- socket_c0_residency_acc (int): Socket C0 residency accumulator
- cpu_set_limits (int): CPU set limits
- max_cpu_set_limits (int): Maximum CPU set limits
- cpu_cur_temp (int): Current CPU temperature
- cpu_cur_power (int): Current CPU power
- cpu_cur_freqlimit (int): Current CPU frequency limit
- cpu_sock_freqlimit (int): Socket frequency limit
- prochot_residency_acc (int): PROCHOT residency accumulator
- ppt_residency_acc (int): PPT residency accumulator
- socket_thm_residency_acc (int): Socket thermal residency accumulator
- vr_thm_residency_acc (int): VR thermal residency accumulator
- hbm_thm_residency_acc (int): HBM thermal residency accumulator
- spare (int): Spare field
- Note: Not all fields are available on all CPU models
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
metrics = amdsmi.amdsmi_get_hsmp_metrics_table(socket)
print("HSMP Metrics Table:")
print(f" Max Socket Temperature: {metrics['max_socket_temperature']:.1f}°C")
print(f" Socket Power: {metrics['socket_power']:.2f} W")
print(f" Socket Power Limit: {metrics['socket_power_limit']:.2f} W")
print(f" Core Clock Limit: {metrics['cclk_frequency_limit']} MHz")
print(f" Fabric Clock: {metrics['fclk_frequency']} MHz")
print(f" Memory Clock: {metrics['uclk_frequency']} MHz")
print(f" Socket C0 Residency: {metrics['socket_c0_residency']}%")
finally:
amdsmi.amdsmi_shut_down()
```
"""Bandwidth and Link Monitoring
Monitor DDR bandwidth, I/O bandwidth, and XGMI link metrics.
def amdsmi_get_cpu_ddr_bw(socket_handle: processor_handle) -> Dict[str, str]:
"""
Get DDR bandwidth metrics for a CPU socket.
Returns DDR bandwidth utilization including maximum bandwidth, utilized bandwidth,
and utilization percentage.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- Dict[str, str]: Dictionary containing:
- 'ddr_bw_max_bw' (str): Maximum DDR bandwidth formatted as "{value} Gbps"
- 'ddr_bw_utilized_bw' (str): Utilized DDR bandwidth formatted as "{value} Gbps"
- 'ddr_bw_utilized_pct' (str): Utilization percentage formatted as "{value} %"
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
ddr_bw = amdsmi.amdsmi_get_cpu_ddr_bw(socket)
print(f"DDR Bandwidth:")
print(f" Max: {ddr_bw['ddr_bw_max_bw']}")
print(f" Utilized: {ddr_bw['ddr_bw_utilized_bw']}")
print(f" Utilization: {ddr_bw['ddr_bw_utilized_pct']}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_current_io_bandwidth(
socket_handle: processor_handle,
encoding: int,
link_name: str
) -> str:
"""
Get current I/O bandwidth for a specific link.
Returns the current I/O bandwidth utilization for the specified link on the CPU socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
- encoding (int): Bandwidth encoding type
- link_name (str): Name of the I/O link to query
Returns:
- str: I/O bandwidth formatted as "{value} Mbps"
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Query I/O bandwidth for a specific link
io_bw = amdsmi.amdsmi_get_cpu_current_io_bandwidth(socket, 0, "P2")
print(f"I/O Bandwidth: {io_bw}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_current_xgmi_bw(
socket_handle: processor_handle,
encoding: int,
link_name: str
) -> str:
"""
Get current XGMI bandwidth for a specific link.
Returns the current XGMI (AMD Infinity Fabric) bandwidth utilization for the
specified link on the CPU socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
- encoding (int): Bandwidth encoding type
- link_name (str): Name of the XGMI link to query
Returns:
- str: XGMI bandwidth formatted as "{value} Mbps"
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Query XGMI bandwidth
xgmi_bw = amdsmi.amdsmi_get_cpu_current_xgmi_bw(socket, 0, "P2")
print(f"XGMI Bandwidth: {xgmi_bw}")
finally:
amdsmi.amdsmi_shut_down()
```
"""DIMM Information
Query DIMM (memory module) temperature, power consumption, and thermal sensors.
def amdsmi_get_cpu_dimm_temp_range_and_refresh_rate(
socket_handle: processor_handle,
dimm_addr: int
) -> Dict[str, int]:
"""
Get DIMM temperature range and refresh rate.
Returns the temperature range and refresh rate for the specified DIMM on the CPU socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
- dimm_addr (int): DIMM address identifier
Returns:
- Dict[str, int]: Dictionary containing:
- 'dimm_temperature_range' (int): Temperature range value
- 'dimm_refresh_rate' (int): Refresh rate value
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Query DIMM 0 temperature range and refresh rate
dimm_info = amdsmi.amdsmi_get_cpu_dimm_temp_range_and_refresh_rate(socket, 0)
print(f"DIMM 0 Temperature Range: {dimm_info['dimm_temperature_range']}")
print(f"DIMM 0 Refresh Rate: {dimm_info['dimm_refresh_rate']}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_dimm_power_consumption(
socket_handle: processor_handle,
dimm_addr: int
) -> Dict[str, str]:
"""
Get DIMM power consumption.
Returns power consumption and update rate for the specified DIMM.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
- dimm_addr (int): DIMM address identifier
Returns:
- Dict[str, str]: Dictionary containing:
- 'dimm_power_consumed' (str): Power consumption formatted as "{value} mW"
- 'dimm_power_update_rate' (str): Update rate formatted as "{value} ms"
- 'dimm_dimm_addr' (int): DIMM address
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Query DIMM 0 power consumption
dimm_power = amdsmi.amdsmi_get_cpu_dimm_power_consumption(socket, 0)
print(f"DIMM Power: {dimm_power['dimm_power_consumed']}")
print(f"Update Rate: {dimm_power['dimm_power_update_rate']}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_dimm_thermal_sensor(
socket_handle: processor_handle,
dimm_addr: int
) -> Dict[str, str]:
"""
Get DIMM thermal sensor reading.
Returns thermal sensor value, update rate, and temperature for the specified DIMM.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
- dimm_addr (int): DIMM address identifier
Returns:
- Dict[str, str]: Dictionary containing:
- 'dimm_thermal_sensor_value' (int): Thermal sensor value
- 'dimm_thermal_update_rate' (str): Update rate formatted as "{value} ms"
- 'dimm_thermal_dimm_addr' (int): DIMM address
- 'dimm_thermal_temperature' (str): Temperature formatted as "{value} Degrees C"
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Query DIMM 0 thermal sensor
dimm_thermal = amdsmi.amdsmi_get_cpu_dimm_thermal_sensor(socket, 0)
print(f"DIMM Temperature: {dimm_thermal['dimm_thermal_temperature']}")
print(f"Sensor Value: {dimm_thermal['dimm_thermal_sensor_value']}")
finally:
amdsmi.amdsmi_shut_down()
```
"""Advanced CPU Control
Configure advanced CPU settings including boost limits, link widths, DPM levels, and APB modes.
def amdsmi_set_cpu_socket_boostlimit(
socket_handle: processor_handle,
boostlimit: int
) -> None:
"""
Set boost frequency limit for a CPU socket.
Configures the maximum boost frequency limit for all cores in the specified socket.
Requires: ESMI library support and appropriate privileges
Parameters:
- socket_handle: Handle for the target CPU socket
- boostlimit (int): Boost limit value in MHz
Returns:
- None
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On operation failure (may require root privileges)
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Set socket boost limit to 4000 MHz
amdsmi.amdsmi_set_cpu_socket_boostlimit(socket, 4000)
print("Socket boost limit set to 4000 MHz")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_set_cpu_xgmi_width(
socket_handle: processor_handle,
min_width: int,
max_width: int
) -> None:
"""
Set XGMI link width range for a CPU socket.
Configures the minimum and maximum XGMI link width for the socket.
Requires: ESMI library support and appropriate privileges
Parameters:
- socket_handle: Handle for the target CPU socket
- min_width (int): Minimum XGMI link width
- max_width (int): Maximum XGMI link width
Returns:
- None
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On operation failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Set XGMI width range
amdsmi.amdsmi_set_cpu_xgmi_width(socket, 8, 16)
print("XGMI width range set to 8-16")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_set_cpu_gmi3_link_width_range(
socket_handle: processor_handle,
min_link_width: int,
max_link_width: int
) -> None:
"""
Set GMI3 link width range for a CPU socket.
Configures the minimum and maximum GMI3 (Global Memory Interconnect 3) link width.
Requires: ESMI library support and appropriate privileges
Parameters:
- socket_handle: Handle for the target CPU socket
- min_link_width (int): Minimum GMI3 link width
- max_link_width (int): Maximum GMI3 link width
Returns:
- None
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On operation failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Set GMI3 link width range
amdsmi.amdsmi_set_cpu_gmi3_link_width_range(socket, 8, 16)
print("GMI3 link width range set to 8-16")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_cpu_apb_enable(socket_handle: processor_handle) -> None:
"""
Enable APB (All-core Performance Boost) for a CPU socket.
Enables the APB feature which allows all cores to boost simultaneously.
Requires: ESMI library support and appropriate privileges
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- None
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On operation failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Enable APB
amdsmi.amdsmi_cpu_apb_enable(socket)
print("APB enabled")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_cpu_apb_disable(
socket_handle: processor_handle,
pstate: int
) -> None:
"""
Disable APB (All-core Performance Boost) for a CPU socket.
Disables the APB feature and sets the specified P-state.
Requires: ESMI library support and appropriate privileges
Parameters:
- socket_handle: Handle for the target CPU socket
- pstate (int): P-state value to set
Returns:
- None
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On operation failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Disable APB with P-state 0
amdsmi.amdsmi_cpu_apb_disable(socket, 0)
print("APB disabled")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_set_cpu_socket_lclk_dpm_level(
socket_handle: processor_handle,
nbio_id: int,
min_val: int,
max_val: int
) -> None:
"""
Set LCLK DPM (Dynamic Power Management) level range for a CPU socket.
Configures the minimum and maximum LCLK DPM levels for the specified NBIO.
Requires: ESMI library support and appropriate privileges
Parameters:
- socket_handle: Handle for the target CPU socket
- nbio_id (int): NBIO (North Bridge I/O) identifier
- min_val (int): Minimum DPM level
- max_val (int): Maximum DPM level
Returns:
- None
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On operation failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Set LCLK DPM level range for NBIO 0
amdsmi.amdsmi_set_cpu_socket_lclk_dpm_level(socket, 0, 0, 3)
print("LCLK DPM level range set to 0-3")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_socket_lclk_dpm_level(
socket_handle: processor_handle,
nbio_id: int
) -> Dict[str, int]:
"""
Get LCLK DPM (Dynamic Power Management) level range for a CPU socket.
Returns the current minimum and maximum LCLK DPM levels for the specified NBIO.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
- nbio_id (int): NBIO (North Bridge I/O) identifier
Returns:
- Dict[str, int]: Dictionary containing:
- 'nbio_max_dpm_level' (int): Maximum DPM level
- 'nbio_min_dpm_level' (int): Minimum DPM level
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Get LCLK DPM level for NBIO 0
dpm_level = amdsmi.amdsmi_get_cpu_socket_lclk_dpm_level(socket, 0)
print(f"DPM Level Range: {dpm_level['nbio_min_dpm_level']}-{dpm_level['nbio_max_dpm_level']}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_set_cpu_pcie_link_rate(
socket_handle: processor_handle,
rate_ctrl: int
) -> str:
"""
Set PCIe link rate control for a CPU socket.
Configures the PCIe link rate control setting and returns the previous mode.
Requires: ESMI library support and appropriate privileges
Parameters:
- socket_handle: Handle for the target CPU socket
- rate_ctrl (int): PCIe rate control value
Returns:
- str: Previous rate control mode value
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On operation failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Set PCIe link rate control
prev_mode = amdsmi.amdsmi_set_cpu_pcie_link_rate(socket, 1)
print(f"PCIe link rate set, previous mode: {prev_mode}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_set_cpu_df_pstate_range(
socket_handle: processor_handle,
max_pstate: int,
min_pstate: int
) -> None:
"""
Set data fabric P-state range for a CPU socket.
Configures the minimum and maximum P-state values for the data fabric.
Requires: ESMI library support and appropriate privileges
Parameters:
- socket_handle: Handle for the target CPU socket
- max_pstate (int): Maximum P-state value
- min_pstate (int): Minimum P-state value
Returns:
- None
Raises:
- AmdSmiParameterException: If parameters are invalid
- AmdSmiLibraryException: On operation failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Set DF P-state range
amdsmi.amdsmi_set_cpu_df_pstate_range(socket, 3, 0)
print("Data fabric P-state range set to 0-3")
finally:
amdsmi.amdsmi_shut_down()
```
"""CPU Residency Monitoring
Monitor C-state residency for power management analysis.
def amdsmi_get_cpu_socket_c0_residency(socket_handle: processor_handle) -> str:
"""
Get C0 residency percentage for a CPU socket.
Returns the percentage of time the CPU socket has spent in C0 (active) state.
C0 residency indicates how much time the CPU is actively executing instructions
versus being in power-saving states.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- str: C0 residency formatted as "{value} %"
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Get C0 residency
c0_residency = amdsmi.amdsmi_get_cpu_socket_c0_residency(socket)
print(f"C0 Residency: {c0_residency}")
# High C0 residency indicates heavy CPU utilization
residency_value = float(c0_residency.split()[0])
if residency_value > 80:
print("CPU is heavily utilized")
elif residency_value < 20:
print("CPU is mostly idle")
finally:
amdsmi.amdsmi_shut_down()
```
"""CPU Information
Query CPU family, model, and system topology information.
def amdsmi_get_cpu_hsmp_proto_ver(socket_handle: processor_handle) -> int:
"""
Get HSMP (Host System Management Port) protocol version.
Returns the HSMP protocol version supported by the CPU socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- int: HSMP protocol version number
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
proto_ver = amdsmi.amdsmi_get_cpu_hsmp_proto_ver(socket)
print(f"HSMP Protocol Version: {proto_ver}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_smu_fw_version(socket_handle: processor_handle) -> Dict[str, int]:
"""
Get SMU (System Management Unit) firmware version.
Returns the SMU firmware version including major, minor, and debug version numbers.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- Dict[str, int]: Dictionary containing:
- 'smu_fw_debug_ver_num' (int): Debug version number
- 'smu_fw_minor_ver_num' (int): Minor version number
- 'smu_fw_major_ver_num' (int): Major version number
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
smu_fw = amdsmi.amdsmi_get_cpu_smu_fw_version(socket)
print(f"SMU FW Version: {smu_fw['smu_fw_major_ver_num']}."
f"{smu_fw['smu_fw_minor_ver_num']}."
f"{smu_fw['smu_fw_debug_ver_num']}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_hsmp_driver_version(socket_handle: processor_handle) -> Dict[str, int]:
"""
Get HSMP driver version.
Returns the HSMP driver version including major and minor version numbers.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- Dict[str, int]: Dictionary containing:
- 'hsmp_driver_major_ver_num' (int): Major version number
- 'hsmp_driver_minor_ver_num' (int): Minor version number
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
driver_ver = amdsmi.amdsmi_get_cpu_hsmp_driver_version(socket)
print(f"HSMP Driver Version: {driver_ver['hsmp_driver_major_ver_num']}."
f"{driver_ver['hsmp_driver_minor_ver_num']}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_threads_per_core() -> int:
"""
Get the number of threads per CPU core.
Returns the number of hardware threads (SMT/hyperthreading) per physical core.
For example, returns 2 for CPUs with 2-way SMT.
Does not require ESMI library support.
Parameters:
- None
Returns:
- int: Number of threads per core
Raises:
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
threads_per_core = amdsmi.amdsmi_get_threads_per_core()
print(f"Threads per core: {threads_per_core}")
if threads_per_core == 2:
print("SMT (Simultaneous Multithreading) is enabled")
elif threads_per_core == 1:
print("SMT is disabled or not supported")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_hsmp_metrics_table_version(socket_handle: processor_handle) -> int:
"""
Get HSMP metrics table version.
Returns the version number of the HSMP metrics table format used by the CPU socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- int: HSMP metrics table version number
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
metrics_ver = amdsmi.amdsmi_get_hsmp_metrics_table_version(socket)
print(f"HSMP Metrics Table Version: {metrics_ver}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_first_online_core_on_cpu_socket(socket_handle: processor_handle) -> int:
"""
Get the first online core index for a CPU socket.
Returns the index of the first online (active) core on the specified CPU socket.
Useful for identifying which core to use for per-socket operations.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- int: Index of the first online core
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
first_core = amdsmi.amdsmi_first_online_core_on_cpu_socket(socket)
print(f"First online core on socket: {first_core}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_model_name(socket_handle: processor_handle) -> str:
"""
Get CPU model name string.
Returns the human-readable CPU model name for the specified socket.
Requires: ESMI library support
Parameters:
- socket_handle: Handle for the target CPU socket
Returns:
- str: CPU model name string (e.g., "AMD EPYC 7763 64-Core Processor")
Raises:
- AmdSmiParameterException: If socket_handle is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
model_name = amdsmi.amdsmi_get_cpu_model_name(socket)
print(f"CPU Model: {model_name}")
finally:
amdsmi.amdsmi_shut_down()
```
"""
def amdsmi_get_cpu_family() -> int:
"""
Get CPU family ID.
Returns the AMD CPU family identifier, which indicates the processor architecture
generation.
Requires: ESMI library support
Parameters:
- None
Returns:
- int: CPU family ID (e.g., 25 for Zen 3, 26 for Zen 4)
Raises:
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
family = amdsmi.amdsmi_get_cpu_family()
print(f"CPU Family: {family} (0x{family:x})")
# Identify architecture
if family == 25:
print("Architecture: Zen 3")
elif family == 26:
print("Architecture: Zen 4")
finally:
amdsmi.amdsmi_shut_down()
```
"""def amdsmi_get_cpu_model() -> int:
"""
Get CPU model ID.
Returns the AMD CPU model identifier, which provides more specific information
about the processor variant within a family.
Requires: ESMI library support
Parameters:
- None
Returns:
- int: CPU model ID
Raises:
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
family = amdsmi.amdsmi_get_cpu_family()
model = amdsmi.amdsmi_get_cpu_model()
print(f"CPU Family: {family}, Model: {model}")
print(f"Full ID: Family 0x{family:x}, Model 0x{model:x}")
finally:
amdsmi.amdsmi_shut_down()
```
"""def amdsmi_get_cpu_socket_count() -> int:
"""
Get number of CPU sockets in the system.
Returns the total number of physical CPU sockets present in the system.
Does not require ESMI library support.
Parameters:
- None
Returns:
- int: Number of CPU sockets
Raises:
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket_count = amdsmi.amdsmi_get_cpu_socket_count()
print(f"System has {socket_count} CPU socket(s)")
finally:
amdsmi.amdsmi_shut_down()
```
"""def amdsmi_get_cpu_cores_per_socket(socket_index: int) -> Dict[str, int]:
"""
Get number of CPU cores per socket.
Returns information about the number of cores in a specific socket.
Does not require ESMI library support.
Parameters:
- socket_index (int): Index of the socket to query (0-based)
Returns:
- dict: Dictionary containing:
- socket_id (int): Socket identifier
- cores_per_socket (int): Number of cores in the socket
Raises:
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket_count = amdsmi.amdsmi_get_cpu_socket_count()
for i in range(socket_count):
info = amdsmi.amdsmi_get_cpu_cores_per_socket(i)
print(f"Socket {info['socket_id']}: {info['cores_per_socket']} cores")
finally:
amdsmi.amdsmi_shut_down()
```
"""def amdsmi_get_cpu_affinity_with_scope(
processor_handle: processor_handle,
scope: AmdSmiAffinityScope
) -> List[int]:
"""
Get CPU affinity for a processor with specified scope.
Returns a list of logical CPU IDs that represent the affinity mask for the
specified processor handle at the given scope level (NUMA node or socket).
Does not require ESMI library support.
Parameters:
- processor_handle: Handle for the target processor (GPU or CPU)
- scope (AmdSmiAffinityScope): Affinity scope level:
- AmdSmiAffinityScope.NUMA_SCOPE: NUMA node scope
- AmdSmiAffinityScope.SOCKET_SCOPE: Socket scope
Returns:
- List[int]: List of logical CPU IDs in the affinity set
Raises:
- AmdSmiParameterException: If processor_handle or scope is invalid
- AmdSmiLibraryException: On query failure
Example:
```python
import amdsmi
from amdsmi import AmdSmiAffinityScope
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
sockets = amdsmi.amdsmi_get_cpusocket_handles()
for socket in sockets:
# Get NUMA-scoped affinity
numa_cpus = amdsmi.amdsmi_get_cpu_affinity_with_scope(
socket, AmdSmiAffinityScope.NUMA_SCOPE
)
print(f"Socket NUMA affinity: CPUs {numa_cpus}")
# Get socket-scoped affinity
socket_cpus = amdsmi.amdsmi_get_cpu_affinity_with_scope(
socket, AmdSmiAffinityScope.SOCKET_SCOPE
)
print(f"Socket affinity: CPUs {socket_cpus}")
finally:
amdsmi.amdsmi_shut_down()
```
"""Usage Examples
Basic CPU Monitoring
Monitor power, temperature, and energy for all CPU sockets:
import amdsmi
import time
# Initialize for CPU monitoring
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
sockets = amdsmi.amdsmi_get_cpusocket_handles()
print(f"Found {len(sockets)} CPU socket(s)\n")
for i, socket in enumerate(sockets):
print(f"=== Socket {i} ===")
# Power
power_str = amdsmi.amdsmi_get_cpu_socket_power(socket)
power_mw = int(power_str.split()[0])
power_w = power_mw / 1000
print(f"Power: {power_w:.2f} W")
# Power cap
cap_str = amdsmi.amdsmi_get_cpu_socket_power_cap(socket)
cap_mw = int(cap_str.split()[0])
cap_w = cap_mw / 1000
print(f"Power Cap: {cap_w:.2f} W")
# Temperature
temp_str = amdsmi.amdsmi_get_cpu_socket_temperature(socket)
temp_c = int(temp_str.split()[0])
print(f"Temperature: {temp_c}°C")
# Socket energy
energy_str = amdsmi.amdsmi_get_cpu_socket_energy(socket)
energy_j = float(energy_str.split()[0])
print(f"Energy Counter: {energy_j:.2f} J\n")
finally:
amdsmi.amdsmi_shut_down()CPU Core Frequency Monitoring
Monitor boost limits for all cores:
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
sockets = amdsmi.amdsmi_get_cpusocket_handles()
for sock_idx, socket in enumerate(sockets):
print(f"\n=== Socket {sock_idx} ===")
cores = amdsmi.amdsmi_get_cpucore_handles(socket)
print(f"Cores: {len(cores)}")
print("\nCore Boost Limits:")
for core_idx, core in enumerate(cores):
boost_str = amdsmi.amdsmi_get_cpu_core_boostlimit(core)
boost_mhz = int(boost_str.split()[0])
boost_ghz = boost_mhz / 1000
print(f" Core {core_idx:2d}: {boost_ghz:.2f} GHz")
finally:
amdsmi.amdsmi_shut_down()Energy Consumption Tracking
Calculate power consumption over time:
import amdsmi
import time
def measure_socket_power(socket, duration=5):
"""Measure average power consumption over time."""
# Initial reading
energy1_str = amdsmi.amdsmi_get_cpu_socket_energy(socket)
energy1_j = float(energy1_str.split()[0])
time1 = time.time()
# Wait
time.sleep(duration)
# Final reading
energy2_str = amdsmi.amdsmi_get_cpu_socket_energy(socket)
energy2_j = float(energy2_str.split()[0])
time2 = time.time()
# Calculate
energy_consumed = energy2_j - energy1_j
actual_duration = time2 - time1
avg_power = energy_consumed / actual_duration
return {
'energy_j': energy_consumed,
'duration_s': actual_duration,
'avg_power_w': avg_power
}
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
print("Measuring power consumption for 5 seconds...")
result = measure_socket_power(socket, 5)
print(f"Energy consumed: {result['energy_j']:.2f} J")
print(f"Duration: {result['duration_s']:.2f} s")
print(f"Average power: {result['avg_power_w']:.2f} W")
finally:
amdsmi.amdsmi_shut_down()HSMP Metrics Dashboard
Display comprehensive CPU metrics:
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Get comprehensive metrics
metrics = amdsmi.amdsmi_get_hsmp_metrics_table(socket)
print("=== HSMP Metrics ===\n")
# Temperature
print("Temperature:")
print(f" Max Socket: {metrics['max_socket_temperature']:.1f}°C")
print(f" Max VR: {metrics['max_vr_temperature']:.1f}°C")
print(f" Max HBM: {metrics['max_hbm_temperature']:.1f}°C")
# Power
print("\nPower:")
print(f" Current: {metrics['socket_power']:.2f} W")
print(f" Limit: {metrics['socket_power_limit']:.2f} W")
print(f" Max Limit: {metrics['max_socket_power_limit']:.2f} W")
# Frequencies
print("\nFrequencies:")
print(f" Core Clock Limit: {metrics['cclk_frequency_limit']} MHz")
print(f" GFX Clock Limit: {metrics['gfx_frequency_limit']} MHz")
print(f" Fabric Clock: {metrics['fclk_frequency']} MHz")
print(f" Memory Clock: {metrics['uclk_frequency']} MHz")
# Utilization
print("\nUtilization:")
print(f" Socket C0 Residency: {metrics['socket_c0_residency']}%")
print(f" GFX Busy: {metrics['socket_gfx_busy']}%")
print(f" DRAM Bandwidth: {metrics['dram_bandwidth_utilization']}%")
# Energy accumulators
print("\nEnergy Accumulators:")
print(f" Socket: {metrics['socket_energy_acc']:.2f}")
print(f" CCD: {metrics['ccd_energy_acc']:.2f}")
print(f" HBM: {metrics['hbm_energy_acc']:.2f}")
finally:
amdsmi.amdsmi_shut_down()System Topology Information
Display CPU system configuration:
import amdsmi
from amdsmi import AmdSmiAffinityScope
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
# System info
family = amdsmi.amdsmi_get_cpu_family()
model = amdsmi.amdsmi_get_cpu_model()
socket_count = amdsmi.amdsmi_get_cpu_socket_count()
print("=== System Configuration ===\n")
print(f"CPU Family: {family} (0x{family:x})")
print(f"CPU Model: {model} (0x{model:x})")
print(f"Sockets: {socket_count}")
# Per-socket info
for i in range(socket_count):
info = amdsmi.amdsmi_get_cpu_cores_per_socket(i)
print(f"\nSocket {info['socket_id']}:")
print(f" Cores: {info['cores_per_socket']}")
# Get socket handle and affinity
sockets = amdsmi.amdsmi_get_cpusocket_handles()
if i < len(sockets):
socket = sockets[i]
# CPU affinity
numa_cpus = amdsmi.amdsmi_get_cpu_affinity_with_scope(
socket, AmdSmiAffinityScope.NUMA_SCOPE
)
print(f" NUMA CPUs: {numa_cpus[:4]}..." if len(numa_cpus) > 4 else numa_cpus)
finally:
amdsmi.amdsmi_shut_down()Power Cap Management
Set and monitor CPU power limits:
import amdsmi
amdsmi.amdsmi_init(amdsmi.AmdSmiInitFlags.INIT_AMD_CPUS)
try:
socket = amdsmi.amdsmi_get_cpusocket_handles()[0]
# Get current settings
current_cap_str = amdsmi.amdsmi_get_cpu_socket_power_cap(socket)
current_cap_mw = int(current_cap_str.split()[0])
current_cap_w = current_cap_mw / 1000
print(f"Current power cap: {current_cap_w:.2f} W")
# Set new power cap (example: 65W)
# NOTE: This requires appropriate privileges
new_cap_w = 65.0
new_cap_mw = int(new_cap_w * 1000)
try:
amdsmi.amdsmi_set_cpu_socket_power_cap(socket, new_cap_mw)
print(f"Power cap set to: {new_cap_w:.2f} W")
# Verify
verify_cap_str = amdsmi.amdsmi_get_cpu_socket_power_cap(socket)
verify_cap_mw = int(verify_cap_str.split()[0])
verify_cap_w = verify_cap_mw / 1000
print(f"Verified power cap: {verify_cap_w:.2f} W")
except Exception as e:
print(f"Failed to set power cap (may require root): {e}")
finally:
amdsmi.amdsmi_shut_down()Related Types
AmdSmiAffinityScope
CPU affinity scope enumeration:
class AmdSmiAffinityScope(IntEnum):
"""
CPU affinity scope levels for querying processor affinity.
"""
NUMA_SCOPE = ... # NUMA node scope affinity
SOCKET_SCOPE = ... # Socket scope affinityNotes
- Most CPU monitoring functions require the ESMI (Embedded System Management Interface) library
- ESMI support depends on the CPU model and system configuration
- Functions that don't require ESMI:
amdsmi_get_cpu_socket_count,amdsmi_get_cpu_cores_per_socket,amdsmi_get_cpu_affinity_with_scope - Setting power caps typically requires root/administrator privileges
- String-formatted return values (power, temperature, energy, frequency) include units in the string (e.g., "45000 mW", "65 Degrees C", "3.5 J", "3500 MHz")
- Energy counters accumulate over time; take multiple readings to calculate consumption over intervals
- The HSMP metrics table provides the most efficient way to get multiple metrics at once
- CPU family and model IDs help identify the processor architecture and variant
- Temperature values are in degrees Celsius
- Power values are in milliwatts (mW) - divide by 1000 for watts
- Frequency values are in megahertz (MHz) - divide by 1000 for gigahertz
- Energy values are in joules (J)
- Core and socket handles are obtained through the handle discovery functions and must be used with their corresponding monitoring functions
- For multi-socket systems, query each socket separately
- The library must be initialized with
INIT_AMD_CPUSorINIT_ALL_PROCESSORSflag for CPU monitoring - Always call
amdsmi_shut_down()to properly release resources