RISCV64 assembly opcode documentation - update

[five-embeddev]

This is an extension of the pull request by @SiyaoIsHiding

#5121

Closes #4584

Instead of scraping the HTML, I've used a file opcodes.yaml which is generated from a number of sources, the RISC-V documentation in tex or adoc, the RISC-V opcodes repositories, the RISC-V assembly manual and even the RISC-V ISA simulator.

The script will to download opcodes.yaml and generate documentation from it.

I've also made some fixes and additions to the opcodes yaml data so we can make meaningful quick references. The most visible one is the addition of psuedo instruction to base ISA mapping.

All of the documents are extracted from the official RISC-V ISA manuals. These are not just targeted at programmers, but also the processor developers, so the descriptions may be verbose from a programming point of view.

The linked html is now hosted as a github io page. The scripts used to generate it are also all included in that github repo associated with those github pages. The version of the RISC-V spec is clearly identified in the URL.

[partouf]

The definition of fmsub.h in opcodes.yaml is

  fmsub.h:
    opcode:
    - fmsub.h
    - rd
    - rs1
    - rs2
    - rs3
    - rm
    - 26..25=2
    - 6..2=0x11
    - 1..0=3
    opcode_group: zfh
    opcode_args: *22
    iss_code:
    - require_either_extension(EXT_ZFH, EXT_ZHINX);
    - require_fp;
    - softfloat_roundingMode = RM;
    - WRITE_FRD_H(f16_mulAdd(FRS1_H, FRS2_H, f16(FRS3_H.v ^ F16_SIGN)));
    - set_fp_exceptions;

As opposed to others, it doesn't have a main_desc, where the ISA value is taken from, but it does have an opcode_group (zfh), I wonder if it shouldn't be saying ISA: zfh ? (I have no idea what it actually means)

fmv.h.z also have the opcode_group: zfh, but that one actually has a main_desc and the description, so I don't know what the best option would be..

[five-embeddev]

You are correct. It should say "(ISA: zfh)". zfh means "Standard Extension for 16-bit Half-Precision Binary Floating-Point Instructions". To generate opcodes.yaml, I'm using the most recent opcodes metadata files, but the html from an older ratified spec version, so it's probably missing fmsub.h in the older documentation file. fmv.h was found in the documentation so main_desc is present.

I'm not sure if any compiler will generate code for the zfh extension.

[partouf]

this is now live

Although it is sometimes a bit confusing, for example for https://godbolt.org/api/asm/riscv64/sd - it mentions SD, but the description is about LW

Is that fixable?

[five-embeddev]

Hi Patrick,

All of the descriptions are automatically extracted from the RISC-V official user manual. The tend to only write per instruction group, for example SD is defined in the RV64 load and store instruction section, that's why it starts with LD:
https://five-embeddev.github.io/riscv-docs-html//riscv-user-isa-manual/Priv-v1.12/rv64.html#load-and-store-instructions

Having said that, I think it is fixable. The easiest way to fix it is to write some custom descriptions for cases like this where the user manual is not clear.

[partouf]

Ahh I see. Unfortunate. Let's just keep it this way unless someone starts complaining