# RISC-V Disassembler

The unit asm/riscvd decodes byte streams containing RV32IM code into listings
where each line contains an operation.

The disassembler is used mainly through "dis ( a -- )", which spits a list of
"listingsz" (default 16) lines. To continue listing, use "disn ( -- )", which
continues where the last "dis" left off.

## Listing format

Each line in the listing has a three-column format:

  <instruction addr> <disassembled instruction> <instruction word>

The columns have a fixed width and are thus aligned with each other.

The instruction address and word are shown as 32-bit hex values.

Disassembled instructions have one of the following formats:

- Instructions without arguments:

  "<mnemnonic>"

  Example: "ret"

- Instructions with registers arguments only:

  "<mnemonic> <rd>, <rs1>, <rs2>"

  <rd>: destination register
  <rs1>: source register 1
  <rs2>: source register 2

  Example: "mul x9, x10, x11"

- Instructions with registers arguments and immediates:

  "<mnemonic> <rd>, <rs1>, <imm>"

  <rd>: destination register
  <rs>: source register
  <imm>: signed decimal immediate value

  Example: "addi x9, x10, -24"

- Instructions with base-offset addressing:

  "<mnemonic> <rd/rs>, <rs1>[<imm>]"

  <rd/rs>: destination or source register, depending on the instruction
  <rs>: source register
  <imm>: signed decimal immediate value

  Example: "sb x10, x20[-8]" (x10 is source register)
  Example: "lb x10, x20[-8]" (x10 is destinatiion register)

- Upper Immediate instructions auipc and lui:

  "auipc/lui <rd>, <imm> ($<hex_imm>)"

  <rd>:      destination register
  <rs>:      source register
  <imm>:     signed decimal immediate value
  <hex_imm>: hex version of the immediate value aligned in upper immediate
             position.

  Example: "lui    x11, 305418240 ($12345000)"
  Example: "auipc  x11,  19087360 ($01234000)"

  32-bit immediate values are typically constructed by pairing a lui or auipc
  instruction with a subsequent instruction, such as jalr or addi, providing
  the lower order bits. The disassembler detects such pairings. See next bullet
  point.

- Branch instructions and instructions referencing immediate 32-bit addresses:

  "<mnemonic> <rs1>, <rs2>, <offset> -> <addr/sym>"

  <rs1>:      source register 1
  <rs2>:      source register 2
  <offset>:   pc relative offset signed decimal value
  <addr/sym>: absolute address in hex, or symbol name if the address is
              found in the dictionary.

  Example:
  "auipc  x30, 305418240 ($12345000)"
  "jalr   xZERO, x30[1656] -> $12345678"

  Example:
  "auipc  xRA, -4096 ($fffff000)"
  "jalr   xRA, xRA[1188] -> foo"

  Example:
  "bge    x10, x20, -4 -> testloop"

  Example:
  "lui    x11, 305418240 ($12345000)"
  "addi   x11, x11, 1656 -> $12345678"

## Supported ISAs

- RV32I Base instruction set.
- RV32M Standard Integer Multiplication and Division instruction extension.

## Pseudo-Instructions

The following pseudo-instructions are detected:

- ret = jalr xZERO, xRA[0]
- mv <rd> <rs> = addi rd, rs, 0
- nop = addi xZERO, xZERO, 0

