From ebfc40b4823fabe29a7d199c0ba955085560c7fd Mon Sep 17 00:00:00 2001 From: Anatoly Parshintsev Date: Mon, 2 Mar 2026 15:28:24 +0000 Subject: [PATCH] [snippy] fix formatting of llvm-ie and llvm-snippy documentation source code --- llvm/tools/llvm-snippy/docs/index.rst | 33 ++++++---- llvm/tools/llvm-snippy/docs/llvm-ie.rst | 81 ++++++++++++++++++------- 2 files changed, 79 insertions(+), 35 deletions(-) diff --git a/llvm/tools/llvm-snippy/docs/index.rst b/llvm/tools/llvm-snippy/docs/index.rst index c522b4c8120f..f3d4b3466ebb 100644 --- a/llvm/tools/llvm-snippy/docs/index.rst +++ b/llvm/tools/llvm-snippy/docs/index.rst @@ -13,9 +13,13 @@ Snippy Documentation (|release|) Overview ======== -LLVM-snippy is a random test generator (RTG) based on LLVM. It currently only supports RISC-V, but is potentially target-independent. +LLVM-snippy is a random test generator (RTG) based on LLVM. It currently only +supports RISC-V, but is potentially target-independent. -LLVM-snippy generates snippets |nbsp| -- |nbsp| sequences of randomly selected machine instructions with randomly selected registers, immediates, and other attributes that you configure via `histograms <#histogram>`__ and organize via `sections <#sections>`__. +LLVM-snippy generates snippets |nbsp| -- |nbsp| sequences of randomly selected +machine instructions with randomly selected registers, immediates, and other +attributes that you configure via `histograms <#histogram>`__ and organize via +`sections <#sections>`__. .. important:: @@ -283,7 +287,9 @@ Following is an example of the configuration layout that contains: march: "rv64ifc_zifencei" model-plugin: None -You may try layout-example.yaml from examples on github or from yml/ and share/examples/ folder in this release as follows and disassemble to see generated snippet. +You may try layout-example.yaml from examples on github or from yml/ and +share/examples/ folder in this release as follows and disassemble to see +generated snippet. :: @@ -291,9 +297,12 @@ You may try layout-example.yaml from examples on github or from yml/ and share/e -o layout-example-1000.elf objdump -d layout-example-1000.elf >& layout-example-1000.dis -As set by the ``rx`` and ``rw`` access parameters ``sections``, snippy will write the code to section ``1``, and loads/stores will go to/from section ``2``. +As set by the ``rx`` and ``rw`` access parameters ``sections``, snippy will +write the code to section ``1``, and loads/stores will go to/from section +``2``. -Better always specify seed for reproducibility. If you dont, then snippy will show you which was used. +Better always specify seed for reproducibility. If you dont, then snippy will +show you which was used. In this example, ``options`` are: @@ -1576,8 +1585,8 @@ reserved at all (default): *ancillary* ones. Ditto instructions that initialize registers emitted when the **-init-regs-in-elf** option is specified. -Consider an example where we want to reserve registers X10 and X11 for reads and modification by -primary instructions: +Consider an example where we want to reserve registers X10 and X11 for reads +and modification by primary instructions: .. _soft-reserve-x1011: @@ -4134,11 +4143,11 @@ The most basic **Svinval** tests can be generated by the following config: Replace supervisor instructions with **HINVAL_FVMA** and **HINVAL_VVMA** to generate test for hypervisor svinval instructions -However, semantics of the instructions from **Svinval** extension depend on the source -registers used (**X0** or other). And the above config chooses source registers -randomly. Meaning that probability of generating **X0** as at least one operand is -``2/32``. To increase the probability of generating **X0** as a source register you -can explicitly reserve other registers. We will also add +However, semantics of the instructions from **Svinval** extension depend on the +source registers used (**X0** or other). And the above config chooses source +registers randomly. Meaning that probability of generating **X0** as at least +one operand is ``2/32``. To increase the probability of generating **X0** as a +source register you can explicitly reserve other registers. We will also add `Operands Reinitialization Config <#operands-reinitialization>`__ to specify values that are written to source registers: diff --git a/llvm/tools/llvm-snippy/docs/llvm-ie.rst b/llvm/tools/llvm-snippy/docs/llvm-ie.rst index 7c86781950e4..1a9d7c313640 100644 --- a/llvm/tools/llvm-snippy/docs/llvm-ie.rst +++ b/llvm/tools/llvm-snippy/docs/llvm-ie.rst @@ -4,22 +4,36 @@ LLVM-IE Documentation Overview ======== -``llvm-ie`` is a utility tool designed to conveniently extract instructions from various computer architectures supported by LLVM based on specific criteria. +``llvm-ie`` is a utility tool designed to conveniently extract instructions +from various computer architectures supported by LLVM based on specific +criteria. -In LLVM, a wide range of backend components—including instructions, registers, and scheduling models—is defined in TableGen (.td) files. The build process compiles these descriptions into the C++ data structures that form the backend's internal representation. +In LLVM, a wide range of backend components—including instructions, registers, +and scheduling models—is defined in TableGen (.td) files. The build process +compiles these descriptions into the C++ data structures that form the +backend's internal representation. -``llvm-ie`` specifically queries the information derived from instruction definitions, which contains rich details such as whether an instruction is a branch, a call, or accesses memory. +``llvm-ie`` specifically queries the information derived from instruction +definitions, which contains rich details such as whether an instruction is a +branch, a call, or accesses memory. -Initially, ``llvm-ie`` was created to extract RISC-V instructions belonging to specific RISC-V extensions. However, its functionality was later expanded to include architecture-independent filters and a modular design for adding new architecture backends. +Initially, ``llvm-ie`` was created to extract RISC-V instructions belonging to +specific RISC-V extensions. However, its functionality was later expanded to +include architecture-independent filters and a modular design for adding new +architecture backends. -While the tool was originally developed as a helper utility for ``llvm-snippy``, which uses it to eliminate boilerplate code, we believe ``llvm-ie`` can be useful in other scenarios as well. +While the tool was originally developed as a helper utility for +``llvm-snippy``, which uses it to eliminate boilerplate code, we believe +``llvm-ie`` can be useful in other scenarios as well. Running llvm-ie =============== -To use ``llvm-ie``, you must explicitly specify the target backend using the ``-arch`` option. +To use ``llvm-ie``, you must explicitly specify the target backend using the +``-arch`` option. -For example, to list instructions corresponding to the "A" extension for the RISC-V architecture, use the following command: +For example, to list instructions corresponding to the "A" extension for the +RISC-V architecture, use the following command: .. code-block:: bash @@ -33,8 +47,10 @@ Target-Independent Options Currently, ``llvm-ie`` supports the following architecture-independent filters: -* ``-memory-access``: Filters for instructions that perform memory accesses (loads/stores). -* ``-control-flow``: Filters for instructions that affect control flow (jumps, branches, calls). +* ``-memory-access``: Filters for instructions that perform memory accesses + (loads/stores). +* ``-control-flow``: Filters for instructions that affect control flow + (jumps, branches, calls). Target-Dependent Options ======================== @@ -44,33 +60,52 @@ RISC-V Options Currently, ``llvm-ie`` supports the following RISC-V-specific options: -* ``-riscv-ext``: Filters instructions by RISC-V extensions using expression logic. -* ``-rv32``: Restricts the output to instructions available in the RV32 base instruction set. -* ``-rv64``: Restricts the output to instructions available in the RV64 base instruction set. +* ``-riscv-ext``: Filters instructions by RISC-V extensions using expression + logic. +* ``-rv32``: Restricts the output to instructions available in the RV32 base + instruction set. +* ``-rv64``: Restricts the output to instructions available in the RV64 base + instruction set. Extension Expressions --------------------- -The ``-riscv-ext`` option is the most powerful, as it allows you to get instructions belonging to specific RISC-V extensions. This option takes an expression composed of RISC-V extension names as operands and three basic operations: +The ``-riscv-ext`` option is the most powerful, as it allows you to get +instructions belonging to specific RISC-V extensions. This option takes an +expression composed of RISC-V extension names as operands and three basic +operations: -* ``+`` : Union (OR) -* ``-`` : Exclusion (NOT) -* ``&`` : Intersection (AND) +* ``+`` : Union (OR) +* ``-`` : Exclusion (NOT) +* ``&`` : Intersection (AND) -You can draw an analogy to set algebra: extension names are sets, and the basic operations ``+``, ``-``, and ``&`` correspond to union, set difference, and intersection, respectively. +You can draw an analogy to set algebra: extension names are sets, and the basic +operations ``+``, ``-``, and ``&`` correspond to union, set difference, and +intersection, respectively. Operation Notes and Caveats ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. **Supported Operations:** Only these three operations (``+``, ``-``, ``&``) are currently supported. Parentheses and other operations are not available. -2. **Precedence and Syntax:** The ``&`` operator has higher precedence than ``+`` and ``-``. To simplify the parser, the ``&`` operator must be written without spaces between its operands (e.g., ``"c&d"`` instead of ``"c & d"``). -3. **Parser Behavior:** The current parser is designed to be permissive and may output extra instructions. This was a deliberate decision to avoid accidentally filtering out required instructions. For example, when asking for the "V" extension, ``llvm-ie`` might also include instructions that require both the "V" and "F" extensions to be present. - To get a more precise output, you can use more complex expressions. For instance, to request the "V" extension but exclude instructions that also require the "F" extension, you could use: +1. **Supported Operations:** Only these three operations (``+``, ``-``, ``&``) + are currently supported. Parentheses and other operations are not + available. +2. **Precedence and Syntax:** The ``&`` operator has higher precedence than + ``+`` and ``-``. To simplify the parser, the ``&`` operator must be written + without spaces between its operands (e.g., ``"c&d"`` instead of + ``"c & d"``). +3. **Parser Behavior:** The current parser is designed to be permissive and + may output extra instructions. This was a deliberate decision to avoid + accidentally filtering out required instructions. For example, when asking + for the "V" extension, ``llvm-ie`` might also include instructions that + require both the "V" and "F" extensions to be present. + To get a more precise output, you can use more complex expressions. For + instance, to request the "V" extension but exclude instructions that also + require the "F" extension, you could use: .. code-block:: bash llvm-ie -arch=riscv -riscv-ext "v - f" - + Usage Examples ============== @@ -79,7 +114,7 @@ Usage Examples # Instructions requiring both C and D extensions llvm-ie -arch=riscv -riscv-ext "d&c" - # Vector instructions excluding D and F extensions + # Vector instructions excluding D and F extensions llvm-ie -arch=riscv -riscv-ext "v - d - f" # Compressed instructions that access memory