Migration to new file-naming and instruction category scheme

[neelgala]

This PR is motivated by the discussion in issue #100 and addresses the concerns raised there.
It is a backwards incompatible PR, and any one depending on this repo or its artifacts will need to
bump their environment (with minimal effort) after this PR is merged.

I have tried my best to split the PR in smaller commits to easier review. However, the individual commits themselves if checked out will be broken.

Brief summary of changes:

• The file names and instruction placement now follow a guideline/policy outlined in the README
• Python script is updated to parse the new format and generate the same set of artifacts as before.
• Makefile file has been updated
• Compressed opcodes have been cleaned up
• A very detailed README describing whats happening and how.
• significantly automated latex-table generation and avoids hardcoding as much as possible.
• outputs of this PR (encoding.h and latex-tables) have been compared to the equivalent artifacts from the the master branch and found to be same except in places described below.

This PR can also close issues: #8, #19, #32, #61, #89, #100

Changes in Artifacts that need to be reviewed:

• encoding.h :

  • The new encoding.h generated from the PR will no longer include pseudo-ops as was
    done earlier. This is because there exist pseudo-ops which have the same mnemonics as the regular
    instruction but differ is just few bits. Eg. slli in RV32 and RV64 have the same mnemonic is both,
    however in RV32 slli is treated as a pseudo_op of RV64::slli with bit 25 set to 0. Thus it is
    impossible to include both variants of the instruction. Also spike doesn't make use the
    pseudo-ops.
  • c.nop instruction has a different mask as compared to before because it now includes the hints
    encodings as well. Previously only c.nop 0 was only considered as legal instruction. Now, the
    immediate value rangin from 0-31 will be considered as a c.nop intruction which is what the
    spec suggests as well
  • Also now the instructions in encoding.h will be alphabetically ordered.

• latex-tables:

  • The latex-code for tables for unpriv and priv have changed slightly. Earlier they were manually
    drafted and hard-coded in a very wierd fashion. In this PR, all the latex tables have 33
    columns: 32 columns for the encoding (1bit per column) and one column for the instruction name.
    This does not affect rendering of the tables in the pdf - manually verified.
  • All unpriv and priv tables are rendered without any changes, except for the RV32I table. Here
    the change is mostly with the ordering of instructions. Since, SLLI, SRAI and SRLI are
    pseudo_ops in rv32_i they are processed at the end and thus appear at the end of the table
    instead of after ANDI. Same argument goes for FENCE.TSO and PAUSE insrtuctions.
  • The ordering of instructions in RV32Zfh tables has changed slightly owing to the inclusion of
    rv_d_zfh and rv_q_zfh extensions according to the new convention.

NEED HELP

Need help in understanding the following:

• I am not sure how the opcodes-custom instructions are meant to be interpreted ? Are all those
  variants of custom0 required ? Can we instead just have 4 entries

  custom0 f7, rs2, rs1, f3, rd 6..2=0x02 1..0=3
  custom1 f7, rs2, rs1, f3, rd 6..2=0x0A 1..0=3
  custom2 f7, rs2, rs1, f3, rd 6..2=0x16 1..0=3
  custom3 f7, rs2, rs1, f3, rd 6..2=0x1E 1..0=3
  

  Though, I am still not sure what value this brings in this project !

• The instructions in opcodes-rvv-pseudo don't seem to be actual pseudo ops. These instructions only
  have a different name but have the exact same encoding as far as I can see (no hardwiring of like
  other pseudo ops). Do we need them ?

[a0u]

I am not sure how the opcodes-custom instructions are meant to be interpreted ? Are all those
variants of custom0 required ? Can we instead just have 4 entries :

custom0 f7, rs2, rs1, f3, rd 6..2=0x02 1..0=3
custom1 f7, rs2, rs1, f3, rd 6..2=0x0A 1..0=3
custom2 f7, rs2, rs1, f3, rd 6..2=0x16 1..0=3
custom3 f7, rs2, rs1, f3, rd 6..2=0x1E 1..0=3

The custom variants are generic instruction formats for the RoCC (Rocket Custom Coprocessor) extension, where bits 14:12 indicate the presence of operands rd/rs1/rs2, respectively.
For example, custom0.rd.rs1 means that the instruction reads rs1 and writes rd.

The decode logic in Rocket, Boom, and a few other cores rely on separate bit-patterns being emitted for each variant:

• https://github.com/chipsalliance/rocket-chip/blob/286df3f2bb28b5fa3ca109014e6ad33fac0e2f18/src/main/scala/rocket/IDecode.scala#L429-L453
• https://github.com/riscv-boom/riscv-boom/blob/ad64c5419151e5e886daee7084d8399713b46b4b/src/main/scala/exu/decode.scala#L419-L444

[aswaterman]

The instructions in opcodes-rvv-pseudo don't seem to be actual pseudo ops. These instructions only
have a different name but have the exact same encoding as far as I can see (no hardwiring of like
other pseudo ops). Do we need them ?

For the most part, these are aliases: the instructions were renamed during the standardization process, but we chose to retain the old names as aliases for compatibility. See, for example, the note at the beginning of this section: https://github.com/riscv/riscv-v-spec/blob/d659c8d91b6ed2a3be41e1f58f868c20f0f161b9/v-spec.adoc#152-vector-count-population-in-mask-vcpopm

[neelgala]

@aswaterman ok will make those changes for the rvv-pseudo ops. Will rename the file as rv_v_aliases and use the $pseudo_op syntax as applicable. I realized I also need to fix the github-actions for this PR.

regarding, the custom opcodes - I understand they are RoCC compliant but do they need to reside here since RoCC is not a RVI adopted/supported spec (hence their are niether ratified/unratified). If they do need to sit here: then they are not parse-able in their current format and will need changes. For example:

custom0.rd.rs1.rs2 rd rs1 imm12 14..12=7 6..2=0x02 1..0=3

is overspecified - rs2 and imm12 have overlapping bits and the parser will complain with an error.

[neelgala]

@aswaterman changes for vector aliases done and also fixed the github actions yaml. I think its ready to merge. I will come back with the custom opcodes fix in a separate PR

[aswaterman]

@neelgala @a0u My preference is to delete the RoCC instructions from this repo. Their presence is a historical artifact. These days, we'd reject PRs to add other folks' custom instructions, and so we shouldn't be privileging our Berkeley tech.

(It's OK that Rocket's/BOOM's Instructions.scala can no longer be directly generated from this codebase. In the long run, it's better to treat them as semi-automatically generated files, so that these repositories become less tightly coupled.)

[neelgala]

@aswaterman done. removed custom opcodes.

[aswaterman]

Thanks. I will review the rest of this PR shortly.

[neelgala]

@aswaterman just setting a reminder on this. Let me know if I can do something to ease the review on this ? Also I request : if you could merge this PR before other PRs so I avoid re-factoring those again here.

[neelgala]

@aswaterman I've made the required changes. Also added the spinalhdl support currently on master. I have locally checked the conflicts and you should be picking changes made on my PR (the parse_opcodes file goes away and the make-targets are redone based on new cli). I am unable to resolve these at my end - let me know if I can help fix it.

[aswaterman]

@neelgala Merged, but I just noticed you deleted support for Go, i.e., make inst.go. Can you make a follow-on PR to add that back?

[neelgala]

will raise a PR asap.