[patch, doc] tidy Pointer Bounds Checker documentation

[patch, doc] tidy Pointer Bounds Checker documentation

[Sandra Loosemore]

[-- Attachment #1: Type: text/plain, Size: 578 bytes --]

Ilya, thanks for getting the -fcheck-pointer-bounds and related 
documentation checked in a while back.  I've committed this further 
patch to clean it up a little bit -- some grammar and markup 
corrections, plus I added some more index entries and cross-references. 
  As I've discussed previously in another thread, as a longer-term 
project I'd really like to reorganize the whole manual so we can treat 
program annotation features in their own sections instead of mixing them 
up with debug options (etc), but this will have to do for the upcoming 
5.0 release.

-Sandra


[-- Attachment #2: doc.log --]
[-- Type: text/x-log, Size: 800 bytes --]

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.

[-- Attachment #3: doc.patch --]
[-- Type: text/x-patch, Size: 19555 bytes --]

Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi	(revision 221548)
+++ gcc/doc/invoke.texi	(working copy)
@@ -5843,31 +5843,42 @@ is usable even in freestanding environme
 @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-b
 @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
 @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 
 @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 librar
 
 @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}
Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi	(revision 221548)
+++ gcc/doc/extend.texi	(working copy)
@@ -3688,15 +3688,16 @@ in the function when compiling with the 
 
 @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 attribu
 @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 pa
 
 @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 pa
 @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, i
 
 @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, c
 
 @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"
 
 @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