amd_smi: AMD GPU System Management Interface via AMD SMI library.

Author: Dong Jun Woun

src/components/amd_smi/README.md

@@ -0,0 +1,94 @@
+# AMD_SMI Component
+
+The **AMD_SMI** (AMD System Management Interface) component exposes hardware
+management counters (and selected controls) for AMD GPUs — e.g., power usage,
+temperatures, clocks, PCIe link metrics, VRAM information, and RAS/ECC status —
+by querying the AMD SMI library at runtime (ROCm ≥ 6.3.4).
+
+- [Environment Variables](#environment-variables)
+- [Enabling the AMD_SMI Component](#enabling-the-amd_smi-component)
+
+---
+
+## Environment Variables
+
+For AMD_SMI, PAPI requires the environment variable `PAPI_AMDSMI_ROOT` to be set
+so that the AMD SMI shared library and headers can be found. This variable is
+required at both **compile** and **run** time.
+
+There is a single case to consider (AMD SMI is available on ROCm ≥ 6.0):
+
+1. **For ROCm versions 6.0 and newer:**  
+   Set `PAPI_AMDSMI_ROOT` to the top-level ROCm directory. For example:
+
+   ```bash
+   export PAPI_AMDSMI_ROOT=/opt/rocm-6.4.0
+   # or
+   export PAPI_AMDSMI_ROOT=/opt/rocm
+   ```
+
+The directory specified by `PAPI_AMDSMI_ROOT` **must contain** the following
+subdirectories:
+
+- `PAPI_AMDSMI_ROOT/lib` (which should include the dynamic library `libamd_smi.so`)
+- `PAPI_AMDSMI_ROOT/include/amd_smi` (AMD SMI headers)
+
+If the library is not found or is not functional at runtime, the component will
+appear as "disabled" in `papi_component_avail`, with a message describing the
+problem (e.g., library not found).
+
+---
+
+## Enabling the AMD_SMI Component
+
+To enable reading (and where supported, writing) of AMD_SMI counters, build
+PAPI with this component enabled. For example:
+
+```bash
+./configure --with-components="amd_smi"
+make
+```
+
+You can verify availability with the utilities in `papi/src/utils/`:
+
+```bash
+papi_component_avail            # shows enabled/disabled components
+papi_native_avail -i amd_smi    # lists native events for this component
+```
+
+---
+
+## File-by-file Summary
+
+- **`linux-amd-smi.c`**  
+  Declares the `papi_vector_t` for this component; initializes on first use; hands off work to `amds_*` for device/event management; implements PAPI hooks (`init_component`, `update_control_state`, `start`, `read`, `stop`, `reset`, `shutdown`, and native-event queries).
+
+- **`amds.c`**  
+  Dynamically loads `libamd_smi.so`, resolves AMD SMI symbols, discovers sockets/devices, and **builds the native event table**. Defines helpers to add simple and counter-based events. Manages global teardown (destroy event table, close library).
+
+- **`amds_accessors.c`**  
+  Implements the **accessors** that read/write individual metrics (e.g., temperatures, fans, PCIe, energy, power caps, RAS/ECC, clocks, VRAM, link topology, XGMI/PCIe metrics, firmware/board info, etc.). Each accessor maps an event’s `(variant, subvariant)` to the right SMI call and returns the value.
+
+- **`amds_ctx.c`**  
+  Provides the **per-eventset context**:  
+  - `amds_ctx_open/close` — acquire/release devices, run per-event open/close hooks.  
+  - `amds_ctx_start/stop` — start/stop counters where needed.  
+  - `amds_ctx_read/write/reset` — read current values, optionally write supported controls (e.g., power cap), zero software view.  
+
+- **`amds_evtapi.c`**  
+  Implements native-event enumeration for PAPI (`enum`, `code_to_name`, `name_to_code`, `code_to_descr`) using the in-memory event table and a small hash map for fast lookups.
+
+- **`amds_priv.h`**  
+  Internal definitions: `native_event_t` (name/descr/device/mode/value + open/close/start/stop/access callbacks), global getters, and the AMD SMI function-pointer declarations (via `amds_funcs.h`).
+
+- **`amds_funcs.h`**  
+  Centralized macro list of **AMD SMI APIs** used by the component; generates function-pointer declarations/definitions so `amds.c` can `dlsym()` them at runtime. Conditional entries handle newer SMI features.
+
+- **`htable.h`**  
+  Minimal chained hash table for **name→event** mapping; used by `amds_evtapi.c` to resolve native event names quickly.
+
+- **`amds.h`**  
+  Public, component-internal API across files: init/shutdown, native-event queries, context ops, and error-string retrieval.
+
+- **`Rules.amd_smi`**  
+  Build integration for PAPI’s make system; compiles this component and sets include/library paths for AMD SMI.

src/components/amd_smi/Rules.amd_smi

@@ -0,0 +1,111 @@
+# Set default if the root environment variable is not already set.
+# Note PAPI_AMDSMI_ROOT is an environment variable that must be set.
+# There are four other environment variables that must be exported
+# for runtime operation; see the README file.
+
+PAPI_AMDSMI_ROOT ?= /opt/rocm
+
+# There is one library used by the AMD_SMI component: libamd_smi64.so
+# By default, the software tries to find this in system paths, including
+# those listed in the environment variable LD_LIBRARY_PATH. If not found
+# there it looks in $(PAPI_AMDSMI_ROOT)/lib/libamd_smi64.so
+
+# However, this can be overridden by exporting PAPI_AMD_SMI_LIB as 
+# something else. It would still need to be a full path and library name.
+# If it is exported, it must work or the component will be disabled. e.g.
+# export PAPI_AMD_SMI_LIB=$(PAPI_AMD_SMI_LIB)/lib/libamd_smi64.so
+# This allows users to overcome non-standard ROCM installs or specify
+# specific version of the libamd_smi64.so library.
+
+# PAPI_AMDSMI_ROOT is used at both at compile time and run time.
+
+# There are many ways to cause this path to be known. Spack is a package
+# manager used on supercomputers, Linux and MacOS. If Spack is aware of ROCM,
+# it encodes the paths to the necessary libraries.
+
+# The environment variable LD_LIBRARY_PATH encodes a list of paths to
+# search for libraries; separated by a colon (:). New paths can be
+# added to LD_LIBRARY_PATH. 
+#
+# Warning: LD_LIBRARY_PATH often contains directories that apply to other
+# installed packages you may be using. Always add to LD_LIBRARY_PATH
+# recursively; for example:
+ 
+# >export LD_LIBRARY_PATH=someNewLibraryDirectory:$LD_LIBRARY_PATH which would
+# append the existing LD_LIBRARY_PATH to the new directory you wish to add.
+# Alternatively, you can prepend it: 
+# >export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:someNewLibraryDirectory Which will
+# search the existing libraries first, then your new directory.
+
+# You can check on the value of LD_LIBRARY_PATH with 
+# >echo $LD_LIBRARY_PATH
+
+# There may be other package managers or utilities, for example on a system
+# with modules; the command 'module load rocm' may modify LD_LIBRARY_PATH.
+
+# A Linux system will also search for libraries by default in the directories
+# listed by /etc/ld.so.conf, and /usr/lib64, /lib64, /usr/lib, /lib. 
+
+# Note:  If you change the exports, PAPI should be rebuilt from scratch; see
+# note below.
+
+# Note: AMD_SMI is typically provided with the ROCM libraries, but in PAPI
+# ROCM and AMD_SMI are treated as separate components, and must be given
+# separately on the configure option --with-components. e.g.
+
+#        From within the papi/src/ director:
+#        make clobber
+#        ./configure --with-components="amd_smi"
+#        make  
+
+# An alternative, for both rocm and amd_smi components:
+#        ./configure --with-components="rocm amd_smi"
+
+# OPERATION, per library:
+# 1) If an override is not empty, we will use it explicitly and fail if it
+# does not work. This means disabling the component; a reason for disabling
+# is shown using the papi utility, papi/src/utils/papi_component_avail
+
+# 2) We will attempt to open the library using the normal system library search
+# paths; if Spack is present and configured correctly it should deliver the
+# proper library. A failure here will be silent; we will proceed to (3).
+ 
+# 3) If that fails, we will try to find the library in the standard installed
+# locations listed above. If this fails, we disable the component, the reason
+# for disabling is shown using the papi utility,
+# papi/src/utils/papi_component_avail. 
+
+COMPSRCS += components/amd_smi/amds.c \
+            components/amd_smi/linux-amd-smi.c \
+            components/amd_smi/amds_accessors.c \
+            components/amd_smi/amds_evtapi.c \
+            components/amd_smi/amds_ctx.c
+COMPOBJS += amds.o \
+            linux-amd-smi.o \
+            amds_accessors.o \
+            amds_evtapi.o \
+            amds_ctx.o
+
+# CFLAGS specifies compile flags; need include files here, and macro defines.
+# Where to find amd_smi.h varied in early ROCM releases. If it changes again,
+# for backward compatibility add *more* -I paths, do not just replace this one.
+
+CFLAGS += -I$(PAPI_AMDSMI_ROOT)/include/amd_smi
+CFLAGS += -I$(PAPI_AMDSMI_ROOT)/include
+CFLAGS += -g
+LDFLAGS += $(LDL) -g
+
+linux-amd-smi.o: components/amd_smi/linux-amd-smi.c $(HEADERS)
+	$(CC) $(LIBCFLAGS) $(OPTFLAGS) -c components/amd_smi/linux-amd-smi.c -o linux-amd-smi.o
+
+amds.o: components/amd_smi/amds.c $(HEADERS)
+	$(CC) $(LIBCFLAGS) $(OPTFLAGS) -c components/amd_smi/amds.c -o amds.o
+
+amds_accessors.o: components/amd_smi/amds_accessors.c $(HEADERS)
+	$(CC) $(LIBCFLAGS) $(OPTFLAGS) -c components/amd_smi/amds_accessors.c -o amds_accessors.o
+
+amds_evtapi.o: components/amd_smi/amds_evtapi.c $(HEADERS)
+	$(CC) $(LIBCFLAGS) $(OPTFLAGS) -c components/amd_smi/amds_evtapi.c -o amds_evtapi.o
+
+amds_ctx.o: components/amd_smi/amds_ctx.c $(HEADERS)
+	$(CC) $(LIBCFLAGS) $(OPTFLAGS) -c components/amd_smi/amds_ctx.c -o amds_ctx.o