[PATCH 1/1] Documentation for MPX.

[PATCH 1/1] Documentation for MPX.

[Walfred Tedeschi]

Hello Eli and Pedro,

This should complement the MPX registers check-in in terms of documentation.
Here I have tried to incorporate feedback from you both.


Thanks a lot for your review on the former patch series.

Best regards,
-Fred


2013-1X-XX  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 |   46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 0 deletions(-)

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..6041b4a 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -21363,6 +21363,42 @@ be returned in a register.
 @kindex show struct-convention
 Show the current setting of the convention to return @code{struct}s
 from functions.
+
+@subsubsection Intel(R) Memory Protection Extensions (MPX).
+
+@item bnd0raw..bnd3raw and bnd0...bnd3 registers display.
+Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
+@footnote{Capital letters are used to distinguish between architecture
+registers and pseudo registers.  A set of pseudo registers for the bound
+registers is created to simplify the display.} 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.
+
+Architectuere 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...}.  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 architecture value can be accessed via bnd0raw...bnd3raw.  Any change
+on bnd0..bnd3 or bnd0raw...bnd3raw is reflect on its counterpart.  When displaying
+bnd0..bnd3 register with Python support also the size of the bounds is displayed.
+
+
 @end table
 
 @node Alpha
@@ -43138,6 +43174,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.7.6.5

[PATCH 1/1] Documentation for MPX.

[Walfred Tedeschi]

Hello Eli and Pedro,

This should complement the MPX registers check-in.

Thanks a lot for your review on the last patch series.
Here I have tried to incorporate feedback from you both.


Bestregards,
-Fred


2013-1X-XX  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 |   46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 0 deletions(-)

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..6041b4a 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -21363,6 +21363,42 @@ be returned in a register.
 @kindex show struct-convention
 Show the current setting of the convention to return @code{struct}s
 from functions.
+
+@subsubsection Intel(R) Memory Protection Extensions (MPX).
+
+@item bnd0raw..bnd3raw and bnd0...bnd3 registers display.
+Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
+@footnote{Capital letters are used to distinguish between architecture
+registers and pseudo registers.  A set of pseudo registers for the bound
+registers is created to simplify the display.} 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.
+
+Architectuere 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...}.  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 architecture value can be accessed via bnd0raw...bnd3raw.  Any change
+on bnd0..bnd3 or bnd0raw...bnd3raw is reflect on its counterpart.  When displaying
+bnd0..bnd3 register with Python support also the size of the bounds is displayed.
+
+
 @end table
 
 @node Alpha
@@ -43138,6 +43174,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.7.6.5

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

[Eli Zaretskii]

> From: y@ecsmtp.iul.intel.com
> Cc: gdb-patches@sourceware.org, Walfred Tedeschi <walfred.tedeschi@intel.com>
> Date: Thu, 21 Nov 2013 15:02:57 +0100
> 
> From: Walfred Tedeschi <walfred.tedeschi@intel.com>
> 
> Hello Eli and Pedro,
> 
> This should complement the MPX registers check-in.
> 
> Thanks a lot for your review on the last patch series.
> Here I have tried to incorporate feedback from you both.

Thanks.  I don't know why, but I received this about a dozen times;
this is one of them, and I hope they are all identical.

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

OK.

> +@subsubsection Intel(R) Memory Protection Extensions (MPX).
> +
> +@item bnd0raw..bnd3raw and bnd0...bnd3 registers display.

Please use @dots{} instead of 3 literal period characters.

> +Memory Protection Extension (MPX) adds the bound registers @samp{BND0}

"Memory Protection Extension" should be in @dfn -- you are introducing
new terminology.  Also, please put here a @cindex entry for this term.

> +@footnote{Capital letters are used to distinguish between architecture
> +registers and pseudo registers.  A set of pseudo registers for the bound
> +registers is created to simplify the display.}

This footnote confused me.  Please explain what you wanted to say, and
I will suggest a better wording.

> +Architectuere registers @samp{BND0} through @samp{BND3} are
   ^^^^^^^^^^^^^
A typo.

> +@smallexample
> +	bnd0raw = {0x32, 0xffffffff8e}
> +	bnd0 = {lbound = 0x32, ubound = 0x71} : size 64
> +@end smallexample

This will cause makeinfo to barf.  You need to escape each { and }
with a @.

> +This way the architecture value can be accessed via bnd0raw...bnd3raw.  Any change

I wonder if it wouldn't be better to use "raw value" instead of
"architecture value".

> +on bnd0..bnd3 or bnd0raw...bnd3raw is reflect on its counterpart.
                                         ^^^^^^^^^^
"reflected in".  Also, please use @dots{} here as well.

>                                                         When displaying
> +bnd0..bnd3 register with Python support also the size of the bounds is displayed.

I'd reword

  When the bnd0..bnd3 registers are displayed via Python, the display
  includes the size of the bounds.

Btw, what is "the size of the bounds"?

[PATCH 1/1] Documentation for MPX.

[y]

From: Walfred Tedeschi <walfred.tedeschi@intel.com>

Hello Eli and Pedro,

This should complement the MPX registers check-in.

Thanks a lot for your review on the last patch series.
Here I have tried to incorporate feedback from you both.


Bestregards,
-Fred


2013-1X-XX  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 |   46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 0 deletions(-)

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..6041b4a 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -21363,6 +21363,42 @@ be returned in a register.
 @kindex show struct-convention
 Show the current setting of the convention to return @code{struct}s
 from functions.
+
+@subsubsection Intel(R) Memory Protection Extensions (MPX).
+
+@item bnd0raw..bnd3raw and bnd0...bnd3 registers display.
+Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
+@footnote{Capital letters are used to distinguish between architecture
+registers and pseudo registers.  A set of pseudo registers for the bound
+registers is created to simplify the display.} 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.
+
+Architectuere 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...}.  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 architecture value can be accessed via bnd0raw...bnd3raw.  Any change
+on bnd0..bnd3 or bnd0raw...bnd3raw is reflect on its counterpart.  When displaying
+bnd0..bnd3 register with Python support also the size of the bounds is displayed.
+
+
 @end table
 
 @node Alpha
@@ -43138,6 +43174,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.7.6.5

[PATCH 1/1] Documentation for MPX.

[y]

From: Walfred Tedeschi <walfred.tedeschi@intel.com>

Hello Eli and Pedro,

This should complement the MPX registers check-in in terms of documentation.
Here I have tried to incorporate feedback from you both.


Thanks a lot for your review on the former patch series.

Best regards,
-Fred


2013-1X-XX  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 |   46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 0 deletions(-)

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..6041b4a 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -21363,6 +21363,42 @@ be returned in a register.
 @kindex show struct-convention
 Show the current setting of the convention to return @code{struct}s
 from functions.
+
+@subsubsection Intel(R) Memory Protection Extensions (MPX).
+
+@item bnd0raw..bnd3raw and bnd0...bnd3 registers display.
+Memory Protection Extension (MPX) adds the bound registers @samp{BND0}
+@footnote{Capital letters are used to distinguish between architecture
+registers and pseudo registers.  A set of pseudo registers for the bound
+registers is created to simplify the display.} 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.
+
+Architectuere 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...}.  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 architecture value can be accessed via bnd0raw...bnd3raw.  Any change
+on bnd0..bnd3 or bnd0raw...bnd3raw is reflect on its counterpart.  When displaying
+bnd0..bnd3 register with Python support also the size of the bounds is displayed.
+
+
 @end table
 
 @node Alpha
@@ -43138,6 +43174,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.7.6.5