invoke.texi (-fcheck-pointer-bounds): Copy-edit, add additional index entries and cross-references.

2015-03-21  Sandra Loosemore  <sandra@codesourcery.com>

	gcc/
	* doc/invoke.texi (-fcheck-pointer-bounds): Copy-edit, add
	additional index entries and cross-references.
	(-fchkp-check-incomplete-type): Likewise.
	(-fchkp-first-field-has-own-bounds): Likewise.
	(-fchkp-narrow-to-innermost-array): Likewise.
	(-fchkp-use-fast-string-functions): Likewise.
	(-fchkp-use-nochk-string-functions): Likewise.
	(-fchkp-use-static-const-bounds): Likewise.
	(-fchkp-treat-zero-dynamic-size-as-infinite): Likewise.
	(-fchkp-instrument-marked-only): Likewise.
	(-fchkp-use-wrappers): Likewise.
	(-static-libmpx): Likewise.
	(-static-libmpxwrappers): Likewise.
	* doc/extend.texi (bnd_legacy): Likewise.
	(bnd_instrument): Likewise.
	(bnd_variable_size): Likewise.
	(Pointer Bounds Checker builtins): Likewise.

From-SVN: r221558

3 files changed, 122 insertions, 79 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index c9737fa..a7ceffe 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,23 @@
+2015-03-21  Sandra Loosemore  <sandra@codesourcery.com>
+
+	* doc/invoke.texi (-fcheck-pointer-bounds): Copy-edit, add
+	additional index entries and cross-references.
+	(-fchkp-check-incomplete-type): Likewise.
+	(-fchkp-first-field-has-own-bounds): Likewise.
+	(-fchkp-narrow-to-innermost-array): Likewise.
+	(-fchkp-use-fast-string-functions): Likewise.
+	(-fchkp-use-nochk-string-functions): Likewise.
+	(-fchkp-use-static-const-bounds): Likewise.
+	(-fchkp-treat-zero-dynamic-size-as-infinite): Likewise.
+	(-fchkp-instrument-marked-only): Likewise.
+	(-fchkp-use-wrappers): Likewise.
+	(-static-libmpx): Likewise.
+	(-static-libmpxwrappers): Likewise.
+	* doc/extend.texi (bnd_legacy): Likewise.
+	(bnd_instrument): Likewise.
+	(bnd_variable_size): Likewise.
+	(Pointer Bounds Checker builtins): Likewise.
+
 2015-03-21  Tom de Vries  <tom@codesourcery.com>
 
 	PR tree-optimization/65458
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index c6fdb24..4d79506 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -3688,15 +3688,16 @@ in the function when compiling with the @option{-fsanitize=undefined} option.
 
 @item bnd_legacy
 @cindex @code{bnd_legacy} function attribute
-The @code{bnd_legacy} attribute on functions is used to inform
-compiler that function should not be instrumented when compiled
-with @option{-fcheck-pointer-bounds} option.
+@cindex Pointer Bounds Checker attributes
+The @code{bnd_legacy} attribute on functions is used to inform the
+compiler that the function should not be instrumented when compiled
+with the @option{-fcheck-pointer-bounds} option.
 
 @item bnd_instrument
 @cindex @code{bnd_instrument} function attribute
-The @code{bnd_instrument} attribute on functions is used to inform
-compiler that function should be instrumented when compiled
-with @option{-fchkp-instrument-marked-only} option.
+The @code{bnd_instrument} attribute on functions is used to inform the
+compiler that the function should be instrumented when compiled
+with the @option{-fchkp-instrument-marked-only} option.
 
 @item regparm (@var{number})
 @cindex @code{regparm} attribute
@@ -5943,10 +5944,12 @@ GCC emits warnings based on this attribute by default; use
 @option{-Wno-designated-init} to suppress them.
 
 @item bnd_variable_size
+@cindex @code{bnd_variable_size} attribute
+@cindex Pointer Bounds Checker attributes
 When applied to a structure field, this attribute tells Pointer
 Bounds Checker that the size of this field should not be computed
-using static type information.  It may be used to mark variable
-sized static array fields placed at the end of a structure.
+using static type information.  It may be used to mark variably-sized
+static array fields placed at the end of a structure.
 
 @smallexample
 struct S
@@ -5958,8 +5961,9 @@ S *p = (S *)malloc (sizeof(S) + 100);
 p->data[10] = 0; //Bounds violation
 @end smallexample
 
