docs(pinmux): Changed 'bank' to 'port'/'mux', added section on PinSpec class

diff --git a/docs/pinmux.mdwn b/docs/pinmux.mdwn
index aa475128f4d85ad3a62fefd32cc865903d2ea4b9..9e5a28659e8fafc4fe0e3be5a7f6f75793f918cd 100644 (file)
--- a/docs/pinmux.mdwn
+++ b/docs/pinmux.mdwn
@@ -10,6 +10,8 @@ Links:
 * <https://bugs.libre-soc.org/show_bug.cgi?id=762>
 * <https://git.libre-soc.org/?p=c4m-jtag.git;a=tree;hb=HEAD>
 * Extra info: [[/docs/pinmux/temp_pinmux_info]]
+* <https://git.libre-soc.org/?p=pinmux.git;a=blob;f=src/stage2.py> - Latest
+manual demo of pinmux generation
 
 Managing IO on an ASIC is nowhere near as simple as on an FPGA.
 An FPGA has built-in IO Pads, the wires terminate inside an
@@ -417,7 +419,8 @@ there will be a lag on the output data compared to the incoming
 
 # Pinmux GPIO Block
 
-The following diagram is an example of a GPIO block with switchable banks and comes from the Ericson presentation on a GPIO architecture.
+The following diagram is an example of a mux'd GPIO block that comes from the
+Ericson presentation on a GPIO architecture.
 
 [[!img gpio-block.svg size="800x"]]
 
@@ -426,15 +429,73 @@ The following diagram is an example of a GPIO block with switchable banks and co
 The block we are developing is very similar, but is lacking some of
 configuration of the former (due to complexity and time constraints).
 
-The implemented pinmux consists of two sub-blocks:
+The implemented pinmux uses two sub-blocks:
 
 1. A Wishbone controlled N-GPIO block.
 
-1. Bank selectable N-port I/O multiplexer (for current usecase set to 4 
-ports/banks).
+1. N-port I/O multiplexer (for current usecase set to 4
+ports).
+
+### Terminology
+
+For clearer explanation, the following definitions will be used in the text.
+As the documentation is actively being written, the experimental code may not
+adhere to these all the time.
+
+* Bank - A group of contiguous pins under a common name.
+* Pin - Bi-directional wire connecting to the chip's pads.
+* Function (pin) - A signal used by the peripheral.
+* Port - Bi-directional signal on the peripheral and pad sides of the
+multiplexer.
+* Muxwidth - Number of input ports to the multiplexers
+* PinMux - Multiplexer for connecting multiple peripheral functions to one IO
+pad.
+
+For example:
+
+A 128-pin chip has 4 banks N/S/E/W corresponding to the 4 sides of the chip.
+Each bank has 32 pins. Each pin can have up to 4 multiplexed functions, thus
+the multiplexer width for each pin is 4.
+
+### PinSpec Class
+
+* <https://git.libre-soc.org/?p=pinmux.git;a=blob;f=src/spec/base.py;h=c8fa2b09d650b1b7cfdb499bfe711a3ebaf5848b;hb=HEAD> PinSpec class
+defined here.
+
+PinSpec is a powerful construct designed to hold all the necessary information
+about the chip's banks. This includes:
+
+1. Number of banks
+1. Number of pins per each bank
+1. Peripherals present (UART, GPIO, I2C, etc.)
+1. Mux configuration for every pin (mux0: gpio, mux1: uart tx, etc.)
+1. Peripheral function signal type (out/in/bi)
+
+### Pinouts
+
+* <https://git.libre-soc.org/?p=pinmux.git;a=blob;f=src/spec/interfaces.py;h=f5ecf4817ba439b607a1909a4fcb6aa2589e2afd;hb=HEAD> Pinouts class
+defined here.
+
+The Pinspec class inherits from the Pinouts class, which allows to view the
+dictionaries containing bank names and pin information.
+
+* keys() - returns dict_key object of all the pins (summing all the banks) which
+is iterable
+* items() - a dict_key of pins, with each pin's mux information
+
+For example, PinSpec object 'ps' has one bank 'A' with 4 pins
+ps.keys() returns dict_keys([0, 1, 2, 3])
+ps.items() returns
+dict_items([(0, {0: ('GPIOA_A0', 'A'), 1: ('UART0_TX', 'A'),
+                                2: ('TWI0_SDA', 'A')}),
+                   (1, {0: ('GPIOA_A1', 'A'), 1: ('UART0_RX', 'A'),
+                                2: ('TWI0_SCL', 'A')}),
+                       (2, {0: ('GPIOA_A2', 'A')}), (3, {0: ('GPIOA_A3', 'A')})])
 
 ## The GPIO block 
 
+*NOTE !* - Need to change 'bank' terminology for the GPIO block in doc and code!
+
 [[!img n-gpio.svg size="600x"]]
 
 The GPIO module is multi-GPIO block integral to the pinmux system.
@@ -534,16 +595,19 @@ because these should be equal.
 
 [[!img iomux-4bank.svg size="600x"]]
 
-This block is an N-to-1 (4 bank shown above) mux and it simultaneously connects:
+This block is an N-to-1 (4-port shown above) mux and it simultaneously connects:
 
 * o/oe signals from one of N peripheral ports, to the pad output port
 
 * i pad port signal to one of N peripheral ports (the rest being set to 0).
 
-*(NOTE: an N-pin 4-bank IOMux has not been implemented yet - do it within the pinmux instead?)*
+The block is then used in a higher-level pinmux block, and instantiated for each
+pin.
 
 ## Combined Block
 
+*NOTE !* - Need to change 'bank' terminology for the GPIO block in doc and code!
+
 [[!img pinmux-1pin.svg size="600x"]]
 
 The GPIO and IOMux blocks are combined in a single block called the