/** 
* @file:   README
* CVS:     $Id$
* @defgroup papi_components Components
* @brief Component Specific Readme file: ROCM_SMI
*/

/** @page component_readme Component Readme 

@section Component Specific Information

rocm_smi/ 

Support for ROCM_SMI (System Management Interface) library.

General information
-------------------

The PAPI ROCM_SMI component allows the user to read things like the
temperature, fan speed, and power consumption of AMD GPU devices.
It can also be used to set limits on the power consumption or fan 
speed, using a PAPI_write() interface.

How to install PAPI with the ROCM_SMI component?
------------------------------------------------

ROCM_SMI is installed as part of the AMD ROCM install; so we require
the same environment variable as the ROCM component: PAPI_ROCM_ROOT.
An example is provided below, setting PAPI_ROCM_ROOT to its default
value:

export PAPI_ROCM_ROOT=/opt/rocm

For a standard installed system, this is the only environment variable
that needs to be set, for both compile and runtime.

The above example works on ICL's Caffeine system.

Within PAPI_ROCM_ROOT, we expect the following standard directories:
PAPI_ROCM_ROOT/rocm_smi/lib
PAPI_ROCM_ROOT/rocm_smi/include/rocm_smi

One library is required for the PAPI ROCM component. The name is
librocm_smi64.so. 

(At this writing, testing was done with librocm_smi64.so.2.1.)

After the exports shown above, PAPI must be configured and built.
When papi is installed, there will be a papi/src directory. Navigate
to that, and execute the following:

> ./configure --with-components="rocm_smi"
> make 

If you are rebuilding PAPI, then before the configure step, execute
> make clobber

TESTING the component is installed: Still from papi/src:
> utils/papi_component_avail

If the component is functional, it will show that. Otherwise it will
report it is disabled, and provide a reason why.

You can see what events are provided by a working component as
follows: 
> utils/papi_native_avail | grep -i "rocm_smi:::"



------------------------UNUSUAL INSTALLATIONS------------------------

System configurations can vary. Some systems use Spack, a package
manager, to automatically keep paths straight. Others (like our own
ICL Saturn System) require "module load" commands to provide some
services, e.g. 'module load rocm', and these may also set environment
variables and change the LD_LIBRARY_PATH search order.

Users may require the help of sysadmin personnel to navigate these
facilities and gain access to the correct libraries.

For the ROCM_SMI component to be operational, it must find the dynamic
library librocm_smi64.so.  

If it is not found (or is not functional) then the component will be
listed as "disabled" with a reason explaining the problem. If
libraries were not found, then they are not in the expected places.

The component can be configured to look for each of these libraries in
a specific place, and using an alternate name if desired. Detailed
instructions are contained in the Rules.rocm_smi file.  They are
technical, users may wish to enlist the help of a sysadmin.

