add in some comments

diff --git a/src/bsv/pinmux_generator.py b/src/bsv/pinmux_generator.py
index 72fc39af381bdb00707601bedc9c105661df3edf..ddbb3fda8182fe63b9f2a387833d2dfc9f7bba71 100644 (file)
--- a/src/bsv/pinmux_generator.py
+++ b/src/bsv/pinmux_generator.py
@@ -118,8 +118,11 @@ def write_pmp(pmp, p, ifaces, iocells):
 
       interface PeripheralSide;
       // declare the interface to the peripherals
-      // Each IO cell will have 3 input field (output from pin mux
-      // and on output field (input to pinmux)''')
+      // Each peripheral's function will be either an input, output
+      // or be bi-directional.  an input field will be an output from the
+      // peripheral and an output field will be an input to the peripheral.
+      // Bi-directional functions also have an output-enable (which
+      // again comes *in* from the peripheral)''')
         # ==============================================================
 
         # == create method definitions for all peripheral interfaces ==#
@@ -133,8 +136,8 @@ def write_pmp(pmp, p, ifaces, iocells):
 
       interface IOCellSide;
       // declare the interface to the IO cells.
-      // Each IO cell will have 3 input field (output from pin mux
-      // and on output field (input to pinmux)''')
+      // Each IO cell will have 1 input field (output from pin mux)
+      // and an output and out-enable field (input to pinmux)''')
 
         # == create method definitions for all iocell interfaces ==#
         ifaces.ifacefmt(bsv_file)
@@ -144,8 +147,24 @@ def write_pmp(pmp, p, ifaces, iocells):
         bsv_file.write('''
 
    interface Ifc_pinmux;
+      // this interface controls how each IO cell is routed.  setting
+      // any given IO cell's mux control value will result in redirection
+      // of not just the input or output to different peripheral functions
+      // but also the *direction* control - if appropriate - as well.
       interface MuxSelectionLines mux_lines;
+
+      // this interface contains the inputs, outputs and direction-control
+      // lines for all peripherals.  GPIO is considered to also be just
+      // a peripheral because it also has in, out and direction-control.
       interface PeripheralSide peripheral_side;
+
+      // this interface is to be linked to the individual IO cells.
+      // if looking at a "non-muxed" GPIO design, basically the
+      // IO cell input, output and direction-control wires are cut
+      // (giving six pairs of dangling wires, named left and right)
+      // these iocells are routed in their place on one side ("left")
+      // and the matching *GPIO* peripheral interfaces in/out/dir
+      // connect to the OTHER side ("right").
       interface IOCellSide iocell_side;
    endinterface
    (*synthesize*)

diff --git a/src/test_bsv/pinmux.bsv b/src/test_bsv/pinmux.bsv
index 640f47bbeedfeb48bd1bda2716d2edb434a4e3e1..c9972505861808073d20fb85575f2803b98ca32d 100644 (file)
--- a/src/test_bsv/pinmux.bsv
+++ b/src/test_bsv/pinmux.bsv
@@ -4,7 +4,7 @@
    https://bitbucket.org/casl/pinmux.
 
    Authors: Neel Gala, Luke
-   Date of generation: Mon Jun 25 15:11:57 2018
+   Date of generation: Mon Jun 25 15:46:34 2018
 */
 
 package pinmux;
@@ -23,8 +23,11 @@ package pinmux;
 
       interface PeripheralSide;
       // declare the interface to the peripherals
-      // Each IO cell will have 3 input field (output from pin mux
-      // and on output field (input to pinmux)
+      // Each peripheral's function will be either an input, output
+      // or be bi-directional.  an input field will be an output from the
+      // peripheral and an output field will be an input to the peripheral.
+      // Bi-directional functions also have an output-enable (which
+      // again comes *in* from the peripheral)
           // interface declaration between IO-0 and pinmux
     (*always_ready,always_enabled*) method  Bit#(1) io0_cell_out;
     (*always_ready,always_enabled*) method  Bit#(1) io0_cell_outen;
@@ -45,8 +48,8 @@ package pinmux;
 
       interface IOCellSide;
       // declare the interface to the IO cells.
-      // Each IO cell will have 3 input field (output from pin mux
-      // and on output field (input to pinmux)
+      // Each IO cell will have 1 input field (output from pin mux)
+      // and an output and out-enable field (input to pinmux)
           // interface declaration between UART-0 and pinmux
     (*always_ready,always_enabled*) method  Action uart_tx (Bit#(1) in);
     (*always_ready,always_enabled*) method  Bit#(1) uart_rx;
@@ -71,8 +74,24 @@ package pinmux;
 
 
    interface Ifc_pinmux;
+      // this interface controls how each IO cell is routed.  setting
+      // any given IO cell's mux control value will result in redirection
+      // of not just the input or output to different peripheral functions
+      // but also the *direction* control - if appropriate - as well.
       interface MuxSelectionLines mux_lines;
+
+      // this interface contains the inputs, outputs and direction-control
+      // lines for all peripherals.  GPIO is considered to also be just
+      // a peripheral because it also has in, out and direction-control.
       interface PeripheralSide peripheral_side;
+
+      // this interface is to be linked to the individual IO cells.
+      // if looking at a "non-muxed" GPIO design, basically the
+      // IO cell input, output and direction-control wires are cut
+      // (giving six pairs of dangling wires, named left and right)
+      // these iocells are routed in their place on one side ("left")
+      // and the matching *GPIO* peripheral interfaces in/out/dir
+      // connect to the OTHER side ("right").
       interface IOCellSide iocell_side;
    endinterface
    (*synthesize*)