adding documentation for generating pimux.bsv

diff --git a/README.md b/README.md
index c907668e77bf3762770dbbfec50df78fc9ff79bf..75a20536b16542957b6acfd4ec9ceb25045413e5 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,39 +1,77 @@
-# PinMux Tool
+* Existing pinmux.bsv for testing purpose:
+```
+cd src/test_bsv
+make
+```

 
 

-This tools currently generates a BSV code which implements the pin-muxing logic between peripheral ports. 
+* Pinmux generator help:
+```
+python src/pinmux_generator.py -h
+```

 
 

-Currently the code supports the following peripherals:
-1. UART (simple RX/TX type)
-2. SPI (single spi)
+* To create a microtest directory and bsv files:
+```
+python src/pinmux_generator.py -v -o microtest -s microtest
+python src/pinmux_generator.py -v -o microtest
+```

 
 

-#### TODO:
-1. Add more peripheral definitions (only IO information required).
-2. Fix a template to specify the user-defined muxing.
-3. Provide support for dedicated pins.
-4. Provide scheme to prevent short-circuit when inputs are mapped to multiple IOs.
+* To create a minitest directory and bsv files:
+```
+python src/pinmux_generator.py -v -o minitest -s minitest
+python src/pinmux_generator.py -v -o minitest
+```

 
 

+* Existing specifications in 'src/spec/' : m_class, i_class, c_class, microtest, minitest

 
 

-## REQUIREMENTS:
-       1. Python2 to generate BSV code.
-       2. BSV compiler to generate verilog code from BSV code.
+* Testing pinmux using cocotb:
+```
+cd src/test_bsv/tests
+```
+---

 
 

-## Quick Start
+### Steps to generate **custom pinmux.bsv** :
+1 . Let's say that the pinmap which we wish to implement is :
+![sample_pinmap](./figure/sample_pinmap.jpg) 

 
 

-Set parameters such as number of UARTs, SPIs, IO Cells, etc. in the file src/params.py . 
+The default order for UART and SPI with pinmux repository is :
+```
+       * UART : tx -> rx
+```
+```
+       * MSPI: ck -> nss -> io0 -> io1
+```
+After generating minitest, this order can be observed in uart.txt, mspi.txt, etc. 

 
 

-    $ make gen_pinmux
+2 . We will rearrange the order of pins of our pinmap to confine to default  order : 
+After reordering, it will look like: 
+![correct_order](./figure/ordered.png)

 
 

-The above command will generate the bsv code (bsv_src/pinmux.bsv). This bsv code implements the pin-muxing logic as specified by the user (currently the pin-muxing logic is not implemented completely)
+3. How to specify this table to generate pinmux.bsv? 
+In pinmux repository, we write the specifications in 'src/spec' directory, like default minitest.py.
+For this case, we will simply modify original minitest.py to suit our table. 
+       * We have only one bank here with 16 rows. So : 'A' : (16,4) in pinbanks. 
+       * In function names, keep only the one which are present in table and update the id as per table. 
+       * Specifying entry in the table: 
+       1) ps.gpio("" ,  ('A', 12) , 0 , 7 , 2 ) 
+       There are 5 arguments passed. 2nd argument specifies bank and pin number.  3rd entry specifies the mux select line (which column?). 4th entry specifies the GPIO id. 5th entry specifies the collection of entries. Here, this will reflect to (GPIOA A7) at pin number 12, and  (GPIOA A8) at pin number 13.
+       
+       2) ps.mspi("2", ('A', 7), 1)
+        There are 4 arguments passed. 1st argument specifies the id of MSPI. 2nd argument specifies the bank and pin number. 3rd argument specifies the mux selection line. Here this will reflect as: 
+        pin number             mux1
+        7                              A MSPI2 CK
+        8                              A MSPI2 NSS
+        9                              A MSPI2 IO0
+        10                             A MSPI2 IO1
+        
+        3) ps.uart(" 3 ", ( 'A', 2 ) , 1 )
+        Here, argument meaning is same as (2)
+        
+        4) ps.pwm("" , ('A', 10) ,  2 ,  5 , 1 )
+        Here, argument meaning is same as (1)

 
 

