### Build and Serve Project Documentation

Source: https://github.com/chipsalliance/t1/blob/master/doc/README.md

This bash script navigates into the language-specific documentation directory, installs necessary dependencies using yarn, builds the documentation with honkit, and then starts a local server to view it.

```bash
pushd "${PWD}/${LANG}"

yarn install
yarn honkit build
yarn honkit serve
```

--------------------------------

### Build and Test ELF

Source: https://github.com/chipsalliance/t1/blob/master/tests/pytorch/README.md

Commands to build the PyTorch test ELF using Nix and list the resulting binary. Includes instructions for starting the emulator with waveform tracing for debugging.

```bash
git add .
nix build '.#t1.blastoise.ip.cases.pytorch.demo' -L
ls ./result/bin/pytorch-demo.elf

# To start the emulator and get waveform, run:
nix build '.#t1.blastoise.ip.cases.pytorch.demo.emu-result.with-trace' -L
```

--------------------------------

### Build and Install ASL Simulation Library with Nix

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

This snippet shows how to build and install the ASL simulation library using Nix, making the generated headers and library files available in the `build/simlib` directory.

```Shell
cd pokedex/model
nix develop ".#pokedex.sim-lib" -c make install
ls ./build/simlib
```

--------------------------------

### Build Project README Documentation

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Command to build the project's README documentation from the 'docs/doc.typ' file. Requires typst and pandoc to be installed.

```Makefile
make doc
```

--------------------------------

### RISC-V Instruction File Directory Structure Example

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

This example illustrates the required directory and file structure for RISC-V instruction definition files, showing how `addi`, `vle64.v`, and `slli` instructions would be organized within the `extensions` directory, mirroring the `riscv-opcodes` repository layout.

```Shell
model/\n└── extensions/\n    ├── rv_i/\n    │   └── addi.asl\n    ├── rv_v/\n    │   └── vle64_v.asl\n    └── rv32_i/\n        └── slli.asl
```

--------------------------------

### Build Project PDF Documentation

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Command to build the project's documentation in PDF format from the 'docs/doc.typ' file. Requires typst and pandoc to be installed.

```Makefile
make doc-pdf
```

--------------------------------

### Set Up T1 VCS DPI Development Environment

Source: https://github.com/chipsalliance/t1/blob/master/README.md

Prepare the development environment for VCS DPI (Direct Programming Interface) components. This involves using Nix to set up the necessary libraries and then building the Rust-based `difftest` with Cargo.

```Shell
$ nix develop .#t1.<config-name>.<top-name>.vcs-dpi-lib
```

```Shell
cd difftest
$ cargo build --feature vcs
```

--------------------------------

### CMake Build Configuration for spike_interfaces C++ Library

Source: https://github.com/chipsalliance/t1/blob/master/difftest/spike_interfaces/CMakeLists.txt

This CMake script defines the build process for the `spike_interfaces` C++ library. It sets the minimum CMake version, specifies C++17 standard, finds the `libspike` dependency, creates a static library, links it, defines public include directories for build and install interfaces, and configures the installation of the library and its headers with CMake export configuration.

```CMake
cmake_minimum_required(VERSION 3.20)
project(spike_interfaces LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)

find_package(libspike REQUIRED)

add_library(${CMAKE_PROJECT_NAME} STATIC spike_interfaces.cc)

target_link_libraries(${CMAKE_PROJECT_NAME} PUBLIC libspike)

target_include_directories(${CMAKE_PROJECT_NAME} INTERFACE
  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
  $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
)

# just playing with CMake export, maybe not necessary
target_sources(${CMAKE_PROJECT_NAME} PUBLIC
  FILE_SET HEADERS
  FILES spike_interfaces.h spike_interfaces_c.h)

install(
  TARGETS ${CMAKE_PROJECT_NAME}
  EXPORT ${CMAKE_PROJECT_NAME}-config
  PUBLIC_HEADER
    FILE_SET HEADERS
)

install(
  EXPORT ${CMAKE_PROJECT_NAME}-config
  NAMESPACE ${CMAKE_PROJECT_NAME}::
  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/${CMAKE_PROJECT_NAME}
)
```

--------------------------------

### List Available T1 Build Configurations

Source: https://github.com/chipsalliance/t1/blob/master/README.md

This command helps users discover all possible combinations of <config-name> and <top-name> that can be used for T1 builds. It is useful for understanding the available build options and their parameters.

```bash
make list-configs
```

--------------------------------

### PyTorch Model Implementation (demo.py)

Source: https://github.com/chipsalliance/t1/blob/master/tests/pytorch/README.md

Example Python code for the PyTorch implementation, demonstrating how to save the imported MLIR module to a file named 'forward.mlir'. This file contains the PyTorch model's graph representation.

```python
# demo.py
#...
with open("forward.mlir", "w") as mlir_module:
    print(graph._imported_module, file = mlir_module)
```

--------------------------------

### Pull T1 Emulator Docker Image

Source: https://github.com/chipsalliance/t1/blob/master/README.md

This command pulls a pre-built Docker image for the T1 emulator from the GitHub Container Registry. Users can specify a configuration, such as 'blastoise' for dlen 256 and vlen 512 support, to get a specific T1 build.

```bash
docker pull ghcr.io/chipsalliance/t1-$config:latest
# For example, config with dlen 256 vlen 512 support
docker pull ghcr.io/chipsalliance/t1-blastoise:latest
```

--------------------------------

