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
This commit is contained in:
Sandra Loosemore 2015-03-21 14:40:55 -04:00 committed by Sandra Loosemore
parent 844d9a76bc
commit 7651042ec6
3 changed files with 122 additions and 79 deletions

View File

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

View File

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

View File

@ -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}