thinkopenly / sail-riscv Goto Github PK

In the Sail definition ("model/riscv_insts_base.sail"), the opcode encoding for "FENCE.I" is defined:

mapping clause encdec = FENCEI()
  <-> 0b000000000000 @ 0b00000 @ 0b001 @ 0b00000 @ 0b0001111

... every bit is constant.

But, the current RISC-V ISA specification (20191213) says:

The unused fields in the FENCE.I instruction, imm[11:0], rs1, and rd, are reserved for finer-grain fences in future extensions. For forward compatibility, base implementations shall ignore these fields, and standard software shall zero these fields.

There needs to be some way to know that for these fields, they are currently expected to be zero, but that may change in the future.

An example from a downstream project, "binutils", respects the reserved fields for the purposes of decode (in "include/opcode/riscv-opc.h"):

#define MASK_FENCE_I  0x707f

If the entire opcode was constant, the mask would be like "EBREAK" (and others):

#define MASK_EBREAK  0xffffffff

It would be really nice to be able to extract human-readable function descriptions from the respective Sail definitions. This text may not yet readily exist for all instructions, but it certainly exists for many in what may or may not be easily extracted prose in the RISC-V Instruction Set Manual. One suggested implementation is to use "doc-comments":

/*!
 * The target address is obtained by adding the sign-extended 12-bit
 * I-immediate to the register rs1, then setting the
 * least-significant bit of the result to zero. The address of the
 * instruction following the jump (pc+4) is written to register rd.
 * Register x0 can be used as the destination if the result is not
 * required.
 */
union clause ast = RISCV_JALR : (bits(12), regidx, regidx)

Instructions like vle16.v have an optional "mask" operand. So, both of the following are valid:

  vle16.v vd,(rs1),vm
  vle16.v vd,(rs1)

This issue is to get this properly parsed, and to come up with a reasonable representation in JSON.

Some functions (function clause execute) call other functions (function).

Currently the latter function definitions are not extracted.

These should be extracted for completeness. These should also be emitted in JSON, possibly as an independent top-level entity containing an array of these type of functions.

Example from model/riscv_insts_vext_mem.sail:

function process_vlxseg (nf, vm, vd, EEW_index_bytes, EEW_data_bytes, EMUL_index_pow, EMUL_data_pow, rs1, vs2, num_elem, mop) = {
[...]
}
[...]
function clause execute(VLUXSEGTYPE(nf, vm, vs2, rs1, width, vd)) = {
[...]
  process_vlxseg(nf_int, vm, vd, EEW_index_bytes, EEW_data_bytes, EMUL_index_pow, EMUL_data_pow, rs1, vs2, num_elem, 1)
}

Coping a currently open issue from upstream. In commit 401e5cb, I implemented a (bad) workaround, but this needs to be fixed as described in the upstream issue (hopefully).

riscv#112

Instruction formats should be formalized in some consistent way.
A cheap, but less robust means is via attribute:

$[format I]
mapping clause encdec = RISCV_JALR(imm, rs1, rd)
  <-> imm @ rs1 @ 0b000 @ rd @ 0b1100111

In talking with Alasdair Armstrong, he suggested a much better way that requires a lot more effort. Per an email from Alasdair:

[...] maybe the best thing would be to do encdec in two steps, i.e. add a data-structure like:

union instruction_format = {
    RFormat : { funct7: bits(7), rs2 : regidx, rs1: regidx, funct3 : bits(3), rd : regidx, opcode : bits(7) }
    IFormat : { imm : bits(12), rs1 : regidx, func3 : bits(3), rd : regidx, opcode : bits(7) }
    /* and so on */
}

then have two mappings bits(32) <-> instruction_format and instruction_format <-> ast.

Currently, fairly innocuous function names are used to mark an instruction as part of an extension:

mapping clause encdec = RISCV_FMINM_S(rs2, rs1, rd) if haveZfa()

A parser would have to know that a function name like "have*" might distinguish an extension, but there are no guarantees.

One suggested solution:

mapping clause encdec = RISCV_FMINM_S(rs2, rs1, rd) if extension("Zfa")

At least using a consistent function name establishes a namespace in which extensions can be enumerated, something like:

val extension : (string) -> bool

function extension(ext) = {
  match ext {
    "Atomics" => misa.A() == 0b1,
    "Zfa" => true,
    "Zfh" => (misa.F() == 0b1) & (mstatus.FS() != 0b00),
    "Zicond" => true,
    _ => false
  }
}

Registers are defined in the Sail code in various places. These definitions should only manifest if the encapsulating extension(s) are enabled, and it should be easily determined when parsing in which extension(s), if any, each register is encapsulated.

Many extensions include discriminators which clearly tag instructions which are included in the extension:

mapping clause encdec = RISCV_FMINM_S(rs2, rs1, rd)     if haveZfa()

(Note that issue #4 suggests a more robust tagging method.)

Not all extensions are well-tagged, however, especially if they are ratified and included in the "base ISA":

/* This file specifies the compressed instructions in the 'C' extension. */
[...]
mapping clause encdec_compressed = C_LW(ui6 @ ui53 @ ui2, rs1, rd)

It would be useful to include tags for these instructions as well, hopefully in a robust way as suggested in issue #4.

It would be really nice to be able to extract the names of the respective instructions from their definitions. One suggestion is to use "attributes":

$[name jump and link register]
union clause ast = RISCV_JALR : (bits(12), regidx, regidx)