### C Interface for MLIR Model (demo.c)

Source: https://github.com/chipsalliance/t1/blob/master/tests/pytorch/README.md

Example C code for 'demo.c' showing how to include necessary headers, declare MLIR C interfaces, define data sizes, declare static data with '.vdata' annotation for memory placement, and set up MemRef objects for input. It also outlines the structure for the test entry function.

```c
// 1. include the memref C++ wrapper.
#include "memref.hpp"

// 2. Declare the MLIR C interface, the argument layout can be guess from the generated MLIR model.
extern "C" void _mlir_ciface_forward(MemRef<float, 1> *output,
                                     MemRef<float, 1> *arg1,
                                     MemRef<float, 1> *arg2);

// 3. Declare the data sizes, here we use a vector that is one-dimension, with length 512.
static const int32_t sizes[1] = {512};

// 4. Declare a static data and add ".vdata" annotation. This can indicate the emulator to put these data to correct memory.
__attribute((section(".vdata"))) float input_float_1[512] = {1, 2, 3};

// 5. Declare a one dimension MemRef with float data type.
MemRef<float, 1> input1(input_float_1, sizes);

// 6. Mark the test function as extern "C", so that the linker can link it with our main function.
extern "C" int test() {
  // call _mlir_ciface_forward(...)
  return 0;
}
```

--------------------------------

### Execute T1 Profiler

Source: https://github.com/chipsalliance/t1/blob/master/profiler/README.md

Run the T1 profiler by providing the input VCD files and an output directory for analysis results. The profiler will generate various analysis results in the specified output directory.

```shell
nix run .#t1.profiler <INPUT_VCD> <OUTPUT_DIR>
```

```shell
nix run .#t1.profiler result-prof-vcd/*.vcd prof-result
```

--------------------------------

### Build and Load T1 Docker Image using Nix

Source: https://github.com/chipsalliance/t1/blob/master/README.md

These commands demonstrate how to build a T1 Docker image using Nix flakes and then load it into the local Docker daemon. This method requires KVM support on the host system, as indicated by the note.

```bash
nix build -L ".#t1.$config.release.docker-image" --out-link docker-image.tar.gz
docker load -i ./docker-image.tar.gz
```

--------------------------------

### Build T1 Chisel Elaborator JAR

Source: https://github.com/chipsalliance/t1/blob/master/README.md

This command builds the wrapped JAR file for the T1 Chisel elaborator. It is a prerequisite for generating the hardware design. The output is placed in the ./result directory.

```shell
nix build .#t1.elaborator
```

--------------------------------

### Run T1 Test Case with VCS Emulator for Coverage Report

Source: https://github.com/chipsalliance/t1/blob/master/README.md

This command uses `nix develop` to enter the development environment and then runs a specific T1 test case, like 'mlir.hello', using the `t1-helper` utility. It specifies the `vcs-emu-cover` emulator type to generate a comprehensive coverage report.

```shell
nix develop -c t1-helper run -i t1emu -c blastoise -e vcs-emu-cover mlir.hello
```

--------------------------------

### Set Up T1 Elaborator Development Environment

Source: https://github.com/chipsalliance/t1/blob/master/README.md

Configure the development environment for the Chisel-based elaborator. This involves bringing up the Scala environment, CIRCT tools, and creating submodules, with an option for editable submodules. The `mill` command is used for building and running the elaborator.

```Shell
$ nix develop .#t1.elaborator
```

```Shell
$ nix develop .#t1.elaborator.editable
```

```Shell
$ mill -i elaborator
```

--------------------------------

### Build T1 Emulator and RTL

Source: https://github.com/chipsalliance/t1/blob/master/README.md

This section provides commands to build various components of the T1 emulator. This includes generating the elaborated IP core SystemVerilog files, and compiling the emulator using either Verilator or VCS, with an option for trace support. Replace <config-name> with the desired configuration.

```shell
nix build .#t1.<config-name>.t1emu.rtl
```

```shell
nix build .#t1.<config-name>.t1emu.verilator-emu
```

```shell
nix build .#t1.<config-name>.t1emu.vcs-emu --impure
```

```shell
nix build .#t1.<config-name>.t1emu.vcs-emu-trace --impure
```

--------------------------------

### Build T1 Project to Verify Coverage Generation

Source: https://github.com/chipsalliance/t1/blob/master/README.md

This command builds a specific test case within the T1 project, such as 'mlir.hello', to check if the coverage generation process is working correctly. The '-L' flag provides verbose logging during the build process.

```shell
nix build .#t1.blastoise.t1emu.cases.mlir.hello -L
```

--------------------------------

### Generate Profiler Input VCD with Nix

Source: https://github.com/chipsalliance/t1/blob/master/profiler/README.md

This command generates a profiler VCD for a specific test case, such as 'codegen.vadd_vv', using the Nix build system. The output VCDs are placed in the specified directory, 'result-prof-vcd'. Currently, only 't1rocketemu' is supported for VCD generation.

```shell
nix build --impure .#t1.blastoise.t1rocketemu.run.codegen.vadd_vv.vcs-prof-vcd -o result-prof-vcd
```

--------------------------------

### Build T1 IP Core SystemVerilog Files

Source: https://github.com/chipsalliance/t1/blob/master/README.md

This command elaborates and builds the T1 IP core, generating the .sv (SystemVerilog) files. The <config-name> placeholder must be replaced with a specific configuration, such as blastoise, which determines design parameters like DLEN. The build output is found in ./result.

