trunk/Tools/WAD/HACK

The WAD Developers Guide

David Beazley (beazley@cs.uchicago.edu)

$Id$

1.  Introduction

This short document is intended for anyone who feels inclined to work
on WAD and make improvements.   It is by no means complete.  However,
it contains random commentary on the current implementation.

2.  A brief word on the execution environment

Because WAD is embedded in the same application it is intended to
debug, it must take an extremely conservative approach to its own
execution environment.  Specifically, it can not rely upon the correct
operation of C library--especially with respect to memory management
and other basic operations.  Because of this, the implementation of
WAD makes every effort to be as self-contained as possible--thus
minimizing its exposure to corrupted libraries in the faulting
application.  Closely related to this, WAD does not rely on any
third-party libraries (e.g., libbfd) since it is almost impossible to
fully verify the way in which such libraries might use other programming
libraries.  

With that said, you might keep the following rules in mind:

     rule 1:   Trust nothing--it might be broken.
     rule 2:   When in doubt, see rule 1.

(Of course, we can probably get away with assuming that the OS isn't
hosed).

3.  Memory management

There are two problems here: first, the dynamic memory
allocator may be corrupted or broken (e.g., as might occur when
you double-free memory or free memory not allocated by malloc). 
Second, the WAD signal handler prefers to execute own on its own
signal handling stack.  This stack is of limited size so it is not
a reliable place to put large amounts of data.

Small buffers and scratch areas are managed through the use of static
variables allocated in the WAD data-segment.  

For dynamic memory management, WAD provides its own memory allocator
in the function wad_malloc().  This function allocates memory by using
mmap() to grab anonymous memory regions (mapped to /dev/zero).  This
memory is currently allocated in chunks of 64Kbytes as needed.

To simplify the implementation and prevent potential memory problems
in WAD itself, WAD never releases the memory that it allocates.  There
is no wad_free() operation nor is there any way to release all of the
memory previously allocated.

Although memory is never released, WAD tries to intern commonly used
strings. An internal string hash is built as WAD runs and in most
cases, each string is mapped to a single instance of the string in
this hash table.  The function wad_string_lookup(char *s) is used to
return a pointer to the string s in the hash table.  If no entry
exists, it is created and a pointer is returned.

4. I/O

It is probably a bad idea to use buffered I/O with WAD.   This may
result in implicit calls to malloc() and related functions.