-By using an attribute for a field we may avoid bound violation
-we most probably do not want to see:
+@noindent
+By using an attribute for the field we may avoid unwanted bound
+violation checks:
 
 @smallexample
 struct S
@@ -8731,6 +8735,7 @@ is called and the @var{flag} argument passed to it.
 
 @node Pointer Bounds Checker builtins
 @section Pointer Bounds Checker Built-in Functions
+@cindex Pointer Bounds Checker builtins
 @findex __builtin___bnd_set_ptr_bounds
 @findex __builtin___bnd_narrow_ptr_bounds
 @findex __builtin___bnd_copy_ptr_bounds
@@ -8744,15 +8749,16 @@ is called and the @var{flag} argument passed to it.
 @findex __builtin___bnd_get_ptr_ubound
 
 GCC provides a set of built-in functions to control Pointer Bounds Checker
-instrumentation.  Note that all Pointer Bounds Checker builtins are allowed
-to use even if you compile with Pointer Bounds Checker off.  The builtins
-behavior may differ in such case as documented below.
+instrumentation.  Note that all Pointer Bounds Checker builtins can be used
+even if you compile with Pointer Bounds Checker off
+(@option{-fno-check-pointer-bounds}).
+The behavior may differ in such case as documented below.
 
-@deftypefn {Built-in Function} void * __builtin___bnd_set_ptr_bounds (const void * @var{q}, size_t @var{size})
+@deftypefn {Built-in Function} {void *} __builtin___bnd_set_ptr_bounds (const void *@var{q}, size_t @var{size})
 
 This built-in function returns a new pointer with the value of @var{q}, and
 associate it with the bounds [@var{q}, @var{q}+@var{size}-1].  With Pointer
-Bounds Checker off built-in function just returns the first argument.
+Bounds Checker off, the built-in function just returns the first argument.
 
 @smallexample
 extern void *__wrap_malloc (size_t n)
@@ -8765,72 +8771,75 @@ extern void *__wrap_malloc (size_t n)
 
 @end deftypefn
 
-@deftypefn {Built-in Function} void * __builtin___bnd_narrow_ptr_bounds (const void * @var{p}, const void * @var{q}, size_t  @var{size})
+@deftypefn {Built-in Function} {void *} __builtin___bnd_narrow_ptr_bounds (const void *@var{p}, const void *@var{q}, size_t  @var{size})
 
 This built-in function returns a new pointer with the value of @var{p}
-and associate it with the narrowed bounds formed by the intersection
-of bounds associated with @var{q} and the [@var{p}, @var{p} + @var{size} - 1].
-With Pointer Bounds Checker off built-in function just returns the first
+and associates it with the narrowed bounds formed by the intersection
+of bounds associated with @var{q} and the bounds
+[@var{p}, @var{p} + @var{size} - 1].
+With Pointer Bounds Checker off, the built-in function just returns the first
 argument.
 
 @smallexample
 void init_objects (object *objs, size_t size)
 @{
   size_t i;
-  /* Initialize objects one-by-one passing pointers with bounds of an object,
-     not the full array of objects.  */
+  /* Initialize objects one-by-one passing pointers with bounds of 
+     an object, not the full array of objects.  */
   for (i = 0; i < size; i++)
-    init_object (__builtin___bnd_narrow_ptr_bounds (objs + i, objs, sizeof(object)));
+    init_object (__builtin___bnd_narrow_ptr_bounds (objs + i, objs,
+                                                    sizeof(object)));
 @}
 @end smallexample
 
 @end deftypefn
 
-@deftypefn {Built-in Function} void * __builtin___bnd_copy_ptr_bounds (const void * @var{q}, const void * @var{r})
+@deftypefn {Built-in Function} {void *} __builtin___bnd_copy_ptr_bounds (const void *@var{q}, const void *@var{r})
 
 This built-in function returns a new pointer with the value of @var{q},
-and associate it with the bounds already associated with pointer @var{r}.
-With Pointer Bounds Checker off built-in function just returns the first
+and associates it with the bounds already associated with pointer @var{r}.
+With Pointer Bounds Checker off, the built-in function just returns the first
 argument.
 
 @smallexample
 /* Here is a way to get pointer to object's field but
    still with the full object's bounds.  */
-int *field_ptr = __builtin___bnd_copy_ptr_bounds (&objptr->int_filed, objptr);
+int *field_ptr = __builtin___bnd_copy_ptr_bounds (&objptr->int_field, 
+                                                  objptr);
 @end smallexample
 
 @end deftypefn
 
