In spite of many errors that still need fixing, this is a major advance
over the previous commit. All verilog modules are in place more or less
as intended, with various functions such as the housekeeping SPI placed
on user area pads, with the ability to switch to user control from the
configuration. The pad control bits are local to the pads and loaded
via serial shift register, so that there are not hundreds of control wires
feeding into the user space. The user has three basic controls over each
pad: in, out, and outenb. Two timer/counters and an SPI master have been
added to the SoC. The SPI master shares I/O with the housekeeping SPI, so
that all housekeeping SPI registers can be accessed from the SoC directly.
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)
