[PATCH] gas/doc: RISC-V: Fix Type U instruction

[Javier Mora <cousteaulecommandant@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1381 bytes --]

The RISC-V Type U instruction (.insn u) at
https://sourceware.org/binutils/docs/as/RISC_002dV_002dFormats.html
shows an incorrect format for the `simm20` immediate.  The bits should
be sequentially arranged (simm20[19:0]) which is how `gas` treats
them, but instead they appear in the Type J format
(simm20[20|10:1|11|19:12]) in the documentation.
Additionally, I changed all occurrences of `opcode6` to `opcode7`
since the opcode has 7 bits, not 6.

(This is my first patch on this project, so my apologies if the format
is not correct!)

As a side note, and speaking of off-by-one errors, I don't quite like
the bit numbering in the instructions: the numbers appear in the ASCII
box diagrams directly under the field boundaries; they should either
appear slightly to the left (indicating that they refer to the first
bit of the next field) or to the right in the case of the leftmost 31;
otherwise it becomes a little confusing (especially since the leftmost
field appears to have one bit less).
Alternatively, you may go full "Python style limits" and
systematically write the index of the bit to the left of the boundary
-- i.e., replace all those 31 with 32 (and the 30 in Type J with 31).
Otherwise the leftmost field is "different".
A third, more explicit but maybe too verbose option is to include both
boundaries in every field.

Thanks in advance.
Keep up the good work!

[-- Attachment #2: 0001-gas-doc-RISC-V-Fix-U-insn-replace-opcode6-7.patch --]
[-- Type: text/x-patch, Size: 4950 bytes --]

From cd25864a6e215323cd68cdfa0fb23313897415da Mon Sep 17 00:00:00 2001
From: Javier Mora <cousteaulecommandant@gmail.com>
Date: Fri, 24 May 2024 20:10:05 +0200
Subject: [PATCH] gas/doc: RISC-V: Fix U insn; replace opcode6->7

The type U RISC-V instruction format in gas/doc/c-riscv.texi shows the
bit arrangement of the simm20 immediate that belongs to the J type;
it should be simm20[19:0] (or simply simm20).
The current behavior of `gas` matches the proposed change.

Additionally, the opcode is called `opcode6` despite of having 7 bits.
Rename it to `opcode7`.
---
 gas/doc/c-riscv.texi | 44 ++++++++++++++++++++++----------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/gas/doc/c-riscv.texi b/gas/doc/c-riscv.texi
index 7484a71798a..1b5e834fc69 100644
--- a/gas/doc/c-riscv.texi
+++ b/gas/doc/c-riscv.texi
@@ -435,7 +435,7 @@ instruction formats:
 
 @display
 @multitable @columnfractions .15 .40
-@item opcode @tab Unsigned immediate or opcode name for 7-bits opcode.
+@item opcode7 @tab Unsigned immediate or opcode name for 7-bits opcode.
 @item opcode2 @tab Unsigned immediate or opcode name for 2-bits opcode.
 @item func7 @tab Unsigned immediate for 7-bits function code.
 @item func6 @tab Unsigned immediate for 6-bits function code.
@@ -549,62 +549,62 @@ The following table lists the RISC-V instruction formats that are available
 with the @samp{.insn} pseudo directive:
 
 @table @code
-@item R type: .insn r opcode6, func3, func7, rd, rs1, rs2
+@item R type: .insn r opcode7, func3, func7, rd, rs1, rs2
 @verbatim
 +-------+-----+-----+-------+----+---------+
-| func7 | rs2 | rs1 | func3 | rd | opcode6 |
+| func7 | rs2 | rs1 | func3 | rd | opcode7 |
 +-------+-----+-----+-------+----+---------+
 31      25    20    15      12   7        0
 @end verbatim
 
-@item R type with 4 register operands: .insn r opcode6, func3, func2, rd, rs1, rs2, rs3
-@itemx R4 type: .insn r4 opcode6, func3, func2, rd, rs1, rs2, rs3
+@item R type with 4 register operands: .insn r opcode7, func3, func2, rd, rs1, rs2, rs3
+@itemx R4 type: .insn r4 opcode7, func3, func2, rd, rs1, rs2, rs3
 @verbatim
 +-----+-------+-----+-----+-------+----+---------+
-| rs3 | func2 | rs2 | rs1 | func3 | rd | opcode6 |
+| rs3 | func2 | rs2 | rs1 | func3 | rd | opcode7 |
 +-----+-------+-----+-----+-------+----+---------+
 31    27      25    20    15      12   7         0
 @end verbatim
 
-@item I type: .insn i opcode6, func3, rd, rs1, simm12
-@itemx I type: .insn i opcode6, func3, rd, simm12(rs1)
+@item I type: .insn i opcode7, func3, rd, rs1, simm12
+@itemx I type: .insn i opcode7, func3, rd, simm12(rs1)
 @verbatim
 +--------------+-----+-------+----+---------+
-| simm12[11:0] | rs1 | func3 | rd | opcode6 |
+| simm12[11:0] | rs1 | func3 | rd | opcode7 |
 +--------------+-----+-------+----+---------+
 31             20    15      12   7         0
 @end verbatim
 
-@item S type: .insn s opcode6, func3, rs2, simm12(rs1)
+@item S type: .insn s opcode7, func3, rs2, simm12(rs1)
 @verbatim
 +--------------+-----+-----+-------+-------------+---------+
-| simm12[11:5] | rs2 | rs1 | func3 | simm12[4:0] | opcode6 |
+| simm12[11:5] | rs2 | rs1 | func3 | simm12[4:0] | opcode7 |
 +--------------+-----+-----+-------+-------------+---------+
 31             25    20    15      12            7         0
 @end verbatim
 
-@item B type: .insn s opcode6, func3, rs1, rs2, symbol
-@itemx SB type: .insn sb opcode6, func3, rs1, rs2, symbol
+@item B type: .insn s opcode7, func3, rs1, rs2, symbol
+@itemx SB type: .insn sb opcode7, func3, rs1, rs2, symbol
 @verbatim
 +-----------------+-----+-----+-------+----------------+---------+
-| simm12[12|10:5] | rs2 | rs1 | func3 | simm12[4:1|11] | opcode6 |
+| simm12[12|10:5] | rs2 | rs1 | func3 | simm12[4:1|11] | opcode7 |
 +-----------------+-----+-----+-------+----------------+---------+
 31                25    20    15      12               7         0
 @end verbatim
 
-@item U type: .insn u opcode6, rd, simm20
+@item U type: .insn u opcode7, rd, simm20
 @verbatim
-+--------------------------+----+---------+
-| simm20[20|10:1|11|19:12] | rd | opcode6 |
-+--------------------------+----+---------+
-31                         12   7         0
++--------+----+---------+
+| simm20 | rd | opcode7 |
++--------+----+---------+
+31       12   7         0
 @end verbatim
 
-@item J type: .insn j opcode6, rd, symbol
-@itemx UJ type: .insn uj opcode6, rd, symbol
+@item J type: .insn j opcode7, rd, symbol
+@itemx UJ type: .insn uj opcode7, rd, symbol
 @verbatim
 +------------+--------------+------------+---------------+----+---------+
-| simm20[20] | simm20[10:1] | simm20[11] | simm20[19:12] | rd | opcode6 |
+| simm20[20] | simm20[10:1] | simm20[11] | simm20[19:12] | rd | opcode7 |
 +------------+--------------+------------+---------------+----+---------+
 31           30             21           20              12   7         0
 @end verbatim
-- 
2.40.1.423.g2807bd2c10