| # Copyright lowRISC contributors. |
| # Licensed under the Apache License, Version 2.0, see LICENSE for details. |
| # SPDX-License-Identifier: Apache-2.0 |
| |
| # A machine readable description of the ISA |
| # |
| # This is used for generating documentation, but also for random test |
| # and decoder generation. |
| |
| # The relative path to a YAML file defining the different instruction |
| # encoding schemes |
| encoding-schemes: enc-schemes.yml |
| |
| # Instructions are divided into a list of groups (under insn-groups). Each |
| # group has the following fields, all of which are required. |
| # |
| # key: An internal name |
| # title: A title used for documentation |
| # doc: Markdown-format documentation for the group |
| # insns: The relative path to the instructions in this group |
| # |
| # Groups appear in the documentation in list order. The insns key points at |
| # another YAML file. That file should contain a list of instruction objects. |
| # Again, the instructions appear in the documentation in list order. |
| # |
| # Each instruction object has the following fields: |
| # |
| # mnemonic: Instruction mnemonic (required) |
| # |
| # group: The instruction group in which this instruction should |
| # appear. Defaults to the first entry in the insn-groups |
| # list. (optional) |
| # |
| # rv32i: A boolean. If true, this instruction came from the RV32I ISA. |
| # Optional, defaults to false. |
| # |
| # synopsis: A longer name for this instruction. If set, used as a subtitle in |
| # the generated documentation. (optional) |
| # |
| # operands: A list of operand names. These have a special syntax, described |
| # below. (required) |
| # |
| # syntax: The syntax for the operands to the instruction. If not given, |
| # this is assumed to be the operands in order, separated by commas. |
| # If given, it should be a string with operand names in angle |
| # brackets ("<foo>, <bar>"). Any other non-whitespace characters |
| # are taken to be required literal syntax. So "foo<bar>" means "the |
| # string 'foo', followed by the bar operand". |
| # |
| # doc: Documentation for the instruction in markdown. (optional) |
| # |
| # decode: Python pseudocode for decoding instruction objects (optional) |
| # |
| # operation: Python pseudocode for the operation of the instruction (optional) |
| # |
| # note: Text that should appear in a callout banner at the top of the |
| # instruction documentation. (optional) |
| # |
| # glued-ops: A boolean. If true, the first operand in the syntax can appear |
| # immediately after the mnemonic (with no space). Optional, |
| # defaults to false. |
| # |
| # trailing-doc: Documentation that should appear after the syntax example but |
| # before the operand table. Useful for things like alternative |
| # assembly syntax, or deviations from the usual meaning of the |
| # instruction. (optional) |
| # |
| # literal-pseudo-op: This instruction is a pseudo-operation that expands into |
| # a list of underlying RISC-V operations, given as a list. |
| # Optional. Can't be specified with encoding or |
| # python-pseudo-op. |
| # |
| # python-pseudo-op: A boolean. If true then this instruction is a |
| # pseudo-operation but is complicated to describe. The |
| # assembler has some hardcoded logic to deal with it. |
| # Optional, default false. Can't be true if encoding or |
| # literal-pseudo-op is specified. |
| # |
| # lsu: An optional dictionary. If set, this is an LSU operation, |
| # described by the fields of the dictionary (defined below). |
| # |
| # straight-line: A boolean. If true, this instruction has no effect on control |
| # flow. Optional, default true. |
| # |
| # The operands field should be a list, corresponding to the operands in the |
| # order they will appear in the syntax. Each operand is either a string (the |
| # operand name) or a dictionary. In the latter case, it has the following |
| # fields: |
| # |
| # name: The name of the operand. Required and must be unique. |
| # |
| # type: The type of the operand. A string. If this can be figured out |
| # from the operand name, it is optional. See below for a list of |
| # possible operand types and the rules for recognising them |
| # automatically. |
| # |
| # doc: A fragment of markdown that documents the operand |
| # |
| # pc-rel: Only valid for immediate operands. If true, this operand is |
| # encoded relative to the current PC. Optional boolean, |
| # defaults to false. |
| # |
| # The valid operand types are as follows: |
| # |
| # gpr: The name of a general purpose register. Syntax "grs" for a |
| # source; "grd" for a destination. |
| # |
| # wdr: The name of a wide register. Syntax "wrs" for a source; |
| # "wrd" for a destination. |
| # |
| # csr: The name of a CSR. Syntax "csr" (always considered a destination) |
| # |
| # wsr: The name of a WSR. Syntax "wsr" (always considered a destination) |
| # |
| # simm: A signed immediate operand. The full syntax is simm12<<3 to mean |
| # a signed immediate of width 12 which must be divisible by 2**3 |
| # and is encoded by shifting right by 3. If there is no shift, the |
| # syntax simm12 is the same as simm12<<0. Similarly, if there is no |
| # known width (which should be inferred from any encoding scheme), |
| # it can be written as just simm or simm<<3. |
| # |
| # uimm: An unsigned immediate operand. Syntax as with simm, but starting |
| # with "uimm". |
| # |
| # enum: An immediate with weird syntax. The syntax is "enum(a,b,c,d)" |
| # where a..d are the different possible syntaxes that can be used. |
| # The values are interpreted as immediates in enumeration order (so |
| # a is 0; d is 3). |
| # |
| # option: A 1-bit immediate with weird syntax. Written "option(foo)" to |
| # mean that if the string "foo" appears then the immediate has |
| # value 1 and if it doesn't the immediate has value 0. |
| # |
| # Operand types are inferred from names as follows: |
| # |
| # grd: GPR destination |
| # grs, grs<n> GPR source |
| # wrd: WDR destination |
| # wrs, wrs<n> WDR source |
| # csr CSR name |
| # wsr WSR name |
| # imm, imm<n> Signed immediate (width <n> if specified) |
| # offset Signed immediate (unspecified width) |
| # |
| # If specified, the lsu field for an instruction should be a dictionary with |
| # the following fields: |
| # |
| # type: A string. "mem-load", "mem-store", "csr" or "wsr" |
| # |
| # target: A string or list of strings, which should be operand names. If a |
| # single string, this means that the named operand contains the |
| # target address. If the operand is an immediate, it is the target |
| # address. If the operand is a register, the value it contains is the |
| # target address. For a list of strings, the associated values are |
| # summed. |
| # |
| # bytes: An integer giving the width of the operation in bytes. This is |
| # required if type is mem-* and cannot be used otherwise. |
| |
| insn-groups: |
| - key: base |
| title: Base Instruction Subset |
| doc: | |
| The base instruction set of OTBN is a limited 32b instruction set. |
| It is used together with the 32b wide General Purpose Register file. |
| The primary use of the base instruction set is the control flow in applications. |
| |
| The base instruction set is an extended subset of [RISC-V's RV32I_Zcsr](https://riscv.org/specifications/isa-spec-pdf/). |
| Refer to the [RISC-V Unprivileged Specification](https://riscv.org/specifications/isa-spec-pdf/) for a detailed instruction specification. |
| Not all RV32 instructions are implemented. |
| The implemented subset is shown below. |
| insns: base-insns.yml |
| |
| - key: bignum |
| title: Big Number Instruction Subset |
| doc: | |
| All Big Number (BN) instructions operate on the Wide Data Registers (WDRs). |
| insns: bignum-insns.yml |