```shell
nix build .#t1.<config-name>.t1.rtl
```

--------------------------------

### Export T1 RTL Properties with Nix

Source: https://github.com/chipsalliance/t1/blob/master/README.md

Export specific RTL properties or dump all available keys from the T1 design using Nix commands. This is useful for inspecting internal design parameters and configurations.

```Shell
$ nix run .#t1.<config-name>.<top-name>.omreader <key>
$ nix run .#t1.<config-name>.<top-name>.emu-omreader <key>
```

```Shell
$ nix run .#t1.<config-name>.<top-name>.omreader -- run --dump-methods
$ nix run .#t1.<config-name>.<top-name>.emu-omreader -- run --dump-methods
```

--------------------------------

### Update Chisel Submodule Versions using nvfetcher

Source: https://github.com/chipsalliance/t1/blob/master/README.md

These commands navigate to the `nix/t1/dependencies` directory and then execute `nvfetcher` to update the versions of Chisel submodules. This process ensures that the project uses the latest compatible versions of its Chisel-related dependencies.

```shell
cd nix/t1/dependencies
nix run '.#nvfetcher'
```

--------------------------------

### ASL Example: Returning a Misaligned Load Exception

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Demonstrates how to return a standard RISC-V misaligned load exception using the Exception helper function. It checks for address misalignment and, if found, returns an Exception with the predefined CAUSE_MISALIGNED_LOAD constant and the faulting address.

```ASL
// ...
// Check if the address is misaligned.
if addr[1:0] != '00' then
  // Return an exception with the standard cause and the faulting address.
  return Exception(CAUSE_MISALIGNED_LOAD, addr);
end

// ...
```

--------------------------------

### Example Generated ReadCSR Dispatcher Logic

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Illustrates the structure of the `ReadCSR` function generated by the `codegen` tool. It uses pattern matching on the `csr_number` to dispatch calls to specific `Read_<CSR_NAME>` handler functions.

```ASL
func ReadCSR(csr_number: bits(12)) => Result
begin
  case csr_number of
    when '1111 0001 0010' =>
      return Read_MARCHID();
    when '0011 0100 0010' =>
      return Read_MCAUSE();
    when '0011 0100 0001' =>
      return Read_MEPC();
    // ...
    otherwise =>
      return Exception(CAUSE_ILLEGAL_INSTRUCTION, ZeroExtend(csr, 32));
  end
end
```

--------------------------------

### Build T1 Rocket Emulator and RTL

Source: https://github.com/chipsalliance/t1/blob/master/README.md

These commands facilitate building the T1 Rocket emulator, which integrates the T1 design with a Rocket core. It covers generating the elaborated SystemVerilog files and compiling the emulator using Verilator or VCS, including a version with trace support. Remember to substitute <config-name> with a valid configuration.

```shell
nix build .#t1.<config-name>.t1rocketemu.rtl
```

```shell
nix build .#t1.<config-name>.t1rocketemu.verilator-emu
```

```shell
nix build .#t1.<config-name>.t1rocketemu.vcs-emu
```

```shell
nix build .#t1.<config-name>.t1rocketemu.vcs-emu-trace
```

--------------------------------

### Example Generated WriteCSR Dispatcher Logic

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Illustrates the structure of the `WriteCSR` function generated by the `codegen` tool. It uses pattern matching on the `csr_number` to dispatch calls to specific `Write_<CSR_NAME>` handler functions, passing the `value` to be written.

```ASL
func WriteCSR(csr_number: bits(12), value: bits(32)) => Result
begin
  case csr_number of
    when '1111 0001 0010' =>
      return Write_MARCHID(value);
    when '0011 0100 0010' =>
      return Write_MCAUSE(value);
    when '0011 0100 0001' =>
      return Write_MEPC(value);
    // ...
    otherwise =>
      return Exception(CAUSE_ILLEGAL_INSTRUCTION, ZeroExtend(csr, 32));
  end
end
```

--------------------------------

### Configure SPIKE_DASM for Disassembly

Source: https://github.com/chipsalliance/t1/blob/master/profiler/README.md

To enable disassembly support within the profiler, the `SPIKE_DASM` environment variable must be set to the path of the `spike-dasm` executable. This command builds `spike` using Nix and sets the environment variable accordingly. If `SPIKE_DASM` is not configured, disassembly information in `inst_map.txt` will be unavailable.

```shell
export SPIKE_DASM=$(nix build --print-out-paths .#spike)/bin/spike-dasm
```

--------------------------------

### ASLi Command: Convert Bit-Slice Operations

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

This ASLi command converts all bit-slice operations to use the `+:` syntax, for example, "x[7:0]" becomes "x[0 +: 8]".

```ASLi Command
:xform_lower
```

--------------------------------

### Run T1 Emulator Test Cases

Source: https://github.com/chipsalliance/t1/blob/master/README.md

Execute test cases on the T1 IP emulator using the `t1-helper run` command. This command allows specifying the top module, configuration, emulator type, and test case name. It supports various emulator types for different needs like tracing or coverage.

```Shell
$ nix develop -c t1-helper run -i <top-name> -c <config-name> -e <emulator-type> <case-name>
```

```Shell
$ nix develop -c t1-helper run -i t1emu -c blastoise -e vcs-emu intrinsic.linear_normalization
```

```Shell
$ nix develop -c t1-helper run -i t1emu -c blastoise -e vcs-emu-trace intrinsic.linear_normalization
```

