diff --git a/verilog/rtl/README b/verilog/rtl/README
new file mode 100644
index 0000000..ec44791
--- /dev/null
+++ b/verilog/rtl/README
@@ -0,0 +1,183 @@
+A quick documentation of the Caravel memory map and operation
+---------------------------------------------------------------
+
+Caravel pinout:
+---------------
+
+	vdd3v3
+	vdd1v8
+	vss
+	gpio	   1 bit, mainly used for external LDO control of user power supply
+	clock	   Master clock input
+	resetb	   Master reset (sense inverted) input
+	flash_csb  SPI flash controller chip select (sense inverted)
+	flash_clk  SPI flash controller clock
+	flash_io0  SPI flash controller data out
+	flash_io1  SPI flash controller data in
+	mprj_io	   32 bits general purpose programmable digital	or analog I/O
+
+Special-use pins for the management SoC:
+----------------------------------------
+
+    On power-up, the "mprj_io" GPIO are under complete control of the managment
+    SoC.  The first 8 user GPIO are special-purpose pads with dedicated functions
+    for the management SoC:
+
+	mprj_io[0]	JTAG I/O
+	mprj_io[1]	SDO, housekeeping SPI
+	mprj_io[2]	SDI, housekeeping SPI
+	mprj_io[3]	CSB, housekeeping SPI
+	mprj_io[4]	SCK, housekeeping SPI
+	mprj_io[5]	Rx, UART
+	mprj_io[6]	Tx, UART
+	mrpj_io[7]	IRQ
+
+    The next 4 user GPIO are designed to be used with an SPI flash controller in
+    the user space.  They allow the four pins to be overridden by the housekeeping
+    SPI to access the SPI flash in pass-through mode.
+
+	mprj_io[8]	user flash CSB
+	mprj_io[9]	user flash SCK
+	mprj_io[10]	user flash IO0
+	mprj_io[11]	user flash IO1
+
+    The user may additionally use any available GPIO for the SPI flash IO2 and IO3
+    lines;  the pass-through mode only uses the basic 4-pin SPI mode.
+
+    All of the special-use pins are configured through a memory-mapped region.  But
+    to avoid a large number of wires in the user space to reach all of the GPIO
+    pad controls, each user GPIO pad has a corresponding local control block.  The
+    control block holds the configuration data for the corresponding pad.  This
+    configuration data is a mirror of the data in the memory-mapped region, and is
+    loaded by a "transfer" bit in another memory-mapped register.  In addition to
+    all of the static control bits for the GPIO, each block contains a single bit
+    that specifies whether that pad is under the control of the user or the management
+    area.  All pins are configured from the management area.  However, the configuration
+    of static control bits leaves three dynamic signals:  input, output, and output
+    enable.  One set of these three signals is available to the user when the pad is
+    under user control.  The other set of these three signals is available to the
+    management SoC.  Again, to reduce wiring, only the two pads for JTAG and the
+    housekeeping SDO have all three pins under control of the SoC;  the remaining
+    pads have a single wire to the management SoC which is either an input wire
+    or an output wire, depending on how the control signals for the pad are set.
+
+    This setup gives a simplified view of the pad to the user:  For digital
+    applications, the user can treat the pad as a simple bidirectional digital
+    pad with an output enable to switch between output and input functions.
+    The user can set the output enable line high or low for a static input or
+    output function.  The user will also have access to the ESD-protected
+    pad connections for analog signals, and can connect to the VDDA domain
+    input digital signal if needed.
+
+Memory map:
+-----------
+
+    The Caravel memory map is as follows:
+
+	SRAM:				0000 0000
+
+	Flash:		Config:		1000 0000
+
+	UART:		Clock divider:	2000 0000
+			Data:		2000 0004
+
+	GPIO:		Data:		2100 0000
+			Output enable:	2100 0004
+			Pullup		2100 0008
+			Pulldown	2100 000c 
+
+	Counter 1:	Config:		2110 0000
+			Value:		2110 0004
+			Data:		2110 0008
+
+	Counter 2:	Config:		2120 0000
+			Value:		2120 0004
+			Data:		2120 0008
+
+	SPI master:	Config:		2130 0000
+			Data:		2130 0004
+
+	Logic analyzer:	Data 0:		2200 0000
+			Data 1:		2200 0004
+			Data 2:		2200 0008
+			Data 3:		2200 000c
+			Enable 0:	2200 0010
+			Enable 1:	2200 0014
+			Enable 2:	2200 0018
+			Enable 3:	2200 001c
+
+	Project ctrl:	Data:		2300 0000
+			Transfer:	2300 0004
+			I/O Config:	2300 0008
+			to		2300 0084
+			Power Config:	2300 0088
+			to		2300 0104
+
+	Flash ctrl:	Config:		2D00 0000
+
+	System:		PLL out:	2F00 0000
+			Trap out:	2F00 0004
+			IRQ7 source:	2F00 0008
+
+	User area base:			3000 0000
+
+	Crossbar:	QSPI control	8000 0000
+			Storage area	9000 0000
+			Any slave 1	a000 0000
+			Any slave 2	b000 0000
+
+Project I/O Control:
+---------------------
+
+	Configuration bits per I/O (13 bits for each GPIO pad):
+								Global Default
+		Bits 12-10:	digital mode (3 bits)		001
+		Bit   9:	voltage trip point select	  0
+		Bit   8:	slow slew select		  0
+		Bit   7:	analog bus polarity		  0
+		Bit   6:	analog bus select		  0
+		Bit   5:	analog bus enable		  0
+		Bit   4:	IB mode select			  0
+		Bit   3:	input disable			  0
+		Bit   2:	holdover value			  0
+		Bit   1:	output disable			  1
+		Bit   0:	management control enable	  1
+
+Default I/O modes:
+------------------
+	mprj_io[0]	JTAG I/O		110 0 0 0 0 0 0 0 0 0 1
+	mprj_io[1]	SDO, housekeeping SPI	110 0 0 0 0 0 0 0 0 0 1
+	all others:				001 0 0 0 0 0 0 0 0 1 1
+	
+
+    Standard GPIO output configuration:
+	mprj_io[6]	Tx, UART		110 0 0 0 0 0 0 0 0 0 1
+
+    Standard GPIO input configuration:
+	mprj_io[*]				001 0 0 0 0 0 0 0 0 1 1
+
+    Standard GPIO input configuration with pullup:
+	mprj_io[*]				010 0 0 0 0 0 0 0 0 1 1
+
+    Standard GPIO input configuration with pulldown:
+	mprj_io[*]				011 0 0 0 0 0 0 0 0 1 1
+
+    Specifically:
+	JTAG and SDO are set to output.  The output enable configure bit
+	is a don't-care, since the output enable line is directly controlled
+	by the module (JTAG or housekeeping SPI, respectively).
+
+	All other I/O are set as input mode only, with output disabled.
+	
+	Tx is set to input like the others;  before enabling the UART
+	from a program in flash, the I/O must be set to an output configuration.
+	
+	Note that the standard input configurations with pull-up and pull-down
+	require that "out" be set 1 or 0, respectively;  since the I/O are
+	designed with minimal wiring, there is only one wire for input and
+	output, so the wire is used for input in these cases, and special
+	signal handling is done locally to set the value of "out" equal to
+	~dm[0].  This is a (minor) restriction on the available I/O modes.
+
+	Other possible modes are open-drain (for I2C), weak drive strength
+	output (5k up + down), and analog mode (digital disabled)