Re: [PATCH] microMIPS support

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Tue, 1 May 2012 00:45:06 +0100
> From: "Maciej W. Rozycki" <macro@codesourcery.com>
> CC: <gdb-patches@sourceware.org>
> 
>  I've just checked a random book that I have handy, that is "MIPS R4000 
> Microprocessor User's Manual" and they mix cases in the index just fine on 
> the similar principles that I'm referring to here.  As does "The Cambridge 
> Grammar of the English Language" (a reference of a better authority 
> probably, but only available in hard copy, so you may not have one readily 
> available to check yourself).
> 
>  Therefore it doesn't appear to me starting index entries with a letter of 
> any particular case is a requirement in English literature (being a 
> non-native English speaker I have to rely on references).

I'm trying to follow the instructions in the Texinfo manual, not in
other books.  The Texinfo manual says to choose a convention for
capitalization of the first word of the index entries, and stick to
it.  (It does allow using caps for proper names.)

Anyway, I think this is a moot point now, because there are no index
entries in your patch whose first word may need capitalization.

> gdb/doc/gdb.texinfo:36670: `MIPS Breakpoint Kinds' has no Up field (perhaps incorrect sectioning?).
> 
> if I add a lone @node definition, or that plus:
> 
> gdb/doc/gdb.texinfo:36670: warning: unreferenced node `MIPS Breakpoint Kinds'.
> 
> if I place a @menu reference to that node in any of the upper sections.  

That's most probably because you added only some of the menus, not all
of them.  The minor variation of your patch below doesn't have this
problem, it produces an Info manual without any warnings or errors.

> I'll be pushing it in this form as soon as the MIPS16 manual
> function call change has been committed.

I believe committing a patch over objections of the responsible
maintainer is against the rules described in MAINTAINERS (as I
understand them).  So please don't do that.

Please use the slightly modified patch below instead.

(After you install your patch, I will follow up with a patch that
changes all occurrences of "MIPS" to use @acronym.  I already have
that patch ready on my box.)

Thanks.

=== modified file 'gdb/doc/gdb.texinfo'
--- gdb/doc/gdb.texinfo	2012-04-29 06:45:02 +0000
+++ gdb/doc/gdb.texinfo	2012-05-02 05:12:51 +0000
@@ -20377,6 +20377,38 @@
 @kindex show mips abi
 Show the MIPS ABI used by @value{GDBN} to debug the inferior.
 
+@item set mips compression @var{arg}
+@kindex set mips compression
+@cindex code compression, @acronym{MIPS}
+Tell @value{GDBN} which @acronym{MIPS} compressed
+@acronym{ISA, Instruction Set Architecture} encoding is used by the
+inferior.  @value{GDBN} uses this for code disassembly and other
+internal interpretation purposes.  This setting is only referred to
+when no executable has been associated with the debugging session or
+the executable does not provide information about the encoding it uses.
+Otherwise this setting is automatically updated from information
+provided by the executable.
+
+Possible values of @var{arg} are @samp{mips16} and @samp{micromips}.
+The default compressed @acronym{ISA} encoding is @samp{mips16}, as
+executables containing @acronym{MIPS16} code frequently are not
+identified as such.
+
+This setting is ``sticky''; that is, it retains its value across
+debugging sessions until reset either explicitly with this command or
+implicitly from an executable.
+
+The compiler and/or assembler typically add symbol table annotations to
+identify functions compiled for the @acronym{MIPS16} or
+@acronym{microMIPS} @acronym{ISA}s.  If these function-scope annotations
+are present, @value{GDBN} uses them in preference to the global
+compressed @acronym{ISA} encoding setting.
+
+@item show mips compression
+@kindex show mips compression
+Show the @acronym{MIPS} compressed @acronym{ISA} encoding used by
+@value{GDBN} to debug the inferior.
+
 @item set mipsfpu
 @itemx show mipsfpu
 @xref{MIPS Embedded, set mipsfpu}.
@@ -36589,9 +36621,21 @@
 target architectures.  Also see @ref{Standard Target Features}, for
 details of XML target descriptions for each architecture.
 
-@subsection ARM
-
-@subsubsection Breakpoint Kinds
+@menu
+* ARM-Specific Protocol Details::
+* MIPS-Specific Protocol Details::
+@end menu
+
+@node ARM-Specific Protocol Details
+@subsection @acronym{ARM}-specific Protocol Details
+
+@menu
+* ARM Breakpoint Kinds::
+@end menu
+
+@node ARM Breakpoint Kinds
+@subsubsection @acronym{ARM} Breakpoint Kinds
+@cindex breakpoint kinds, @acronym{ARM}
 
 These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
 
@@ -36604,37 +36648,64 @@
 32-bit Thumb mode (Thumb-2) breakpoint.
 
 @item 4
-32-bit ARM mode breakpoint.
+32-bit @acronym{ARM} mode breakpoint.
 
 @end table
 
-@subsection MIPS
-
-@subsubsection Register Packet Format
+@node MIPS-Specific Protocol Details
+@subsection @acronym{MIPS}-specific Protocol Details
+
+@menu
+* MIPS Register packet Format::
+* MIPS Breakpoint Kinds::
+@end menu
+
+@node MIPS Register packet Format
+@subsubsection @acronym{MIPS} Register Packet Format
 
 The following @code{g}/@code{G} packets have previously been defined.
 In the below, some thirty-two bit registers are transferred as
 sixty-four bits.  Those registers should be zero/sign extended (which?)
 to fill the space allocated.  Register bytes are transferred in target
 byte order.  The two nibbles within a register byte are transferred
-most-significant - least-significant.
+most-significant -- least-significant.
 
 @table @r
 
 @item MIPS32
-
 All registers are transferred as thirty-two bit quantities in the order:
 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point
 registers; fsr; fir; fp.
 
 @item MIPS64
-
 All registers are transferred as sixty-four bit quantities (including
 thirty-two bit registers such as @code{sr}).  The ordering is the same
 as @code{MIPS32}.
 
 @end table
 
+@node MIPS Breakpoint Kinds
+@subsubsection @acronym{MIPS} Breakpoint Kinds
+@cindex breakpoint kinds, @acronym{MIPS}
+
+These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets.
+
+@table @r
+
+@item 2
+16-bit @acronym{MIPS16} mode breakpoint.
+
+@item 3
+16-bit @acronym{microMIPS} mode breakpoint.
+
+@item 4
+32-bit standard @acronym{MIPS} mode breakpoint.
+
+@item 5
+32-bit @acronym{microMIPS} mode breakpoint.
+
+@end table
+
 @node Tracepoint Packets
 @section Tracepoint Packets
 @cindex tracepoint packets