Re: PATCH: Document i386 target features

["H.J. Lu" <hjl.tools@gmail.com>]

On Mon, Feb 8, 2010 at 10:37 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Mon, 8 Feb 2010 07:33:37 -0800
>> From: "H.J. Lu" <hongjiu.lu@intel.com>
>>
>> Here is the patch to document i386 target features for i386 XML files
>> I checked in.  OK to install?
>
> Thanks, I have a few comments:
>
>> +@cindex target descriptions, I386 features
>
> Index entries are supposed to be mostly in lower case.  Would it be
> okay to use "i386" instead of I386 here?
>
>> +targets.  It should contain registers @samp{eax} through @samp{edi}
>> +plus @samp{eip} for i386 and @samp{rax} through @samp{r15} plus
>> +@samp{rip} for amd64, @samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds},
>> +@samp{es}, @samp{fs}, @samp{gs}, registers @samp{st0} through @samp{st7},
>> +@samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff},
>> +@samp{foseg}, @samp{fooff} and @samp{fop}.
>
> This list is very long, and makes the sentence long and hard to
> grasp.  I think it would be more palatable as an itemized list, like
> so:
>
>  It should contain the following registers:
>
>  @itemize @minus
>  @item
>  @samp{eax} through @samp{edi} and @samp{eip} for i386
>  @item
>  @samp{rax} through @samp{r15} plus @samp{rip} for amd64
>  @item
>  @samp{eflags}
>  @item
>  @samp{cs}, @samp{ss}, @samp{ds}, @samp{es}, @samp{fs}, @samp{gs}
>  ...
>  @end itemize
>
> (I grouped related registers together to make the list shorter).
>
> Btw, is it "contain the following registers" or "describe the
> following registers"?
>
>> +They may be i386 or amd64 depending on the target.
>
> Who are "they" here?
>

Thanks for your comments. This patch generates:

.4.2 i386 Features
-------------------

The `org.gnu.gdb.i386.core' feature is required for i386/amd64 targets.
It should describe the following registers:

     `eax' through `edi' plus `eip' for i386

   - `rax' through `r15' plus `rip' for amd64

   - `eflags', `cs', `ss', `ds', `es', `fs', `gs'

   - `st0' through `st7'

   - `fctrl', `fstat', `ftag', `fiseg', `fioff', `foseg', `fooff' and
     `fop'

   The register sets may be different, depending on the target.
...

Will it be OK to install?

Thanks.

-- 
H.J.
--
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f01a720..0b17685 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -32796,6 +32796,7 @@ registers using the capitalization used in the
description.

 @menu
 * ARM Features::
+* i386 Features::
 * MIPS Features::
 * M68K Features::
 * PowerPC Features::
@@ -32831,6 +32832,43 @@ quad-precision registers from pairs of
double-precision registers.
 If this feature is present, @samp{org.gnu.gdb.arm.vfp} must also
 be present and include 32 double-precision registers.

+@node i386 Features
+@subsection i386 Features
+@cindex target descriptions, i386 features
+
+The @samp{org.gnu.gdb.i386.core} feature is required for i386/amd64
+targets.  It should describe the following registers:
+
+@itemize @minus
+@samp{eax} through @samp{edi} plus @samp{eip} for i386
+@item
+@samp{rax} through @samp{r15} plus @samp{rip} for amd64
+@item
+@samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds}, @samp{es},
+@samp{fs}, @samp{gs}
+@item
+@samp{st0} through @samp{st7}
+@item
+@samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff},
+@samp{foseg}, @samp{fooff} and @samp{fop}
+@end itemize
+
+The register sets may be different, depending on the target.
+
+The @samp{org.gnu.gdb.i386.sse} feature is required.  It should
+describe registers:
+
+@itemize @minus
+@samp{xmm0} through @samp{xmm7} for i386
+@item
+@samp{xmm0} through @samp{xmm15} for amd64
+@item
+@samp{mxcsr}
+@end itemize
+
+The @samp{org.gnu.gdb.i386.linux} feature is optional.  It should
+describe a single register, @samp{orig_eax}.
+
 @node MIPS Features
 @subsection MIPS Features
 @cindex target descriptions, MIPS features