```Shell
$ nix develop -c t1-helper run -i t1emu -c blastoise -e vcs-emu-trace intrinsic.linear_normalization
$ nix develop -c t1-helper run pytorch.llama
```

```Shell
$ nix develop -c t1-helper run -v pytorch.lenet
```

```Shell
$ nix develop -c t1-helper run -i t1emu -c blastoise -e vcs-emu mlir.hello
$ nix develop -c t1-helper check
```

```Shell
$ nix develop -c t1-helper run -i t1emu -c blastoise -e vcs-emu-cover mlir.hello
```

--------------------------------

### Manage and Develop T1 Test Cases

Source: https://github.com/chipsalliance/t1/blob/master/README.md

Commands for listing, developing, and building specific test cases within the T1 project. Test cases are categorized by type (e.g., asm, mlir, pytorch) and can be filtered using regular expressions. This allows for focused development and testing.

```Shell
$ nix develop -c t1-helper listCases -c <config-name> -i <top-name> <regexp>
```

```Shell
$ t1-helper listCases -c blastoise -i t1emu mlir
[INFO] Fetching current test cases

* mlir.axpy_masked
* mlir.conv
* mlir.hello
* mlir.matmul
* mlir.maxvl_tail_setvl_front
* mlir.rvv_vp_intrinsic_add
* mlir.rvv_vp_intrinsic_add_scalable
* mlir.stripmining
* mlir.vectoradd

$ t1-helper listCases -c blastoise -i t1emu '.*vslid.*'
[INFO] Fetching current test cases

* codegen.vslide1down_vx
* codegen.vslide1up_vx
* codegen.vslidedown_vi
* codegen.vslidedown_vx
* codegen.vslideup_vi
* codegen.vslideup_vx
```

```Shell
$ nix develop .#t1.blastoise.t1emu.cases.pytorch.llama
```

```Shell
$ nix build .#t1.<config-name>.<top-name>.cases.intrinsic.matmul -L
$ ls -al ./result
```

--------------------------------

### Recoded Float64 Div/Sqrt Module Function Interface

Source: https://github.com/chipsalliance/t1/blob/master/dependencies/berkeley-hardfloat/doc/divSqrtRecodedFloat64_mulAddZ31.txt

This section details the primary function interface of the `divSqrtRecodedFloat64_mulAddZ31` module, including how division and square root operations are started, the meaning of input and output signals, the pipelining behavior, and the latency for operations. It also specifies the format of exception flags.

```APIDOC
Module: divSqrtRecodedFloat64_mulAddZ31
Purpose: Computes division or square root for standard 64-bit floating-point in recoded form, using a separate integer multiplier-adder. Pipelined operation.

Pipelining:
  - Can work on up to four operations concurrently (mix of div/sqrt).

Starting Operations:
  - inValid (input): Asserted to indicate a new operation request.
  - sqrtOp (input): 0 for division, 1 for square root.
  - inReady_div (output): Asserted (=1) when a new division can be started.
  - inReady_sqrt (output): Asserted (=1) when a new square root can be started.

  Conditions for starting an operation:
    - inValid & (sqrtOp == 0) & inReady_div   ->  division is started
    - inValid & (sqrtOp == 1) & inReady_sqrt  ->  square root is started

Inputs (when starting an operation):
  - a (recoded form): Dividend for division.
  - b (recoded form): Divisor for division; argument for square root.
  - roundingMode (input): Rounding mode.

Input Stability:
  - inValid, sqrtOp, and b are expected to be stable very early in the cycle when inValid is asserted.

Readiness Signal Behavior:
  - inReady_div/inReady_sqrt may deassert even if no new operation is started (e.g., if inValid was 0).
  - Opportunities to add new operations depend on existing pipeline state and arguments of in-progress operations.

Minimum Delay for Starting Same Kind of Operation (after previous start):
  - Division after division: at most 6 cycles later.
  - Square root after square root: at most 10 cycles later.

Result Delivery:
  - Operations results are delivered strictly in the same order they were started.

Outputs (when result is ready):
  - outValid_div (output): Asserted (=1) when a division result is ready.
  - outValid_sqrt (output): Asserted (=1) when a square root result is ready.
  - out (recoded form): The function result (same format as a and b inputs).
  - exceptionFlags (bit vector): Bit vector of exception flags, format: { invalid, infinity, overflow, underflow, inexact }
    - "infinity" exception is also known as "divide-by-zero".

Output Stability:
  - out and exceptionFlags are expected to be stable only late in a clock cycle.

Latency (from beginning of starting cycle to end of final cycle):
  - Division: 19 cycles or less.
  - Square root: 27 cycles or less.
  - Minimum special-case latency: 2 cycles (for either division or square root).
```

--------------------------------

### Update Nix Flake Dependencies

Source: https://github.com/chipsalliance/t1/blob/master/README.md

This command updates the `nixpkgs` and other flake inputs to their latest versions as defined in the project's `flake.lock` file. It ensures that the project's dependencies are current, which is crucial for maintaining a stable build environment.

```shell
nix flake update
```

--------------------------------

### Define Coverpoints in JSON for MLIR Test Cases

Source: https://github.com/chipsalliance/t1/blob/master/README.md

This JSON file defines coverpoints for a specific test case, such as 'mlir.hello'. It specifies assertions, trees, and modules that are used to track code coverage. The 'assert' array contains objects with 'name' and 'description' for individual instruction coverage.

```json
{
  "assert": [
    {
      "name": "vmv_v_i",
      "description": "single instruction vmv.v.i"
    }
  ],
  "tree": [],
  "module": []
}
```

--------------------------------

### Parse Coverpoint JSON and Generate Coverage File with jq

Source: https://github.com/chipsalliance/t1/blob/master/README.md

This shell script, typically part of a `default.nix` file, parses the coverpoint JSON file using `jq`. It extracts assertion, tree, and module names to generate a `.cover` file. If the JSON file is not found, it defaults to covering all assertions.

```shell
if [ -f ${caseName}.json ]; then
  ${jq}/bin/jq -r '[.assert[] | "+assert " + .name] + [.tree[] | "+tree " + .name] + [.module[] | "+module " + .name] | .[]' \
      ${caseName}.json > $pname.cover
else 
  echo "-assert *" > $pname.cover
fi
```

--------------------------------

### T1 RTL Property Schema Reference

Source: https://github.com/chipsalliance/t1/blob/master/README.md

Defines the structure and types of various RTL properties available for the T1 project, including vector lengths, extensions, and decoder instructions. This schema is crucial for understanding the data format when exporting properties.

```APIDOC
vlen: Integer
dlen: Integer
extensionsJson: Json
  [*]: string
march: String
decoderInstructionsJson | decoderInstructionsJsonPretty: Json
  [*]: array
  [*].attributes: object
  [*].attributes[*]: array
  [*].attributes[*].description: string
  [*].attributes[*].identifier: string
  [*].attributes[*].value: string
```

--------------------------------

### FFI Memory Write API Definitions

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Defines the required platform functions for memory write operations, allowing writes of 8, 16, or 32 bits to physical memory addresses. These functions return a boolean indicating success or failure, for example, due to an access fault.

```APIDOC
func FFI_write_physical_memory_8bits(addr : bits(32), data : bits(8)) => boolean;
func FFI_write_physical_memory_16bits(addr : bits(32), data : bits(16)) => boolean;
func FFI_write_physical_memory_32bits(addr : bits(32), data : bits(32)) => boolean;
```

--------------------------------

### ASLi Command: Filter Unlisted Functions from Imports

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

This ASLi command filters out functions not specified in the `imports` field of the configuration. The `imports` field should be defined in a configuration file as a JSON array of function names, for example: `{"imports": ["TraceMemRead", "TraceMemWrite"]}`.

```ASLi Command
:filter_unlisted_functions imports
```

--------------------------------

### Nix Build Configuration (build.nix)

Source: https://github.com/chipsalliance/t1/blob/master/tests/pytorch/README.md

Configuration for 'build.nix' using `buildBuddyE2ETest` to define the test case name and the `optPhase`. The `optPhase` specifies a series of `buddy-opt` commands to lower MLIR, convert to LLVM, and generate `forward-lowered.mlir`.

```nix
{ buildBuddyE2ETest }:
buildBuddyE2ETest {
  caseName = "demo";

  optPhase = ''
    echo "Lowering MLIR"
    python ./demo.py \
    | buddy-opt --pass-pipeline "builtin.module(func.func(tosa-to-linalg-named, tosa-to-linalg, tosa-to-tensor, tosa-to-arith),\n        empty-tensor-to-alloc-tensor, convert-elementwise-to-linalg, arith-bufferize, \n        func.func(linalg-bufferize, tensor-bufferize), func-bufferize)" \
    | buddy-opt --pass-pipeline "builtin.module(func.func(buffer-deallocation-simplification, convert-linalg-to-loops), \n        eliminate-empty-tensors, func.func(llvm-request-c-wrappers))" \
    | buddy-opt --lower-affine \
        --convert-math-to-llvm \
        --convert-math-to-libm \
        --convert-scf-to-cf \
        --convert-arith-to-llvm \
        --expand-strided-metadata \
        --finalize-memref-to-llvm \
        --lower-vector-exp \
        --lower-rvv=rv32 \
        --convert-vector-to-llvm \
        --convert-func-to-llvm \
        --reconcile-unrealized-casts \
        -o forward-lowered.mlir

    optArtifacts+=(
      "forward-lowered.mlir"
    )
  '';
}
```

--------------------------------

### Create PyTorch Test Skeleton

Source: https://github.com/chipsalliance/t1/blob/master/tests/pytorch/README.md

Instructions to set up the directory structure and initial files for a new PyTorch test case named 'demo' within the 'tests/pytorch' directory.

```bash
cd tests/pytorch
mkdir -p demo
cd demo
touch demo.cc demo.py build.nix
```

--------------------------------

### Get MTVEC Mode Bits

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Retrieves the 2-bit representation of the `MTVEC_MODE` enumeration. Returns '00' for direct mode and '01' for vectored mode.

```RISC-V ISA DSL
getter MTVEC_MODE_BITS => bits(2)
begin
  case MTVEC_MODE of
    when MTVEC_DIRECT_MODE => return '00';
    when MTVEC_VECTORED_MODE => return '01';
  end
end
```

--------------------------------

### Manually Run Buddy Compiler Tools

Source: https://github.com/chipsalliance/t1/blob/master/tests/pytorch/README.md

Steps to manually run Buddy compiler tools for debugging. This involves entering the Nix development shell, creating a temporary directory, unpacking sources, and executing the build phase.

