Skip to content

Move more useful information higher on instruction display page #659

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ThinkOpenly opened this issue Apr 24, 2025 · 3 comments · Fixed by #719
Closed

Move more useful information higher on instruction display page #659

ThinkOpenly opened this issue Apr 24, 2025 · 3 comments · Fixed by #719
Assignees
Labels
enhancement New feature or request

Comments

@ThinkOpenly
Copy link
Collaborator

Is your feature request related to a problem? Please describe.
If the primary audience for the RISC-V ISA Manual instruction pages is programmers/engineers, then the order of the information displayed could be better. Currently, the information is displayed in this order:

  • name
  • long name
  • defining extension/version
  • containing profiles
  • encoding
  • assembly syntax
  • synopsis
  • valid access modes
  • decode variables (how to extract fields from the opcode)
  • implementation (IDL/Sail code)
  • exceptions

Describe the solution you'd like

  • name
  • long name
  • assembly syntax
  • synopsis
  • execution
  • exceptions
  • encoding
  • decode variables
  • defining extension (although a better use of space would be to the right of the name)
  • valid access modes
  • containing profiles

Additional context
Image

@ThinkOpenly ThinkOpenly added the enhancement New feature or request label Apr 24, 2025
@kbroch-rivosinc
Copy link
Collaborator

kbroch-rivosinc commented Apr 25, 2025

Here's a table to help visualize this change:

Before After
1-name 1-name
2-long name 2-long name
3-defining ext/ver 6-assembly syntax
4-containing profiles 7-synopsis
5-encoding 10-implementation (IDL/Sail)
6-assembly syntax 11-exceptions
7-synopsis 5-encoding
8-valid access modes 9-decode variables
9-decode variables 3-defining ext/ver
10-implementation (IDL/Sail) 8-valid access modes
11-exceptions 4-containing profiles

I don't have a strong opinion on the ordering but more that we should condense some of the output to make all of it close to fitting on a single page. Right now as you have shown https://riscv-software-src.github.io/riscv-unified-db/manual/html/isa/isa_20240411/insts/bge the worst is "containing profiles" which can be upwards of 15 LOC which takes up 1/2 page.

Rather then listing one profile per line, I would just have a single line of comma separate profiles and an abbreviation for "Mandatory"

ex: "in profiles: RVA20S64 (M), RVA20U64 (M), RVA22S64 (M) (M = Mandatory)"

@dhower-qc
Copy link
Collaborator

  1. I suggest we keep implementation (IDL/Sail) after encoding/decode variables since the implementation is going to reference those fields.
  2. For the profiles, we could also display it in a table format (with the profile names rotated so they are vertical)
RVA20S64 RVA20U64 RVA22S64 ...
M M M ...

@ThinkOpenly
Copy link
Collaborator Author

  1. I suggest we keep implementation (IDL/Sail) after encoding/decode variables since the implementation is going to reference those fields.

Moving "decode variables" up above "execution":

  1. name
  2. long name
  3. assembly syntax
  4. synopsis
  5. decode variables
  6. execution
  7. exceptions
  8. encoding
  9. defining extension (although a better use of space would be to the right of the name)
  10. valid access modes
  11. containing profiles
  1. For the profiles, we could also display it in a table format (with the profile names rotated so they are vertical)>
    RVA20S64 RVA20U64 RVA22S64 ...
    M M M ...

I thought about suggesting a table, but was worried its width would be unbounded over time.

I'm OK with a list, or lists:

Optional: RVA20S64, RVA20U64
Mandatory: RVA22S64, ...

Lists will wrap as needed to fit the display.

@kbroch-rivosinc kbroch-rivosinc self-assigned this May 1, 2025
kbroch-rivosinc added a commit that referenced this issue May 2, 2025
fixes #659
move more important/useful info higher up# <type>(<scope>): <short summary>
kbroch-rivosinc added a commit that referenced this issue May 2, 2025
fixes #659
move more important/useful info higher up# <type>(<scope>): <short summary>
kbroch-rivosinc added a commit that referenced this issue May 5, 2025
fixes #659
move more important/useful info higher up# <type>(<scope>): <short summary>
kbroch-rivosinc added a commit that referenced this issue May 7, 2025
fixes #659
move more important/useful info higher up# <type>(<scope>): <short summary>
github-merge-queue bot pushed a commit that referenced this issue May 7, 2025
fixes #659
move more important/useful info higher up# <type>(<scope>): <short
summary>

still WIP, I haven't turned the containing profiles into a list, just
moved it to the bottom.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants