[PATCH v2 1/1] Documentation for MPX.

[PATCH v2 1/1] Documentation for MPX.

[Walfred Tedeschi]

Hello Eli and Pedro,

I tried to cover all feedback you gave me.
Concerning the footnote I have reduced it to avoid
early confusion, the topic will be explained anyhow later.

Thanks a lot for your review,
-Fred

Pedro: I am just back from christmas as you can see. :-)

2013-11-28  Walfred Tedeschi  <walfred.tedeschi@intel.com>

	* NEWS:  Add section for Intel(R) Architecture Instructions
	Extesions mentioning MPX.
doc/
	* gdb.texinfo (i386 Features): Add MPX feature registers.
	(x86 Specific featuresx86 Architecture-specific Issues): Adds
	a subsubsection for MPX and describes the display of the
	boundary registers.


---
 gdb/NEWS            |  2 ++
 gdb/doc/gdb.texinfo | 44 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/gdb/NEWS b/gdb/NEWS
index 9fc3638..fdb33d4 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -5558,3 +5558,5 @@ GDB now handles cross debugging.  If you are remotely debugging between
 two different machines, type ``./configure host -target=targ''.
 Host is the machine where GDB will run; targ is the machine
 where the program that you are debugging will run.
+
+ *  GDB now supports access to Intel(R) MPX registers on GNU/Linux.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d854f46..7eacba2 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -21363,6 +21363,40 @@ be returned in a register.
 @kindex show struct-convention
 Show the current setting of the convention to return @code{struct}s
 from functions.
