[committed] MIPS/opcodes: Rework documentation for instruction args

Message ID alpine.DEB.2.21.2409151132200.64337@angie.orcam.me.uk
State New
Headers
Series [committed] MIPS/opcodes: Rework documentation for instruction args |

Checks

Context Check Description
linaro-tcwg-bot/tcwg_binutils_build--master-aarch64 success Build passed
linaro-tcwg-bot/tcwg_binutils_check--master-aarch64 fail Patch failed to apply
linaro-tcwg-bot/tcwg_binutils_build--master-arm fail Patch failed to apply

Commit Message

Maciej W. Rozycki Sept. 15, 2024, 12:28 p.m. UTC
  Rewrite the inline documentation for the characters used in the `args' 
member of `struct mips_opcode' to make it consistent in terms of style
and formatting.  Discard references to inexistent macros.
---
 include/opcode/mips.h |  796 +++++++++++++++++++++++++-------------------------
 1 file changed, 399 insertions(+), 397 deletions(-)

binutils-mips-opcodes-op-doc-rework.diff
  

Patch

Index: binutils-gdb/include/opcode/mips.h
===================================================================
--- binutils-gdb.orig/include/opcode/mips.h
+++ binutils-gdb/include/opcode/mips.h
@@ -516,237 +516,241 @@  mips_opcode_32bit_p (const struct mips_o
   return mo->mask >> 16 != 0;
 }
 
