Index: gty.texi
===================================================================
--- gty.texi	(revision 166469)
+++ gty.texi	(working copy)
@@ -70,6 +70,7 @@
 * GGC Roots::           Making global variables GGC roots.
 * Files::               How the generated files work.
 * Invoking the garbage collector::   How to invoke the garbage collector.
+* Troubleshooting::     When something does not work as expected.
 @end menu
 
 @node GTY Options
@@ -355,10 +356,12 @@
 
 The type machinery expects the types to be of constant size.  When this
 is not true, for example, with structs that have array fields or unions,
-the type machinery cannot tell how many bytes need to be allocated at 
+the type machinery cannot tell how many bytes need to be allocated at
 each allocation.  The @code{variable_size} is used to mark such types.
-The type machinery then provides allocators that take a parameter 
-indicating an exact size of object being allocated.  
+The type machinery then provides allocators that take a parameter
+indicating an exact size of object being allocated.  Note that the size
+must be provided in bytes whereas the @code{length} option works with
+array lengths in number of elements.
 
 For example,
 @smallexample
@@ -374,6 +377,12 @@
   field_vec = ggc_alloc_sorted_fields_type (size);
 @end smallexample
 
+If @var{field_vec->elts} stores @var{n} elements, then @var{size}
+could be calculated as follows:
+@smallexample
+  size_t size = sizeof (struct sorted_fields_type) + n * sizeof (tree);
+@end smallexample
+
 @findex special
 @item special ("@var{name}")
 
@@ -487,12 +496,43 @@
 with many other garbage collectors, it is not implicitly invoked by
 allocation routines when a lot of memory has been consumed. So the
 only way to have GGC reclaim storage it to call the @code{ggc_collect}
-function explicitly. This call is an expensive operation, as it may
-have to scan the entire heap. Beware that local variables (on the GCC
+function explicitly.  This call is an expensive operation, as it may
+have to scan the entire heap.  Beware that local variables (on the GCC
 call stack) are not followed by such an invocation (as many other
 garbage collectors do): you should reference all your data from static
 or external @code{GTY}-ed variables, and it is advised to call
-@code{ggc_collect} with a shallow call stack. The GGC is an exact mark
+@code{ggc_collect} with a shallow call stack.  The GGC is an exact mark
 and sweep garbage collector (so it does not scan the call stack for
-pointers). In practice GCC passes don't often call @code{ggc_collect}
+pointers).  In practice GCC passes don't often call @code{ggc_collect}
 themselves, because it is called by the pass manager between passes.
+
+At the time of the @code{ggc_collect} call all pointers in the GC-marked
+structures must be valid or @code{NULL}.  In practice this means that
+there should not be uninitialized pointer fields in the structures even
+if your code never reads or writes those fields at a particular
+instance.  One way to ensure this is to use cleared versions of
+allocators unless all the fields are initialized manually immediately
+after allocation.
+
+@node Troubleshooting
+@section Troubleshooting the garbage collector
+@cindex garbage collector, troubleshooting
+
+With the current garbage collector implementation, most issues should
+show up as GCC compilation errors.  Some of the most commonly
+encountered issues are described below.
+
+@itemize @bullet
+@item Gengtype does not produce allocators for a @code{GTY}-marked type.
+Gengtype checks if there is at least one possible path from GC roots to
+at least one instance of each type before outputting allocators.  If
+there is no such path, the @code{GTY} markers will be ignored and no
+allocators will be output.  Solve this by making sure that there exists
+at least one such path.  If creating it is unfeasible or raises a ``code
+smell'', consider if you really must use GC for allocating such type.
+
+@item Link-time errors about undefined @code{gt_ggc_r_foo_bar} and
+similarly-named symbols.  Check if your @file{foo_bar} source file has
+@code{#include "gt-foo_bar.h"} as its very last line.
+
+@end itemize