| # 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". |
| # |
| # 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. |
| # |
| # doc: Documentation for the instruction in markdown. (optional) |
| # |
| # note: Text that should appear in a callout banner at the top of the |
| # instruction documentation. (optional) |
| # |
| # errs: A list of errors that might be signalled by this instruction. |
| # This should be a list of strings, each of which is interpreted as |
| # markdown. |
| # |
| # 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. |
| # |
| # cycles: A positive integer, giving the number of cycles that the |
| # instruction takes to execute. Optional, default 1. |
| # |
| # iflow: An optional list of dictionaries. If set, this describes the |
| # information flow properties of the instruction according to the |
| # dictionaries' fields (defined below). The default is to assume all |
| # source registers flow to all destination registers, the new |
| # destination register value does not depend on the old value, and |
| # that there is no information flow to or from memory, flags, or |
| # special registers. |
| # |
| # 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. |
| # |
| # abbrev: An optional shortened name for the operand. If given, it |
| # must not match the short name or full name of any other |
| # operand. |
| # |
| # 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 allowed values for the "type" field are: |
| # |
| # grs A source GPR. Read and not written. |
| # |
| # grd A destination GPR. Written and not read. |
| # |
| # wrs A source WDR. Read and not written. |
| # |
| # wrd A source WDR. Written and not read. |
| # |
| # wrb A WDR that is both read and written. |
| # |
| # csr A CSR (may be read and/or written) |
| # |
| # wsr A WSR (may be read and/or written) |
| # |
| # 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. The syntax simm12 means the same as |
| # simm12<<0. If there is no known width (which should be inferred from |
| # any encoding scheme), the type can be written as just simm or |
| # simm<<3. |
| # |
| # uimm An unsigned immediate operand. The full syntax is 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 (type grd) |
| # grs, grs<n> GPR source (type grs) |
| # wrd: WDR destination (type wrd) |
| # wrs, wrs<n> WDR source (type wrs) |
| # csr CSR (type csr) |
| # wsr WSR (type wsr) |
| # imm, imm<n> Signed immediate (width <n> if specified) (type simm or simm<n>) |
| # offset Signed immediate (unspecified width) (type simm) |
| # |
| # Operands ending in _inc are special: if an operand name has the form |
| # <foo>_inc, it is assumed that a) the operand has the "option" type, b) |
| # another operand is a GPR and has the name <foo>, and c) the instruction |
| # increments the <foo> register if <foo>_inc=1. |
| # |
| # If specified, the lsu field for an instruction should be a dictionary with |
| # the following fields: |
| # |
| # type: A string. "mem-load", "mem-store", "wsr-load", "wsr-store" or "csr" |
| # |
| # 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. |
| # |
| # |
| # If specified, the iflow field for an instruction should be a list of |
| # dictionaries, each specifying an information flow "rule". Rules have the |
| # following fields: |
| # |
| # to: A list of strings, representing the locations that receive information |
| # from locations in the "from" list (i.e. information-flow sinks). Every |
| # location updated by the instruction should be in the "to" list. Each |
| # string should be either: |
| # - a register operand name such as "grd" or "wrs1" |
| # - "wref-<reg operand name>" for instructions where a WDR is indirectly |
| # accessed via a GPR operand |
| # - "dmem" for memory, which is treated as a monolithic block |
| # - "acc" or "mod" to represent special registers ACC and MOD |
| # - a flag (represented as "<flag group>-<flag>" e.g. fg0-all, flags-c), where: |
| # * <flag group> can be either "fg0", "fg1", or (if the instruction has |
| # a `flag_group` operand) simply "flags" to select that flag group |
| # * <flag> can be l, c, m, z, or "all". |
| # |
| # from: List of strings with the same format as the "to" field; represents |
| # the locations that information in this rule is flowing from (i.e. |
| # information-flow sources). If the "from" list is empty, that means |
| # the locations in the "to" list are updated to constants, and their |
| # values no longer depend on their previous values. |
| # |
| # test: Optional list of strings specifying when this rule applies. The rule |
| # only applies if all tests in the list are true. Each list item is a |
| # string of the form "<operand> <comparison> <value>", where: |
| # - <operand> is the name of one of the instruction's operands |
| # - <comparison> is "==", "!=", ">=", or "<=" |
| # - <value> is an integer that is within the allowed range of values |
| # for this operand (for instance, for a flag group it would be 0 or 1, |
| # and for a register it would be between 0 and 31). |
| |
| 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. |
| Refer to the [RISC-V Unprivileged Specification](https://github.com/riscv/riscv-isa-manual/releases/download/Ratified-IMAFDQC/riscv-spec-20191213.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 |
