From 7651042ec6493ee65d79baf0dd46ee8a606753f9 Mon Sep 17 00:00:00 2001 From: Sandra Loosemore Date: Sat, 21 Mar 2015 14:40:55 -0400 Subject: [PATCH] invoke.texi (-fcheck-pointer-bounds): Copy-edit, add additional index entries and cross-references. 2015-03-21 Sandra Loosemore 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 --- gcc/ChangeLog | 20 +++++++++ gcc/doc/extend.texi | 104 ++++++++++++++++++++++++-------------------- gcc/doc/invoke.texi | 77 ++++++++++++++++++-------------- 3 files changed, 122 insertions(+), 79 deletions(-) diff --git a/gcc/ChangeLog b/gcc/ChangeLog index c9737faebc7..a7ceffe9ada 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -1,3 +1,23 @@ +2015-03-21 Sandra Loosemore + + * 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 PR tree-optimization/65458 diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index c6fdb2453c8..4d79506a2e6 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 133cca9042e..59e833a043b 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} -- 2.30.2