-    $ make gen_verilog
-The above command can be used to generate the verilog from the bsv file. It requires the presence of a BSV compiler. (see:[Bluespec](https://www.bluespec.com))    
+        
+The complete python file for this table is : src/spec/minitest.py .
+Original minitest: src/spec/minitest_old.py

 
 
 
 

-    $make
-The above command will execute both: gen_pinmux and gen_verilog .

 
 

-## Steps to Add peripheral interfaces to PinMux
-
-1.     Create interface declaration for the peripheral to be added. Remember these are interfaces defined for the pinmux and hence will be opposite to those defined at the peripheral. For eg. the output TX from the UART will be input (method Action) for the pinmux. These changes will have to be done in src/interface_decl.py
-2. Define the wires that will be required to transfer data from the peripheral interface to the IO cell and vice-versa. Create a mkDWire for each input/output between the the peripheral and the pinmux. Also create an implicit wire of GenericIOType        for each cell that can be connected to a each bit from the peripheral. These changes will have to be done in src/wire_def.py
-3. Create the definitions for each of the methods defined in Step-1. Use the wires from Step-2 to transfer data to/from each method. These changes will have to be done in src/interface_decl.py

diff --git a/README_old.md b/README_old.md
new file mode 100644 (file)
index 0000000..c907668
--- /dev/null
+++ b/README_old.md
@@ -0,0 +1,39 @@
+# PinMux Tool
+
+This tools currently generates a BSV code which implements the pin-muxing logic between peripheral ports. 
+
+Currently the code supports the following peripherals:
+1. UART (simple RX/TX type)
+2. SPI (single spi)
+
+#### TODO:
+1. Add more peripheral definitions (only IO information required).
+2. Fix a template to specify the user-defined muxing.
+3. Provide support for dedicated pins.
+4. Provide scheme to prevent short-circuit when inputs are mapped to multiple IOs.
+
+
+## REQUIREMENTS:
+       1. Python2 to generate BSV code.
+       2. BSV compiler to generate verilog code from BSV code.
+
+## Quick Start
+
+Set parameters such as number of UARTs, SPIs, IO Cells, etc. in the file src/params.py . 
+
+    $ make gen_pinmux
+
+The above command will generate the bsv code (bsv_src/pinmux.bsv). This bsv code implements the pin-muxing logic as specified by the user (currently the pin-muxing logic is not implemented completely)
+
+    $ make gen_verilog
+The above command can be used to generate the verilog from the bsv file. It requires the presence of a BSV compiler. (see:[Bluespec](https://www.bluespec.com))    
+
+
+    $make
+The above command will execute both: gen_pinmux and gen_verilog .
+
+## Steps to Add peripheral interfaces to PinMux
+
+1.     Create interface declaration for the peripheral to be added. Remember these are interfaces defined for the pinmux and hence will be opposite to those defined at the peripheral. For eg. the output TX from the UART will be input (method Action) for the pinmux. These changes will have to be done in src/interface_decl.py
+2. Define the wires that will be required to transfer data from the peripheral interface to the IO cell and vice-versa. Create a mkDWire for each input/output between the the peripheral and the pinmux. Also create an implicit wire of GenericIOType        for each cell that can be connected to a each bit from the peripheral. These changes will have to be done in src/wire_def.py
+3. Create the definitions for each of the methods defined in Step-1. Use the wires from Step-2 to transfer data to/from each method. These changes will have to be done in src/interface_decl.py

diff --git a/figure/ordered.png b/figure/ordered.png
new file mode 100644 (file)
index 0000000..64f29fb
Binary files /dev/null and b/figure/ordered.png differ

diff --git a/figure/sample_pinmap.jpg b/figure/sample_pinmap.jpg
new file mode 100644 (file)
index 0000000..e54083b
Binary files /dev/null and b/figure/sample_pinmap.jpg differ

diff --git a/src/spec/minitest.py b/src/spec/minitest.py
index a30fa50e1e370c969d72cc5d504b9764018d753b..a9d8a09371b08aa41a3626b912c75ae4cf987628 100644 (file)
--- a/src/spec/minitest.py
+++ b/src/spec/minitest.py
@@ -1,5 +1,5 @@
 #!/usr/bin/env python
 #!/usr/bin/env python

-
+# aardonyx file

 from spec.base import PinSpec
 
 from spec.ifaceprint import display, display_fns, check_functions
 from spec.base import PinSpec
 
 from spec.ifaceprint import display, display_fns, check_functions


@@ -8,8 +8,7 @@ from spec.ifaceprint import display_fixed
 
 def pinspec():
     pinbanks = {
 
 def pinspec():
     pinbanks = {

-        'A': (28, 4),
-        'B': (4, 1),
+        'A': (16, 4),

     }
     fixedpins = {
         'CTRL_SYS': [
     }
     fixedpins = {
         'CTRL_SYS': [


@@ -31,58 +30,45 @@ def pinspec():
             'VDD_GPIOB',
             'GND_GPIOB',
         ]}
             'VDD_GPIOB',
             'GND_GPIOB',
         ]}

-    function_names = {'EINT': 'External Interrupt',
-                      'FB': 'MC68k FlexBus',
-                      'IIS': 'I2S Audio',
-                      'JTAG': 'JTAG (JTAG_SEL=HI/LO)',
-                      'LCD': '24-pin RGB/TTL LCD',
-                      'RG': 'RGMII Ethernet',
-                      'MMC': 'eMMC 1/2/4/8 pin',
+    function_names = {

                       'PWM': 'PWM (pulse-width modulation)',
                       'PWM': 'PWM (pulse-width modulation)',

-                      'SD0': 'SD/MMC 0',
-                      'SD1': 'SD/MMC 1',
-                      'SD2': 'SD/MMC 2',
-                      'MSPI0': 'SPI (Serial Peripheral Interface) Master 0',
-                      'MSPI1': 'SPI (Serial Peripheral Interface) Master 1',
-                      'MQSPI': 'Quad SPI Master 0',
-                      'TWI0': 'I2C 0',
-                      'TWI1': 'I2C 1',
-                      'TWI2': 'I2C 2',
-                      'QUART0': 'UART (TX/RX/CTS/RTS) 0',
-                      'QUART1': 'UART (TX/RX/CTS/RTS) 1',
-                      'UART0': 'UART (TX/RX) 0',
+                      'MSPI2': 'SPI (Serial Peripheral Interface) Master 1',

                       'UART1': 'UART (TX/RX) 1',
                       'UART1': 'UART (TX/RX) 1',

-                      'UART2': 'UART (TX/RX) 2',
-                      'ULPI0': 'ULPI (USB Low Pin-count) 0',
-                      'ULPI1': 'ULPI (USB Low Pin-count) 1',
-                      'ULPI2': 'ULPI (USB Low Pin-count) 2',
+                      'UART3': 'UART (TX/RX) 2',

                       }
 
     ps = PinSpec(pinbanks, fixedpins, function_names)
 
                       }
 
     ps = PinSpec(pinbanks, fixedpins, function_names)
 

-    # Bank A, 0-27
-    ps.gpio("", ('A', 0), 0, 0, 28)
-    ps.rgbttl("", ('A', 0), 1, limit=22)
-    ps.mspi("0", ('A', 10), 2)
-    ps.mquadspi("0", ('A', 4), 2)
-    ps.uart("0", ('A', 16), 2)
-    ps.i2c("1", ('A', 18), 2)
-    ps.pwm("", ('A', 21), 2, 0, 3)
-    ps.sdmmc("0", ('A', 22), 3)
-    ps.eint("", ('A', 0), 3, 0, 4)
-    ps.eint("", ('A', 20), 2, 4, 1)
-    ps.eint("", ('A', 23), 1, 5, 1)
-    ps.sdmmc("1", ('A', 4), 3)
-    ps.jtag("", ('A', 10), 3)
-    ps.uartfull("0", ('A', 14), 3)
-    ps.uartfull("1", ('A', 18), 3)
-    ps.jtag("", ('A', 24), 2)
-    ps.mspi("1", ('A', 24), 1)
-    ps.i2c("0", ('A', 0), 2)
-    ps.uart("1", ('A', 2), 2)
-    ps.uart("2", ('A', 14), 2)
-
-    ps.mquadspi("1", ('B', 0), 0)
+    ps.gpio("", ('A', 1), 0, 0, 1)
+    ps.gpio("", ('A', 0), 0, 1, 1)
+    ps.gpio("", ('A', 3), 0, 2, 1)
+    ps.gpio("", ('A', 2), 0, 3, 1)
+    ps.gpio("", ('A', 4), 0, 5, 2)
+    ps.gpio("", ('A', 6), 0, 9, 1)
+
+    ps.gpio("", ('A', 7), 0, 13, 1)
+    ps.gpio("", ('A', 8), 0, 10, 1)
+    ps.gpio("", ('A', 9), 0, 12, 1)
+    ps.gpio("", ('A', 10), 0, 11, 1)
+
+    ps.gpio("", ('A', 11), 0, 4, 1)
+    ps.gpio("", ('A', 12), 0, 7, 2)
+    ps.gpio("", ('A', 14), 0, 14, 2)
+
+
+
+
+
+    ps.pwm("", ('A', 2), 2, 0, 1)
+    ps.pwm("", ('A', 4), 2, 1, 3)
+    ps.pwm("", ('A', 8), 2, 4, 1)
+    ps.pwm("", ('A', 10), 2, 5, 1)
+    #ps.pwm("", ('A', 13), 2, 5, 1)
+    ps.mspi("2", ('A', 7), 1)
+    ps.uart("1", ('A', 0), 1)
+    ps.uart("3", ('A', 2), 1)
+
+    #ps.mquadspi("1", ('B', 0), 0)

 
     # Scenarios below can be spec'd out as either "find first interface"
     # by name/number e.g. SPI1, or as "find in bank/mux" which must be
 
     # Scenarios below can be spec'd out as either "find first interface"
     # by name/number e.g. SPI1, or as "find in bank/mux" which must be


@@ -93,7 +79,7 @@ def pinspec():
 
     minitest = ['ULPI0/8', 'ULPI1', 'MMC', 'SD0', 'UART0',
                 'TWI0', 'MSPI0', 'B3:SD1', ]
 
     minitest = ['ULPI0/8', 'ULPI1', 'MMC', 'SD0', 'UART0',
                 'TWI0', 'MSPI0', 'B3:SD1', ]

-    minitest_eint = ['EINT_0', 'EINT_1', 'EINT_2', 'EINT_3', 'EINT_4']
+    minitest_eint = []

     minitest_pwm = ['B2:PWM_0']
     descriptions = {
         'MMC': 'internal (on Card)',
     minitest_pwm = ['B2:PWM_0']
     descriptions = {
         'MMC': 'internal (on Card)',

diff --git a/src/spec/minitest_old.py b/src/spec/minitest_old.py
new file mode 100644 (file)
index 0000000..a30fa50
--- /dev/null
+++ b/src/spec/minitest_old.py
@@ -0,0 +1,114 @@
+#!/usr/bin/env python
+
+from spec.base import PinSpec
+
+from spec.ifaceprint import display, display_fns, check_functions
+from spec.ifaceprint import display_fixed
+
+
+def pinspec():
+    pinbanks = {
+        'A': (28, 4),
+        'B': (4, 1),
+    }
+    fixedpins = {
+        'CTRL_SYS': [
+            'TEST',
+            'JTAG_SEL',
+            'UBOOT_SEL',
+            'NMI#',
+            'RESET#',
+            'CLK24M_IN',
+            'CLK24M_OUT',
+            'PLLTEST',
+            'PLLREGIO',
+            'PLLVP25',
+            'PLLDV',
+            'PLLVREG',
+            'PLLGND',
+        ],
+        'POWER_GPIO': [
+            'VDD_GPIOB',
+            'GND_GPIOB',
+        ]}
+    function_names = {'EINT': 'External Interrupt',
+                      'FB': 'MC68k FlexBus',
+                      'IIS': 'I2S Audio',
+                      'JTAG': 'JTAG (JTAG_SEL=HI/LO)',
+                      'LCD': '24-pin RGB/TTL LCD',
+                      'RG': 'RGMII Ethernet',
+                      'MMC': 'eMMC 1/2/4/8 pin',
+                      'PWM': 'PWM (pulse-width modulation)',
+                      'SD0': 'SD/MMC 0',
+                      'SD1': 'SD/MMC 1',
+                      'SD2': 'SD/MMC 2',
+                      'MSPI0': 'SPI (Serial Peripheral Interface) Master 0',
+                      'MSPI1': 'SPI (Serial Peripheral Interface) Master 1',
+                      'MQSPI': 'Quad SPI Master 0',
+                      'TWI0': 'I2C 0',
+                      'TWI1': 'I2C 1',
+                      'TWI2': 'I2C 2',
+                      'QUART0': 'UART (TX/RX/CTS/RTS) 0',
+                      'QUART1': 'UART (TX/RX/CTS/RTS) 1',
+                      'UART0': 'UART (TX/RX) 0',
+                      'UART1': 'UART (TX/RX) 1',
+                      'UART2': 'UART (TX/RX) 2',
+                      'ULPI0': 'ULPI (USB Low Pin-count) 0',
+                      'ULPI1': 'ULPI (USB Low Pin-count) 1',
+                      'ULPI2': 'ULPI (USB Low Pin-count) 2',
+                      }
+
+    ps = PinSpec(pinbanks, fixedpins, function_names)
+
+    # Bank A, 0-27
+    ps.gpio("", ('A', 0), 0, 0, 28)
+    ps.rgbttl("", ('A', 0), 1, limit=22)
+    ps.mspi("0", ('A', 10), 2)
+    ps.mquadspi("0", ('A', 4), 2)
+    ps.uart("0", ('A', 16), 2)
+    ps.i2c("1", ('A', 18), 2)
+    ps.pwm("", ('A', 21), 2, 0, 3)
+    ps.sdmmc("0", ('A', 22), 3)
+    ps.eint("", ('A', 0), 3, 0, 4)
+    ps.eint("", ('A', 20), 2, 4, 1)
+    ps.eint("", ('A', 23), 1, 5, 1)
+    ps.sdmmc("1", ('A', 4), 3)
+    ps.jtag("", ('A', 10), 3)
+    ps.uartfull("0", ('A', 14), 3)
+    ps.uartfull("1", ('A', 18), 3)
+    ps.jtag("", ('A', 24), 2)
+    ps.mspi("1", ('A', 24), 1)
+    ps.i2c("0", ('A', 0), 2)
+    ps.uart("1", ('A', 2), 2)
+    ps.uart("2", ('A', 14), 2)
+
+    ps.mquadspi("1", ('B', 0), 0)
+
+    # Scenarios below can be spec'd out as either "find first interface"
+    # by name/number e.g. SPI1, or as "find in bank/mux" which must be
+    # spec'd as "BM:Name" where B is bank (A-F), M is Mux (0-3)
+    # EINT and PWM are grouped together, specially, but may still be spec'd
+    # using "BM:Name".  Pins are removed in-order as listed from
+    # lists (interfaces, EINTs, PWMs) from available pins.
+
+    minitest = ['ULPI0/8', 'ULPI1', 'MMC', 'SD0', 'UART0',
+                'TWI0', 'MSPI0', 'B3:SD1', ]
+    minitest_eint = ['EINT_0', 'EINT_1', 'EINT_2', 'EINT_3', 'EINT_4']
+    minitest_pwm = ['B2:PWM_0']
+    descriptions = {
+        'MMC': 'internal (on Card)',
+        'SD0': 'user-facing: internal (on Card), multiplexed with JTAG\n'
+        'and UART2, for debug purposes',
+        'TWI2': 'I2C.\n',
+        'E2:SD1': '',
+        'MSPI1': '',
+        'UART0': '',
+        'B1:LCD/22': '18-bit RGB/TTL LCD',
+        'ULPI0/8': 'user-facing: internal (on Card), USB-OTG ULPI PHY',
+        'ULPI1': 'dual USB2 Host ULPI PHY'
+    }
+
+    ps.add_scenario("MiniTest", minitest, minitest_eint, minitest_pwm,
+                    descriptions)
+
+    return ps