```bash
nix develop '.#t1.blastoise.ip.cases.pytorch.demo' -L
cd $(mktemp -d -t 'pytorch-debug-XXX')
pwd

# Unpack sources
unpackPhase
# Check commands:
echo -e "$buildPhase"
# Run build
bash -c "$buildPhase"
```

--------------------------------

### Compile MemrefCopy Library

Source: https://github.com/chipsalliance/t1/blob/master/tests/pytorch/README.md

A bash snippet demonstrating how to compile the `MemrefCopy.cc` library using `$CXX` and add the resulting object file (`memrefCopy.o`) to the `llcArtifacts` array for linking.

```bash
# ...
    echo "Compiling memrefCopy library"
    $CXX -nostdlib -c ${../lib/MemrefCopy.cc} -o memrefCopy.o
    llcArtifacts+=(
      memrefCopy.o
    )
# ...
```

--------------------------------

### Debug PyTorch Code

Source: https://github.com/chipsalliance/t1/blob/master/tests/pytorch/README.md

Command to debug PyTorch code by running the `demo.py` script within the `buddy-mlir` Python environment provided by Nix.

```bash
nix run '.#buddy-mlir.pyenv' -- demo.py
```

--------------------------------

### Nix Bootstrap Process State Diagram

Source: https://github.com/chipsalliance/t1/blob/master/dependencies/docs.md

A Mermaid state diagram illustrating the complete dirty Nix bootstrap process for the T1 project. It details four main states: 'Clone submodules source code', 'Chisel: Fetch Ivy and publish local', 'Submodules (w/o Chisel): Fetch Ivy', and 'T1: Fetch and Dump Ivy', showing their internal substates and the transitions between them, culminating in 'Build T1 Nix'.

```Mermaid
stateDiagram-v2
    state "Clone submodules source code" as clone_submodules {
        state "json parse nvfetcher generated.json" as parse_json
        state "git clone submodule A,B,C" as git_clone
        state "patch submodule(remove .git...)" as clean_repo
        parse_json --> git_clone
        git_clone --> clean_repo
    }

    state "Chisel: Fetch Ivy and publish local" as bootstrap_chisel {
        state "fetch ivy" as fetch_chisel_ivy
        state "publish local" as publish_chisel_local
        state "dump Nix expression" as dump_chisel
        fetch_chisel_ivy --> publish_chisel_local
        publish_chisel_local --> dump_chisel
    }

    state "Submodules (w/o Chisel): Fetch Ivy" as fetch_submodules {
        state "fetch ${module} ivy" as fetch_ivy
        state "dump ${module} ivy" as dump_ivy
        fetch_ivy --> dump_ivy
    }

    state "T1: Fetch and Dump Ivy" as bootstrap_t1 {
        state "nix build submodule ivy" as build_nix
        state "install jar to new mill home" as install_jar
        state "dump T1 ivy" as dump
        build_nix --> install_jar
        install_jar --> dump
    }

    clone_submodules --> bootstrap_chisel
    bootstrap_chisel --> fetch_submodules
    fetch_submodules --> bootstrap_t1

    state "Build T1 Nix" as build_t1_nix
    bootstrap_t1 --> build_t1_nix
```

--------------------------------

### Generate Project Files for ASLi Compilation

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Commands to navigate to the model directory and use Nix to build the project target. This process prepares the full source code for ASLi compilation and lists the generated files in the 'build/1-rvcore' directory.

```Shell
cd pokedex/model
nix develop ".#pokedex.sim-lib" -c make project
ls ./build/1-rvcore
```

--------------------------------

### Build Pokedex Simulator with Nix or Cargo

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

This section provides two methods to compile the final Pokedex simulator: using Nix for a direct build or manually with Cargo after entering a Nix development shell.

```Shell
nix build '.#pokedex.simulator'
ls ./result/bin
```

```Shell
nix develop '.#pokedex.simulator.dev'
cd pokedex/simulator
cargo build
```

--------------------------------

### Build and Test Floating-Point Units

Source: https://github.com/chipsalliance/t1/blob/master/dependencies/berkeley-hardfloat/README.md

Command to compile and run unit tests for the floating-point units. This process requires the 'berkeley-testfloat-3' package and utilizes a C simulator for execution.

```Shell
make
```

--------------------------------

### Generate C Code from ASLi

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Commands to navigate to the model directory and use Nix to execute the 'asl2c' make target. This command generates C code from ASLi and lists the output files in the 'build/2-cgen' directory, including dumps and C source/header files.

```Shell
cd pokedex/model
nix develop ".#pokedex.sim-lib" -c make asl2c
ls ./build/2-cgen
```

--------------------------------

### Rust RISC-V Simulator File Structure

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

This section outlines the directory and file structure of the Rust-based RISC-V simulator. It details the organization of the 'difftest' and 'pokedex' components, including their source files for CLI entries, event parsers, FFI functions, ASL model wrappers, and core simulator logic, along with associated build and dependency files.

```APIDOC
model/simulator/
    ├── difftest
    │   ├── assets
    │   ├── src
    │   │   ├── main.rs            -- difftest CLI entry
    │   │   ├── pokedex.rs         -- parser for pokedex simulator event
    │   │   └── spike.rs           -- parser for spike event
    │   └── Cargo.toml
    ├── pokedex
    │   ├── src
    │   │   ├── bin
    │   │   │   └── pokedex.rs     -- pokedex CLI entry
    │   │   ├── ffi.rs             -- FFI functions implementation
    │   │   ├── lib.rs
    │   │   ├── model.rs           -- ASL model function and variable wrapper
    │   │   └── simulator.rs       -- Simulator logic and states
    │   ├── asl_export.h           -- wrapper for ASL exported header
    │   ├── build.rs
    │   └── Cargo.toml
    ├── Cargo.lock
    └── Cargo.toml
```

