Review comments

Author: Matt Williams

docs/reference/glossary.rst

@@ -0,0 +1,109 @@
+.. meta::
+  :description: Defined concepts commonly used in AQLprofile
+  :keywords: AQLprofile, ROCm
+
+AQLprofile glossary
+===================
+
+Learn the definitions of concepts commonly used in AQLprofile.
+
+Agents
+------
+
+Agents represent computational devices (CPUs, GPUs) in the Heterogeneous
+System Architecture (HSA) runtime. In AQLprofile, agents are discovered
+via HSA APIs and encapsulated in the ``AgentInfo`` structure. Each agent
+contains metadata including device type, name, compute unit count, and
+memory pools.
+
+Agents are enumerated using HSA API ``hsa_iterate_agents``, and their
+properties are queried via another HSA API, ``hsa_agent_get_info``.
+Agents are used to target specific GPUs for profiling, and to allocate
+resources such as command buffers and memory pools.
+
+Counters and events
+-------------------
+
+Performance counters are special circuits on the hardware that count
+specific GPU events (for example, cycles, instructions, cache hits). Events
+specify which counters to collect, identified by block name, block
+index, and counter ID.
+
+-  Events are described using ``hsa_ven_amd_aqlprofile_event_t``
+   structures.
+-  Events are grouped into profiles and collected during profiling
+   sessions.
+
+.. code:: cpp
+
+   const hsa_ven_amd_aqlprofile_event_t events_arr1[] = {
+       {HSA_VEN_AMD_AQLPROFILE_BLOCK_NAME_SQ, 0, 2 /*CYCLES*/},
+       {HSA_VEN_AMD_AQLPROFILE_BLOCK_NAME_SQ, 0, 3 /*BUSY_CYCLES*/},
+       // ...
+   };
+
+Counter blocks
+--------------
+
+Counter blocks correspond to hardware units on the GPU (for example, SQ, TCC,
+TCP). Each block exposes a set of counters/events.
+
+-  Block names (for example, ``HSA_VEN_AMD_AQLPROFILE_BLOCK_NAME_SQ``) map to
+   specific hardware blocks.
+-  Events specify both the block and the counter within that block.
+
+Command buffers
+---------------
+
+Command buffers are memory regions that store AQL packets and PM4
+commands, which control GPU profiling operations. They're allocated per
+agent, and must meet alignment and size requirements dictated by the
+hardware.
+
+Command packets
+---------------
+
+Command packets are AQL or PM4 packets that encode profiling commands
+for the GPU. They're constructed and written into command buffers.
+
+They're built using AQLprofile APIs or helper functions and submitted to
+the GPU via HSA queues.
+
+.. code:: cpp
+
+   bool Queue::Submit(hsa_ext_amd_aql_pm4_packet_t* packet) {
+       // Write packet to queue and signal doorbell
+   }
+
+Output buffer
+-------------
+
+Output buffers are memory regions that store outputs such as counter
+values and thread trace tokens. They're allocated using HSA memory pools
+associated with the agent.
+
+Profile object
+--------------
+
+The profile object encapsulates all information required to perform a
+profiling session. It's represented by the
+``hsa_ven_amd_aqlprofile_profile_t`` struct, which includes the agent,
+event type, list of events, command buffer, and additional parameters.
+
+Profile objects are constructed by specifying the agent, event type
+(PMC, SQTT), events to collect, and associated buffers. They're passed
+to AQLprofile APIs to start, stop, and read profiling data.
+
+.. code:: cpp
+
+   hsa_ven_amd_aqlprofile_profile_t *profile =
+       new hsa_ven_amd_aqlprofile_profile_t{
+           agent_info->dev_id,
+           HSA_VEN_AMD_AQLPROFILE_EVENT_TYPE_PMC,
+           events,
+           num_events,
+           NULL,
+           0,
+           0,
+           0};
+

docs/reference/supported-architectures.rst

@@ -10,7 +10,7 @@ across multiple architectures.
 
 .. note::
 
-   The GFX versions (GFX9, GFX10, GFX11, GFX12) refer to the architecture families of the hardware for that version.
+   The GFX versions (GFX9XX, GFX10XX, GFX11XX, GFX12XX) refer to the architecture families of the hardware for that version. See `System requirements (Linux) <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html>`__ for more info.
 
 Here's a summary of the counter blocks supported for each architecture:
 

projects/aqlprofile/docs/reference/glossary.rst

@@ -1,11 +1,11 @@
 .. meta::
-  :description: Defined terms commonly used in AQLprofile
+  :description: Defined concepts commonly used in AQLprofile
   :keywords: AQLprofile, ROCm
 
-AQLprofile terms
-================
+AQLprofile glossary
+===================
 
-Learn the definitions of terms commonly used in AQLprofile.
+Learn the definitions of concepts commonly used in AQLprofile.
 
 Agents
 ------

projects/aqlprofile/docs/sphinx/_toc.yml

@@ -21,8 +21,8 @@ subtrees:
 
   - caption: Reference
     entries:
-    - file: reference/terms.rst
-      title: Terms  
+    - file: reference/glossary.rst
+      title: Glossary  
     - file: reference/supported-architectures.rst
       title: Supported architectures and counter blocks  
     - file: reference/api-list.rst

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

@@ -21,8 +21,8 @@ subtrees:
 
   - caption: Reference
     entries:
-    - file: reference/terms.rst
-      title: Terms  
+    - file: reference/glossary.rst
+      title: Glossary  
     - file: reference/supported-architectures.rst
       title: Supported architectures and counter blocks  
     - file: reference/api-list.rst