-/* These are the characters which may appear in the args field of an
-   instruction.  They appear in the order in which the fields appear
-   when the instruction is used.  Commas and parentheses in the args
-   string are ignored when assembling, and written into the output
+/* These are the characters which may appear in the args field of a
+   regular MIPS instruction.  They appear in the order in which the fields
+   appear when the instruction is used.  Commas and parentheses in the
+   args string are ignored when assembling, and written into the output
    when disassembling.
 
-   Each of these characters corresponds to a mask field defined above.
-
-   "1" 5 bit sync type (OP_*_STYPE)
-   "<" 5 bit shift amount (OP_*_SHAMT)
-   ">" shift amount between 32 and 63, stored after subtracting 32 (OP_*_SHAMT)
-   "a" 26 bit target address (OP_*_TARGET)
-   "+i" likewise, but flips bit 0
-   "b" 5 bit base register (OP_*_RS)
-   "c" 10 bit breakpoint code (OP_*_CODE)
-   "d" 5 bit destination register specifier (OP_*_RD)
-   "h" 5 bit prefx hint (OP_*_PREFX)
-   "i" 16 bit unsigned immediate (OP_*_IMMEDIATE)
-   "j" 16 bit signed immediate (OP_*_DELTA)
-   "k" 5 bit cache opcode in target register position (OP_*_CACHE)
-   "o" 16 bit signed offset (OP_*_DELTA)
-   "p" 16 bit PC relative branch target address (OP_*_DELTA)
-   "q" 10 bit extra breakpoint code (OP_*_CODE2)
-   "r" 5 bit same register used as both source and target (OP_*_RS)
-   "s" 5 bit source register specifier (OP_*_RS)
-   "t" 5 bit target register (OP_*_RT)
-   "u" 16 bit upper 16 bits of address (OP_*_IMMEDIATE)
-   "v" 5 bit same register used as both source and destination (OP_*_RS)
-   "w" 5 bit same register used as both target and destination (OP_*_RT)
-   "U" 5 bit same destination register in both OP_*_RD and OP_*_RT
-       (used by clo and clz)
-   "C" 25 bit coprocessor function code (OP_*_COPZ)
-   "B" 20 bit syscall/breakpoint function code (OP_*_CODE20)
-   "J" 19 bit wait function code (OP_*_CODE19)
-   "x" accept and ignore register name
-   "z" must be zero register
-   "K" 5 bit Hardware Register (rdhwr instruction) (OP_*_RD)
-   "+A" 5 bit ins/ext/dins/dext/dinsm/dextm position, which becomes
-        LSB (OP_*_SHAMT; OP_*_EXTLSB or OP_*_STYPE may be used for
-        microMIPS compatibility).
+   "1" 5-bit SYNC type at bit 6.
+   "<" 5-bit shift amount at bit 6 (SHAMT).
+   ">" Shift amount between 32 and 63, stored after subtracting 32, at bit 6
+       (SHAMT).
+   "a" 26-bit target address at bit 0 (TARGET).
+   "+i" Likewise, but flips bit 0.
+   "b" 5-bit base register at bit 21 (RS).
+   "c" 10-bit breakpoint code at bit 16.
+   "d" 5-bit destination register at bit 11 (RD).
+   "h" 5-bit PREFX hint at bit 11.
+   "i" 16-bit unsigned immediate at bit 0 (IMMEDIATE).
+   "j" 16-bit signed immediate at bit 0 (DELTA).
+   "k" 5-bit CACHE opcode in target register position at bit 16.
+   "o" 16-bit signed offset at bit 0 (DELTA).
+   "p" 16-bit PC relative branch target address at bit 0 (DELTA).
+   "q" 10-bit extra breakpoint code at bit 6.
+   "r" 5-bit same register used as both source and target at bit 21 (RS).
+   "s" 5-bit source register at bit 21 (RS).
+   "t" 5-bit target register at bit 16 (RT).
+   "u" 16-bit upper 16 bits of address at bit 0 (IMMEDIATE).
+   "v" 5-bit same register used as both source and destination at bit 21 (RS).
+   "w" 5-bit same register used as both target and destination at bit 16 (RT).
+   "U" 5-bit same destination register at both bit 11 and 16 (both RD and RT)
+       (used by CLO and CLZ).
+   "C" 25-bit coprocessor function code at bit 0.
+   "B" 20-bit syscall/breakpoint function code at bit 6.
+   "J" 19-bit WAIT function code at bit 6.
+   "x" Accept and ignore register name.
+   "z" Must be zero register.
+   "K" 5-bit Hardware Register (RDHWR instruction) at bit 11 (RD).
+   "+A" 5-bit INS/EXT/DINS/DEXT/DINSM/DEXTM position at bit 6,
+	which becomes LSB (SHAMT).
 	Enforces: 0 <= pos < 32.
-   "+B" 5 bit ins/dins size, which becomes MSB (OP_*_INSMSB).
+   "+B" 5-bit INS/DINS size at bit 11, which becomes MSB.
 	Requires that "+A" or "+E" occur first to set position.
 	Enforces: 0 < (pos+size) <= 32.
-   "+C" 5 bit ext/dext size, which becomes MSBD (OP_*_EXTMSBD).
+   "+C" 5-bit EXT/DEXT size at bit 11, which becomes MSBD.
 	Requires that "+A" or "+E" occur first to set position.
 	Enforces: 0 < (pos+size) <= 32.
-	(Also used by "dext" w/ different limits, but limits for
+	(Also used by DEXT w/ different limits, but limits for
 	that are checked by the M_DEXT macro.)
-   "+E" 5 bit dinsu/dextu position, which becomes LSB-32 (OP_*_SHAMT).
+   "+E" 5-bit DINSU/DEXTU position at bit 6, which becomes LSB-32 (SHAMT).
 	Enforces: 32 <= pos < 64.
-   "+F" 5 bit "dinsm/dinsu" size, which becomes MSB-32 (OP_*_INSMSB).
+   "+F" 5-bit DINSM/DINSU size at bit 11, which becomes MSB-32.
 	Requires that "+A" or "+E" occur first to set position.
 	Enforces: 32 < (pos+size) <= 64.
-   "+G" 5 bit "dextm" size, which becomes MSBD-32 (OP_*_EXTMSBD).
+   "+G" 5-bit DEXTM size at bit 11, which becomes MSBD-32.
 	Requires that "+A" or "+E" occur first to set position.
 	Enforces: 32 < (pos+size) <= 64.
-   "+H" 5 bit "dextu" size, which becomes MSBD (OP_*_EXTMSBD).
+   "+H" 5-bit DEXTU size at bit 11, which becomes MSBD.
 	Requires that "+A" or "+E" occur first to set position.
 	Enforces: 32 < (pos+size) <= 64.
 
    Floating point instructions:
-   "D" 5 bit destination register (OP_*_FD)
-   "M" 3 bit compare condition code (OP_*_CCC) (only used for mips4 and up)
-   "N" 3 bit branch condition code (OP_*_BCC) (only used for mips4 and up)
-   "S" 5 bit fs source 1 register (OP_*_FS)
-   "T" 5 bit ft source 2 register (OP_*_FT)
-   "R" 5 bit fr source 3 register (OP_*_FR)
-   "V" 5 bit same register used as floating source and destination (OP_*_FS)
-   "W" 5 bit same register used as floating target and destination (OP_*_FT)
+   "D" 5-bit destination register at bit 6 (FD).
+   "M" 3-bit compare condition code at bit 8 (only used for mips4 and up).
+   "N" 3-bit branch condition code at bit 18 (only used for mips4 and up).
+   "S" 5-bit fs source 1 register at bit 11 (FS).
+   "T" 5-bit ft source 2 register at bit 16 (FT).
+   "R" 5-bit fr source 3 register at bit 21 (FR).
+   "V" 5-bit same register used as floating source and destination at bit 11
+       (FS).
+   "W" 5-bit same register used as floating target and destination at bit 16
+       (FT).
 
    Coprocessor instructions:
-   "E" 5 bit target register (OP_*_RT)
-   "G" 5 bit destination register (OP_*_RD)
-   "H" 3 bit sel field for (d)mtc* and (d)mfc* (OP_*_SEL)
-   "P" 5 bit performance-monitor register (OP_*_PERFREG)
-   "e" 5 bit vector register byte specifier (OP_*_VECBYTE)
-   "g" 5 bit control destination register (OP_*_RD)
-   "%" 3 bit immediate vr5400 vector alignment operand (OP_*_VECALIGN)
+   "E" 5-bit target register at bit 16 (RT).
+   "G" 5-bit destination register at bit 11 (RD).
+   "H" 3-bit sel field for (D)MTC* and (D)MFC* at bit 0.
+   "P" 5-bit performance-monitor register at bit 1.
+   "e" 3-bit vector register byte specifier at bit 22.
+   "g" 5-bit control destination register at bit 11 (RD).
+   "%" 3-bit immediate vr5400 vector alignment operand at bit 21.
 
    Macro instructions:
-   "A" General 32 bit expression
-   "I" 32 bit immediate (value placed in imm_expr).
-   "F" 64 bit floating point constant in .rdata
-   "L" 64 bit floating point constant in .lit8
-   "f" 32 bit floating point constant
-   "l" 32 bit floating point constant in .lit4
+   "A" General 32-bit expression.
+   "I" 32-bit immediate (value placed in imm_expr).
+   "F" 64-bit floating point constant in .rdata.
+   "L" 64-bit floating point constant in .lit8.
+   "f" 32-bit floating point constant.
+   "l" 32-bit floating point constant in .lit4.
 
    MDMX and VR5400 instruction operands (note that while these use the
    FP register fields, the MDMX instructions accept both $fN and $vN names
    for the registers):
-   "O"	alignment offset (OP_*_ALN)
-   "Q"	vector/scalar/immediate source (OP_*_VSEL and OP_*_FT)
-   "X"	destination register (OP_*_FD)
-   "Y"	source register (OP_*_FS)
-   "Z"	source register (OP_*_FT)
+   "O" 3-bit alignment offset at bit 21.
+   "Q" 10-bit vector/scalar/immediate source at bit 16.
+   "X" 5-bit destination register at bit 6 (FD).
+   "Y" 5-bit source register at bit 11 (FS).
+   "Z" 5-bit source register at bit 16 (FT).
 
    R5900 VU0 Macromode instructions:
-   "+5" 5 bit floating point register (FD)
-   "+6" 5 bit floating point register (FS)
-   "+7" 5 bit floating point register (FT)
-   "+8" 5 bit integer register (FD)
-   "+9" 5 bit integer register (FS)
-   "+0" 5 bit integer register (FT)
-   "+K" match an existing 4-bit channel mask starting at bit 21
-   "+L" 2-bit channel index starting at bit 21
-   "+M" 2-bit channel index starting at bit 23
-   "+N" match an existing 2-bit channel index starting at bit 0
-   "+f" 15 bit immediate for VCALLMS
-   "+g" 5 bit signed immediate for VIADDI
-   "+m" $ACC register (syntax only)
-   "+q" $Q register (syntax only)
-   "+r" $R register (syntax only)
-   "+y" $I register (syntax only)
-   "#+" "++" decorator in ($reg++) sequence
-   "#-" "--" decorator in (--$reg) sequence
+   "+5" 5-bit floating point register at bit 6 (FD).
+   "+6" 5-bit floating point register at bit 11 (FS).
+   "+7" 5-bit floating point register at bit 16 (FT).
+   "+8" 5-bit integer register at bit 6 (FD).
+   "+9" 5-bit integer register at bit 11 (FS).
+   "+0" 5-bit integer register at bit 16 (FT).
+   "+K" Match an existing 4-bit channel mask starting at bit 21.
+   "+L" 2-bit channel index starting at bit 21.
+   "+M" 2-bit channel index starting at bit 23.
+   "+N" Match an existing 2-bit channel index starting at bit 0.
+   "+f" 15-bit immediate for VCALLMS at bit 6.
+   "+g" 5-bit signed immediate for VIADDI at bit 6.
+   "+m" $ACC register (syntax only).
+   "+q" $Q register (syntax only).
+   "+r" $R register (syntax only).
+   "+y" $I register (syntax only).
+   "#+" "++" decorator in ($reg++) sequence.
+   "#-" "--" decorator in (--$reg) sequence.
 
    DSP ASE usage:
-   "2" 2 bit unsigned immediate for byte align (OP_*_BP)
-   "3" 3 bit unsigned immediate (OP_*_SA3)
-   "4" 4 bit unsigned immediate (OP_*_SA4)
-   "5" 8 bit unsigned immediate (OP_*_IMM8)
-   "6" 5 bit unsigned immediate (OP_*_RS)
-   "7" 2 bit dsp accumulator register (OP_*_DSPACC)
-   "8" 6 bit unsigned immediate (OP_*_WRDSP)
-   "9" 2 bit dsp accumulator register (OP_*_DSPACC_S)
-   "0" 6 bit signed immediate (OP_*_DSPSFT)
-   ":" 7 bit signed immediate (OP_*_DSPSFT_7)
-   "'" 6 bit unsigned immediate (OP_*_RDDSP)
-   "@" 10 bit signed immediate (OP_*_IMM10)
+   "2" 2-bit unsigned immediate for byte align at bit 11.
+   "3" 3-bit unsigned immediate at bit 21.
+   "4" 4-bit unsigned immediate at bit 21.
+   "5" 8-bit unsigned immediate at bit 16.
+   "6" 5-bit unsigned immediate at bit 21 (RS).
+   "7" 2-bit DSP accumulator register at bit 11.
+   "8" 6-bit unsigned immediate at bit 11.
+   "9" 2-bit DSP accumulator register at bit 21.
+   "0" 6-bit signed immediate at bit 20.
+   ":" 7-bit signed immediate at bit 19.
+   "'" 6-bit unsigned immediate at bit 16.
+   "@" 10-bit signed immediate at bit 16.
 
    MT ASE usage:
-   "!" 1 bit usermode flag (OP_*_MT_U)
-   "$" 1 bit load high flag (OP_*_MT_H)
-   "*" 2 bit dsp/smartmips accumulator register (OP_*_MTACC_T)
-   "&" 2 bit dsp/smartmips accumulator register (OP_*_MTACC_D)
-   "y" 5 bit control target register (OP_*_RT)
+   "!" 1-bit usermode flag at bit 5.
+   "$" 1-bit load high flag at bit 4.
+   "*" 2-bit DSP/SmartMIPS accumulator register at bit 18.
+   "&" 2-bit DSP/SmartMIPS accumulator register at bit 13.
+   "y" 5-bit control target register at bit 16 (RT).
 
    MCU ASE usage:
-   "~" 12 bit offset (OP_*_OFFSET12)
-   "\" 3 bit position for aset and aclr (OP_*_3BITPOS)
+   "~" 12-bit offset at bit 0.
+   "\" 3-bit position for ASET and ACLR at bit 12.
 
    VIRT ASE usage:
-   "+J" 10-bit hypcall code (OP_*CODE10)
+   "+J" 10-bit HYPCALL code at bit 11.
 
    UDI immediates:
-   "+1" UDI immediate bits 6-10
-   "+2" UDI immediate bits 6-15
-   "+3" UDI immediate bits 6-20
-   "+4" UDI immediate bits 6-25
+   "+1" UDI immediate bits 6-10.
+   "+2" UDI immediate bits 6-15.
+   "+3" UDI immediate bits 6-20.
+   "+4" UDI immediate bits 6-25.
 
    Octeon:
-   "+x" Bit index field of bbit.  Enforces: 0 <= index < 32.
-   "+X" Bit index field of bbit aliasing bbit32.  Matches if 32 <= index < 64,
-	otherwise skips to next candidate.
-   "+p" Position field of cins/cins32/exts/exts32. Enforces 0 <= pos < 32.
-   "+P" Position field of cins/exts aliasing cins32/exts32.  Matches if
-	32 <= pos < 64, otherwise skips to next candidate.
-   "+Q" Immediate field of seqi/snei.  Enforces -512 <= imm < 512.
-   "+s" Length-minus-one field of cins32/exts32.  Requires msb position
-	of the field to be <= 31.
-   "+S" Length-minus-one field of cins/exts.  Requires msb position
-	of the field to be <= 63.
+   "+x" Bit index field of BBITx at bit 16.
+	Enforces: 0 <= index < 32.
+   "+X" Bit index field of BBITx aliasing BBITx32 at bit 16.
+	Matches if 32 <= index < 64, otherwise skips to next candidate.
+   "+p" Position field of CINS/CINS32/EXTS/EXTS32 at bit 6.
+	Enforces 0 <= pos < 32.
+   "+P" Position field of CINS/EXTS aliasing CINS32/EXTS32 at bit 6.
+	Matches if 32 <= pos < 64, otherwise skips to next candidate.
+   "+Q" Immediate field of SEQI/SNEI at bit 6.
+	Enforces -512 <= imm < 512.
+   "+s" Length-minus-one field of CINS32/EXTS32 at bit 11.
+	Requires MSB position of the field to be <= 31.
+   "+S" Length-minus-one field of CINS/EXTS at bit 11.
+	Requires MSB position of the field to be <= 63.
 
    Loongson-ext ASE:
-   "+a" 8-bit signed offset in bit 6 (OP_*_OFFSET_A)
-   "+b" 8-bit signed offset in bit 3 (OP_*_OFFSET_B)
-   "+c" 9-bit signed offset in bit 6 (OP_*_OFFSET_C)
-   "+z" 5-bit rz register (OP_*_RZ)
-   "+Z" 5-bit fz register (OP_*_FZ)
+   "+a" 8-bit signed offset at bit 6.
+   "+b" 8-bit signed offset at bit 3.
+   "+c" 9-bit signed offset at bit 6.
+   "+z" 5-bit rz register at bit 0.
+   "+Z" 5-bit fz register at bit 0.
 
    interAptiv MR2:
-   "-m" register list for SAVE/RESTORE instruction
+   "-m" Register list for SAVE/RESTORE instruction.
 
    Enhanced VA Scheme:
-   "+j" 9-bit signed offset in bit 7 (OP_*_EVAOFFSET)
+   "+j" 9-bit signed offset at bit 7.
 
    MSA Extension:
-   "+d" 5-bit MSA register (FD)
-   "+e" 5-bit MSA register (FS)
-   "+h" 5-bit MSA register (FT)
-   "+k" 5-bit GPR at bit 6
-   "+l" 5-bit MSA control register at bit 6
-   "+n" 5-bit MSA control register at bit 11
-   "+o" 4-bit vector element index at bit 16
-   "+u" 3-bit vector element index at bit 16
-   "+v" 2-bit vector element index at bit 16
-   "+w" 1-bit vector element index at bit 16
-   "+T" (-512 .. 511) << 0 at bit 16
-   "+U" (-512 .. 511) << 1 at bit 16
-   "+V" (-512 .. 511) << 2 at bit 16
-   "+W" (-512 .. 511) << 3 at bit 16
-   "+~" 2 bit LSA/DLSA shift amount from 1 to 4 at bit 6
-   "+!" 3 bit unsigned bit position at bit 16
-   "+@" 4 bit unsigned bit position at bit 16
-   "+#" 6 bit unsigned bit position at bit 16
-   "+$" 5 bit unsigned immediate at bit 16
-   "+%" 5 bit signed immediate at bit 16
-   "+^" 10 bit signed immediate at bit 11
-   "+&" 0 vector element index
-   "+*" 5-bit register vector element index at bit 16
-   "+|" 8-bit mask at bit 16
+   "+d" 5-bit MSA register at bit 6 (FD).
+   "+e" 5-bit MSA register at bit 11 (FS).
+   "+h" 5-bit MSA register at bit 16 (FT).
+   "+k" 5-bit GPR at bit 6.
+   "+l" 5-bit MSA control register at bit 6.
+   "+n" 5-bit MSA control register at bit 11.
+   "+o" 4-bit vector element index at bit 16.
+   "+u" 3-bit vector element index at bit 16.
+   "+v" 2-bit vector element index at bit 16.
+   "+w" 1-bit vector element index at bit 16.
+   "+T" (-512 .. 511) << 0 at bit 16.
+   "+U" (-512 .. 511) << 1 at bit 16.
+   "+V" (-512 .. 511) << 2 at bit 16.
+   "+W" (-512 .. 511) << 3 at bit 16.
+   "+~" 2-bit LSA/DLSA shift amount from 1 to 4 at bit 6.
+   "+!" 3-bit unsigned bit position at bit 16.
+   "+@" 4-bit unsigned bit position at bit 16.
+   "+#" 6-bit unsigned bit position at bit 16.
+   "+$" 5-bit unsigned immediate at bit 16.
+   "+%" 5-bit signed immediate at bit 16.
+   "+^" 10-bit signed immediate at bit 11.
+   "+&" 0 vector element index.
+   "+*" 5-bit register vector element index at bit 16.
+   "+|" 8-bit mask at bit 16.
 
    MIPS R6:
-   "+:" 11-bit mask at bit 0
-   "+'" 26 bit PC relative branch target address
-   "+"" 21 bit PC relative branch target address
-   "+;" 5 bit same register in both OP_*_RS and OP_*_RT
-   "+I" 2bit unsigned bit position at bit 6
-   "+O" 3bit unsigned bit position at bit 6
-   "+R" must be program counter
-   "-a" (-262144 .. 262143) << 2 at bit 0
-   "-b" (-131072 .. 131071) << 3 at bit 0
-   "-d" Same as destination register GP
-   "-s" 5 bit source register specifier (OP_*_RS) not $0
-   "-t" 5 bit target register specifier (OP_*_RT) not $0
-   "-u" 5 bit target register specifier (OP_*_RT) greater than OP_*_RS
-   "-v" 5 bit target register specifier (OP_*_RT) not $0 not OP_*_RS
-   "-w" 5 bit target register specifier (OP_*_RT) less than or equal to OP_*_RS
-   "-x" 5 bit source register specifier (OP_*_RS) greater than OP_*_RT
-   "-y" 5 bit source register specifier (OP_*_RS) not $0 less than OP_*_RT
-   "-A" symbolic offset (-262144 .. 262143) << 2 at bit 0
-   "-B" symbolic offset (-131072 .. 131071) << 3 at bit 0
+   "+:" 11-bit mask at bit 0.
+   "+'" 26-bit PC relative branch target address at bit 0.
+   "+"" 21-bit PC relative branch target address at bit 0.
+   "+;" 5-bit same register at both bit 16 and 21 (both RT and RS).
+   "+I" 2-bit unsigned bit position at bit 6.
+   "+O" 3-bit unsigned bit position at bit 6.
+   "+R" Must be program counter.
+   "-a" (-262144 .. 262143) << 2 at bit 0.
+   "-b" (-131072 .. 131071) << 3 at bit 0.
+   "-d" Same as destination register GP.
+   "-s" 5-bit source register at bit 21 (RS) not $0.
+   "-t" 5-bit target register at bit 16 (RT) not $0
+   "-u" 5-bit target register at bit 16 (RT) greater than RS.
+   "-v" 5-bit target register at bit 16 (RT) not $0 not RS.
+   "-w" 5-bit target register at bit 16 (RT) less than or equal to RS.
+   "-x" 5-bit source register at bit 21 (RS) greater than RT.
+   "-y" 5-bit source register at bit 21 (RS) not $0 less than RT.
+   "-A" Symbolic offset (-262144 .. 262143) << 2 at bit 0.
+   "-B" Symbolic offset (-131072 .. 131071) << 3 at bit 0.
 
    GINV ASE usage:
-   "+\" 2 bit Global TLB invalidate type at bit 8
+   "+\" 2-bit Global TLB invalidate type at bit 8.
 
    Other:
-   "()" parens surrounding optional value
-   ","  separates operands
+   "()" Parens surrounding optional value.
+   ","  Separates operands.
    "+"  Start of extension sequence.
+   "-"  Start of extension sequence.
 
    Characters used so far, for quick reference when adding more:
    "1234567890"
@@ -758,13 +762,13 @@  mips_opcode_32bit_p (const struct mips_o
    following), for quick reference when adding more:
    "1234567890"
    "~!@#$%^&*|:'";\"
-   "ABCEFGHIJKLMNOPQRSTUVWXZ"
+   "ABC EFGHIJKLMNOPQRSTUVWX Z"
    "abcdefghijklmnopqrs uvwxyz"
 
    Extension character sequences used so far ("-" followed by the
    following), for quick reference when adding more:
-   "AB"
-   "abdmstuvwxy"
+   "AB                        "
+   "ab d        m     stuvwxy "
 */
 
 /* These are the bits which may be set in the pinfo field of an
@@ -1589,80 +1593,81 @@  extern int bfd_mips_num_opcodes;
 #define MIPS16OP_MASK_RZ	0x7
 #define MIPS16OP_SH_RZ		2
 
-/* These are the characters which may appears in the args field of a MIPS16
-   instruction.  They appear in the order in which the fields appear when the
-   instruction is used.  Commas and parentheses in the args string are ignored
-   when assembling, and written into the output when disassembling.
+/* These are the characters which may appears in the args field of a
+   MIPS16 instruction.  They appear in the order in which the fields
+   appear when the instruction is used.  Commas and parentheses in the
+   args string are ignored when assembling, and written into the output
+   when disassembling.
 
-   "y" 3 bit register (MIPS16OP_*_RY)
-   "x" 3 bit register (MIPS16OP_*_RX)
-   "z" 3 bit register (MIPS16OP_*_RZ)
-   "Z" 3 bit register (MIPS16OP_*_MOVE32Z)
-   "v" 3 bit same register as source and destination (MIPS16OP_*_RX)
-   "w" 3 bit same register as source and destination (MIPS16OP_*_RY)
-   "." zero register ($0)
-   "S" stack pointer ($sp or $29)
-   "P" program counter
-   "R" return address register ($ra or $31)
-   "X" 5 bit MIPS register (MIPS16OP_*_REGR32)
-   "Y" 5 bit MIPS register (MIPS16OP_*_REG32R)
-   "0" 5-bit ASMACRO p0 immediate
-   "1" 3-bit ASMACRO p1 immediate
-   "2" 3-bit ASMACRO p2 immediate
-   "3" 5-bit ASMACRO p3 immediate
-   "4" 3-bit ASMACRO p4 immediate
-   "6" 6 bit unsigned break code (MIPS16OP_*_IMM6)
-   "a" 26 bit jump address
-   "i" likewise, but flips bit 0
-   "e" 11 bit extension value
-   "l" register list for entry instruction
-   "L" register list for exit instruction
-   ">" 5-bit SYNC code
-   "9" 9-bit signed immediate
-   "G" global pointer ($gp or $28)
-   "N" 5-bit coprocessor register
-   "O" 3-bit sel field for MFC0/MTC0
-   "Q" 5-bit hardware register
-   "T" 5-bit CACHE opcode or PREF hint
-   "b" 5-bit INS/EXT position, which becomes LSB
+   "y" 3-bit register at bit 5 (RY).
+   "x" 3-bit register at bit 8 (RX).
+   "z" 3-bit register at bit 2 (RZ).
+   "Z" 3-bit register at bit 0 (MOV32Z).
+   "v" 3-bit same register as source and destination at bit 8 (RX).
+   "w" 3-bit same register as source and destination at bit 5 (RY).
+   "." Zero register ($0).
+   "S" Stack pointer ($sp or $29).
+   "P" Program counter.
+   "R" Return address register ($ra or $31).
+   "X" 5-bit MIPS register at bit 0 (REGR32).
+   "Y" 5-bit shuffled MIPS register at bit 3 (REG32R).
+   "0" 5-bit ASMACRO p0 immediate.
+   "1" 3-bit ASMACRO p1 immediate.
+   "2" 3-bit ASMACRO p2 immediate.
+   "3" 5-bit ASMACRO p3 immediate.
+   "4" 3-bit ASMACRO p4 immediate.
+   "6" 6-bit unsigned break code at bit 5.
+   "a" 26-bit jump address.
+   "i" Likewise, but flips bit 0.
+   "e" 11-bit extension value.
+   "l" Register list for ENTRY instruction.
+   "L" Register list for EXIT instruction.
+   ">" 5-bit SYNC code.
+   "9" 9-bit signed immediate.
+   "G" global pointer ($gp or $28).
+   "N" 5-bit coprocessor register.
+   "O" 3-bit sel field for MFC0/MTC0.
+   "Q" 5-bit hardware register.
+   "T" 5-bit CACHE opcode or PREF hint.
+   "b" 5-bit INS/EXT position, which becomes LSB.
        Enforces: 0 <= pos < 32.
-   "c" 5-bit INS size, which becomes MSB
+   "c" 5-bit INS size, which becomes MSB.
        Requires that "b" occurs first to set position.
        Enforces: 0 < (pos+size) <= 32.
-   "d" 5-bit EXT size, which becomes MSBD
+   "d" 5-bit EXT size, which becomes MSBD.
        Requires that "b" occurs first to set position.
        Enforces: 0 < (pos+size) <= 32.
-   "n" 2-bit immediate (1 .. 4)
-   "o" 5-bit unsigned immediate * 16
-   "r" 3-bit register
-   "s" 3-bit ASMACRO select immediate
-   "u" 16-bit unsigned immediate
+   "n" 2-bit immediate (1 .. 4).
+   "o" 5-bit unsigned immediate * 16.
+   "r" 3-bit register.
+   "s" 3-bit ASMACRO select immediate.
+   "u" 16-bit unsigned immediate.
 
-   "I" an immediate value used for macros
+   "I" An immediate value used for macros.
 
    The remaining codes may be extended.  Except as otherwise noted,
    the full extended operand is a 16 bit signed value.
-   "<" 3 bit unsigned shift count * 0 (MIPS16OP_*_RZ) (full 5 bit unsigned)
-   "[" 3 bit unsigned shift count * 0 (MIPS16OP_*_RZ) (full 6 bit unsigned)
-   "]" 3 bit unsigned shift count * 0 (MIPS16OP_*_RX) (full 6 bit unsigned)
-   "5" 5 bit unsigned immediate * 0 (MIPS16OP_*_IMM5)
-   "F" 4 bit signed immediate * 0 (MIPS16OP_*_IMM4) (full 15 bit signed)
-   "H" 5 bit unsigned immediate * 2 (MIPS16OP_*_IMM5)
-   "W" 5 bit unsigned immediate * 4 (MIPS16OP_*_IMM5)
-   "D" 5 bit unsigned immediate * 8 (MIPS16OP_*_IMM5)
-   "j" 5 bit signed immediate * 0 (MIPS16OP_*_IMM5)
-   "8" 8 bit unsigned immediate * 0 (MIPS16OP_*_IMM8)
-   "V" 8 bit unsigned immediate * 4 (MIPS16OP_*_IMM8)
-   "C" 8 bit unsigned immediate * 8 (MIPS16OP_*_IMM8)
-   "U" 8 bit unsigned immediate * 0 (MIPS16OP_*_IMM8) (full 16 bit unsigned)
-   "k" 8 bit signed immediate * 0 (MIPS16OP_*_IMM8)
-   "K" 8 bit signed immediate * 8 (MIPS16OP_*_IMM8)
-   "p" 8 bit conditional branch address (MIPS16OP_*_IMM8)
-   "q" 11 bit branch address (MIPS16OP_*_IMM11)
-   "A" 8 bit PC relative address * 4 (MIPS16OP_*_IMM8)
-   "B" 5 bit PC relative address * 8 (MIPS16OP_*_IMM5)
-   "E" 5 bit PC relative address * 4 (MIPS16OP_*_IMM5)
-   "m" 7 bit register list for SAVE/RESTORE instruction (18 bit extended)
+   "<" 3-bit unsigned shift count * 1 at bit 2 (SHAMT) (full 5-bit unsigned).
+   "[" 3-bit unsigned shift count * 1 at bit 2 (SHAMT) (full 6-bit unsigned).
+   "]" 3-bit unsigned shift count * 1 at bit 8 (RX) (full 6-bit unsigned).
+   "5" 5-bit unsigned immediate * 1 at bit 0 (IMM5).
+   "F" 4-bit signed immediate * 1 a bit 0 (IMM4) (full 15-bit signed).
+   "H" 5-bit unsigned immediate * 2 at bit 0 (IMM5).
+   "W" 5-bit unsigned immediate * 4 at bit 0 (IMM5).
+   "D" 5-bit unsigned immediate * 8 at bit 0 (IMM5).
+   "j" 5-bit signed immediate * 1 at bit 0 (IMM5).
+   "8" 8-bit unsigned immediate * 1 at bit 0 (IMM8).
+   "V" 8-bit unsigned immediate * 4 at bit 0 (IMM8).
+   "C" 8-bit unsigned immediate * 8 at bit 0 (IMM8).
+   "U" 8-bit unsigned immediate * 1 at bit 0 (IMM8) (full 16-bit unsigned).
+   "k" 8-bit signed immediate * 1 at bit 0 (IMM8).
+   "K" 8-bit signed immediate * 8 at bit 0 (IMM8).
+   "p" 8-bit conditional branch address at bit 0 (IMM8).
+   "q" 11-bit branch address at bit 0 (IMM11).
+   "A" 8-bit PC relative address * 4 at bit 0 (IMM8).
+   "B" 5-bit PC relative address * 8 at bit 0 (IMM5).
+   "E" 5-bit PC relative address * 4 at bit 0 (IMM5).
+   "m" 7-bit register list for SAVE/RESTORE instruction (18-bit extended).
 
    Characters used so far, for quick reference when adding more:
    "0123456 89"
@@ -1713,190 +1718,186 @@  extern const int bfd_mips16_num_opcodes;
 #define MICROMIPSOP_MASK_MJ		0x1f
 #define MICROMIPSOP_SH_MJ		0
 
-/* These are the characters which may appears in the args field of a microMIPS
-   instruction.  They appear in the order in which the fields appear
-   when the instruction is used.  Commas and parentheses in the args
-   string are ignored when assembling, and written into the output
+/* These are the characters which may appears in the args field of a
+   microMIPS instruction.  They appear in the order in which the fields
+   appear when the instruction is used.  Commas and parentheses in the
+   args string are ignored when assembling, and written into the output
    when disassembling.
 
    The followings are for 16-bit microMIPS instructions.
 
-   "ma" must be $28
-   "mc" 3-bit MIPS registers 2-7, 16, 17 (MICROMIPSOP_*_MC) at bit 4
-        The same register used as both source and target.
-   "md" 3-bit MIPS registers 2-7, 16, 17 (MICROMIPSOP_*_MD) at bit 7
-   "me" 3-bit MIPS registers 2-7, 16, 17 (MICROMIPSOP_*_ME) at bit 1
-        The same register used as both source and target.
-   "mf" 3-bit MIPS registers 2-7, 16, 17 (MICROMIPSOP_*_MF) at bit 3
-   "mg" 3-bit MIPS registers 2-7, 16, 17 (MICROMIPSOP_*_MG) at bit 0
-   "mh" 3-bit MIPS register pair (MICROMIPSOP_*_MH) at bit 7
-   "mj" 5-bit MIPS registers (MICROMIPSOP_*_MJ) at bit 0
-   "ml" 3-bit MIPS registers 2-7, 16, 17 (MICROMIPSOP_*_ML) at bit 4
-   "mm" 3-bit MIPS registers 0, 2, 3, 16-20 (MICROMIPSOP_*_MM) at bit 1
-   "mn" 3-bit MIPS registers 0, 2, 3, 16-20 (MICROMIPSOP_*_MN) at bit 4
-   "mp" 5-bit MIPS registers (MICROMIPSOP_*_MP) at bit 5
-   "mq" 3-bit MIPS registers 0, 2-7, 17 (MICROMIPSOP_*_MQ) at bit 7
-   "mr" must be program counter
-   "ms" must be $29
-   "mt" must be the same as the previous register
-   "mx" must be the same as the destination register
-   "my" must be $31
-   "mz" must be $0
+   "ma" Must be $28.
+   "mc" 3-bit registers 2-7, 16, 17 at bit 4.
+	The same register used as both source and target.
+   "md" 3-bit registers 2-7, 16, 17 at bit 7.
+   "me" 3-bit registers 2-7, 16, 17 at bit 1.
+	The same register used as both source and target.
+   "mf" 3-bit registers 2-7, 16, 17 at bit 3.
+   "mg" 3-bit registers 2-7, 16, 17 at bit 0.
+   "mh" 3-bit register pair at bit 7.
+   "mj" 5-bit registers at bit 0.
+   "ml" 3-bit registers 2-7, 16, 17 at bit 4.
+   "mm" 3-bit registers 0, 2, 3, 16-20 at bit 1.
+   "mn" 3-bit registers 0, 2, 3, 16-20 at bit 4.
+   "mp" 5-bit registers at bit 5.
+   "mq" 3-bit registers 0, 2-7, 17 at bit 7.
+   "mr" Must be program counter.
+   "ms" Must be $29.
+   "mt" Must be the same as the previous register.
+   "mx" Must be the same as the destination register.
+   "my" Must be $31.
+   "mz" Must be $0.
 
-   "mA" 7-bit immediate (-64 .. 63) << 2 (MICROMIPSOP_*_IMMA)
-   "mB" 3-bit immediate (-1, 1, 4, 8, 12, 16, 20, 24) (MICROMIPSOP_*_IMMB)
+   "mA" 7-bit immediate (-64 .. 63) << 2 at bit 0.
+   "mB" 3-bit immediate (-1, 1, 4, 8, 12, 16, 20, 24) at bit 1.
    "mC" 4-bit immediate (1, 2, 3, 4, 7, 8, 15, 16, 31, 32, 63, 64, 128, 255,
-        32768, 65535) (MICROMIPSOP_*_IMMC)
-   "mD" 10-bit branch address (-512 .. 511) << 1 (MICROMIPSOP_*_IMMD)
-   "mE" 7-bit branch address (-64 .. 63) << 1 (MICROMIPSOP_*_IMME)
-   "mF" 4-bit immediate (0 .. 15)  (MICROMIPSOP_*_IMMF)
-   "mG" 4-bit immediate (-1 .. 14) (MICROMIPSOP_*_IMMG)
-   "mH" 4-bit immediate (0 .. 15) << 1 (MICROMIPSOP_*_IMMH)
-   "mI" 7-bit immediate (-1 .. 126) (MICROMIPSOP_*_IMMI)
-   "mJ" 4-bit immediate (0 .. 15) << 2 (MICROMIPSOP_*_IMMJ)
-   "mL" 4-bit immediate (0 .. 15) (MICROMIPSOP_*_IMML)
-   "mM" 3-bit immediate (1 .. 8) (MICROMIPSOP_*_IMMM)
-   "mN" 2-bit immediate (0 .. 3) for register list (MICROMIPSOP_*_IMMN)
-   "mO" 4-bit immediate (0 .. 15) (MICROMIPSOP_*_IMML)
-   "mP" 5-bit immediate (0 .. 31) << 2 (MICROMIPSOP_*_IMMP)
-   "mU" 5-bit immediate (0 .. 31) << 2 (MICROMIPSOP_*_IMMU)
-   "mW" 6-bit immediate (0 .. 63) << 2 (MICROMIPSOP_*_IMMW)
-   "mX" 4-bit immediate (-8 .. 7) (MICROMIPSOP_*_IMMX)
-   "mY" 9-bit immediate (-258 .. -3, 2 .. 257) << 2 (MICROMIPSOP_*_IMMY)
-   "mZ" must be zero
+	32768, 65535) at bit 0.
+   "mD" 10-bit branch address (-512 .. 511) << 1 at bit 0.
+   "mE" 7-bit branch address (-64 .. 63) << 1 at bit 0.
+   "mF" 4-bit immediate (0 .. 15) at bit 0.
+   "mG" 4-bit immediate (-1 .. 14) at bit 0.
+   "mH" 4-bit immediate (0 .. 15) << 1 at bit 0.
+   "mI" 7-bit immediate (-1 .. 126) at bit 0.
+   "mJ" 4-bit immediate (0 .. 15) << 2 at bit 0.
+   "mL" 4-bit immediate (0 .. 15) at bit 0.
+   "mM" 3-bit immediate (1 .. 8) at bit 1.
+   "mN" 2-bit immediate (0 .. 3) for register list at bit 4.
+   "mO" 4-bit immediate (0 .. 15) at bit 0.
+   "mP" 5-bit immediate (0 .. 31) << 2 at bit 0.
+   "mU" 5-bit immediate (0 .. 31) << 2 at bit 0.
+   "mW" 6-bit immediate (0 .. 63) << 2 at bit 1.
+   "mX" 4-bit immediate (-8 .. 7) at bit 1.
+   "mY" 9-bit immediate (-258 .. -3, 2 .. 257) << 2 at bit 1.
+   "mZ" Must be zero.
 
    In most cases 32-bit microMIPS instructions use the same characters
    as MIPS (with ADDIUPC being a notable exception, but there are some
    others too).
 
-   "." 10-bit signed offset/number (MICROMIPSOP_*_OFFSET10)
-   "1" 5-bit sync type (MICROMIPSOP_*_STYPE)
-   "<" 5-bit shift amount (MICROMIPSOP_*_SHAMT)
-   ">" shift amount between 32 and 63, stored after subtracting 32
-       (MICROMIPSOP_*_SHAMT)
-   "\" 3-bit position for ASET and ACLR (MICROMIPSOP_*_3BITPOS)
-   "|" 4-bit trap code (MICROMIPSOP_*_TRAP)
-   "~" 12-bit signed offset (MICROMIPSOP_*_OFFSET12)
-   "a" 26-bit target address (MICROMIPSOP_*_TARGET)
-   "+i" likewise, but flips bit 0
-   "b" 5-bit base register (MICROMIPSOP_*_RS)
-   "c" 10-bit higher breakpoint code (MICROMIPSOP_*_CODE)
-   "d" 5-bit destination register specifier (MICROMIPSOP_*_RD)
-   "h" 5-bit PREFX hint (MICROMIPSOP_*_PREFX)
-   "i" 16-bit unsigned immediate (MICROMIPSOP_*_IMMEDIATE)
-   "j" 16-bit signed immediate (MICROMIPSOP_*_DELTA)
-   "k" 5-bit cache opcode in target register position (MICROMIPSOP_*_CACHE)
-   "n" register list for 32-bit LWM/SWM instruction (MICROMIPSOP_*_RT)
-   "o" 16-bit signed offset (MICROMIPSOP_*_DELTA)
-   "p" 16-bit PC-relative branch target address (MICROMIPSOP_*_DELTA)
-   "q" 10-bit lower breakpoint code (MICROMIPSOP_*_CODE2)
-   "r" 5-bit same register used as both source and target (MICROMIPSOP_*_RS)
-   "s" 5-bit source register specifier (MICROMIPSOP_*_RS)
-   "t" 5-bit target register (MICROMIPSOP_*_RT)
-   "u" 16-bit upper 16 bits of address (MICROMIPSOP_*_IMMEDIATE)
-   "v" 5-bit same register used as both source and destination
-       (MICROMIPSOP_*_RS)
-   "w" 5-bit same register used as both target and destination
-       (MICROMIPSOP_*_RT)
-   "x" 5-bit source 3 register for ALNV.PS (MICROMIPSOP_*_RS3)
-   "z" must be zero register
-   "C" 23-bit coprocessor function code (MICROMIPSOP_*_COPZ)
-   "K" 5-bit Hardware Register (RDHWR instruction) (MICROMIPSOP_*_RS)
+   "." 10-bit signed offset/number at bit 6.
+   "1" 5-bit SYNC type at bit 16.
+   "<" 5-bit shift amount at bit 11.
+   ">" Shift amount between 32 and 63, stored after subtracting 3, at bit 11.
+   "\" 3-bit position for ASET and ACLR at bit 21.
+   "|" 4-bit trap code at bit 12.
+   "~" 12-bit signed offset at bit 0.
+   "a" 26-bit target address at bit 0.
+   "+i" Likewise, but flips bit 0.
+   "b" 5-bit base register at bit 16 (RS).
+   "c" 10-bit higher breakpoint code at bit 16.
+   "d" 5-bit destination register at bit 11 (RD).
+   "h" 5-bit PREFX hint at bit 11.
+   "i" 16-bit unsigned immediate at bit 0.
+   "j" 16-bit signed immediate at bit 0.
+   "k" 5-bit CACHE opcode in target register position at bit 21.
+   "n" 5-bit register list for 32-bit LWM/SWM instruction at bit 21 (RT).
+   "o" 16-bit signed offset at bit 0.
+   "p" 16-bit PC-relative branch target address at bit 0.
+   "q" 10-bit lower breakpoint code at bit 6.
+   "r" 5-bit same register used as both source and target at bit 16 (RS).
+   "s" 5-bit source register at bit 16 (RS).
+   "t" 5-bit target register at bit 21 (RT).
+   "u" 16-bit upper 16 bits of address at bit 0.
+   "v" 5-bit same register used as both source and destination at bit 16 (RS).
+   "w" 5-bit same register used as both target and destination at bit 21 (RT).
+   "x" 5-bit source 3 register for ALNV.PS at bit 6.
+   "z" Must be zero register.
+   "C" 23-bit coprocessor function code at bit 3.
+   "K" 5-bit Hardware Register (RDHWR instruction) at bit 16 (RS).
 
-   "+A" 5-bit INS/EXT/DINS/DEXT/DINSM/DEXTM position, which becomes
-        LSB (MICROMIPSOP_*_EXTLSB).
+   "+A" 5-bit INS/EXT/DINS/DEXT/DINSM/DEXTM position at bit 6,
+	which becomes LSB.
 	Enforces: 0 <= pos < 32.
-   "+B" 5-bit INS/DINS size, which becomes MSB (MICROMIPSOP_*_INSMSB).
+   "+B" 5-bit INS/DINS size at bit 11, which becomes MSB.
 	Requires that "+A" or "+E" occur first to set position.
 	Enforces: 0 < (pos+size) <= 32.
-   "+C" 5-bit EXT/DEXT size, which becomes MSBD (MICROMIPSOP_*_EXTMSBD).
+   "+C" 5-bit EXT/DEXT size at bit 11, which becomes MSBD.
 	Requires that "+A" or "+E" occur first to set position.
 	Enforces: 0 < (pos+size) <= 32.
 	(Also used by DEXT w/ different limits, but limits for
 	that are checked by the M_DEXT macro.)
-   "+E" 5-bit DINSU/DEXTU position, which becomes LSB-32 (MICROMIPSOP_*_EXTLSB).
+   "+E" 5-bit DINSU/DEXTU position at bit 6, which becomes LSB-32.
 	Enforces: 32 <= pos < 64.
-   "+F" 5-bit DINSM/DINSU size, which becomes MSB-32 (MICROMIPSOP_*_INSMSB).
+   "+F" 5-bit DINSM/DINSU size at bit 11., which becomes MSB-32.
 	Requires that "+A" or "+E" occur first to set position.
 	Enforces: 32 < (pos+size) <= 64.
-   "+G" 5-bit DEXTM size, which becomes MSBD-32 (MICROMIPSOP_*_EXTMSBD).
+   "+G" 5-bit DEXTM size at bit 11, which becomes MSBD-32.
 	Requires that "+A" or "+E" occur first to set position.
 	Enforces: 32 < (pos+size) <= 64.
-   "+H" 5-bit DEXTU size, which becomes MSBD (MICROMIPSOP_*_EXTMSBD).
+   "+H" 5-bit DEXTU size at bit 11, which becomes MSBD.
 	Requires that "+A" or "+E" occur first to set position.
 	Enforces: 32 < (pos+size) <= 64.
-   "+J" 10-bit SYSCALL/WAIT/SDBBP/HYPCALL function code
-        (MICROMIPSOP_*_CODE10)
+   "+J" 10-bit SYSCALL/WAIT/SDBBP/HYPCALL function code at bit 16.
 
    PC-relative addition (ADDIUPC) instruction:
-   "mQ" 23-bit offset (-4194304 .. 4194303) << 2 (MICROMIPSOP_*_IMMQ)
-   "mb" 3-bit MIPS registers 2-7, 16, 17 (MICROMIPSOP_*_MB) at bit 23
+   "mQ" 23-bit offset (-4194304 .. 4194303) << 2 at bit 0.
+   "mb" 3-bit MIPS registers 2-7, 16, 17 at bit 23.
 
    Floating point instructions:
-   "D" 5-bit destination register (MICROMIPSOP_*_FD)
-   "M" 3-bit compare condition code (MICROMIPSOP_*_CCC)
-   "N" 3-bit branch condition code (MICROMIPSOP_*_BCC)
-   "R" 5-bit fr source 3 register (MICROMIPSOP_*_FR)
-   "S" 5-bit fs source 1 register (MICROMIPSOP_*_FS)
-   "T" 5-bit ft source 2 register (MICROMIPSOP_*_FT)
+   "D" 5-bit destination register at bit 11 (FD).
+   "M" 3-bit compare condition code at bit 13 (CCC).
+   "N" 3-bit branch condition code at bit 18 (BCC).
+   "R" 5-bit fr source 3 register at bit 6 (FR).
+   "S" 5-bit fs source 1 register at bit 16 (FS).
+   "T" 5-bit ft source 2 register at bit 21 (FT).
    "V" 5-bit same register used as floating source and destination or target
-       (MICROMIPSOP_*_FS)
+       at bit 16 (FS).
 
    Coprocessor instructions:
-   "E" 5-bit target register (MICROMIPSOP_*_RT)
-   "G" 5-bit source register (MICROMIPSOP_*_RS)
-   "H" 3-bit sel field for (D)MTC* and (D)MFC* (MICROMIPSOP_*_SEL)
-   "g" 5-bit control source register (MICROMIPSOP_*_RS)
+   "E" 5-bit target register at bit 21 (RT).
+   "G" 5-bit source register at bit 16 (RS).
+   "H" 3-bit sel field for (D)MTC* and (D)MFC* at bit 11.
+   "g" 5-bit control source register at bit 16 (RS).
 
    Macro instructions:
-   "A" general 32 bit expression
+   "A" General 32-bit expression.
    "I" 32-bit immediate (value placed in imm_expr).
-   "F" 64-bit floating point constant in .rdata
-   "L" 64-bit floating point constant in .lit8
-   "f" 32-bit floating point constant
-   "l" 32-bit floating point constant in .lit4
+   "F" 64-bit floating point constant in .rdata.
+   "L" 64-bit floating point constant in .lit8.
+   "f" 32-bit floating point constant.
+   "l" 32-bit floating point constant in .lit4.
 
    DSP ASE usage:
-   "2" 2-bit unsigned immediate for byte align (MICROMIPSOP_*_BP)
-   "3" 3-bit unsigned immediate (MICROMIPSOP_*_SA3)
-   "4" 4-bit unsigned immediate (MICROMIPSOP_*_SA4)
-   "5" 8-bit unsigned immediate (MICROMIPSOP_*_IMM8)
-   "6" 5-bit unsigned immediate (MICROMIPSOP_*_RS)
-   "7" 2-bit DSP accumulator register (MICROMIPSOP_*_DSPACC)
-   "8" 6-bit unsigned immediate (MICROMIPSOP_*_WRDSP)
-   "0" 6-bit signed immediate (MICROMIPSOP_*_DSPSFT)
-   "@" 10-bit signed immediate (MICROMIPSOP_*_IMM10)
-   "^" 5-bit unsigned immediate (MICROMIPSOP_*_RD)
+   "2" 2-bit unsigned immediate for byte align at bit 14.
+   "3" 3-bit unsigned immediate at bit 13.
+   "4" 4-bit unsigned immediate at bit 12.
+   "5" 8-bit unsigned immediate at bit 13.
+   "6" 5-bit unsigned immediate at bit 16 (RS).
+   "7" 2-bit DSP accumulator register at bit 14.
+   "8" 6-bit unsigned immediate at bit 14.
+   "0" 6-bit signed immediate at bit 16.
+   "@" 10-bit signed immediate at bit 16.
+   "^" 5-bit unsigned immediate at bit 11 (RD).
 
    microMIPS Enhanced VA Scheme:
-   "+j" 9-bit signed offset in bit 0 (OP_*_EVAOFFSET)
+   "+j" 9-bit signed offset in bit 0.
 
    MSA Extension:
-   "+d" 5-bit MSA register (FD)
-   "+e" 5-bit MSA register (FS)
-   "+h" 5-bit MSA register (FT)
-   "+k" 5-bit GPR at bit 6
-   "+l" 5-bit MSA control register at bit 6
-   "+n" 5-bit MSA control register at bit 11
-   "+o" 4-bit vector element index at bit 16
-   "+u" 3-bit vector element index at bit 16
-   "+v" 2-bit vector element index at bit 16
-   "+w" 1-bit vector element index at bit 16
-   "+x" 5-bit shift amount at bit 16
-   "+T" (-512 .. 511) << 0 at bit 16
-   "+U" (-512 .. 511) << 1 at bit 16
-   "+V" (-512 .. 511) << 2 at bit 16
-   "+W" (-512 .. 511) << 3 at bit 16
-   "+~" 2 bit LSA/DLSA shift amount from 1 to 4 at bit 6
-   "+!" 3 bit unsigned bit position at bit 16
-   "+@" 4 bit unsigned bit position at bit 16
-   "+#" 6 bit unsigned bit position at bit 16
-   "+$" 5 bit unsigned immediate at bit 16
-   "+%" 5 bit signed immediate at bit 16
-   "+^" 10 bit signed immediate at bit 11
-   "+&" 0 vector element index
-   "+*" 5-bit register vector element index at bit 16
-   "+|" 8-bit mask at bit 16
+   "+d" 5-bit MSA register at bit 6 (FD).
+   "+e" 5-bit MSA register at bit 11 (FS).
+   "+h" 5-bit MSA register at bit 16 (FT).
+   "+k" 5-bit GPR at bit 6.
+   "+l" 5-bit MSA control register at bit 6.
+   "+n" 5-bit MSA control register at bit 11.
+   "+o" 4-bit vector element index at bit 16.
+   "+u" 3-bit vector element index at bit 16.
+   "+v" 2-bit vector element index at bit 16.
+   "+w" 1-bit vector element index at bit 16.
+   "+x" 5-bit shift amount at bit 16.
+   "+T" (-512 .. 511) << 0 at bit 16.
+   "+U" (-512 .. 511) << 1 at bit 16.
+   "+V" (-512 .. 511) << 2 at bit 16.
+   "+W" (-512 .. 511) << 3 at bit 16.
+   "+~" 2-bit LSA/DLSA shift amount from 1 to 4 at bit 6.
+   "+!" 3-bit unsigned bit position at bit 16.
+   "+@" 4-bit unsigned bit position at bit 16.
+   "+#" 6-bit unsigned bit position at bit 16.
+   "+$" 5-bit unsigned immediate at bit 16.
+   "+%" 5-bit signed immediate at bit 16.
+   "+^" 10-bit signed immediate at bit 11.
+   "+&" 0 vector element index.
+   "+*" 5-bit register vector element index at bit 16.
+   "+|" 8-bit mask at bit 16.
 
    MT ASE usage:
    "!" 1-bit usermode flag at bit 10.
@@ -1907,10 +1908,11 @@  extern const int bfd_mips16_num_opcodes;
    "y" 5-bit control target register at bit 21 (RT).
 
    Other:
-   "()" parens surrounding optional value
-   ","  separates operands
-   "+"  start of extension sequence
-   "m"  start of microMIPS extension sequence
+   "()" Parens surrounding optional value.
+   ","  Separates operands.
+   "m"  Start of microMIPS extension sequence.
+   "+"  Start of extension sequence.
+   "-"  Start of extension sequence.
 
    Characters used so far, for quick reference when adding more:
    "12345678 0"
@@ -1918,13 +1920,6 @@  extern const int bfd_mips16_num_opcodes;
    "ABCDEFGHIJKLMN   RST V    "
    "abcd fghijklmnopqrstuvwxyz"
 
-   Extension character sequences used so far ("+" followed by the
-   following), for quick reference when adding more:
-   ""
-   "~!@#$%^&*|"
-   "ABCEFGHJTUVW"
-   "dehijklnouvwx"
-
    Extension character sequences used so far ("m" followed by the
    following), for quick reference when adding more:
    ""
@@ -1932,6 +1927,13 @@  extern const int bfd_mips16_num_opcodes;
    " BCDEFGHIJ LMNOPQ   U WXYZ"
    " bcdefghij lmn pq st   xyz"
 
+   Extension character sequences used so far ("+" followed by the
+   following), for quick reference when adding more:
+   ""
+   "~!@#$%^&*|"
+   "ABC EFGH J         TUVW   "
+   "   de  hijkl no     uvwx  "
+
    Extension character sequences used so far ("-" followed by the
    following), for quick reference when adding more:
    ""