diff --git a/vvp/README.txt b/vvp/README.txt
index 11334e208..13783a08f 100644
--- a/vvp/README.txt
+++ b/vvp/README.txt
@@ -1,7 +1,7 @@
 /*
  * Copyright (c) 2001 Stephen Williams (steve@icarus.com)
  *
- *  $Id: README.txt,v 1.16 2001/04/18 04:21:23 steve Exp $
+ *  $Id: README.txt,v 1.17 2001/04/25 04:35:05 steve Exp $
  */
 
 VVP SIMULATION ENGINE
@@ -99,6 +99,67 @@ Almost all of the structural aspects of a simulation can be
 represented by functors, which perform the very basic task of
 combining up to four inputs down to one output.
 
+
+UDP STATEMENTS:
+
+A UDP statement either defines a User Defined Primitive, or
+instantiates a previously defined UDP by creating a UDP functor.  A
+UDP functor has as many inputs as the UDP definition requires.
+
+UDPs come in sequential and combinatorial flavors.  Sequential UDPs
+carry an output state and can respond to edges at the inputs.  The
+output of a combinatorial UDPs is a function of its current inputs
+only.
+
+The function of a UDP is defined via a table.  The rows of the table
+are strings which describe input states or edges, and the new output
+state.	Combinatorial UDPs require one character for each input, and
+one character at the end for the output state.	Sequential UDPs need
+an additional char for the current state, which is the first char of
+the row.  
+
+Any input transition or the new state must match at most one row (or
+all matches must provide the same output state).  If no row matches,
+the output becomes 1'bx.
+
+The output state can be specified as "0", "1", or "x".	Sequential
+UDPs may also have "-": no change.
+
+An input or current output state can be "1", "0", "x", or "?" (don't
+care).	For Sequential UDPs, at most one input state specification may
+be replaced by an edge specification.  Valid edges are:
+
+	"*": (??)	"_": (?0)	"+": (?1)	"%": (?x)
+	"r": (01)	"R": (x1)	"f": (10)	"F": (x0)
+	"p": (0?)	"n": (1?)	"P": (0x)	"N": (1x)
+
+A combinatorial UDP is defined like this:
+
+	<type> .udp/comb "<name>", <number>, "<row0>", "<row1>", ... ; 
+ 
+<type> is a label that identifies the UDP.  <number> is the number of
+inputs.	 "<name>" is there for public identification.  Sequential UDPs
+need an additional initialization value:
+
+	<type> .udp/sequ "<name>", <number>, <init>, "<row0>", "<row1>", ... ; 
+
+<init> is the initial value for all instances of the UDP.  We do not
+provide initial values for individual instances.  <init> must be a
+number 0, 1, or 2 (for 1'bx).
+
+A UDP functor instance is created so:
+
+	<label> .udp  <type>, <symbol_list> ;
+
+Where <label> identifies the functor, <type> is the label of a UDP
+defined earlier, and <symbol_list> is a list of symbols, one for each
+input of the UDP.
+
+ATTN: The "<name>" attribute of the UDP is pretty useless, and may go
+away in future versions.  It may be useful for diagnostic messages,
+though.
+ 
+
 VARIABLE STATEMENTS:
 
 A variable is a bit vector that can be written by behavioral code (so
diff --git a/vvp/compile.h b/vvp/compile.h
index ce29ac3ac..8cf97d5de 100644
--- a/vvp/compile.h
+++ b/vvp/compile.h
@@ -19,7 +19,7 @@
  *    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
  */
 #if !defined(WINNT)
-#ident "$Id: compile.h,v 1.17 2001/04/24 02:23:59 steve Exp $"
+#ident "$Id: compile.h,v 1.18 2001/04/25 04:35:05 steve Exp $"
 #endif
 
 # include  <stdio.h>
@@ -66,8 +66,13 @@ extern void compile_vpi_symbol(const char*label, vpiHandle obj);
 extern vpiHandle compile_vpi_lookup(const char*label);
 
 /* 
- * The first function creates a UDP, the second function adds table 
-   entries, and the third one instantiates a UDP functor.
+ * The `compile_udp_def' function creates a UDP.  The `table' is a
+ * NULL terminated array of char*, as assembled by `compile_udp_table'.  
+ * `compile_udp_table' is called with `table'==NULL to create a new 
+ * table, or with an existing table to append to.
+ *
+ * `compile_udp_functor' creates a mode-3 functor refering to the 
+ * labeled UDP.  
  */
 
 extern void compile_udp_def(int sequ, char*label, char *name,
@@ -155,6 +160,9 @@ extern void compile_dump(FILE*fd);
 
 /*
  * $Log: compile.h,v $
+ * Revision 1.18  2001/04/25 04:35:05  steve
+ *  Document the UDP implementation.
+ *
  * Revision 1.17  2001/04/24 02:23:59  steve
  *  Support for UDP devices in VVP (Stephen Boettcher)
  *