-@deftypefn {Built-in Function} void * __builtin___bnd_init_ptr_bounds (const void * @var{q})
+@deftypefn {Built-in Function} {void *} __builtin___bnd_init_ptr_bounds (const void *@var{q})
 
 This built-in function returns a new pointer with the value of @var{q}, and
-associate it with INIT (allowing full memory access) bounds. With Pointer
-Bounds Checker off built-in function just returns the first argument.
+associates it with INIT (allowing full memory access) bounds. With Pointer
+Bounds Checker off, the built-in function just returns the first argument.
 
 @end deftypefn
 
-@deftypefn {Built-in Function} void * __builtin___bnd_null_ptr_bounds (const void * @var{q})
+@deftypefn {Built-in Function} {void *} __builtin___bnd_null_ptr_bounds (const void *@var{q})
 
 This built-in function returns a new pointer with the value of @var{q}, and
-associate it with NULL (allowing no memory access) bounds. With Pointer
-Bounds Checker off built-in function just returns the first argument.
+associates it with NULL (allowing no memory access) bounds. With Pointer
+Bounds Checker off, the built-in function just returns the first argument.
 
 @end deftypefn
 
-@deftypefn {Built-in Function} void __builtin___bnd_store_ptr_bounds (const void ** @var{ptr_addr}, const void * @var{ptr_val})
+@deftypefn {Built-in Function} void __builtin___bnd_store_ptr_bounds (const void **@var{ptr_addr}, const void *@var{ptr_val})
 
 This built-in function stores the bounds associated with pointer @var{ptr_val}
 and location @var{ptr_addr} into Bounds Table.  This can be useful to propagate
 bounds from legacy code without touching the associated pointer's memory when
-pointers were copied as integers.  With Pointer Bounds Checker off built-in
+pointers are copied as integers.  With Pointer Bounds Checker off, the built-in
 function call is ignored.
 
 @end deftypefn
 
-@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_lbounds (const void * @var{q})
+@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_lbounds (const void *@var{q})
 
 This built-in function checks if the pointer @var{q} is within the lower
-bound of its associated bounds.  With Pointer Bounds Checker off built-in
+bound of its associated bounds.  With Pointer Bounds Checker off, the built-in
 function call is ignored.
 
 @smallexample
@@ -8848,19 +8857,19 @@ extern void *__wrap_memset (void *dst, int c, size_t len)
 
 @end deftypefn
 
-@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_ubounds (const void * @var{q})
+@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_ubounds (const void *@var{q})
 
 This built-in function checks if the pointer @var{q} is within the upper
-bound of its associated bounds.  With Pointer Bounds Checker off built-in
+bound of its associated bounds.  With Pointer Bounds Checker off, the built-in
 function call is ignored.
 
 @end deftypefn
 
-@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_bounds (const void * @var{q}, size_t @var{size})
+@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_bounds (const void *@var{q}, size_t @var{size})
 
 This built-in function checks if [@var{q}, @var{q} + @var{size} - 1] is within
 the lower and upper bounds associated with @var{q}.  With Pointer Bounds Checker
-off built-in function call is ignored.
+off, the built-in function call is ignored.
 
 @smallexample
 extern void *__wrap_memcpy (void *dst, const void *src, size_t n)
@@ -8877,11 +8886,12 @@ extern void *__wrap_memcpy (void *dst, const void *src, size_t n)
 
 @end deftypefn
 
-@deftypefn {Built-in Function} const void * __builtin___bnd_get_ptr_lbound (const void * @var{q})
+@deftypefn {Built-in Function} {const void *} __builtin___bnd_get_ptr_lbound (const void *@var{q})
 
-This built-in function returns the lower bound (which is a pointer) associated
-with the pointer @var{q}.  This is at least useful for debugging using printf.
-With Pointer Bounds Checker off built-in function returns 0.
+This built-in function returns the lower bound associated
+with the pointer @var{q}, as a pointer value.  
+This is useful for debugging using @code{printf}.
+With Pointer Bounds Checker off, the built-in function returns 0.
 
 @smallexample
 void *lb = __builtin___bnd_get_ptr_lbound (q);
@@ -8891,11 +8901,11 @@ printf ("q = %p  lb(q) = %p  ub(q) = %p", q, lb, ub);
 
 @end deftypefn
 
