Fix host hooks documentation

[Ian Lance Taylor <ian at wasabisystems dot com>]

This patch adds some brief comments to the fields in struct
host_hooks.

It also corrects the documentation of the host hooks in
hostconfig.tex.  The existing documentation refers to a non-existent
host hook HOST_HOOKS_PCH_LOAD_PCH.  I corrected this, and rewrote the
documentation to avoid passive voice and to be generally clearer (at
least, clearer to me).

OK for mainline?

Ian


2004-03-06  Ian Lance Taylor  <ian@wasabisystems.com>

	* hosthooks.h (struct host_hooks): Add comments for fields.
	* doc/hostconfig.texi (Host Common): Correct documentation.


Index: hosthooks.h
===================================================================
RCS file: /cvs/gcc/gcc/gcc/hosthooks.h,v
retrieving revision 1.4
diff -c -r1.4 hosthooks.h
*** hosthooks.h	29 Jul 2003 23:36:46 -0000	1.4
--- hosthooks.h	6 Mar 2004 15:22:15 -0000
***************
*** 23,31 ****
--- 23,37 ----
  
  struct host_hooks
  {
+   /* Set up host-specific signal handling.  */
    void (*extra_signals) (void);
  
+   /* When creating a PCH, return the address of the space into which
+      the PCH will be loaded, or NULL to use the default algorithm.  */
    void * (*gt_pch_get_address) (size_t);
+   /* When loading a PCH, if the address is the one which would have
+      been returned by GT_PCH_GET_ADDRESS, and there is enough room for
+      the size, return true.  Otherwise, return false.  */
    bool (*gt_pch_use_address) (void *, size_t);
  
    /* Whenever you add entries here, make sure you adjust hosthooks-def.h.  */
Index: doc/hostconfig.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/hostconfig.texi,v
retrieving revision 1.7
diff -c -r1.7 hostconfig.texi
*** doc/hostconfig.texi	29 Jul 2003 23:36:47 -0000	1.7
--- doc/hostconfig.texi	6 Mar 2004 15:22:15 -0000
***************
*** 38,78 ****
  variable in @file{config.gcc}.
  
  @deftypefn {Host Hook} void HOST_HOOKS_EXTRA_SIGNALS (void)
! This host hook is used to set up handling for extra signals.  The most
  common thing to do in this hook is to detect stack overflow.
  @end deftypefn
  
  @deftypefn {Host Hook} void * HOST_HOOKS_GT_PCH_GET_ADDRESS (size_t @var{size})
! This host hook returns the address of some space in which a PCH may be
! loaded with @samp{HOST_HOOKS_PCH_LOAD_PCH}.  The space will need to
! have @var{size} bytes.  If insufficient space is available,
! @samp{NULL} may be returned; the PCH machinery will try to find a
! suitable address using a heuristic.
! 
! The memory does not have to be available now.  In fact, usually
! @samp{HOST_HOOKS_PCH_LOAD_PCH} will already have been called.  The memory
! need only be available in future invocations of GCC.
! @end deftypefn
  
! @deftypefn {Host Hook} bool HOST_HOOKS_GT_PCH_USE_ADDRESS (size_t @var{size}, void * @var{address})
! This host hook is called when a PCH file is about to be loaded.  If
! @var{address} is the address that would have been returned by
! @samp{HOST_HOOKS_PCH_MEMORY_ADDRESS}, and @var{size} is smaller than
! the maximum than @samp{HOST_HOOKS_PCH_MEMORY_ADDRESS} would have
! accepted, return true, otherwise return false.
! 
! In addition, free any address space reserved that isn't needed to hold
! @var{size} bytes (whether or not true is returned).  The PCH machinery will
! use @samp{mmap} with @samp{MAP_FIXED} to load the PCH if @samp{HAVE_MMAP_FILE},
! or will use @samp{fread} otherwise.
  
! If no PCH will be loaded, this hook may be called with @var{size}
! zero, in which case all reserved address space should be freed.
  
  Do not try to handle values of @var{address} that could not have been
! returned by this executable; just return false.  Such values usually
! indicate an out-of-date PCH file (built by some other GCC executable),
! and such a PCH file won't work.
  @end deftypefn
  
  @node Filesystem
--- 38,92 ----
  variable in @file{config.gcc}.
  
  @deftypefn {Host Hook} void HOST_HOOKS_EXTRA_SIGNALS (void)
! This host hook sets up any host-specific signal handling.  The most
  common thing to do in this hook is to detect stack overflow.
  @end deftypefn
  
  @deftypefn {Host Hook} void * HOST_HOOKS_GT_PCH_GET_ADDRESS (size_t @var{size})
! This host hook returns the address in memory where a PCH (a
! PreCompiled Header) should be loaded.  The compiler calls this hook
! when creating a PCH.  When a future compiler invocation wants to load
! the PCH, it must be able to load it at this memory address.  The space
! must have @var{size} bytes.  If there is no enough space available,
! the hook should return @code{NULL}.
! 
! If this hook returns @code{NULL}, the compiler will use a heuristic
! which works on most hosts.  The default version of this hook simply
! returns @code{NULL}.
  
! The memory need not be available when the hook is called.  It need
! only be available in future invocations of GCC when they load the PCH.
! @end deftypefn
  
! @deftypefn {Host Hook} bool HOST_HOOKS_GT_PCH_USE_ADDRESS (void *@var{address}, size_t @var{size})
! The compiler calls this host hook when it is about to load a PCH.
! This hook should return @code{true} if @var{address} is an address
! which could have been returned by the host hook
! @samp{HOST_HOOKS_GT_PCH_GET_ADDRESS} with an argument of @var{size}.
! Otherwise, this hook should return @code{false}.
! 
! If this hook returns @code{false}, the compiler will use a heuristic
! which works on most hosts.  The default version of this hook simply
! returns @code{false}.
! 
! This hook should also free any reserved address space which is not
! required, given that the PCH has a maximum of @var{size} bytes.  The
! hook should do this regardless of whether it returns @code{true} or
! @code{false}.
! 
! The memory must be available after this hook returns @code{true}.  The
! compiler will then use @code{mmap} with @code{MAP_FIXED} to load the
! PCH, or, if @code{mmap} is not available on the host, the compiler
! will simply read the data using @code{fread}.
! 
! If the compiler is not going to load a PCH during this compilation, it
! may call this hook with a @var{size} parameter of zero, in which case
! the hook should free any reserved address space.
  
  Do not try to handle values of @var{address} that could not have been
! returned by this executable; just return @code{false}.  Such values
! usually indicate an out-of-date PCH file (built by some other GCC
! executable), and such a PCH file won't work.
  @end deftypefn
  
  @node Filesystem