check-memory-usage documentation

[Andrew Morton]

I've been working with Tristan on getting some documentation in
place for GCC's '-fcheck-memory-usage' option.

I'm putting this up here for review, after which I'll texify it
and raise a patch.  (If you don't like this process, feel free
to shout at me)



=================================================================

** extend.texi section "Declaring Attributes of Functions" is
   missing a description of __attribute__((no_check_memory_usage)). 
   Here it is:

@cindex @code{no_check_memory_usage} function attribute
@item no_check_memory_usage
This attribute instructs GCC to not add memory checking instrumentation
to this function even when the invokation command included
@samp{-fcheck-memory-usage}. This permits the use of @code{asm}
statements without having to compile the function with different
options.  This also allows you to write memory checking support
routines of your own, without getting infinite recursion if
they are compiled with @code{-fcheck-memory-usage}.

@smallexample
void chkr_check_exec (const void *) __attribute__ ((no_check_memory_usage));
void chkr_check_exec (const void *ptr)
{
	/* Check that we can execute at *ptr */
	...
}
@end smallexample




=================================================================

** There's a bit of stuff in extend.texi about
   no_check_memory_usage.  Leave this alone.

=================================================================

** There's some stuff in invoke.texi for -fcheck-memory-usage which
   really shouldn't be there, because it's describing the use of GNU
   Checker.  But let's leave it there for a while.


=================================================================

** New documentation for gcc.texi


Memory access checking
----------------------

GCC's memory checking features allow an application to check its own
memory access operations at runtime.  GCC generates calls to special
library functions which must be available when the instrumented
application is executed.

Accesses to all memory locations are checked.  This includes statically
allocated addresses such as global variables, because these may become
'uninitialized' when partially initialized aggregates are copied to
them.

The 'checker' subsystem must maintain an internal representation of the
state of each byte of memory which is used by the application. 
GCC expects the checker library to implement five functions which
manipulate and check these states. The memory states are:

  Unallocated: the application may not access the byte at all.

  Readonly: the application may read the byte

  Writeonly: the application may only write the byte.  Usually this
  means that the byte is uninitialized, and when written it will
  transition to the Readwrite state.

  Readwrite: the application may read or write the byte.

The memory checking feature of GCC understands these states and their
transitions.  GCC will emit code to call the checker functions to
manipulate these states on behalf of the checked application.

The five 'checker' functions are:

chkr_check_addr(void *ptr, size_t size, unsigned char mode)

  GCC emits calls to chkr_check_addr() immediately prior to
  generating code which will affect the memory between *ptr and
  *(ptr+size-1) inclusive.

  An implementation of chkr_check_addr() may then verify that this is
  correct use of the indicated memory region.  The checker subsystem
  may alter its representation of the state of the affected memory, if
  appropriate.

  mode describes the action which the instrumented application will
  be performing upon the affected memory region.  The values of mode
  are:


  MEMORY_USE_BAD = 0

    Internal to GCC; this value is not passed to chkr_check_addr().

  MEMORY_USE_RO = 1

    Advise the checker subsystem that the instrumented application
    is about to read from [ptr, ptr+size)

  MEMORY_USE_WO = 2

    Advise the checker subsystem that the instrumented application
    is about to write to [ptr, ptr+size)

  MEMORY_USE_RW = 3

    Advise the checker subsystem that the instrumented application
    is about to read then write [ptr, ptr+size).  This is used for
    memory increment and decrement operations such as 

        int *ptr = ...;
        (*ptr)++;

  MEMORY_USE_TW = 6

    Asks the checker subsystem to verify that the instrumented
    application may write to [ptr, ptr+from).  This differs from
    MEMORY_USE_WO in that the checker subsystem will not proceed to
    mark the affected memory as being validly readable - this is purely
    a check.

    This value is used internally by GNU Checker.  It is not used
    by GCC.

  MEMORY_USE_DONT = 99

    This mode is internal to gcc.  Gcc uses it to indicate that
    checker instrumentation should not be created.



chkr_set_right(void *ptr, size_t size, unsigned char mode)

  GCC emits calls to this function to inform the checker subsystem
  that it should alter its internal representation of the state of the
  memory at [ptr, ptr+from).

chkr_copy_bitmap(void *to, void *from, nbytes)

  GCC emits a call to chkr_copy_bitmap() immediately prior to emitting
  code which copies an aggregate from one area of memory to another.

  It is expected that the checker subsystem will copy the memory
  state information information for [to, to+bytes) onto the state
  for [from, from+nbytes).

  This feature allows checker to correctly track the state of
  partially initialized structures even when they are copied via
  structure assignment.

chkr_check_exec(const void *ptr)

  GCC emits a call to chkr_check_exec() immediately prior to emitting
  a call to the function at *ptr.  This allows the checker subsystem to
  verify that ptr is a valid address for execution.

  chkr_check_exec() is typically invoked when a call is about to be
  made via a function pointer.


chkr_check_str(const void *ptr, unsigned char mode)

  GCC emits a call to chkr_check_str() immediately prior to emitting
  a builtin string function.

  At present this is only used for strlen(), so mode is set to
  MEMORY_USE_RO.  The checker subsystem will verify that the
  null-terminated string starting at ptr lies within initialized,
  readable memory.

Suppressing memory checking
---------------------------

GCC's generation of memory checking calls may be suspended for
individual functions by the use of the no_check_memory_usage attribute:

void not_checked(...) __attribute__ ((no_check_memory_usage));

void not_checked(...)
{
	...
}

This may be used to avoid generating infinitely recursive code when
compiling the chkr_*() functions themselves with -fcheck-memory-usage.


GCC does not support the use of 'asm' statements within memory-checked
functions, so the no_check_memory_usage attribute may be used to
suspend memory checking within those functions.