--------------------------------

### divSqrtRecFN_small Module Interface Specification

Source: https://github.com/chipsalliance/t1/blob/master/dependencies/berkeley-hardfloat/doc/divSqrtRecFN_small.txt

Detailed specification of the 'divSqrtRecFN_small' module's inputs, outputs, and operational logic for floating-point division and square root computations. It outlines how operations are initiated, the roles of various parameters, and the format of results and exception flags.

```APIDOC
Module: divSqrtRecFN_small

Purpose: Computes division or square root for standard floating-point numbers in recoded form.
Concurrency: One operation at a time; last cycle of previous operation can overlap with first cycle of next.

Inputs:
  - inValid: bool (stable early in cycle; when asserted, all other inputs stable early)
  - sqrtOp: bool (false for division, true for square root)
  - a: recoded_float (dividend for division, argument for square root)
  - b: recoded_float (divisor for division)
  - roundingMode: enum (rounding mode)
  - detectTininess: bool (specifies tininess detection; must be held constant during operation)

Outputs:
  - inReady: bool (indicates if a new operation can be started)
  - outValid_div: bool (true when division result is ready)
  - outValid_sqrt: bool (true when square root result is ready)
  - out: recoded_float (function result; stable late in cycle)
  - exceptionFlags: bit_vector (stable late in cycle)
    Format: { invalid, infinity, overflow, underflow, inexact }
    Note: "infinity" exception is also known as "divide-by-zero".

Operation Start Condition: inValid && inReady == true

Division (sqrtOp == false):
  Inputs: a (dividend), b (divisor), roundingMode
  Operation: a / b

Square Root (sqrtOp == true):
  Inputs: a (argument), roundingMode
  Operation: sqrt(a)
```

--------------------------------

### Implement RISC-V `addi` Instruction Logic in ASL

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

This ASL code defines the core logic for the 'add immediate' (addi) instruction. It decodes operands, performs a NOP optimization for `rd=0`, calculates the result, and updates the Program Counter (PC). This code is intended to be placed directly in an `.asl` file without a surrounding function block.

```ASL
// Decode operands from the instruction bits.
// Read following arg luts sections for details about `Get*` API.
let rd  : integer{0..31} = UInt(GetRD(instruction));

// NOP optimization
if rd != 0 then
  let imm : bits(12) = GetIMM(instruction);
  let rs1 : integer{0..31} = UInt(GetRS1(instruction));
  X[rd] = X[rs1] + SignExtend(imm, 32);
end

PC = PC + 4;

return Retired();
```

--------------------------------

### RISC-V ISA Specification Reference

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Provides a reference link to the official RISC-V ISA Specification document, specifically the latest ratified version released on May 08, 2025. This document serves as the basis for the implemented instruction set architecture.

```APIDOC
RISC-V ISA Specification (Release 2025-05-08):
  URL: https://github.com/riscv/riscv-isa-manual/releases/tag/20250508
  Description: Official specification document for the RISC-V instruction set architecture.
```

--------------------------------

### ASLi Command: Create Bounded Integer

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

This ASLi command creates a bounded integer type.

```ASLi Command
:xform_bounded
```

--------------------------------

### Arg Luts API Naming and Signature Convention

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Documentation for the Arg Luts API, which abstracts the extraction of argument fields from instructions. This API aims to reduce decoding bugs and simplify development by providing consistent functions for field extraction.

```APIDOC
Naming: All functions start with a `Get` prefix, followed by the field name in uppercase (e.g., `GetRD`, `GetRS1`).
Signature: Each function accepts the 32-bit instruction as a `bits(32)` parameter and returns a bit vector whose size is determined by the field's definition in the lookup table.
```

--------------------------------

### ASLi Command: Convert Getter/Setter Syntax

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

This ASLi command converts getter/setter syntax to function calls, e.g., `Mem[a, sz] = x` becomes `Mem_set(a, sz, x)`.

```ASLi Command
:xform_getset
```

--------------------------------

### FFI Hook API Definitions

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Defines platform hook functions required by the model to notify real-time information. These include a hook for executing fence instructions and another for notifying when a General Purpose Register (GPR) is written.

```APIDOC
// Execute when executing fence instruction
func FFI_emulator_do_fence();
// Execute when GPR get written
func FFI_write_GPR_hook(reg_idx: integer{0..31}, data: bits(32));
```

--------------------------------

### Generated ASL Code for RISC-V `addi` Instruction

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

This ASL code shows the structure of the generated function for the 'addi' instruction after running the `codegen` tool. It includes the logic from `addi.asl` within an `Execute_ADDI` function and demonstrates how it's integrated into a global instruction dispatcher `Execute` function, handling instruction decoding and execution.

