Documentation updates

-Replaced README with cleaner version. -Added PDF introductory document (same as README) [ROCm/rocm_smi_lib commit: 4449411e35]
2019-02-15 17:23:12 -06:00
commit b6d8b3e92e
@@ -1,65 +0,0 @@
-# rocm_smi_lib
-
-C++ Library interface for ROCm-SMI to allow you to monitor/trace GPU system attributes 
-
-For developer familiar with NVML here is  table to help you map the API between the two libraries
-
-| NVML API	| Type |	Sub-type	| Rocm-smi equivalent API  |
-|-------------------|--------|---------------|-----------------------------------|
-| **Power State**  | | | |	
-| GetEnforcedPowerLimit|	Device	|Power|	rsmi_dev_power_cap_set() |
-| GetPowerManagementLimit|	Device	|Power	|rsmi_dev_power_cap_get() |
-| GetPowerManagementLimitConstraints|	Device|	Power|	rsmi_dev_power_cap_range_get()|
-| GetPowerUsage|	Device| Power | rsmi_dev_power_ave_get()|
-| SetPowerManagementLimit |	Device	| Power| rsmi_dev_power_cap_set()|
-| **Performance State**  | | | |	
-| GetApplicationsClock	| Device |Clocks |	rsmi_dev_get_gpu_sys_freq() rsmi_dev_get_mem_sys_freq()|
-| GetAutoBoostedClocksEnabled |	Device	|Clocks| rsmi_dev_perf_level_get()|
-| GetClock	|Device	|Clocks	 |rsmi_dev_get_gpu_sys_freq(). rsmi_dev_get_mem_sys_freq()|
-| GetClockInfo | 	Device	| Clocks	| rsmi_dev_get_gpu_sys_freq(),  rsmi_dev_get_mem_sys_freq()|
-| GetMaxClockInfo | Device	| Clocks	| rsmi_dev_get_gpu_sys_freq(),  rsmi_dev_get_mem_sys_freq()|
-| GetSupportedGraphicsClocks|	Device |	Clocks|	rsmi_dev_get_gpu_sys_freq(), rsmi_dev_get_mem_sys_freq()|
-| GetSupportedMemoryClocks	|Device| Clocks |rsmi_dev_get_gpu_sys_freq() rsmi_dev_get_mem_sys_freq()|
-| SetAutoBoostedClocksEnabled|	Device|	Clocks | rsmi_dev_perf_level_set() |
-| GetFanSpeed	| Device | Physcial | rsmi_dev_mon_get_fan_speed() rsmi_dev_mon_get_max_fan_speed()  rsmi_dev_fan_rpms_get() |
-| GetTemperature |	Device	|Physcial |	rsmi_dev_temp_metric_get() |
-| GetTemperatureThreshold. |	Device	| Physcial | rsmi_dev_temp_metric_get()|
-| **Initialization and Cleanup**	| | | |	
-| Init	| | | |
-| InitWithFlags | Mngt | Admin | rsmi_init() |
-| Shutdown| Mngt | 	Admin	 |rsmi_shut_down() |
-|**Error Reporting** | | | |		
-| ErrorString |	ErrRpt	 |Err. Rep  | rsmi_status_string()  |
-| **Unit Queries**	| | | |		
-| UnitGetCount  |Unit | Admin | rsmi_num_monitor_devices()  |
-| UnitGetFanSpeedInfo | Unit | Physcial | rsmi_dev_fan_rpms_get(), rsmi_dev_van_speed_get() |
-| UnitGetTemperature |. Device | Physical | rsmi_dev_temp_metric_get() |
-| UnitGetUnitInfo| 	Unit |ID. | rsmi_dev_id_get() (device ID) | 
-| **Unit Commands**	| | | |		
-| DeviceSetApplicationsClocks |	Device | Clocks| rsmi_dev_gpu_clk_freq_set() |
-| DeviceSetComputeMode |	Device | Performance | rsmi_dev_power_profile_set() rsmi_dev_gpu_clk_freq_set() rsmi_dev_perf_level_set() |
-| DeviceSetGpuOperationMode|	Device |	Power | rsmi_dev_power_profile_set()|
-| DeviceSetPowerManagementLimit	| Device |	Power | rsmi_dev_power_cap_set() rsmi_dev_power_profile_set()|
-| **ROCm Only Clock Management API**	| | | 
-|	| Device |	Clocks	| rsmi_dev_perf_level_get() |
-|	| Device |	Clocks| rsmi_dev_perf_level_set() |
-|	| Device. |	Clocks	| rsmi_dev_overdrive_level_get() |
-|	| Device. |	Clocks |	rsmi_dev_overdrive_level_set() |
-
-Example application is logging performance data like Kerenl execution time  vs GPU Temprature,  GPU and Memory Clocks 
-
-### To build library and example:
-mkdir -p build
-
-cd build
-
-cmake ..
-
-make
-
-cd ..
-
-The above commands will result in building the library librocm_smi.so and
-an example, rocm_smi_ex, which links with this library.
-
-
@@ -0,0 +1,75 @@
+
+# ROCm System Management Interface (ROCm SMI) Library
+
+The ROCm System Management Interface Library, or ROCm SMI library, is part of the Radeon Open Compute [ROCm](https://github.com/RadeonOpenCompute) software stack . It is a C library for Linux that provides a user space interface for applications to monitor and control GPU applications. 
+
+# Building ROCm SMI
+
+#### Additional Required software for building
+In order to build the ROCm SMI library, the following components are required. Note that the software versions listed are what was used in development. Earlier versions are not guaranteed to work:
+* CMake (v3.5.0)
+* g++ (5.4.0)
+
+In order to build the latest documentation, the following are required:
+* DOxygen (1.8.11)
+* latex (pdfTeX 3.14159265-2.6-1.40.16)
+
+The source code for ROCm SMI is available on [Github](https://github.com/RadeonOpenCompute/rocm_smi_lib).
+
+After the the ROCm SMI library git repository has been cloned to a local Linux machine, building the library is achieved by following the typical CMake build sequence. Specifically,
+##### ```$ mk -p build```
+##### ```$ cd build```
+##### ```$ cmake <location of root of ROCm SMI library CMakeLists.txt>```
+##### ```$ make```
+The built library will appear in the `build` folder.
+
+#### Building the Documentation
+The documentation PDF file can be built with the following steps (continued from the steps above):
+##### ```$ make doc```
+##### ```$ cd latex```
+##### ```$ make```
+The reference manual, `refman.pdf` will be in the `latex` directory upon a successful build.
+
+#### Building the Tests
+In order to verify the build and capability of ROCm SMI on your system and to see an example of how ROCm SMI can be used, you may build and run the tests that are available in the repo. To build the tests, follow these steps:
+
+##### ```# Set environment variables used in CMakeLists.txt file```
+##### ```$ ROCM_DIR=<location of ROCm SMI library>```
+
+##### ```$ mkdir <location for test build>```
+##### ```$ cd <location for test build>```
+##### ```$ cmake -DROCM_DIR=<location of ROCM SMI library .so> <ROCm SMI source root>/tests/rocm_smi_test```
+To run the test, execute the program `rsmitst` that is built from the steps above. Make sure ROCm SMI library is in your library search path when executing the test program.
+
+# Hello ROCm SMI
+The only required ROCm-SMI call for any program that wants to use ROCm-SMI is the `rsmi_init()` call. This call initializes some internal data structures that will be used by subsequent ROCm-SMI calls. 
+
+When ROCm-SMI is no longer being used, `rsmi_shut_down()` should be called. This provides a way to do any releasing of resources that ROCm-SMI may have held. In many cases, this may have no effect, but may be necessary in future versions of the library.
+
+A simple "Hello World" type program that displays the device ID of detected devices would look like this:
+
+```
+#include <stdint.h>
+#include "rocm_smi/rocm_smi.h"
+int main() {
+  rsmi_status_t ret; 
+  uint32_t num_devices; 
+  uint64_t dev_id; 
+ 
+  // We will skip return code checks for this example, but it 
+  // is recommended to always check this as some calls may not
+  // apply for some devices or ROCm releases
+ 
+  ret = rsmi_init(0);
+  ret = rsmi_num_monitor_devices(&num_devices);
+ 
+  for (int i=0; i < num_devices; ++i) {
+    ret = rsmi_dev_id_get(i &dev_id);
+    // dev_id holds the device ID of device i, upon a
+    // successful call  
+  }  
+  ret = rsmi_shut_down();
+  return 0;
+}
+```
+
@@ -32,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.

-PROJECT_NAME           = "ROCm System Management Interface (ROCm SMI) API "
+PROJECT_NAME           = "ROCmSMI"

 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -44,7 +44,7 @@ PROJECT_NUMBER         =
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.

-PROJECT_BRIEF          =
+PROJECT_BRIEF          = "ROCm SMI Reference Manual"

 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55
@@ -758,7 +758,8 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.

-INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/include/rocm_smi/rocm_smi.h
+INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/docs/README.md \
+                         @CMAKE_CURRENT_SOURCE_DIR@/include/rocm_smi/rocm_smi.h

 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -907,7 +908,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.

-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = @CMAKE_CURRENT_SOURCE_DIR@/docs/ROCm_SMI_Intro.md

 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
@@ -1436,7 +1437,7 @@ EXT_LINKS_IN_WINDOW    = NO
 # Minimum value: 8, maximum value: 50, default value: 10.
 # This tag requires that the tag GENERATE_HTML is set to YES.

-FORMULA_FONTSIZE       = 10
+FORMULA_FONTSIZE       = 16

 # Use the FORMULA_TRANPARENT tag to determine whether or not the images
 # generated for formulas are transparent PNGs. Transparent PNGs are not