+
+@cindex Intel(R) Memory Protection Extensions (MPX).
+@subsubsection Intel(R) @dfn{Memory Protection Extensions} (MPX).
+
+@item bnd0raw..bnd3raw and bnd0@dots{}bnd3 registers display.
+Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
+@footnote{The register named with capital letters represent the architecture
+registers.} through @samp{BND3}.  Bound registers store a pair of 64-bit values
+which are the lower bound and upper bound.  Bounds are effective addresses or
+memory locations.  The upper bounds are architecturally represented in 1's
+complement form.  A bound having lower bound = 0, and upper bound = 0
+(1's complement of all bits set) will allow access to the entire address space.
+
+Architecture registers @samp{BND0} through @samp{BND3} are
+represented in @value{GDBN} as @samp{bnd0raw} through @samp{bnd3raw}.
+Pseudo registers @samp{bnd0} through @samp{bnd3} display the upper bound
+performing the complement of one operation on the upper bound value, i.e.@
+when upper bound in @samp{bnd0raw} is 0 in the @value{GDBN} @samp{bnd0} it will
+be @code{0xfff@dots{}}.  In this sense it can also be noted that the upper bounds are
+inclusive.
+
+As an example, assume that the register BND0 holds bounds for a pointer having
+access allowed for the range between 0x32 and 0x71.  The values present on
+bnd0raw and bnd registers are presented as follows:
+
+@smallexample
+	bnd0raw = @{0x32, 0xffffffff8e@}
+	bnd0 = @{lbound = 0x32, ubound = 0x71@} : size 64
+@end smallexample
+
+This way the raw value can be accessed via bnd0raw@dots{}bnd3raw.  Any change
+on bnd0@dots{}bnd3 or bnd0raw@dots{}bnd3raw is reflect on its counterpart.  When the
+bnd0@dots{}bnd3 registers are displayed via Python, the display includes the memory size,
+in bits, accessible to the pointer.
 @end table
 
 @node Alpha
@@ -43138,6 +43172,16 @@ describe the upper 128 bits of @sc{ymm} registers:
 @samp{ymm0h} through @samp{ymm15h} for amd64
 @end itemize
 
+The @samp{org.gnu.gdb.i386.mpx} is an optional feature representing Intel(R)
+Memory Protection Extension (MPX).  It should describe the following registers:
+
+@itemize @minus
+@item
+@samp{bnd0raw} through @samp{bnd3raw} for i386 and amd64.
+@item
+@samp{bndcfgu} and @samp{bndstatus} for i386 and amd64.
+@end itemize
+
 The @samp{org.gnu.gdb.i386.linux} feature is optional.  It should
 describe a single register, @samp{orig_eax}.
 
-- 
1.8.1.2

Re: [PATCH v2 1/1] Documentation for MPX.

[Eli Zaretskii]

> From: Walfred Tedeschi <walfred.tedeschi@intel.com>
> Cc: gdb-patches@sourceware.org, Walfred Tedeschi <walfred.tedeschi@intel.com>
> Date: Thu, 28 Nov 2013 11:54:02 +0100
> 
> I tried to cover all feedback you gave me.
> Concerning the footnote I have reduced it to avoid
> early confusion, the topic will be explained anyhow later.

Thanks.

> diff --git a/gdb/NEWS b/gdb/NEWS
> index 9fc3638..fdb33d4 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -5558,3 +5558,5 @@ GDB now handles cross debugging.  If you are remotely debugging between
>  two different machines, type ``./configure host -target=targ''.
>  Host is the machine where GDB will run; targ is the machine
>  where the program that you are debugging will run.
> +
> + *  GDB now supports access to Intel(R) MPX registers on GNU/Linux.

This is OK.

> +@cindex Intel(R) Memory Protection Extensions (MPX).
> +@subsubsection Intel(R) @dfn{Memory Protection Extensions} (MPX).

@cindex should be after the @subsubsection line.

> +@item bnd0raw..bnd3raw and bnd0@dots{}bnd3 registers display.
> +Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
> +@footnote{The register named with capital letters represent the architecture
> +registers.} through @samp{BND3}.  Bound registers store a pair of 64-bit values
> +which are the lower bound and upper bound.  Bounds are effective addresses or
> +memory locations.  The upper bounds are architecturally represented in 1's
> +complement form.  A bound having lower bound = 0, and upper bound = 0
> +(1's complement of all bits set) will allow access to the entire address space.
> +
> +Architecture registers @samp{BND0} through @samp{BND3} are
> +represented in @value{GDBN} as @samp{bnd0raw} through @samp{bnd3raw}.

Hmm... didn't I suggest to use "raw registers" instead of
"architectural registers"?  In fact, what are the differences between
this version of the patch and the previous one, they seem identical.

RE: [PATCH v2 1/1] Documentation for MPX.

[Tedeschi, Walfred]

Hi Eli,

Thanks for your review! 

About the "Architecture": You have made a comment on another place about Raw values/Architecture values. That was changed. The line is this one:
     +This way the raw value can be accessed via bnd0raw@dots{}bnd3raw.  Any 
     +change on bnd0@dots{}bnd3 or bnd0raw@dots{}bnd3raw is reflect on its 
     +counterpart.
Before:
    +This way the architecture value can be accessed via bnd0raw...bnd3raw.   
    +Any change on bnd0..bnd3 or bnd0raw...bnd3raw is reflect on its 
    +counterpart.  When displaying


I will add here a list of changes in V2:
1. Added @cindex for MPX and @def for MPX.
2.Exchanged "..." by @dots{}
3.Fix typo on "Architecture registers...." as mentioned.
4.Example is fixed (using "@{"  for "{" and  "@}" for "}").

About the phrase:
>+Architecture registers @samp{BND0} through @samp{BND3} are 
> +represented in @value{GDBN} as @samp{bnd0raw} through @samp{bnd3raw}. 

My intention was to emphasize that the BND register, as presented on Intel manual, is represented in GDB by bndraw.  Therefore the use of " Architecture registers".
Since we have already defined that BND are the architecture register we could omit the "Architecture Registers on the phrase writing like:

>+@samp{BND0} through @samp{BND3} are 
> +represented in @value{GDBN} as @samp{bnd0raw} through @samp{bnd3raw}.

What do you think?


Thanks a lot and best regards,
-Fred 


-----Original Message-----
From: Eli Zaretskii [mailto:eliz@gnu.org] 
Sent: Thursday, November 28, 2013 9:13 PM
To: Tedeschi, Walfred
Cc: palves@redhat.com; gdb-patches@sourceware.org
Subject: Re: [PATCH v2 1/1] Documentation for MPX.

> From: Walfred Tedeschi <walfred.tedeschi@intel.com>
> Cc: gdb-patches@sourceware.org, Walfred Tedeschi 
> <walfred.tedeschi@intel.com>
> Date: Thu, 28 Nov 2013 11:54:02 +0100
> 
> I tried to cover all feedback you gave me.
> Concerning the footnote I have reduced it to avoid early confusion, 
> the topic will be explained anyhow later.

Thanks.

> diff --git a/gdb/NEWS b/gdb/NEWS
> index 9fc3638..fdb33d4 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -5558,3 +5558,5 @@ GDB now handles cross debugging.  If you are 
> remotely debugging between  two different machines, type ``./configure host -target=targ''.
>  Host is the machine where GDB will run; targ is the machine  where 
> the program that you are debugging will run.
> +
> + *  GDB now supports access to Intel(R) MPX registers on GNU/Linux.

This is OK.

> +@cindex Intel(R) Memory Protection Extensions (MPX).
> +@subsubsection Intel(R) @dfn{Memory Protection Extensions} (MPX).

@cindex should be after the @subsubsection line.

> +@item bnd0raw..bnd3raw and bnd0@dots{}bnd3 registers display.
> +Memory Protection Extension (MPX) adds the bound registers 
> +@samp{BND0} @footnote{The register named with capital letters 
> +represent the architecture registers.} through @samp{BND3}.  Bound 
> +registers store a pair of 64-bit values which are the lower bound and 
> +upper bound.  Bounds are effective addresses or memory locations.  
> +The upper bounds are architecturally represented in 1's complement 
> +form.  A bound having lower bound = 0, and upper bound = 0 (1's complement of all bits set) will allow access to the entire address space.
> +
> +Architecture registers @samp{BND0} through @samp{BND3} are 
> +represented in @value{GDBN} as @samp{bnd0raw} through @samp{bnd3raw}.

Hmm... didn't I suggest to use "raw registers" instead of "architectural registers"?  In fact, what are the differences between this version of the patch and the previous one, they seem identical.
Intel GmbH
Dornacher Strasse 1
85622 Feldkirchen/Muenchen, Deutschland
Sitz der Gesellschaft: Feldkirchen bei Muenchen
Geschaeftsfuehrer: Christian Lamprechter, Hannes Schwaderer, Douglas Lusk
Registergericht: Muenchen HRB 47456
Ust.-IdNr./VAT Registration No.: DE129385895
Citibank Frankfurt a.M. (BLZ 502 109 00) 600119052

Re: [PATCH v2 1/1] Documentation for MPX.

[Eli Zaretskii]

> From: "Tedeschi, Walfred" <walfred.tedeschi@intel.com>
> CC: "palves@redhat.com" <palves@redhat.com>, "gdb-patches@sourceware.org"
> 	<gdb-patches@sourceware.org>
> Date: Fri, 29 Nov 2013 09:41:39 +0000
> 
> About the "Architecture": You have made a comment on another place about Raw values/Architecture values. That was changed. The line is this one:
>      +This way the raw value can be accessed via bnd0raw@dots{}bnd3raw.  Any 
>      +change on bnd0@dots{}bnd3 or bnd0raw@dots{}bnd3raw is reflect on its 
>      +counterpart.
> Before:
>     +This way the architecture value can be accessed via bnd0raw...bnd3raw.   
>     +Any change on bnd0..bnd3 or bnd0raw...bnd3raw is reflect on its 
>     +counterpart.  When displaying

OK, but I meant to use "raw" everywhere, not just in that part.

> I will add here a list of changes in V2:
> 1. Added @cindex for MPX and @def for MPX.
> 2.Exchanged "..." by @dots{}
> 3.Fix typo on "Architecture registers...." as mentioned.
> 4.Example is fixed (using "@{"  for "{" and  "@}" for "}").

Right.

> About the phrase:
> >+Architecture registers @samp{BND0} through @samp{BND3} are 
> > +represented in @value{GDBN} as @samp{bnd0raw} through @samp{bnd3raw}. 
> 
> My intention was to emphasize that the BND register, as presented on Intel manual, is represented in GDB by bndraw.  Therefore the use of " Architecture registers".
> Since we have already defined that BND are the architecture register we could omit the "Architecture Registers on the phrase writing like:
> 
> >+@samp{BND0} through @samp{BND3} are 
> > +represented in @value{GDBN} as @samp{bnd0raw} through @samp{bnd3raw}.
> 
> What do you think?

Fine with me, thanks.