[binutils-gdb] s390: Enhance formatting of instruction formats in documentation
Jens Remus
jremus@sourceware.org
Tue Nov 10 16:48:12 GMT 2026
https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=ee56ca89a04b9fc9bb0f4d2144d489a19a679829
commit ee56ca89a04b9fc9bb0f4d2144d489a19a679829
Author: Jens Remus <jremus@linux.ibm.com>
Date: Tue Nov 10 17:46:02 2026 +0100
s390: Enhance formatting of instruction formats in documentation
Use a width of 4 characters for each nibble (4-bits) and one character
as separator between in the ASCII-art drawings of the instruction
formats. This ensures the width of instructions of same byte size
(i.e. 2/4/6-bytes) is identical and the width of bit fields within is
to scale.
While at it add a template, to ease drawing and verification.
gas/
* doc/c-s390.texi (s390 Formats): Enhance formatting of
instruction formats.
Signed-off-by: Jens Remus <jremus@linux.ibm.com>
Diff:
---
gas/doc/c-s390.texi | 265 ++++++++++++++++++++++++++++------------------------
1 file changed, 142 insertions(+), 123 deletions(-)
diff --git a/gas/doc/c-s390.texi b/gas/doc/c-s390.texi
index 9f0620c8d85..38d610bd04e 100644
--- a/gas/doc/c-s390.texi
+++ b/gas/doc/c-s390.texi
@@ -353,100 +353,120 @@ The following table lists the s390 instruction formats that are available
with the @samp{.insn} pseudo directive:
@table @code
-@item E format
+@ignore
+@item <fmt> format: <insn> <op1>,<op2>,<op3>,<op4>,<op5>
@verbatim
-+-------------+
-| OpCode |
-+-------------+
-0 15
++----+----+----+----+
+| N1 | N2 | N3 | N4 |
++----+----+----+----+
+0 4 8 12 15
+
++----+----+----+----+----+----+----+----+
+| N1 | N2 | N3 | N4 | N5 | N6 | N7 | N8 |
++----+----+----+----+----+----+----+----+
+0 4 8 12 16 20 24 28 31
+
++----+----+----+----+----+----+----+----+----+----+----+----+
+| N1 | N2 | N3 | N4 | N5 | N6 | N7 | N8 | N9 | NA | NB | NC |
++----+----+----+----+----+----+----+----+----+----+----+----+
+0 4 8 12 16 20 24 28 32 36 40 44 47
+@end verbatim
+@end ignore
+
+@item E format: <insn>
+@verbatim
++-------------------+
+| OpCode |
++-------------------+
+0 15
@end verbatim
@item RI format: <insn> R1,I2
@verbatim
-+--------+----+----+------------------+
-| OpCode | R1 |OpCd| I2 |
-+--------+----+----+------------------+
-0 8 12 16 31
++---------+----+----+-------------------+
+| OpCode | R1 |OpCd| I2 |
++---------+----+----+-------------------+
+0 8 12 16 31
@end verbatim
@item RIE format: <insn> R1,R3,I2
@verbatim
-+--------+----+----+------------------+--------+--------+
-| OpCode | R1 | R3 | I2 |////////| OpCode |
-+--------+----+----+------------------+--------+--------+
-0 8 12 16 32 40 47
++---------+----+----+-------------------+---------+---------+
+| OpCode | R1 | R3 | I2 |/////////| OpCode |
++---------+----+----+-------------------+---------+---------+
+0 8 12 16 32 40 47
@end verbatim
@item RIL format: <insn> R1,I2
@verbatim
-+--------+----+----+------------------------------------+
-| OpCode | R1 |OpCd| I2 |
-+--------+----+----+------------------------------------+
-0 8 12 16 47
++---------+----+----+---------------------------------------+
+| OpCode | R1 |OpCd| I2 |
++---------+----+----+---------------------------------------+
+0 8 12 16 47
@end verbatim
@item RILU format: <insn> R1,U2
@verbatim
-+--------+----+----+------------------------------------+
-| OpCode | R1 |OpCd| U2 |
-+--------+----+----+------------------------------------+
-0 8 12 16 47
++---------+----+----+---------------------------------------+
+| OpCode | R1 |OpCd| U2 |
++---------+----+----+---------------------------------------+
+0 8 12 16 47
@end verbatim
@item RIS format: <insn> R1,I2,M3,D4(B4)
@verbatim
-+--------+----+----+----+-------------+--------+--------+
-| OpCode | R1 | M3 | B4 | D4 | I2 | Opcode |
-+--------+----+----+----+-------------+--------+--------+
-0 8 12 16 20 32 40 47
++---------+----+----+----+--------------+---------+---------+
+| OpCode | R1 | M3 | B4 | D4 | I2 | OpCode |
++---------+----+----+----+--------------+---------+---------+
+0 8 12 16 20 32 40 47
@end verbatim
@item RR format: <insn> R1,R2
@verbatim
-+--------+----+----+
-| OpCode | R1 | R2 |
-+--------+----+----+
-0 8 12 15
++---------+----+----+
+| OpCode | R1 | R2 |
++---------+----+----+
+0 8 12 15
@end verbatim
@item RRE format: <insn> R1,R2
@verbatim
-+------------------+--------+----+----+
-| OpCode |////////| R1 | R2 |
-+------------------+--------+----+----+
-0 16 24 28 31
++-------------------+---------+----+----+
+| OpCode |/////////| R1 | R2 |
++-------------------+---------+----+----+
+0 16 24 28 31
@end verbatim
@item RRF format: <insn> R1,R2,R3,M4
@verbatim
-+------------------+----+----+----+----+
-| OpCode | R3 | M4 | R1 | R2 |
-+------------------+----+----+----+----+
-0 16 20 24 28 31
++-------------------+----+----+----+----+
+| OpCode | R3 | M4 | R1 | R2 |
++-------------------+----+----+----+----+
+0 16 20 24 28 31
@end verbatim
@item RRS format: <insn> R1,R2,M3,D4(B4)
@verbatim
-+--------+----+----+----+-------------+----+----+--------+
-| OpCode | R1 | R3 | B4 | D4 | M3 |////| OpCode |
-+--------+----+----+----+-------------+----+----+--------+
-0 8 12 16 20 32 36 40 47
++---------+----+----+----+--------------+----+----+---------+
+| OpCode | R1 | R3 | B4 | D4 | M3 |////| OpCode |
++---------+----+----+----+--------------+----+----+---------+
+0 8 12 16 20 32 36 40 47
@end verbatim
@item RS format: <insn> R1,R3,D2(B2)
@verbatim
-+--------+----+----+----+-------------+
-| OpCode | R1 | R3 | B2 | D2 |
-+--------+----+----+----+-------------+
-0 8 12 16 20 31
++---------+----+----+----+--------------+
+| OpCode | R1 | R3 | B2 | D2 |
++---------+----+----+----+--------------+
+0 8 12 16 20 31
@end verbatim
@item RSE format: <insn> R1,R3,D2(B2)
@verbatim
-+--------+----+----+----+-------------+--------+--------+
-| OpCode | R1 | R3 | B2 | D2 |////////| OpCode |
-+--------+----+----+----+-------------+--------+--------+
-0 8 12 16 20 32 40 47
++---------+----+----+----+--------------+---------+---------+
+| OpCode | R1 | R3 | B2 | D2 |/////////| OpCode |
++---------+----+----+----+--------------+---------+---------+
+0 8 12 16 20 32 40 47
@end verbatim
@item RSI format: <insn> R1,R3,I2
@@ -459,148 +479,147 @@ with the @samp{.insn} pseudo directive:
@item RSY format: <insn> R1,R3,D2(B2)
@verbatim
-+--------+----+----+----+-------------+--------+--------+
-| OpCode | R1 | R3 | B2 | DL2 | DH2 | OpCode |
-+--------+----+----+----+-------------+--------+--------+
-0 8 12 16 20 32 40 47
++---------+----+----+----+--------------+---------+---------+
+| OpCode | R1 | R3 | B2 | DL2 | DH2 | OpCode |
++---------+----+----+----+--------------+---------+---------+
+0 8 12 16 20 32 40 47
@end verbatim
@item RX format: <insn> R1,D2(X2,B2)
@verbatim
-+--------+----+----+----+-------------+
-| OpCode | R1 | X2 | B2 | D2 |
-+--------+----+----+----+-------------+
-0 8 12 16 20 31
++---------+----+----+----+--------------+
+| OpCode | R1 | X2 | B2 | D2 |
++---------+----+----+----+--------------+
+0 8 12 16 20 31
@end verbatim
@item RXE format: <insn> R1,D2(X2,B2)
@verbatim
-+--------+----+----+----+-------------+--------+--------+
-| OpCode | R1 | X2 | B2 | D2 |////////| OpCode |
-+--------+----+----+----+-------------+--------+--------+
-0 8 12 16 20 32 40 47
++---------+----+----+----+--------------+---------+---------+
+| OpCode | R1 | X2 | B2 | D2 |/////////| OpCode |
++---------+----+----+----+--------------+---------+---------+
+0 8 12 16 20 32 40 47
@end verbatim
@item RXF format: <insn> R1,R3,D2(X2,B2)
@verbatim
-+--------+----+----+----+-------------+----+---+--------+
-| OpCode | R3 | X2 | B2 | D2 | R1 |///| OpCode |
-+--------+----+----+----+-------------+----+---+--------+
-0 8 12 16 20 32 36 40 47
++---------+----+----+----+--------------+----+----+---------+
+| OpCode | R3 | X2 | B2 | D2 | R1 |////| OpCode |
++---------+----+----+----+--------------+----+----+---------+
+0 8 12 16 20 32 36 40 47
@end verbatim
@item RXY format: <insn> R1,D2(X2,B2)
@verbatim
-+--------+----+----+----+-------------+--------+--------+
-| OpCode | R1 | X2 | B2 | DL2 | DH2 | OpCode |
-+--------+----+----+----+-------------+--------+--------+
-0 8 12 16 20 32 36 40 47
++---------+----+----+----+--------------+---------+---------+
+| OpCode | R1 | X2 | B2 | DL2 | DH2 | OpCode |
++---------+----+----+----+--------------+---------+---------+
+0 8 12 16 20 32 40 47
@end verbatim
@item S format: <insn> D2(B2)
@verbatim
-+------------------+----+-------------+
-| OpCode | B2 | D2 |
-+------------------+----+-------------+
-0 16 20 31
++-------------------+----+--------------+
+| OpCode | B2 | D2 |
++-------------------+----+--------------+
+0 16 20 31
@end verbatim
@item SI format: <insn> D1(B1),I2
@verbatim
-+--------+---------+----+-------------+
-| OpCode | I2 | B1 | D1 |
-+--------+---------+----+-------------+
-0 8 16 20 31
++---------+---------+----+--------------+
+| OpCode | I2 | B1 | D1 |
++---------+---------+----+--------------+
+0 8 16 20 31
@end verbatim
@item SIY format: <insn> D1(B1),U2
@verbatim
-+--------+---------+----+-------------+--------+--------+
-| OpCode | I2 | B1 | DL1 | DH1 | OpCode |
-+--------+---------+----+-------------+--------+--------+
-0 8 16 20 32 36 40 47
++---------+---------+----+--------------+---------+---------+
+| OpCode | I2 | B1 | DL1 | DH1 | OpCode |
++---------+---------+----+--------------+---------+---------+
+0 8 16 20 32 40 47
@end verbatim
@item SIL format: <insn> D1(B1),I2
@verbatim
-+------------------+----+-------------+-----------------+
-| OpCode | B1 | D1 | I2 |
-+------------------+----+-------------+-----------------+
-0 16 20 32 47
++-------------------+----+--------------+-------------------+
+| OpCode | B1 | D1 | I2 |
++-------------------+----+--------------+-------------------+
+0 16 20 32 47
@end verbatim
-@item SS format: <insn> D1(R1,B1),D2(B3),R3
+@item SS format: <insn> D1(R1,B1),D2(B2),R3
@verbatim
-+--------+----+----+----+-------------+----+------------+
-| OpCode | R1 | R3 | B1 | D1 | B2 | D2 |
-+--------+----+----+----+-------------+----+------------+
-0 8 12 16 20 32 36 47
++---------+----+----+----+--------------+----+--------------+
+| OpCode | R1 | R3 | B1 | D1 | B2 | D2 |
++---------+----+----+----+--------------+----+--------------+
+0 8 12 16 20 32 36 47
@end verbatim
@item SSE format: <insn> D1(B1),D2(B2)
@verbatim
-+------------------+----+-------------+----+------------+
-| OpCode | B1 | D1 | B2 | D2 |
-+------------------+----+-------------+----+------------+
-0 8 12 16 20 32 36 47
++-------------------+----+--------------+----+--------------+
+| OpCode | B1 | D1 | B2 | D2 |
++-------------------+----+--------------+----+--------------+
+0 16 20 32 36 47
@end verbatim
@item SSF format: <insn> D1(B1),D2(B2),R3
@verbatim
-+--------+----+----+----+-------------+----+------------+
-| OpCode | R3 |OpCd| B1 | D1 | B2 | D2 |
-+--------+----+----+----+-------------+----+------------+
-0 8 12 16 20 32 36 47
++---------+----+----+----+--------------+----+--------------+
+| OpCode | R3 |OpCd| B1 | D1 | B2 | D2 |
++---------+----+----+----+--------------+----+--------------+
+0 8 12 16 20 32 36 47
@end verbatim
@item VRV format: <insn> V1,D2(V2,B2),M3
@verbatim
-+--------+----+----+----+-------------+----+------------+
-| OpCode | V1 | V2 | B2 | D2 | M3 | Opcode |
-+--------+----+----+----+-------------+----+------------+
-0 8 12 16 20 32 36 47
++---------+----+----+----+--------------+----+--------------+
+| OpCode | V1 | V2 | B2 | D2 | M3 | OpCode |
++---------+----+----+----+--------------+----+--------------+
+0 8 12 16 20 32 36 47
@end verbatim
@item VRI format: <insn> V1,V2,I3,M4,M5
@verbatim
-+--------+----+----+-------------+----+----+------------+
-| OpCode | V1 | V2 | I3 | M5 | M4 | Opcode |
-+--------+----+----+-------------+----+----+------------+
-0 8 12 16 28 32 36 47
++---------+----+----+--------------+----+----+--------------+
+| OpCode | V1 | V2 | I3 | M5 | M4 | OpCode |
++---------+----+----+--------------+----+----+--------------+
+0 8 12 16 28 32 36 47
@end verbatim
@item VRX format: <insn> V1,D2(R2,B2),M3
@verbatim
-+--------+----+----+----+-------------+----+------------+
-| OpCode | V1 | R2 | B2 | D2 | M3 | Opcode |
-+--------+----+----+----+-------------+----+------------+
-0 8 12 16 20 32 36 47
++---------+----+----+----+--------------+----+--------------+
+| OpCode | V1 | R2 | B2 | D2 | M3 | OpCode |
++---------+----+----+----+--------------+----+--------------+
+0 8 12 16 20 32 36 47
@end verbatim
@item VRS format: <insn> R1,V3,D2(B2),M4
@verbatim
-+--------+----+----+----+-------------+----+------------+
-| OpCode | R1 | V3 | B2 | D2 | M4 | Opcode |
-+--------+----+----+----+-------------+----+------------+
-0 8 12 16 20 32 36 47
++---------+----+----+----+--------------+----+--------------+
+| OpCode | R1 | V3 | B2 | D2 | M4 | OpCode |
++---------+----+----+----+--------------+----+--------------+
+0 8 12 16 20 32 36 47
@end verbatim
@item VRR format: <insn> V1,V2,V3,M4,M5,M6
@verbatim
-+--------+----+----+----+---+----+----+----+------------+
-| OpCode | V1 | V2 | V3 |///| M6 | M5 | M4 | Opcode |
-+--------+----+----+----+---+----+----+----+------------+
-0 8 12 16 24 28 32 36 47
++---------+----+----+----+----+----+----+----+--------------+
+| OpCode | V1 | V2 | V3 |////| M6 | M5 | M4 | OpCode |
++---------+----+----+----+----+----+----+----+--------------+
+0 8 12 16 20 24 28 32 36 47
@end verbatim
@item VSI format: <insn> V1,D2(B2),I3
@verbatim
-+--------+---------+----+-------------+----+------------+
-| OpCode | I3 | B2 | D2 | V1 | Opcode |
-+--------+---------+----+-------------+----+------------+
-0 8 16 20 32 36 47
++---------+---------+----+--------------+----+--------------+
+| OpCode | I3 | B2 | D2 | V1 | OpCode |
++---------+---------+----+--------------+----+--------------+
+0 8 16 20 32 36 47
@end verbatim
-
@end table
For the complete list of all instruction format variants see the
More information about the Binutils-cvs
mailing list