1 files changed, 78 insertions, 0 deletions
diff --git a/Tools/WAD/HACK b/Tools/WAD/HACK
new file mode 100644
index 0000000..2e6d17a
--- /dev/null
+++ b/Tools/WAD/HACK
@@ -0,0 +1,78 @@
+The WAD Developers Guide
+
+David Beazley (beazley@cs.uchicago.edu)
+
+$Id: HACK 10001 2007-10-17 21:33:57Z wsfulton $
+
+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.
+
+
+
+
+
+
+
+
+
+
+