```ASL
// the code generated for addi
func Execute_ADDI(instruction : bits(32)) => Result
begin
  // code from addi.asl will be inserted here

  let rd  : integer{0..31} = UInt(GetRD(instruction));

  // NOP optimization
  if rd != 0 then
    let imm : bits(12) = GetIMM(instruction);
    let rs1 : integer{0..31} = UInt(GetRS1(instruction));
    X[rd] = X[rs1] + SignExtend(imm, 32);
  end

  PC = PC + 4;

  return Retired();
end

// The global dispatcher function, now with a branch for addi
func Execute(instruction: bits(32)) => Result
begin
  case instruction of
    when 'xxxx xxxx xxxx xxxx x000 xxxx x001 0011' =>
        return Execute_ADDI(instruction);
    // ...
    otherwise =>
      return Exception(CAUSE_ILLEGAL_INSTRUCTION, instruction);
  end
end
```

--------------------------------

### ASL Exception Handling Helper Functions API

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Detailed API documentation for the helper functions used with the ASL Result type. Describes OK for successful returns, Exception for failures with cause and trap value, and Retired for successful operations without a return value.

```APIDOC
OK(value: bits(32)): Result
  Description: Returns a successful result.
  Parameters:
    value: The successful value (bits(32)).
  Returns: A Result record with is_ok set to TRUE and the value field populated.

Exception(cause: integer, trap_value: bits(32)): Result
  Description: Returns a failure.
  Parameters:
    cause: The exception type (integer).
    trap_value: Relevant context about the error (bits(32), e.g., faulting address).
  Returns: A Result record with is_ok set to FALSE, cause set to the exception type, and trap_value holding context.

Retired(): Result
  Description: Returns a successful operation that does not produce a return value.
  Parameters: None.
  Returns: A Result record with is_ok set to TRUE, cause set to -1, and value set to zeros.
```

--------------------------------

### C Function Signatures for FFI Memory Reads

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

C language function signatures corresponding to the FFI memory read platform implementations, showing the translated types and parameters. These are the C prototypes that the platform must implement.

```C
FFI_ReadResult_N_32 FFI_instruction_fetch_0(uint32_t pc);

FFI_ReadResult_N_8 FFI_read_physical_memory_8bits_0(uint32_t addr);
FFI_ReadResult_N_16 FFI_read_physical_memory_16bits_0(uint32_t addr);
FFI_ReadResult_N_32 FFI_read_physical_memory_32bits_0(uint32_t addr);
```

--------------------------------

### FFI Trap API Definitions

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

Defines platform functions required for exception and interrupt trap support. These APIs allow the model to query for pending external/time interrupts and to handle 'ebreak' and 'ecall' instructions.

```APIDOC
func FFI_machine_external_interrupt_pending() => bit;
func FFI_machine_time_interrupt_pending() => bit;
func FFI_ebreak();
func FFI_ecall();
```

--------------------------------

### External Multiplier-Adder Interface for Div/Sqrt Module

Source: https://github.com/chipsalliance/t1/blob/master/dependencies/berkeley-hardfloat/doc/divSqrtRecodedFloat64_mulAddZ31.txt

This section describes the interface requirements for the external integer multiplier-adder that the `divSqrtRecodedFloat64_mulAddZ31` module depends on. It specifies the multiplier-adder's capabilities, pipelining, and the signals used to control its inputs and receive its computed result.

```APIDOC
Required Component: Outside integer multiplier-adder.

Functionality:
  - Multiplies two 54-bit integer factors.
  - Adds an additional 105-bit term.
  - Generates a 105-bit integer result.

Pipelining:
  - Must be fully pipelined with three cycles of latency.

Input Registers:
  - Assumed that multiplication factors are held in registers just preceding the multiplier-adder unit.

Factor Inputs (supplied by div/sqrt module):
  - mulAddA_0 (output): Value for factor A register.
  - latchMulAddA_0 (output): Asserted (=1) to latch mulAddA_0 into its corresponding register.
  - mulAddB_0 (output): Value for factor B register.
  - latchMulAddB_0 (output): Asserted (=1) to latch mulAddB_0 into its corresponding register.

Addend Input (supplied by div/sqrt module):
  - mulAddC_2 (output): 105-bit term C.

Result Output (received by div/sqrt module):
  - mulAddResult_3 (input): The 105-bit integer result (A * B + C).

Timing for Result:
  - If usingMulAdd[0] is 1 in cycle T:
    - A and B are values of factor registers in cycle T + 1.
    - C is value of mulAddC_2 in cycle T + 2.
    - The result (A * B + C) must be returned in mulAddResult_3 well before the end of cycle T + 3.

Usage Indicator:
  - usingMulAdd (bit vector): Indicates when the multiplier-adder is required, up to four clock cycles in advance.
    - usingMulAdd[0] indicates current requirement.

Latching Control:
  - When usingMulAdd[0] is 1, the A and B factor registers can only be latched under the control of latchMulAddA_0 and latchMulAddB_0.
```

--------------------------------

### ASLi Command: Lift Let-Expressions

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

This ASLi command hoists let-expressions as high as possible in an expression to facilitate later transformations, e.g., `F(G(let t = 1 in H(t)))` becomes `let t = 1 in F(G(H(t)))`.

```ASLi Command
:xform_hoist_lets
```

--------------------------------

### Generated Instruction Execution Function Signature

Source: https://github.com/chipsalliance/t1/blob/master/pokedex/README.md

The `codegen` CLI tool automatically generates a unique function for each instruction, named `Execute_<INSTRUCTION_NAME>`. This function encapsulates the instruction's core logic and receives the 32-bit instruction opcode as its primary argument, returning a `Result`.

```APIDOC
func Execute_<INSTRUCTION_NAME>(instruction: bits(32)) => Result
```