-@deftypefn {Built-in Function} const void * __builtin___bnd_get_ptr_ubound (const void * @var{q})
+@deftypefn {Built-in Function} {const void *} __builtin___bnd_get_ptr_ubound (const void *@var{q})
 
 This built-in function returns the upper bound (which is a pointer) associated
-with the pointer @var{q}.  With Pointer Bounds Checker off built-in function
-returns -1.
+with the pointer @var{q}.  With Pointer Bounds Checker off,
+the built-in function returns -1.
 
 @end deftypefn
 
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 133cca9..59e833a 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -5843,31 +5843,42 @@ is usable even in freestanding environments.
 @item -fcheck-pointer-bounds
 @opindex fcheck-pointer-bounds
 @opindex fno-check-pointer-bounds
+@cindex Pointer Bounds Checker options
 Enable Pointer Bounds Checker instrumentation.  Each memory reference
-is instrumented with checks of pointer used for memory access against
-bounds associated with that pointer.  Generated instrumentation may
-be controlled by various @option{-fchkp-*} options.  Currently there
-is only Intel MPX based implementation available, thus i386 target
-and @option{-mmpx} are required.  MPX based instrumentation requires
-a runtime library to enable MPX in a hardware and handle bounds
+is instrumented with checks of the pointer used for memory access against
+bounds associated with that pointer.  
+
+Currently there
+is only an implementation for Intel MPX available, thus x86 target
+and @option{-mmpx} are required to enable this feature.  
+MPX-based instrumentation requires
+a runtime library to enable MPX in hardware and handle bounds
 violation signals.  By default when @option{-fcheck-pointer-bounds}
 and @option{-mmpx} options are used to link a program, the GCC driver
-links against @option{libmpx} runtime library.  MPX based instrumentation
-may be used for a debugging and also it may be included into a release
-version to increase program security.  Depending on usage you may
-put different requirements to runtime library.  Current version
- of MPX runtime library is more oriented to be used as a debugging
+links against the @file{libmpx} runtime library.  MPX-based instrumentation
+may be used for debugging and also may be included in production code
+to increase program security.  Depending on usage, you may
+have different requirements for the runtime library.  The current version
+of the MPX runtime library is more oriented for use as a debugging
 tool.  MPX runtime library usage implies @option{-lpthread}.  See
 also @option{-static-libmpx}.  The runtime library  behavior can be
 influenced using various @env{CHKP_RT_*} environment variables.  See
 @uref{https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler}
 for more details.
 
+Generated instrumentation may be controlled by various
+@option{-fchkp-*} options and by the @code{bnd_variable_size}
+structure field attribute (@pxref{Type Attributes}) and
+@code{bnd_legacy}, and @code{bnd_instrument} function attributes
+(@pxref{Function Attributes}).  GCC also provides a number of built-in
+functions for controlling the Pointer Bounds Checker.  @xref{Pointer
+Bounds Checker builtins}, for more information.
+
 @item -fchkp-check-incomplete-type
 @opindex fchkp-check-incomplete-type
 @opindex fno-chkp-check-incomplete-type
 Generate pointer bounds checks for variables with incomplete type.
-Enabled by default
+Enabled by default.  
 
 @item -fchkp-narrow-bounds
 @opindex fchkp-narrow-bounds
@@ -5880,15 +5891,15 @@ and @option{-fchkp-first-field-has-own-bounds}.  Enabled by default.
 @item -fchkp-first-field-has-own-bounds
 @opindex fchkp-first-field-has-own-bounds
 @opindex fno-chkp-first-field-has-own-bounds
-Forces Pointer Bounds Checker to use narrowed bounds for address of the
-first field in the structure.  By default pointer to the first field has
-the same bounds as pointer to the whole structure.
+Forces Pointer Bounds Checker to use narrowed bounds for the address of the
+first field in the structure.  By default a pointer to the first field has
+the same bounds as a pointer to the whole structure.
 
 @item -fchkp-narrow-to-innermost-array
 @opindex fchkp-narrow-to-innermost-array
 @opindex fno-chkp-narrow-to-innermost-array
 Forces Pointer Bounds Checker to use bounds of the innermost arrays in
-case of nested static arryas access.  By default it is disabled and
+case of nested static array access.  By default this option is disabled and
 bounds of the outermost array are used.
 
 @item -fchkp-optimize
@@ -5900,13 +5911,13 @@ optimization levels @option{-O}, @option{-O2}, @option{-O3}.
 @item -fchkp-use-fast-string-functions
 @opindex fchkp-use-fast-string-functions
 @opindex fno-chkp-use-fast-string-functions
