Updates for Doxygen

assembler_tools/hec-assembler-tools/README.md

@@ -4,15 +4,15 @@ The tools in this directory are the reference implementation of and Assembler co
 
 ## Table of Contents
 1. [Dependencies](#dependencies)
-2. [Inputs](#as_inputs)
-3. [Outputs](#as_outputs)
-   1. [Assembler Instruction Specs](#asm_specs)
-4. [Executing the Assembler](#executing_asm)
-   1. [Running for a Pre-Generated Kernel](#executing_single)
-   2. [Hardware Spec Configuration](#spec_configuration)
+2. [Inputs](#inputs)
+3. [Outputs](#outputs)
+   1. [Assembler Instruction Specs](#assembler-output-instruction-specs)
+4. [Executing the Assembler](#executing-the-assembler)
+   1. [Running for a Pre-Generated Kernel](#running-for-a-pre-generated-kernel)
+   2. [Hardware Spec Configuration](#hardware-spec-configuration)
 5. [Debug Tools](./debug_tools/README.md)
 
-## Dependencies <a name="dependencies"></a>
+## Dependencies
 
 This project is Python based. Dependencies for the project are as follows:
 
@@ -28,7 +28,7 @@ This project is Python based. Dependencies for the project are as follows:
 
 It is recommended to install Python dependencies and run inside a [Python virtual environment](https://virtualenv.pypa.io/en/stable/index.html) to avoid polluting the global Python.
 
-## Inputs <a name="as_inputs"></a>
+## Inputs
 
 The assembler framework requires two inputs:
 
@@ -40,20 +40,21 @@ Kernels and metadata are structured in comma-separated value (csv) files.
 
 P-ISA kernels, along with corresponding memory metadata required as input to the assembler, are generated by the upper layers in the Encrypted Computing SDK stack, e.g. the [Program Mapper](../../README.md#encrypted-computing-sdk-phase-1-components-and-tasks) component of the [p-ISA tools](../../p-isa_tools).
 
-## Outputs <a name="as_outputs"></a>
+## Outputs
 
-On a successful run, given a P-ISA kernel in file `filename.csv` (and corresponding memory metadata file), the assmebler generates three files:
+On a successful run, given a P-ISA kernel in file `filename.csv` (and corresponding memory metadata file), the assembler generates three files:
 
 - `filename.minst`: contains the list of instructions for the MINST queue.
 - `filename.cinst`: contains the list of instructions for the CINST queue.
 - `filename.xinst`: contains the list of instructions for the XINST queue.
 
-### Assembler Output Instruction Specs <a name="asm_specs"></a>
+### Assembler Output Instruction Specs
 
-The format for the output files and instruction set can be found at [HCGF Instruction Specification](docsrc/specs.md).
+The format for the output files and instruction set for HERACLES can be found
+at [Instruction Specification](docsrc/specs.md).
 
-## Executing the Assembler <a name="executing_asm"></a>
-### Running for a Pre-Generated Kernel <a name="executing_single"></a>
+## Executing the Assembler
+### Running for a Pre-Generated Kernel
 
 Given a P-ISA kernel (`filename.csv`) and corresponding memory mapping file (`filename.mem`), there are three steps to assemble them into HERACLES code.
 
@@ -100,7 +101,7 @@ python3 he_as.py -h
 python3 he_link.py -h
 ```
 
-### Hardware Spec Configuration <a name="spec_configuration"></a>
+### Hardware Spec Configuration
 
 #### Default Configuration
 The HERACLES assembler comes with default configurations for ISA and Memory parameters. These configurations are defined in JSON files located in the config folder:
@@ -116,4 +117,4 @@ To modify the ISA or Memory specifications, follow these steps:
 - **Specify the Path:** Use the **--isa_spec** and **--mem_spec** command-line flags to specify the path to your modified configuration files when running the scripts.
 
 #### Additional Notes
-Memory Parameters: For he_as.py and he_link.py, certain memory parameters like spad_size and hbm_size can be overwritten directly from the command line, providing flexibility in configuration without modifying the JSON files.
+Memory Parameters: For he_as.py and he_link.py, certain memory parameters like spad_size and hbm_size can be overwritten directly from the command line, providing flexibility in configuration without modifying the JSON files.

assembler_tools/hec-assembler-tools/debug_tools/README.md

@@ -2,7 +2,7 @@
 
 This folder contains a collection of scripts designed to assist with debugging and testing various aspects of the assembler and instruction scheduling processes.
 
-## Dependencies <a name="dependencies"></a>
+## Dependencies
 
 These tools are Python based. Dependencies for these scripts are the same as [those](../README.md#dependencies) for the parent project.
 
@@ -17,7 +17,7 @@ Below is a detailed description and usage example for each tool.
 
 ## Tools Overview
 
-### `main.py`
+### main.py
 
   This script serves as the main entry point for running ASM-ISA assembly and P-ISA scheduling processes. It handles the preprocessing, assembly, and scheduling of instructions, transforming them from high-level representations to executable formats.
 
@@ -27,43 +27,43 @@ Below is a detailed description and usage example for each tool.
   ```bash
   python main.py --mem_file <memory_file> --prefix <input_prefix> --isa_spec <isa_spec_file> -v
   ```
-  - `--mem_file`: Specifies the input memory file.  
-  - `--prefix`: One or more input prefixes to process, representing different instructions or kernels.  
-  - `--isa_spec`: Input ISA specification (.json) file that defines the parameters of the instruction set architecture.  
+  - `--mem_file`: Specifies the input memory file.
+  - `--prefix`: One or more input prefixes to process, representing different instructions or kernels.
+  - `--isa_spec`: Input ISA specification (.json) file that defines the parameters of the instruction set architecture.
   - `-v`: Enables verbose mode.
 
 ---
 
-### `isolation_test.py`
+### isolation_test.py
 
   This script isolates specific variables in P-ISA by replacing instructions that do not affect the specified variables with NOPs (no operation instructions). The isolation test is used to focus on specific variables within a P-ISA kernel, allowing developers to analyze the impact of these variables.
 
 - **Usage**:
   ```bash
   python isolation_test.py --pisa_file <pisa_file> --xinst_file <xinst_file> --out_file <output_file> --track <variables_to_track> -v
   ```
-  - `--pisa_file`: Input P-ISA prep (.csv) file containing instructions.  
-  - `--xinst_file`: Input XInst instruction file.  
-  - `--out_file`: Output file name where the modified instructions will be saved.  
-  - `--track`: Set of variables to track.  
+  - `--pisa_file`: Input P-ISA prep (.csv) file containing instructions.
+  - `--xinst_file`: Input XInst instruction file.
+  - `--out_file`: Output file name where the modified instructions will be saved.
+  - `--track`: Set of variables to track.
   - `-v`: Enables verbose mode.
 
 ---
 
-### `deadlock_test.py`
+### deadlock_test.py
 
   This script checks for deadlocks in the CInstQ and MInstQ caused by sync instructions. It raises an exception if a deadlock is found, indicating a potential issue in instruction scheduling.
 
 - **Usage**:
   ```bash
   python deadlock_test.py <input_dir> [input_prefix]
   ```
-  - `<input_dir>`: Directory containing instruction files, typically organized by prefixes.  
+  - `<input_dir>`: Directory containing instruction files, typically organized by prefixes.
   - `[input_prefix]`: Optional prefix for instruction files, used to specify particular sets of instructions.
 
 ---
 
-### `order_test.py`
+### order_test.py
   This script tests all registers in an XInstQ to determine if any register is used out of order based on the P-ISA instruction order. It is specifically designed for kernels that do not involve evictions.
 
   The script helps ensure that registers are accessed in the correct sequence, which is crucial for maintaining the integrity of instruction execution in systems where register order matters. This is particularly important for debugging and optimizing instruction scheduling.
@@ -75,34 +75,34 @@ Below is a detailed description and usage example for each tool.
   - `--input_file`: Specifies the input (.xinst) file containing the XInstQ instructions.
   - `-v`: Enables verbose mode for detailed output, providing insights into the processing steps and results.
 
-### `xinst_timing_check/inject_bundles.py`
+### xinst_timing_check/inject_bundles.py
 
   This script injects dummy bundles into instruction files after the first bundle, simulating additional instruction loads for testing purposes. The injection of dummy bundles is used to test the system's handling of instruction loads and synchronization points.
 
 - **Usage**:
   ```bash
   python inject_bundles.py <input_dir> <output_dir> [input_prefix] [output_prefix] --isa_spec <isa_spec_file> -b <dummy_bundles> -ne
   ```
-  - `<input_dir>`: Directory containing input files to be processed.  
-  - `<output_dir>`: Directory to save output files with injected bundles.  
-  - `[input_prefix]`: Optional prefix for input files, specifying the target instruction set.  
-  - `[output_prefix]`: Optional prefix for output files, defining the naming convention for saved files.  
-  - `--isa_spec`: Input ISA specification (.json) file, providing architectural details.  
-  - `-b`: Number of dummy bundles to insert, simulating additional instruction loads.  
+  - `<input_dir>`: Directory containing input files to be processed.
+  - `<output_dir>`: Directory to save output files with injected bundles.
+  - `[input_prefix]`: Optional prefix for input files, specifying the target instruction set.
+  - `[output_prefix]`: Optional prefix for output files, defining the naming convention for saved files.
+  - `--isa_spec`: Input ISA specification (.json) file, providing architectural details.
+  - `-b`: Number of dummy bundles to insert, simulating additional instruction loads.
   - `-ne`: Skip exit in dummy bundles, altering the behavior of injected instructions.
 
 ---
 
-### `xinst_timing_check/xtiming_check.py`
+### xinst_timing_check/xtiming_check.py
 
   This script checks timing for register access, ensuring registers are not read before their write completes, and checks for bank write conflicts.
 
 - **Usage**:
   ```bash
   python xtiming_check.py <input_dir> [input_prefix] --isa_spec <isa_spec_file>
   ```
-  - `<input_dir>`: Directory containing input files for timing analysis.  
-  - `[input_prefix]`: Optional prefix for input files, specifying the target instruction set.  
+  - `<input_dir>`: Directory containing input files for timing analysis.
+  - `[input_prefix]`: Optional prefix for input files, specifying the target instruction set.
   - `--isa_spec`: Input ISA specification (.json) file, providing architectural details for timing validation.
 
 ---

assembler_tools/hec-assembler-tools/docsrc/specs.md

@@ -1,23 +1,23 @@
-# HCGF Instruction Specification {#HCGF_specs}
+# HERACLES Instruction Specification
 
 Terms used in this document are defined in the HERACLES Instruction Set Architecture (ISA).
 
 [Changelog](changelog.md)
 
 ## Table of Contents
 1. [Introduction](#introduction)
-2. [Memory Specification](#mem_spec)
-   1. [Word Size](#word_spec)
-   2. [High-Bandwidth Memory (HBM)](#hbm_spec)
-   3. [Scratch Pad (SPAD)](#spad_spec)
-   4. [Register Banks](#registers_spec)
-3. [Output File Formats](#output_format)
-   1. [XINST File](#output_xinst)
-   2. [CINST File](#output_cinst)
-   3. [MINST File](#output_minst)
-4. [Instruction Set](#instr_spec)
-
-## Introduction <a name="introduction"></a>
+2. [Memory Specification](#memory-specification)
+   1. [Word Size](#word-size)
+   2. [High-Bandwidth Memory (HBM)](#high-bandwidth-memory-hbm)
+   3. [Scratch Pad (SPAD)](#scratch-pad-spad)
+   4. [Register Banks](#register-banks)
+3. [Output File Formats](#output-file-formats)
+   1. [XINST File](#xinst-file)
+   2. [CINST File](#cinst-file)
+   3. [MINST File](#minst-file)
+4. [Instruction Set](#instruction-set)
+
+## Introduction
 
 HERACLES architecture allows fine-grained control of memory movement between DRAM, SRAM, and register files. The architecture features three execution queues that control memory movement among the different levels, as well as control of the compute engine.
 
@@ -45,7 +45,7 @@ The three queues must work in concert to ensure memory consistency and optimized
 
 The output of the assembler tool is composed of three files containing the instructions for each of the three execution queues for the HERACLES respectively.
 
-## Memory Specification <a name="mem_spec"></a>
+## Memory Specification
 
 #### Summary of Sizes and Memory Capacities in HERACLES Instructions and Memory Model
 
@@ -55,9 +55,9 @@ The output of the assembler tool is composed of three files containing the instr
 | XINST Queue Capacity | 1 | MB | 512 | Capacity of XInst queue in Cfetch engine. |
 | CINST Queue Capacity | 128 | KB | 4 | Capacity of CInst queue in Cfetch engine. |
 | MINST Queue Capacity | 128 | KB | 4 | Capacity of MInst queue in Mfetch engine. |
-| XINST Intruction width | 64 | bits | | Size of instructions in the Xinst queue. |
-| CINST Intruction width | 64 | bits | | Size of instructions in the Cinst queue. |
-| MINST Intruction width | 64 | bits | | Size of instructions in the Minst queue. |
+| XINST Instruction width | 64 | bits | | Size of instructions in the Xinst queue. |
+| CINST Instruction width | 64 | bits | | Size of instructions in the Cinst queue. |
+| MINST Instruction width | 64 | bits | | Size of instructions in the Minst queue. |
 | XINST bundle size | 64 | instructions | | Number of instructions in an XInst bundle. |
 | HBM Capacity`*` | 48 | GB | 1,572,864 | Capacity of DRAM. |
 | SPAD Capacity`*` | 48 | MB | 1,536 | Capacity of SRAM/cache. |
@@ -70,7 +70,7 @@ The output of the assembler tool is composed of three files containing the instr
 
 See HERACLES ISA for more information.
 
-### Word Size <a name="word_spec_"></a>
+### Word Size
 
 A "word" is the *smallest addressable data unit* in the HERACLES memory model.
 
@@ -88,7 +88,7 @@ Data sizes in bytes are offered for *reference purposes only*. Since the smalles
 
 Note that the information included here is at the abstraction level that concerns the assembler. The HERACLES architecture further partitions the memory into blocks, and the compute engine into 64 compute tile pairs. For more information on the low level architecture refer to the HERACLES architecture documentation.
 
-### High-Bandwidth Memory (HBM) <a name="hbm_spec"></a>
+### High-Bandwidth Memory (HBM)
 
 **HBM capacity**: 48GB == 1,572,864 words.
 
@@ -111,7 +111,7 @@ Instruction pointers for MINST and CINST queues will automatically start once th
 
 Execution of XINST queue, however is controlled by CInst.
 
-### Scratch Pad (SPAD)  <a name="spad_spec"></a>
+### Scratch Pad (SPAD)
 
 **SPAD capacity**: 48MB == 1,536 words.
 
@@ -125,7 +125,7 @@ Data transfers from SPAD into the CE's register file are available in the corres
 
 **Temporary Store Queue Buffer capacity**: 4 words.
 
-### Register Banks <a name="registers_spec"></a>
+### Register Banks
 
 The CE features 64 compute tile pairs (these are the compute units of the CE) arranged in 8 rows of 8 tile pairs. Each tile pair has 4 register banks with 72 registers. Each register has a capacity of 512 bytes. However, the architecture will ensure that all tile pairs will execute the same instruction on the same clock cycle on the same registers; therefore, we can treat the CE as a unit with the characteristics listed below.
 
@@ -141,9 +141,9 @@ As a unit, the CE features a register file with 4 **register banks**.
 
 - A register bank cannot be accessed for writing more than once in the same cycle. Writes normally occur on the last cycle of instructions.
 
-- A register bank can be accessed for a single read and a single write simulataneously in the same cycle.
+- A register bank can be accessed for a single read and a single write simultaneously in the same cycle.
 
-## Output File Formats <a name="output_format"></a>
+## Output File Formats
 
 The assembler provides its output in three csv-style files.
 
@@ -153,7 +153,7 @@ All output files support inline comments using the hash symbol `#`. All text to
 
 Note that full line comments are not supported, and every line must contain an instruction.
 
-### XINST File <a name="output_xinst"></a>
+### XINST File
 
 Contains the instructions for the XINST execution queue.
 
@@ -185,7 +185,7 @@ F99, 1056, ntt, r24b2, r25b3, r60b2, r61b3, r35b1, 13, 12 # dst: r24b2, r25b3, s
 
 Check instruction specification for exceptions.
 
-### CINST File <a name="output_cinst"></a>
+### CINST File
 
 Contains the instructions for the CINST execution queue.
 
@@ -215,7 +215,7 @@ Example:
 
 Check instruction specification for exceptions.
 
-### MINST File <a name="output_minst"></a>
+### MINST File
 
 Contains the instructions for the MINST execution queue.
 
@@ -245,7 +245,7 @@ Example:
 
 Check instruction specification for exceptions.
 
-## Instruction Set <a name="instr_spec"></a>
+## Instruction Set
 
 Instructions are pipelined. Thus, they will have a throughput time and a total latency.
 
@@ -261,7 +261,7 @@ The following instruction set functionally matches those of HERACLES ISA. It is
 
 | MINST | CINST | XINST |
 |-|-|-|
-| [msyncc](inst_spec/minst/minst_msyncc.md) | [bload](inst_spec/cinst/cinst_bload.md) | [move](inst_spec/xinst/xinst_move.md) |
+| [msyncc](inst_spec/minst/minst_msyncc.md) | [bloat](inst_spec/cinst/cinst_bload.md) | [move](inst_spec/xinst/xinst_move.md) |
 | [mload](inst_spec/minst/minst_mload.md) | [bones](inst_spec/cinst/cinst_bones.md) | [xstore](inst_spec/xinst/xinst_xstore.md) |
 | [mstore](inst_spec/minst/minst_mstore.md) | [nload](inst_spec/cinst/cinst_nload.md) | [rshuffle](inst_spec/xinst/xinst_rshuffle.md) |
 |  | [xinstfetch](inst_spec/cinst/cinst_xinstfetch.md) | [ntt](inst_spec/xinst/xinst_ntt.md) |