[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