-Allow to use @code{*_nobnd} versions of string functions (not copying bounds)
+Enables use of @code{*_nobnd} versions of string functions (not copying bounds)
 by Pointer Bounds Checker.  Disabled by default.
 
 @item -fchkp-use-nochk-string-functions
 @opindex fchkp-use-nochk-string-functions
 @opindex fno-chkp-use-nochk-string-functions
-Allow to use @code{*_nochk} versions of string functions (not checking bounds)
+Enables use of @code{*_nochk} versions of string functions (not checking bounds)
 by Pointer Bounds Checker.  Disabled by default.
 
 @item -fchkp-use-static-bounds
@@ -5918,16 +5929,17 @@ bounds of static variables.  Enabled by default.
 @item -fchkp-use-static-const-bounds
 @opindex fchkp-use-static-const-bounds
 @opindex fno-chkp-use-static-const-bounds
-Use statically initialized bounds for constant bounds instead of
-generating them each time it is required.  By default enabled when
+Use statically-initialized bounds for constant bounds instead of
+generating them each time they are required.  By default enabled when
 @option{-fchkp-use-static-bounds} is enabled.
 
 @item -fchkp-treat-zero-dynamic-size-as-infinite
 @opindex fchkp-treat-zero-dynamic-size-as-infinite
 @opindex fno-chkp-treat-zero-dynamic-size-as-infinite
-With this option zero size obtained dynamically for objects with
-incomplete type will be treated as infinite by Pointer Bounds
-Checker.  It may be helpful if program is linked with a library
+With this option, objects with incomplete type whose
+dynamically-obtained size is zero are treated as having infinite size
+instead by Pointer Bounds
+Checker.  This option may be helpful if a program is linked with a library
 missing size information for some symbols.  Disabled by default.
 
 @item -fchkp-check-read
@@ -5958,15 +5970,16 @@ Enabled by default.
 @opindex fchkp-instrument-marked-only
 @opindex fno-chkp-instrument-marked-only
 Instructs Pointer Bounds Checker to instrument only functions
-marked with @code{bnd_instrument} attribute.  Disabled by default.
+marked with the @code{bnd_instrument} attribute
+(@pxref{Function Attributes}).  Disabled by default.
 
 @item -fchkp-use-wrappers
 @opindex fchkp-use-wrappers
 @opindex fno-chkp-use-wrappers
-Allows Pointer Bounds Checker to replace calls to built-in function
-with calls to wrapper functions.  When the @option{-fchkp-use-wrappers}
+Allows Pointer Bounds Checker to replace calls to built-in functions
+with calls to wrapper functions.  When @option{-fchkp-use-wrappers}
 is used to link a program, the GCC driver automatically links
-agains @option{libmpxwrappers}.  See also @option{-static-libmpxwrappers}.
+against @file{libmpxwrappers}.  See also @option{-static-libmpxwrappers}.
 Enabled by default.
 
 @item -fdump-final-insns@r{[}=@var{file}@r{]}
@@ -11278,9 +11291,9 @@ other libraries statically.
 
 @item -static-libmpx
 @opindex static-libmpx
-When @option{-fcheck-pointer bounds} and @option{-mmpx} options are
+When the @option{-fcheck-pointer bounds} and @option{-mmpx} options are
 used to link a program, the GCC driver automatically links against
-@option{libmpx}.  If @file{libmpx} is available as a shared library,
+@file{libmpx}.  If @file{libmpx} is available as a shared library,
 and the @option{-static} option is not used, then this links against
 the shared version of @file{libmpx}.  The @option{-static-libmpx}
 option directs the GCC driver to link @file{libmpx} statically,
@@ -11288,9 +11301,9 @@ without necessarily linking other libraries statically.
 
 @item -static-libmpxwrappers
 @opindex static-libmpxwrappers
-When @option{-fcheck-pointer bounds}, @option{-mmpx} options are used and
-@option{-fno-chkp-use-wrappers} option is not used to link a program, the
-GCC driver automatically links against @option{libmpxwrappers}.  If
+When the @option{-fcheck-pointer bounds} and @option{-mmpx} options are used
+to link a program without also using @option{-fno-chkp-use-wrappers}, the
+GCC driver automatically links against @file{libmpxwrappers}.  If
 @file{libmpxwrappers} is available as a shared library, and the
 @option{-static} option is not used, then this links against the shared
 version of @file{libmpxwrappers}.  The @option{-static-libmpxwrappers}