[SWDEV-510820] Add missing goamdsmi documentation (#147)

* add API doc comments to goamdsmi.go
* update README and usage
* add sphinx directive to parse go doc
* fix walrus operator typos
* make docs more consistent
* add Go docs to index.md

---------

Signed-off-by: Arif, Maisam <Maisam.Arif@amd.com>

[ROCm/amdsmi commit: 15c32f6116]

projects/amdsmi/README.md

@@ -26,10 +26,23 @@ for more information.
 * [Install the AMD SMI library and CLI tool](https://rocm.docs.amd.com/projects/amdsmi/en/latest/install/install.html)
 
 ## Requirements
-The following are required to install and use the AMD SMI libraries and CLI tool.
+
+The following are required to install and use the AMD SMI library through its language interfaces and CLI.
+
+* `amdgpu` driver must be loaded for [`amdsmi_init()`](./docs/how-to/amdsmi-cpp-lib#hello-amd-smi) to work.
+* Export `LD_LIBRARY_PATH` to the `amdsmi` installation directory.
+
+  ```bash
+  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/rocm/lib:/opt/rocm/lib64
+  ```
+
+### Python interface and CLI tool prerequisites
 
 * Python 3.6.8+ (64-bit)
-* `amdgpu` driver must be loaded for [`amdsmi_init()`](./docs/how-to/amdsmi-cpp-lib#hello-amd-smi) to work.
+
+### Go API prerequisites
+
+* Go version 1.20 or greater
 
 ## Install amdgpu driver and AMD SMI with ROCm
 
@@ -97,6 +110,17 @@ Refer to the [user guide](https://rocm.docs.amd.com/projects/amdsmi/en/latest/ho
 detailed [Python API reference](https://rocm.docs.amd.com/projects/amdsmi/en/latest/reference/amdsmi-py-api.html) in the
 ROCm documentation portal.
 
+### Go library
+
+The AMD SMI Go interface provides a simple
+[API](https://rocm.docs.amd.com/projects/amdsmi/en/latest/reference/amdsmi-go-lib.html)
+for AMD hardware management. It streamlines hardware monitoring and control
+while leveraging Golang's features.
+
+Refer to the [user guide](https://rocm.docs.amd.com/projects/amdsmi/en/latest/how-to/amdsmi-go-lib.html) and the
+[Go API reference](https://rocm.docs.amd.com/projects/amdsmi/en/latest/reference/amdsmi-go-api.html) in the
+ROCm documentation portal.
+
 ### CLI tool
 
 A versatile command line tool for managing and monitoring AMD hardware. You can use `amd-smi` for:

projects/amdsmi/docs/_extension/go_api_ref.py

@@ -0,0 +1,276 @@
+import re
+import os
+from pathlib import Path
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from sphinx.application import Sphinx
+from sphinx.util.typing import ExtensionMetadata
+
+
+class GoApiRefDirective(Directive):
+    """
+    Directive for generating Go API reference documentation.
+
+    Usage:
+    .. go-api-ref:: path/to/gofile.go
+       :section: gpu
+    """
+
+    required_arguments = 1  # Requires one argument: the path to the Go file
+    optional_arguments = 0
+    has_content = False
+    option_spec = {
+        "section": directives.unchanged,  # Optional section filter
+    }
+
+    def run(self):
+        # Get the path to the Go file
+        go_file_path = self.arguments[0]
+        env = self.state.document.settings.env
+
+        # Get the section filter if provided
+        section_filter = self.options.get("section", None)
+
+        # Resolve the path relative to the document
+        doc_dir = Path(env.doc2path(env.docname)).parent
+        source_path = (doc_dir / go_file_path).resolve()
+
+        # Check if the file exists
+        if not source_path.exists():
+            msg = f"Go source file not found: {source_path}"
+            return [nodes.warning("", nodes.paragraph("", msg))]
+
+        # Parse the Go file and generate documentation
+        functions = parse_go_file(str(source_path))
+
+        # Create a container for the API documentation
+        container = nodes.container()
+        container["classes"].append("go-api-reference")
+
+        # Add the API documentation to the container
+        content = generate_rst_content(functions, section_filter)
+        self.state_machine.insert_input(content, source=str(source_path))
+
+        return [container]
+
+
+def parse_go_file(file_path):
+    """Parse a Go file and extract function documentation."""
+    with open(file_path, "r") as f:
+        content = f.read()
+
+    # Pattern to match function documentation and definition
+    pattern = r"(\/\/[^\n]*(?:\n\/\/[^\n]*)*)\n\s*func\s+([A-Za-z0-9_]+)\s*\((.*?)\)\s*(\(.*?\)|\w+)\s*\{"
+    matches = re.findall(pattern, content, re.DOTALL)
+
+    functions = []
+    for match in matches:
+        doc_comment = match[0]
+        func_name = match[1]
+        params = match[2].strip()
+        return_type = match[3].strip()
+
+        # Process the comment lines
+        doc_lines = []
+        for line in doc_comment.split("\n"):
+            if line.strip().startswith("//"):
+                # Remove the comment marker and one space after it (if present)
+                comment_text = line.strip()[2:]
+                if comment_text.startswith(" "):
+                    comment_text = comment_text[1:]
+                doc_lines.append(comment_text)
+
+        # Extract sections from the doc comment
+        description = []
+        input_params = []
+        output_params = []
+        example = []
+
+        current_section = "description"
+
+        for line in doc_lines:
+            if line.startswith("Input parameter"):
+                current_section = "input"
+                input_params.append(line)
+            elif line.startswith("Output:"):
+                current_section = "output"
+                output_params.append(line)
+            elif line.startswith("Example:"):
+                current_section = "example"
+                example.append(line)
+            elif current_section == "description":
+                description.append(line)
+            elif current_section == "input":
+                input_params.append(line)
+            elif current_section == "output":
+                output_params.append(line)
+            elif current_section == "example":
+                example.append(line)
+
+        # Combine description lines into a single line
+        desc_text = " ".join([line.strip() for line in description if line.strip()])
+
+        # Combine output lines into a single line
+        output_text = " ".join([line.strip() for line in output_params if line.strip()])
+
+        # Determine the section based on function name
+        parts = func_name.split("_")
+        section = parts[1] if len(parts) > 1 else "other"
+
+        functions.append(
+            {
+                "name": func_name,
+                "params": params,
+                "return_type": return_type,
+                "description": desc_text,
+                "input_params": "\n".join(input_params).strip(),
+                "output_params": output_text,
+                "example": "\n".join(example).strip(),
+                "section": section.lower(),  # Store the section for filtering
+            }
+        )
+
+    return functions
+
+
+def generate_rst_content(functions, section_filter=None):
+    """Generate reStructuredText content from parsed functions."""
+    lines = []
+
+    # Filter functions by section if a filter is provided
+    if section_filter:
+        section_filter = section_filter.lower()
+        functions = [f for f in functions if f["section"] == section_filter]
+
+        if not functions:
+            lines.append(f"No functions found in section: {section_filter}")
+            return lines
+
+    # Group functions by prefix if no section filter is provided
+    if not section_filter:
+        # Group functions by prefix (e.g., GO_gpu_, GO_cpu_)
+        function_groups = {}
+        for func in functions:
+            section = func["section"]
+            if section not in function_groups:
+                function_groups[section] = []
+            function_groups[section].append(func)
+
+        # Define the order of sections (GPU first, then CPU, then others)
+        section_order = []
+
+        # Add GPU section first if it exists
+        if "gpu" in function_groups:
+            section_order.append("gpu")
+
+        # Add CPU section next if it exists
+        if "cpu" in function_groups:
+            section_order.append("cpu")
+
+        # Add all other sections in alphabetical order
+        for prefix in sorted(function_groups.keys()):
+            if prefix not in ["gpu", "cpu"]:
+                section_order.append(prefix)
+
+        # Write each group in the specified order
+        for section in section_order:
+            funcs = function_groups[section]
+            lines.append(f"{section.upper()} Functions")
+            lines.append("-" * len(f"{section.upper()} Functions"))
+            lines.append("")
+
+            for func in funcs:
+                add_function_documentation(lines, func)
+    else:
+        # If a section filter is provided, just document those functions without section headers
+        for func in functions:
+            add_function_documentation(lines, func)
+
+    return lines
+
+
+def add_function_documentation(lines, func):
+    """Add documentation for a single function to the lines list."""
+    lines.append(func['name'])
+    lines.append("~" * len(f"``{func['name']}``"))
+    lines.append("")
+
+    # Function signature
+    return_type = func["return_type"]
+    if return_type.startswith("(") and return_type.endswith(")"):
+        return_type = return_type[1:-1]
+
+    lines.append(".. code-block:: go")
+    lines.append("")
+    lines.append(f"   func {func['name']}({func['params']}) {return_type}")
+    lines.append("")
+
+    # Description
+    if func["description"]:
+        lines.append(func["description"])
+        lines.append("")
+
+    # Input parameters
+    if func["input_params"]:
+        for input_line in func["input_params"].split("\n"):
+            lines.append(input_line)
+        lines.append("")
+
+    # Output parameters
+    if func["output_params"]:
+        lines.append(func["output_params"])
+        lines.append("")
+
+    # Example
+    if func["example"]:
+        # Process the example to properly format code blocks
+        example_lines = func["example"].split("\n")
+        in_code_block = False
+
+        for i, line in enumerate(example_lines):
+            stripped_line = line.strip()
+
+            # Check if this is the Example: line
+            if stripped_line == "Example:":
+                lines.append("Example:")
+                continue
+
+            # Check if we're entering a code block
+            if (
+                not in_code_block
+                and i > 0
+                and (
+                    stripped_line.startswith("import")
+                    or stripped_line.startswith("if")
+                    or stripped_line.startswith("for")
+                )
+            ):
+                in_code_block = True
+                lines.append("")
+                lines.append(".. code-block:: go")
+                lines.append("")
+
+            # Add the line to the formatted example
+            if in_code_block:
+                # For code blocks, add indentation
+                lines.append(f"   {line}")
+            elif stripped_line:  # Only add non-empty lines outside code blocks
+                lines.append(line)
+
+        lines.append("")
+
+
+def setup(app):
+    """
+    Setup function for Sphinx extension.
+    This will be called by Sphinx when the extension is loaded.
+    """
+    # Register the directive
+    app.add_directive("go-api-ref", GoApiRefDirective)
+
+    return {
+        "version": "0.1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

projects/amdsmi/docs/conf.py

@@ -5,7 +5,10 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import re
+import sys
+from pathlib import Path
 
+sys.path.append(str(Path('_extension').resolve()))
 
 # get version number to print in docs
 def get_version_info(filepath):
@@ -49,7 +52,7 @@ suppress_warnings = ["etoc.toctree"]
 external_toc_path = "./sphinx/_toc.yml"
 
 external_projects_current_project = "amdsmi"
-extensions = ["rocm_docs", "rocm_docs.doxygen"]
+extensions = ["rocm_docs", "rocm_docs.doxygen", "go_api_ref"]
 
 doxygen_root = "doxygen"
 doxysphinx_enabled = True

projects/amdsmi/docs/how-to/amdsmi-go-lib.md

@@ -0,0 +1,83 @@
+---
+myst:
+  html_meta:
+    "description lang=en": "Get started with the AMD SMI Go interface."
+    "keywords": "api, smi, lib, go, golang, system, management, interface, ROCm"
+---
+
+# AMD SMI Go interface overview
+
+The AMD SMI Go interface provides a convenient way to interact with AMD
+hardware through a simple and accessible [API](../reference/amdsmi-go-api.md).
+The API is compatible with Go 1.20 and higher and requires the AMD driver to
+be loaded for initialization. Review the [prerequisites](#install_reqs).
+
+```{seealso}
+Refer to the [Go library API reference](../reference/amdsmi-go-api.md).
+```
+
+(go_prereqs)=
+## Prerequisites
+
+Before get started, make sure your environment satisfies the following prerequisites.
+See the [requirements](#install_reqs) section for more information.
+
+1. Ensure `amdgpu` drivers are installed properly for initialization.
+
+2. Export `LD_LIBRARY_PATH` to the `amdsmi` installation directory.
+
+   ```bash
+   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/rocm/lib:/opt/rocm/lib64:
+   ```
+
+3. Install Go 1.20+.
+
+   For example, to install from [https://golang.org/dl/go1.20.12.linux-amd64.tar.gz]():
+
+   ```bash
+   git clone https://github.com/udhos/update-golang
+   cd update-golang
+   sudo ./update-golang.sh
+   source /etc/profile.d/golang_path.sh
+   go version
+   ```
+
+## Get started
+
+```{note}
+``hipcc`` and other compilers will not automatically link in the ``libamd_smi``
+dynamic library. To compile code that uses the AMD SMI library API, ensure the
+``libamd_smi.so`` can be located by setting the ``LD_LIBRARY_PATH`` environment
+variable to the directory containing ``librocm_smi64.so`` (usually
+``/opt/rocm/lib``) or by passing the ``-lamd_smi`` flag to the compiler.
+```
+
+A Go application using AMD SMI must call `goamdsmi.GO_gpu_init()` to initialize
+the AMI SMI library before all other calls. This call initializes the internal
+data structures required for subsequent AMD SMI operations.
+
+`goamdsmi.GO_gpu_shutdown()` must be the last call to properly close connection to
+driver and make sure that any resources held by AMD SMI are released.
+
+## Usage
+
+For an example on using the AMD SMI Go API, refer to this implementation
+[https://github.com/amd/amd_smi_exporter/tree/master](https://github.com/amd/amd_smi_exporter/tree/master).
+
+```{seealso}
+Refer to the [Go library API reference](../reference/amdsmi-go-api.md).
+```
+
+### Add AMD SMI library to your project
+
+To include the AMD SMI Go API in your project, update your Makefile or Go module configuration
+to fetch the appropriate version of the AMD SMI library.
+
+```shell
+go get github.com/ROCm/amdsmi@amd-staging 
+```
+
+When using a Makefile, ensure you're fetching the latest AMD SMI repository
+with Go API support. See
+[https://github.com/amd/amd_smi_exporter/blob/master/src/Makefile](https://github.com/amd/amd_smi_exporter/blob/master/src/Makefile)
+for an example implementation.

projects/amdsmi/docs/how-to/amdsmi-py-lib.md

@@ -9,15 +9,36 @@ myst:
 
 The AMD SMI Python interface provides a convenient way to interact with AMD
 hardware through a simple and accessible [API](../reference/amdsmi-py-api.md).
-Compatible with Python 3.6 and higher, this library requires the AMD driver to
-be loaded for initialization -- review the [prerequisites](#install_reqs).
 
 ```{seealso}
 Refer to the [Python library API reference](../reference/amdsmi-py-api.md).
 ```
 
+## Prerequisites
+
+Before get started, make sure your environment satisfies the following prerequisites.
+See the [requirements](#install_reqs) section for more information.
+
+1. Ensure `amdgpu` drivers are installed properly for initialization.
+
+2. Export `LD_LIBRARY_PATH` to the `amdsmi` installation directory.
+
+   ```bash
+   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/rocm/lib:/opt/rocm/lib64:
+   ```
+
+3. Install Python 3.6.8+.
+
 ## Get started
 
+```{note}
+``hipcc`` and other compilers will not automatically link in the ``libamd_smi``
+dynamic library. To compile code that uses the AMD SMI library API, ensure the
+``libamd_smi.so`` can be located by setting the ``LD_LIBRARY_PATH`` environment
+variable to the directory containing ``librocm_smi64.so`` (usually
+``/opt/rocm/lib``) or by passing the ``-lamd_smi`` flag to the compiler.
+```
+
 To get started, the `amdsmi` folder should be copied and placed next to
 the importing script. Import it as follows:
 
@@ -51,18 +72,6 @@ File name             | Description
 (py_usage)=
 ## Usage
 
-```{note}
-``hipcc`` and other compilers will not automatically link in the ``libamd_smi``
-dynamic library. To compile code that uses the AMD SMI library API, ensure the
-``libamd_smi.so`` can be located by setting the ``LD_LIBRARY_PATH`` environment
-variable to the directory containing ``librocm_smi64.so`` (usually
-``/opt/rocm/lib``) or by passing the ``-lamd_smi`` flag to the compiler.
-```
-
-```{seealso}
-Refer to the [Python library API reference](../reference/amdsmi-py-api.md).
-```
-
 An application using AMD SMI must call `amdsmi_init()` to initialize the AMI SMI
 library before all other calls. This call initializes the internal data
 structures required for subsequent AMD SMI operations. In the call, a flag can
@@ -72,6 +81,10 @@ type.
 `amdsmi_shut_down()` must be the last call to properly close connection to
 driver and make sure that any resources held by AMD SMI are released.
 
+```{seealso}
+Refer to the [Python library API reference](../reference/amdsmi-py-api.md).
+```
+
 (py_exceptions)=
 ## Exceptions
 

projects/amdsmi/docs/index.md

@@ -30,6 +30,7 @@ AMD SMI is the successor to <https://github.com/ROCm/rocm_smi_lib>.
 :::{grid-item-card} How to
 * [C++ library usage](./how-to/amdsmi-cpp-lib.md)
 * [Python library usage](./how-to/amdsmi-py-lib.md)
+* [Go library usage](./how-to/amdsmi-go-lib.md)
 * [CLI tool usage](./how-to/amdsmi-cli-tool.md)
 :::
 
@@ -41,6 +42,7 @@ AMD SMI is the successor to <https://github.com/ROCm/rocm_smi_lib>.
   * [Data structures](../doxygen/docBin/html/annotated)
   * [Data fields](../doxygen/docBin/html/functions_data_fields)
 * [Python API](./reference/amdsmi-py-api.md)
+* [Go API](./reference/amdsmi-go-api.md)
 :::
 
 :::{grid-item-card} Tutorials

projects/amdsmi/docs/install/install.md

@@ -13,12 +13,29 @@ and command line tool either as part of the
 
 (install_reqs)=
 ## Requirements
-The following are required to install and use the AMD SMI libraries and CLI
-tool.
 
-* Python 3.6.8+ (64-bit)
-* `amdgpu` driver must be loaded for [`amdsmi_init()`](#cpp_hello_amdsmi) to
-  work.
+The following are required to install and use the AMD SMI library through its language interfaces and CLI.
+
+* The `amdgpu` driver must be loaded for AMD SMI initialization to work.
+
+* Export `LD_LIBRARY_PATH` to the `amdsmi` installation directory.
+
+  ```bash
+  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/rocm/lib:/opt/rocm/lib64
+  ```
+
+### Python interface and CLI tool prerequisites
+
+* Python version 3.6.8 or greater (64-bit)
+
+* Modules:
+  * `python3-wheel`
+
+  * `python3-setuptools`
+
+### Go interface prerequisites
+
+* Go version 1.20 or greater
 
 ### Supported platforms
 

projects/amdsmi/docs/reference/amdsmi-go-api.md

@@ -0,0 +1,33 @@
+---
+myst:
+  html_meta:
+    "description lang=en": "Explore the AMD SMI Go API."
+    "keywords": "api, smi, lib, system, management, interface, ROCm, golang"
+---
+
+# AMD SMI Go API reference
+
+The AMD SMI Go interface provides a convenient way to interact with AMD
+hardware through a simple and accessible API. The API is compatible with Go
+version 1.20 and higher and requires the AMD driver to be loaded for
+initialization. Review the [prerequisites](#go_prereqs) before getting
+started.
+
+This section provides documentation for the AMD SMI Go API. Explore these
+sections to understand the full scope of available functionalities and how to
+implement them in your applications.
+
+## GPU functions
+
+```{eval-rst}
+.. go-api-ref:: ../../goamdsmi.go
+   :section: gpu
+```
+
+## CPU functions
+
+
+```{eval-rst}
+.. go-api-ref:: ../../goamdsmi.go
+   :section: cpu
+```

projects/amdsmi/docs/sphinx/_toc.yml.in

@@ -15,6 +15,8 @@ subtrees:
     title: C++ library usage
   - file: how-to/amdsmi-py-lib.md
     title: Python library usage
+  - file: how-to/amdsmi-go-lib.md
+    title: Go library usage
   - file: how-to/amdsmi-cli-tool.md
     title: CLI tool usage
 
@@ -35,6 +37,8 @@ subtrees:
       title: Data fields
   - file: reference/amdsmi-py-api.md
     title: Python API
+  - file: reference/amdsmi-go-api.md
+    title: Go API
   - file: reference/changelog.md
     title: Changelog
 

projects/amdsmi/goamdsmi.go

@@ -31,140 +31,694 @@ package goamdsmi
 */
 import "C"
 
-//GPU ROCM or AMDSMI calls
+// ``GO_gpu_init`` initializes the GPU and reports whether the initialization was
+// successful. This function must be called before using other AMD SMI
+// functions.
+//
+// Output: ``bool``, returns true on success or false on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       GPU initialization is successful...
+//   }
 func GO_gpu_init() (bool) {
 	return bool(C.goamdsmi_gpu_init())
 }
 
+// ``GO_gpu_shutdown`` shuts down the GPU and reports whether the shutdown was successful.
+//
+// Output: ``bool``, returns true on success or false on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_shutdown() {
+//       GPU shutdown is successful...
+//   }
 func GO_gpu_shutdown() (bool) {
 	return bool(C.goamdsmi_gpu_shutdown())
 }
 
+// ``GO_gpu_num_monitor_devices`` returns the number of GPU monitor devices
+// available.
+//
+// Output: ``uint``, returns the number of GPU monitor devices on success or 0 on
+// fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_shutdown() {
+//       GPU shutdown is successful...
+//   }
 func GO_gpu_num_monitor_devices() (uint) {
 	return uint(C.goamdsmi_gpu_num_monitor_devices())
 }
 
+// ``GO_gpu_dev_name_get`` returns the name of the GPU device at the specified GPU
+// index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``char*``, returns GPU device name on success or "NA" on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           goamdsmi.GO_gpu_dev_name_get(i)
+//       }
+//   }
 func GO_gpu_dev_name_get(i int) (*C.char) {
 	return C.goamdsmi_gpu_dev_name_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_id_get`` returns the device ID of the GPU device at the specified GPU
+// index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint16``, returns GPU device ID on success or ``0xFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           value16 := goamdsmi.GO_gpu_dev_id_get(i)
+//       }
+//   }
 func GO_gpu_dev_id_get(i int) (C.uint16_t) {
 	return C.uint16_t(C.goamdsmi_gpu_dev_id_get(C.uint(i)))
 }
 
+// ``GO_gpu_dev_pci_id_get`` returns the device PCI ID of the device at the
+// specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU devices PCI ID on success or ``0xFFFFFFFFFFFFFFFF``
+// on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       dev_pci_id := int(goamdsmi.GO_gpu_dev_pci_id_get())
+//   }
 func GO_gpu_dev_pci_id_get(i int) (C.uint64_t) {
 	return C.goamdsmi_gpu_dev_pci_id_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_vbios_version_get`` returns the VBIOS version of the GPU device at the
+// specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``char*``, returns VBIOS version on success or "NA" on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       dev_pci_id := int(goamdsmi.GO_gpu_dev_pci_id_get())
+//   }
 func GO_gpu_dev_vbios_version_get(i int) (*C.char) {
 	return C.goamdsmi_gpu_dev_vbios_version_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_vendor_name_get`` returns the vendor name of the GPU device at the
+// specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``char*``, returns the GPU device name on success or "NA" on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           goamdsmi.GO_gpu_dev_vendor_name_get()
+//       }
+//   }
 func GO_gpu_dev_vendor_name_get(i int) (*C.char) {
 	return C.goamdsmi_gpu_dev_vendor_name_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_power_cap_get`` returns the power cap of the GPU at the specified
+// GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU power cap on success or ``0xFFFFFFFFFFFFFFFF`` on
+// fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           dev_power_cap := int(goamdsmi.GO_gpu_dev_power_cap_get(i))
+//       }
+//   }
 func GO_gpu_dev_power_cap_get(i int) (C.uint64_t) {
     return C.goamdsmi_gpu_dev_power_cap_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_power_get`` returns the power of the GPU at the specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU power on success or ``0xFFFFFFFFFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           dev_power := int(goamdsmi.GO_gpu_dev_power_get(i))
+//       }
+//   }
 func GO_gpu_dev_power_get(i int) (C.uint64_t) {
     return C.goamdsmi_gpu_dev_power_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_temp_metric_get`` returns the temperature of the GPU at the
+// specified GPU index, sensor, and metric number.
+//
+// Input parameters:
+//   - int, GPU index.
+//   - int, sensor number.
+//   - int, metric number.
+//
+// Output: ``uint64``, returns GPU temperature on success or ``0xFFFFFFFFFFFFFFFF`` on
+// fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           temp := int(goamdsmi.GO_gpu_dev_temp_metric_get(i, 1, 0))
+//       }
+//   }
 func GO_gpu_dev_temp_metric_get(i int, sensor int, metric int) (C.uint64_t) {
     return C.goamdsmi_gpu_dev_temp_metric_get(C.uint(i), C.uint(sensor), C.uint(metric))
 }
 
+// ``GO_gpu_dev_perf_level_get`` returns the perf level of the GPU at the
+// specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint32``, returns GPU perf level on success or ``0xFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           dev_perf_level := int(goamdsmi.GO_gpu_dev_perf_level_get(i))
+//       }
+//   }
 func GO_gpu_dev_perf_level_get(i int) (C.uint32_t) {
 	return C.goamdsmi_gpu_dev_perf_level_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_overdrive_level_get`` returns the overdrive level of the GPU at the
+// specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint32``, returns GPU perf level on success or ``0xFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           dev_overdrive_level := int(goamdsmi.GO_gpu_dev_overdrive_level_get(i))
+//       }
+//   }
 func GO_gpu_dev_overdrive_level_get(i int) (C.uint32_t) {
 	return C.goamdsmi_gpu_dev_perf_level_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_mem_overdrive_level_get`` returns the mem overdrive level of the GPU at the
+// specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint32``, returns GPU perf level on success or ``0xFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           mem_overdrive_level := int(goamdsmi.GO_gpu_dev_mem_overdrive_level_get(i))
+//       }
+//   }
 func GO_gpu_dev_mem_overdrive_level_get(i int) (C.uint32_t) {
 	return C.goamdsmi_gpu_dev_overdrive_level_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_gpu_clk_freq_get_sclk`` returns the system clock (SCLK) frequency of
+// the GPU at the specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU SCLK frequency level on success or
+// ``0xFFFFFFFFFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           dev_sclk_freq := int(goamdsmi.GO_gpu_dev_gpu_clk_freq_get_sclk(i))
+//       }
+//   }
 func GO_gpu_dev_gpu_clk_freq_get_sclk(i int) (C.uint64_t) {
 	return C.goamdsmi_gpu_dev_gpu_clk_freq_get_sclk(C.uint(i))
 }
 
+// ``GO_gpu_dev_gpu_clk_freq_get_mclk`` returns the memory clock (MCLK) frequency of
+// the GPU at the specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU MCLK frequency level on success or
+// ``0xFFFFFFFFFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           dev_sclk_freq := int(goamdsmi.GO_gpu_dev_gpu_clk_freq_get_mclk(i))
+//       }
+//   }
 func GO_gpu_dev_gpu_clk_freq_get_mclk(i int) (C.uint64_t) {
     return C.goamdsmi_gpu_dev_gpu_clk_freq_get_mclk(C.uint(i))
 }
 
+// ``GO_gpu_od_volt_freq_range_min_get_sclk`` returns the minimum system clock
+// (SCLK) frequency of the GPU at the specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU minimum SCLK frequency level on success or
+// ``0xFFFFFFFFFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           dev_min_sclk := int(goamdsmi.GO_gpu_od_volt_freq_range_min_get_sclk(i))
+//       }
+//   }
 func GO_gpu_od_volt_freq_range_min_get_sclk(i int) (C.uint64_t) {
 	return C.goamdsmi_gpu_od_volt_freq_range_min_get_sclk(C.uint(i))
 }
 
+// ``GO_gpu_od_volt_freq_range_min_get_mclk`` returns the minimum memory clock
+// (MCLK) frequency of the GPU at the specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU minimum MCLK frequency level on success or
+// ``0xFFFFFFFFFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           dev_min_mclk := int(goamdsmi.GO_gpu_od_volt_freq_range_min_get_mclk(i))
+//       }
+//   }
 func GO_gpu_od_volt_freq_range_min_get_mclk(i int) (C.uint64_t) {
 	return C.goamdsmi_gpu_od_volt_freq_range_min_get_mclk(C.uint(i))
 }
 
+// ``GO_gpu_od_volt_freq_range_max_get_sclk`` returns the maximum system clock
+// (SCLK) frequency of the GPU at the specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU maximum SCLK frequency level on success or
+// ``0xFFFFFFFFFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           dev_max_sclk := int(goamdsmi.GO_gpu_od_volt_freq_range_max_get_sclk(i))
+//       }
+//   }
 func GO_gpu_od_volt_freq_range_max_get_sclk(i int) (C.uint64_t) {
 	return C.goamdsmi_gpu_od_volt_freq_range_max_get_sclk(C.uint(i))
 }
 
+// ``GO_gpu_od_volt_freq_range_max_get_mclk`` returns the maximum memory clock
+// (MCLK) frequency of the GPU at the specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU maximum MCLK frequency level on success or
+// ``0xFFFFFFFFFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           dev_max_mclk := int(goamdsmi.GO_gpu_od_volt_freq_range_max_get_mclk(i))
+//       }
+//   }
 func GO_gpu_od_volt_freq_range_max_get_mclk(i int) (C.uint64_t) {
 	return C.goamdsmi_gpu_od_volt_freq_range_max_get_mclk(C.uint(i))
 }
 
+// ``GO_gpu_dev_gpu_busy_percent_get`` returns the busy percentage of the GPU at the
+// specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint32``, returns GPU busy percentage on success or ``0xFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           dev_busy_perc := int(goamdsmi.GO_gpu_dev_gpu_busy_percent_get(i))
+//       }
+//   }
 func GO_gpu_dev_gpu_busy_percent_get(i int) (C.uint32_t) {
 	return C.goamdsmi_gpu_dev_gpu_busy_percent_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_gpu_memory_busy_percent_get`` returns the memory busy percentage of
+// the GPU at the specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU memory busy percentage on success or
+// ``0xFFFFFFFFFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           mem_busy_perc := int(goamdsmi.GO_gpu_dev_gpu_memory_busy_percent_get(i))
+//       }
+//   }
 func GO_gpu_dev_gpu_memory_busy_percent_get(i int) (C.uint64_t) {
 	return C.goamdsmi_gpu_dev_gpu_memory_busy_percent_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_gpu_memory_usage_get`` returns the memory usage of the GPU at the
+// specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU memory usage on success or ``0xFFFFFFFFFFFFFFFF`` on
+// fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           mem_usage := int(goamdsmi.GO_gpu_dev_gpu_memory_usage_get(i))
+//       }
+//   }
 func GO_gpu_dev_gpu_memory_usage_get (i int) (C.uint64_t) {
 	return C.goamdsmi_gpu_dev_gpu_memory_usage_get(C.uint(i))
 }
 
+// ``GO_gpu_dev_gpu_memory_total_get`` returns the total memory of the GPU at the
+// specified GPU index.
+//
+// Input parameter: ``int``, GPU index.
+//
+// Output: ``uint64``, returns GPU memory usage on success or ``0xFFFFFFFFFFFFFFFF`` on
+// fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_gpu_init() {
+//       num_gpus := int(goamdsmi.GO_gpu_num_monitor_devices())
+//       for i := 0; i < num_gpus; i++ {
+//           mem_total := int(goamdsmi.GO_gpu_dev_gpu_memory_total_get(i))
+//       }
+//   }
 func GO_gpu_dev_gpu_memory_total_get (i int) (C.uint64_t) {
 	return C.goamdsmi_gpu_dev_gpu_memory_total_get(C.uint(i))
 }
 
 //CPU ESMI or AMDSMI calls
+
+// ``GO_cpu_init`` initializes the CPU and reports whether the initialization was
+// successful.
+//
+// Output: ``bool``, returns true on success or false on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_cpu_init() {
+//       CPU initialization is successful...
+//   }
 func GO_cpu_init() (bool) {
 	return bool(C.goamdsmi_cpu_init())
 }
 
+// ``GO_cpu_number_of_sockets_get`` returns the number of available CPU sockets.
+//
+// Output: ``uint``, returns the number of CPU sockets on success or 0 on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_cpu_init() {
+//       num_sockets := int(goamdsmi.GO_cpu_number_of_sockets_get())
+//   }
 func GO_cpu_number_of_sockets_get() (uint) {
 	return uint(C.goamdsmi_cpu_number_of_sockets_get())
 }
 
+// ``GO_cpu_number_of_threads_get`` returns the number of available CPU sockets.
+//
+// Output: ``uint``, returns the number of CPU threads on success or 0 on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_cpu_init() {
+//       num_threads := int(goamdsmi.GO_cpu_number_of_threads_get())
+//   }
 func GO_cpu_number_of_threads_get() (uint) {
 	return uint(C.goamdsmi_cpu_number_of_threads_get())
 }
 
+// ``GO_cpu_threads_per_core_get`` returns the thread count per available CPU core.
+//
+// Output: ``uint``, returns the CPU thread count on success or 0 on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_cpu_init() {
+//       num_threads_per_core := int(goamdsmi.GO_cpu_threads_per_core_get())
+//   }
 func GO_cpu_threads_per_core_get() (uint) {
 	return uint(C.goamdsmi_cpu_threads_per_core_get())
 }
 
+// ``GO_cpu_core_energy_get`` returns the CPU core energy for the specified thread
+// index.
+//
+// Input parameter: ``int``, thread index.
+//
+// Output: ``uint64``, returns CPU core energy on success or ``0xFFFFFFFFFFFFFFFF`` on
+// fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_cpu_init() {
+//       num_threads := int(goamdsmi.GO_cpu_number_of_threads_get())
+//       for i := 0; i < num_threads; i++ {
+//           core_energy := int(goamdsmi.GO_cpu_core_energy_get(i))
+//       }
+//   }
 func GO_cpu_core_energy_get(i int) (C.uint64_t) {
 	return C.goamdsmi_cpu_core_energy_get(C.uint(i))
 }
 
+// ``GO_cpu_core_boostlimit_get`` returns the CPU core boost limit for the specified
+// thread index.
+//
+// Input parameter: ``int``, thread index.
+//
+// Output: ``uint32``, returns CPU core boost limit on success or ``0xFFFFFFFF`` on
+// fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_cpu_init() {
+//       num_threads := int(goamdsmi.GO_cpu_number_of_threads_get())
+//       for i := 0; i < num_threads; i++ {
+//           core_boost_limit := int(goamdsmi.GO_cpu_core_boostlimit_get(i))
+//       }
+//   }
 func GO_cpu_core_boostlimit_get(i int) (C.uint32_t) {
 	return C.goamdsmi_cpu_core_boostlimit_get(C.uint(i))
 }
 
+// ``GO_cpu_socket_energy_get`` returns the CPU socket energy for the specified
+// socket index.
+//
+// Input parameter: ``int``, socket index.
+//
+// Output: ``uint64``, returns socket energy level on success or ``0xFFFFFFFFFFFFFFFF``
+// on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_cpu_init() {
+//       num_sockets := int(goamdsmi.GO_cpu_number_of_sockets_get())
+//       for i := 0; i < num_sockets; i++ {
+//           socket_energy := int(goamdsmi.GO_cpu_socket_energy_get(i))
+//       }
+//   }
 func GO_cpu_socket_energy_get(i int) (C.uint64_t) {
 	return C.goamdsmi_cpu_socket_energy_get(C.uint(i))
 }
 
+// ``GO_cpu_socket_power_get`` returns the socket power for the specified socket
+// index.
+//
+// Input parameter: ``int``, socket index.
+//
+// Output: ``uint32``, returns socket energy level on success or ``0xFFFFFFFF``
+// on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_cpu_init() {
+//       num_sockets := int(goamdsmi.GO_cpu_number_of_sockets_get())
+//       for i := 0; i < num_sockets; i++ {
+//           socket_power := int(goamdsmi.GO_cpu_socket_power_get(i))
+//       }
+//   }
 func GO_cpu_socket_power_get(i int) (C.uint32_t) {
 	return C.goamdsmi_cpu_socket_power_get(C.uint(i))
 }
 
+// ``GO_cpu_socket_power_cap_get`` returns the socket power cap for the specified
+// socket index.
+//
+// Input parameter: ``int``, socket index.
+//
+// Output: ``uint32``, returns socket power cap on success or ``0xFFFFFFFF``
+// on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_cpu_init() {
+//       num_sockets := int(goamdsmi.GO_cpu_number_of_sockets_get())
+//       for i := 0; i < num_sockets; i++ {
+//           socket_power_cap := int(goamdsmi.GO_cpu_socket_power_cap_get(i))
+//       }
+//   }
 func GO_cpu_socket_power_cap_get(i int) (C.uint32_t) {
 	return C.goamdsmi_cpu_socket_power_cap_get(C.uint(i))
 }
 
+// ``GO_cpu_socket_power_cap_get`` returns the PROCHOT status for the specified
+// socket index.
+//
+// Input parameter: ``int``, socket index.
+//
+// Output: ``uint32``, returns PROCHOT status on success or ``0xFFFFFFFF`` on fail.
+//
+// Example:
+//
+//   import "github.com/ROCm/amdsmi"
+//
+//   if true == goamdsmi.GO_cpu_init() {
+//       num_sockets := int(goamdsmi.GO_cpu_number_of_sockets_get())
+//       for i := 0; i < num_sockets; i++ {
+//           prochot_status := int(goamdsmi.GO_cpu_prochot_status_get(i))
+//       }
+//   }
 func GO_cpu_prochot_status_get(i int) (C.uint32_t) {
 	return C.goamdsmi_cpu_prochot_status_get(C.uint(i))
 }