docs: Fix docutils warnings (#59)

* fix typo * fix `Lexing literal_block` docutils warning * fix `Title underline too short` docutils warning * use consistent file type * fix `Malformed table` error * improve index.rst and front-load TOC [ROCm/rocprofiler-systems commit: a70034055e]
2024-12-13 15:59:07 -05:00
@@ -16,7 +16,7 @@ Executables
 This section lists the ROCm Systems Profiler executables.

 rocprof-sys-avail: `source/bin/rocprof-sys-avail <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/bin/rocprof-sys-avail>`_
-------------------------------------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------------------------------------------------------------------------

 The ``main`` routine of ``rocprof-sys-avail`` has three important sections:

@@ -25,7 +25,7 @@ The ``main`` routine of ``rocprof-sys-avail`` has three important sections:
 * Printing hardware counters

 rocprof-sys-sample: `source/bin/rocprof-sys-sample <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/bin/rocprof-sys-sample>`_
----------------------------------------------------------------------------------------------------------------------------------
+--------------------------------------------------------------------------------------------------------------------------------------------------

 * Requires a command-line format of ``rocprof-sys-sample <options> -- <command> <command-args>``
 * Translates command-line options into environment variables
@@ -33,7 +33,7 @@ rocprof-sys-sample: `source/bin/rocprof-sys-sample <https://github.com/ROCm/rocp
 * Is launched by using ``execvpe`` with ``<command> <command-args>`` and a modified environment

 rocprof-sys-casual: `source/bin/rocprof-sys-causal <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/bin/rocprof-sys-causal>`_
----------------------------------------------------------------------------------------------------------------------------------
+---------------------------------------------------------------------------------------------------------------------------------------------------

 When there is exactly one causal profiling configuration variant (which enables debugging),
 ``rocprof-sys-casual`` has a nearly identical design to ``rocprof-sys-sample``
@@ -46,7 +46,7 @@ the following actions take place for each variant:
 * the parent process waits for the child process to finish

 rocprof-sys-instrument: `source/bin/rocprof-sys-instrument <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/bin/rocprof-sys-instrument>`_
----------------------------------------------------------------------------------------------------------------------------------------------
+--------------------------------------------------------------------------------------------------------------------------------------------------------------

 * Requires a command-line format of ``rocprof-sys-instrument <options> -- <command> <command-args>``
 * Allows the user to provide options specifying whether to perform runtime instrumentation, use binary rewrite, or
@@ -95,7 +95,7 @@ librocprof-sys: `source/lib/rocprof-sys <https://github.com/ROCm/rocprofiler-sys
 This is the main library encapsulating all the capabilities.

 librocprof-sys-dl: `source/lib/rocprof-sys-dl <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/lib/rocprof-sys-dl>`_
--------------------------------------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------------------------------------------------------------------

 This is a lightweight, front-end library for ``librocprof-sys`` which serves three primary purposes:

@@ -106,7 +106,7 @@ This is a lightweight, front-end library for ``librocprof-sys`` which serves thr
 * Coordinates communication between ``librocprof-sys-user`` and ``librocprof-sys``

 librocprof-sys-user: `source/lib/rocprof-sys-user <https://github.com/ROCm/rocprofiler-systems/tree/amd-mainline/source/lib/rocprof-sys-user>`_
--------------------------------------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------------------------------------------------------------------------

 * Provides a set of functions and types for the users to add to their code, for example,
  disabling data collection globally or on a specific thread or
@@ -2,9 +2,9 @@
   :description: ROCm Systems Profiler glossary and reference
   :keywords: rocprof-sys, rocprofiler-systems, Omnitrace, ROCm, glossary, terminology, profiler, tracking, visualization, tool, Instinct, accelerator, AMD

-*******************
-ROCm Systems Profiler Glossary
-*******************
+********
+Glossary
+********

 This topic explains the terminology necessary to use ROCm Systems Profiler.
 The list below provides a basic glossary for those who
@@ -13,59 +13,59 @@ when certain terms have different
 contextual meanings, for example, the ROCm Systems Profiler meaning of the term "module"
 when instrumenting Python.

-**Binary**
+Binary
  A file written in the Executable and Linkable Format (ELF). This is the standard file
  format for executable files, shared libraries, etc.

-**Binary instrumentation**
+Binary instrumentation
  Inserting callbacks to instrumentation into an existing binary. This can be performed
  statically or dynamically.

-**Static binary instrumentation**
+Static binary instrumentation
  Loads an existing binary, determines instrumentation points, and generates a new binary
  with instrumentation directly embedded. It is applicable to executables and libraries but
  limited to only the functions defined in the binary. This is also known as **Binary rewrite**.

-**Dynamic binary instrumentation**
+Dynamic binary instrumentation
  Loads an existing binary into memory, inserts instrumentation, and runs the binary.
  It is limited to executables but is capable of instrumenting linked libraries.
  This is also known as **Runtime instrumentation**.

-**Statistical sampling**
+Statistical sampling
  At periodic intervals, the application is paused and the current call-stack of the CPU
  is recorded along with various other metrics. It uses timers that measure either
  (A) real clock time or (B) the CPU time used by the current thread and the CPU time
  expended on behalf of the thread by the system. This is also known as simply **sampling**.

-  **Sampling rate**
+  Sampling rate
    * The period at which (A) or (B) are triggered (in units of ``# interrupts / second``)
    * Higher values increase the number of samples

-  **Sampling delay**
+  Sampling delay
    * How long to wait before (A) and (B) begin triggering at their designated rate

-  **Sampling duration**
+  Sampling duration
    * The amount of time (in real-time) after the start of the application to record samples.
    * After this time limit has been reached, no more samples are recorded.

-**Process sampling**
+Process sampling
  At periodic (real-time) intervals, a background thread records global metrics without
  interrupting the current process. These metrics include, but are not limited to:
  CPU frequency, CPU memory high-water mark (i.e. peak memory usage), GPU temperature,
  and GPU power usage.

-  **Sampling rate**
+  Sampling rate
    * The real-time period for recording metrics (in units of ``# measurements / second``)
    * Higher values increase the number of samples

-  **Sampling delay**
+  Sampling delay
    * How long to wait (in real-time) before recording samples

-  **Sampling duration**
+  Sampling duration
    * The amount of time (in real-time) after the start of the application to record samples.
    * After this time limit has been reached, no more samples are recorded.

-**Module**
+Module
  With respect to binary instrumentation, a module is defined as either the filename
  (such as ``foo.c``) or library name (``libfoo.so``) which contains the definition
  of one or more functions.
@@ -74,18 +74,18 @@ when instrumenting Python.
  the definition of one or more functions. The full path to this file typically contains the
  name of the "Python module".

-**Basic block**
+Basic block
  A straight-line code sequence with no branches in (except for the entry) and
  no branches out (except for the exit).

-**Address range**
+Address range
  The instructions for a function in a binary start at certain address with the ELF file
  and end at a certain address. The range is ``end - start``.

  The address range is a decent approximation for the "cost" of a function.
  For example, a larger address range approximately equates to more instructions.

-**Instrumentation traps**
+Instrumentation traps
  On the x86 architecture, because instructions are of variable size, an instruction
  might be too small for Dyninst to replace it with the normal code sequence
  used to call instrumentation. When instrumentation is placed at points other
@@ -93,10 +93,10 @@ when instrumenting Python.
  the instrumentation fits. (By default, ``rocprof-sys-instrument`` avoids instrumentation
  which requires a trap.)

-**Overlapping functions**
+Overlapping functions
  Due to language constructs or compiler optimizations, it might be possible for
  multiple functions to overlap (that is, share part of the same function body)
  or for a single function to have multiple entry points. In practice, it's
  impossible to determine the difference between multiple overlapping functions
  and a single function with multiple entry points. (By default, ``rocprof-sys-instrument``
-  avoids instrumenting overlapping functions.)
+  avoids instrumenting overlapping functions.)