PATCH: Document i386 target features

PATCH: Document i386 target features

[H.J. Lu]

Hi,

Here is the patch to document i386 target features for i386 XML files
I checked in.  OK to install?

Thanks.


H.J.
---
2010-02-08  H.J. Lu  <hongjiu.lu@intel.com>

	* gdb.texinfo: Document i386 target features.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f01a720..c53f01a 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,26 @@ 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 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}.
+They may be i386 or amd64 depending on the target.
+
+The @samp{org.gnu.gdb.i386.sse} feature is required.  It should
+contain registers @samp{xmm0} through @samp{xmm7} for i386,
+registers @samp{xmm0} through @samp{xmm15} for amd64 and @samp{mxcsr}.
+
+The @samp{org.gnu.gdb.i386.linux} feature is optional.  It should
+contain a single register, @samp{orig_eax}.
+
 @node MIPS Features
 @subsection MIPS Features
 @cindex target descriptions, MIPS features

Re: PATCH: Document i386 target features

[Eli Zaretskii]

> 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?

Re: PATCH: Document i386 target features

[H.J. Lu]

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

Re: PATCH: Document i386 target features

[Eli Zaretskii]

> Date: Mon, 8 Feb 2010 11:13:00 -0800
> From: "H.J. Lu" <hjl.tools@gmail.com>
> Cc: gdb-patches@sourceware.org
> 
> Will it be OK to install?

Yes, but...

> +@itemize @minus
> +@samp{eax} through @samp{edi} plus @samp{eip} for i386

You forgot @item line after the @itemize line.

That's why the first line in the result lacks the dash:

> It should describe the following registers:
> 
>      `eax' through `edi' plus `eip' for i386
> 
>    - `rax' through `r15' plus `rip' for amd64

> +@itemize @minus
> +@samp{xmm0} through @samp{xmm7} for i386

And here as well.

Okay with these two changes.

Thanks.