Links:
+* Main page on pinmux: [[/docs/pinmux]]
* <https://bugs.libre-soc.org/show_bug.cgi?id=50>
-* <https://git.libre-soc.org/?p=pinmux.git;a=blob;f=src/spec/testing_stage1.py>
* <https://git.libre-soc.org/?p=c4m-jtag.git>
-* Main page on pinmux: [[/docs/pinmux]]
+* <https://git.libre-soc.org/?p=soc.git;a=blob;f=src/soc/bus/simple_gpio.py;hb=HEAD>
+* <https://git.libre-soc.org/?p=pinmux.git;a=blob;f=src/spec/testing_stage1.py;hb=HEAD>
+* <https://git.libre-soc.org/?p=pinmux.git;a=blob;f=src/spec/simple_gpio.py;hb=HEAD>
+* ST Ericsson presentation on the GPIO subsystem: <https://ftp.libre-soc.org/Pin_Control_Subsystem_Overview.pdf>
+* Technical guide to JTAG: <https://www.corelis.com/education/tutorials/jtag-tutorial/jtag-technical-primer>
+* Presentation on JTAG: <http://www.facweb.iitkgp.ac.in/~isg/ADV-TESTING/SLIDES/5-JTAG.pdf>
+* Useful information on mandatory JTAG instructions: <https://www.corelis.com/education/tutorials/jtag-tutorial/jtag-technical-primer/#JTAG_Instructions>
+* IRC conversation on the 14th about GPIO improvement: <https://libre-soc.org/irclog/%23libre-soc.2022-01-14.log.html>
+* IRC conversation on the 16th about nmigen Records: <https://libre-soc.org/irclog/%23libre-soc.2022-01-16.log.html>
The tasks initially set out by Luke in 2019 (bug 50 description):
* auto-generation of Technical Reference Manual sections
# Definitions
-Useful definitions required for understanding the undertaken tasks.
+Useful definitions required for understanding the undertaken tasks.
+See the main page for more indepth explanation on IO Pads, JTAG.
## JTAG Boundary Scan (BS) chain
-Essentially a combination of a multiplexer and shift register. The BS chain allows core signals to connect straight to the ASIC pads, or allow an external JTAG device to individually control the core inputs and pad outputs via the shift register.
+Essentially a combination of a multiplexer and shift register.
+The BS chain allows core signals to connect straight to the ASIC pads,
+or allow an external JTAG device to individually control the core inputs
+and pad outputs via the shift register.
## Core
-Refers to peripherals coming from the ASIC (I2C, SPI, UART, GPIO, etc.). Core signals come from the the actual HDL of the peripherals, and connect to the JTAG Boundary Scan chain.
+Refers to peripherals coming from the ASIC (I2C, SPI, UART, GPIO, etc.).
+ Core signals come from the the actual HDL of the peripherals,
+and connect to the JTAG Boundary Scan chain.
## Pad/s
-Refers to the ASIC pads which are routed out to the outside world. These pads are what a chip user can interact with directly (for good or bad...).
+Refers to the ASIC pads which are routed out to the outside world.
+These pads are what a chip user can interact with directly (for good or bad...).
## Pinmux
-Pin multiplexer allows ASIC pads to support a range of functions (although only one at a time per pad). Each function is allocated to a "bank", and the selected bank can be configured by the user.
-
-A pinmux is an absolute must when the amount of functionality (or peripheral signals) greatly exceed the available number of pins on a package. Also, pinmuxing allows to select packages with smaller pincounts, thus producing cheaper (and higher yield) chips.
+Pin multiplexer allows ASIC pads to support a range of functions
+(although only one at a time per pad).
+Each function is allocated to a "bank", and the selected bank
+can be configured by the user.
-For example: A pad can be I2C SDA on bank0, a GPIO on bank1, a UART RX on bank2. By setting the bank select to 1, the pad can act as a GPIO (input or output).
+A pinmux is an absolute must when the amount of functionality
+(or peripheral signals) greatly exceed the available number
+of pins on a package.
+Also, pinmuxing allows to select packages with smaller pincounts,
+thus producing cheaper (and higher yield) chips.
-# Current progress on code for testing periph pin generation and JTAG in "testing_stage1.py":
+For example: A pad can be I2C SDA on bank0, a GPIO on bank1,
+a UART RX on bank2. By setting the bank select to 1,
+the pad can act as a GPIO (input or output).
+# Progress on code in "testing_stage1.py":
## Dummy pinset
-A test pinset that specifies which peripherals are to be added. In this case, four GPIOs, one UART, one I2C.
+A test pinset that specifies which peripherals are to be added.
+In this case, four GPIOs, one UART, one I2C.
## Resource signal creation
-"create_resources()" function parses a given pinset (the dummy one in this case), and creates a resources list containing the peripherals (with nmigen subsignals such as sda, gpio_o/i/oe etc.).
+"create_resources()" function parses a given pinset
+(the dummy one in this case), and creates a resources list containing
+the peripherals (with nmigen subsignals such as sda, gpio_o/i/oe etc.).
-Within this function, Resource.family(), JTAGResource(), UARTResource(), I2CResource() create the signals with correct direction (input/output/inout).
+Within this function, Resource.family(), JTAGResource(), UARTResource(),
+I2CResource() create the signals with correct direction (input/output/inout).
The returned "resources" list is used in....?
## Blinker test module
-Contains a JTAG module from Chips4Makers (c4m-jtag ?). The JTAG module is the backbone of the Blinker test module, because from it the Boundary Scan chain is produced.
-By using "jtag.request('i2c')" (or 'uart', 'gpio', etc.), the Boundary Scan chain is extended. Subsignals used to connect the peripherals from the core"
\ No newline at end of file
+Contains a JTAG module from Chips4Makers (c4m-jtag).
+The JTAG module is the backbone of the Blinker test module,
+because from it the Boundary Scan chain is produced.
+
+By using "jtag.request('i2c')" (or 'uart', 'gpio', etc.),
+the Boundary Scan chain is extended. The JTAG module then provides subsignals
+to connect to core as well as pad side.
+
+I2C and UART are connected in a loopback configuration (input to output),
+allowing to test both signals at the same time. The GPIO output is an XOR of
+the GPIO input, and a test input controlled by sim (gpio_o_test).
+The oe signals are controlled by the sim using test input registers.
+
+## ASIC Platform
+Performs some magic with file template code.
+Resource list (dummy pinset) provided at instantiation is added to the internal
+resource list (?).
+More magic with configuring pins that are inputs/outputs/tristates.
+Core/Pad pins are connected to the appropriate JTAG pins.
+
+## Unit tests
+### GPIO test
+For every output configuration of four GPIOs (16), go through each input
+configuration.
+Assert that signal states match the function in the Blinker class.
+
+### UART test
+Check TX matches RX when high and low.
+
+### I2C test
+Check SDA out and SCL out match SDA/SCL in.
+Check oe's by driving the test registers.
+
+### JTAG test BS chain
+The unit test has four test cases, two before the peripherals are exercised,
+and two after:
+
+1. Send 0xFFFFF via TDI in EX_TEST mode
+1. Send 0xFFFFF via TDO in BS_SAMPLE mode
+1. Send 0x00000 via TDI in EX_TEST mode
+1. Send 0x00000 via TDI in BS_SAMPLE mode
+
+The expected results are:
+
+1. All core outputs high (as these set by JTAG BS), all pad inputs low
+(not asserted yet)
+1. All signals should be low (as JTAG TDI is ignored and all inputs low).
+1. All pad inputs and sim controlled input (output enables etc.) should be high.
+1. All signals should be high.
+
+These test cases are performed by the "jtag_unit_test" with selected JTAG
+ instructions (SAMPLE or EXTEST), data to send via TDI, and expected TDO data
+vector. The TDO and TDI data is compared using asserts.
+
+NOTE: Currently the last test case's TDO data does not match the actual
+core/pad signal values. Not sure why the returned TDO is incorrect, however
+the signals are correct.
+
+# Pinmux GPIO Block
+## Diagram
+[[!img banked_gpio_block.jpg size="600x"]]
+
+*(Diagram is missing the "ie" signal as part of the bundle of signals given to the peripherals, will be updated later)*
+
+## Explanation
+The simple GPIO module is multi-GPIO block integral to the pinmux system.
+To make the block flexible, it has a variable number of of I/Os based on an
+input parameter.
+
+By default, the block is memory-mapped WB bus GPIO. The CPU
+core can just write the configuration word to the GPIO row address. From this
+perspective, it is no different to a conventional GPIO block.
+
+### Bank Select Options
+* bank 0 - WB bus has full control (GPIO peripheral)
+* bank 1,2,3 - WB bus only controls puen/pden, periphal gets o/oe/i/ie (Not
+fully specified how this should be arranged yet)
+
+Bank select however, allows to switch over the control of the GPIO block to
+another peripheral. The peripheral will be given sole connectivity to the
+o/oe/i/ie signals, while additional parameters such as pull up/down will either
+be automatically configured (as the case for I2C), or will be configurable
+via the WB bus. *(This has not been implemented yet, so open to discussion)*
+
+## Configuration Word
+After a discussion with Luke on IRC (14th January 2022), new layout of the
+8-bit data word for configuring the GPIO (through CSR):
+
+* oe - Output Enable (see the Ericson presentation for the GPIO diagram)
+* ie - Input Enable
+* puen - Pull-Up resistor enable
+* pden - Pull-Down resistor enable
+* i/o - When configured as output (oe set), this bit sets/clears output. When
+configured as input, shows the current state of input (read-only)
+* bank_sel[2:0] - Bank Select (only 4 banks used)
+
+### Simultaneous/Packed Configuration
+To make the configuration more efficient, multiple GPIOs can be configured with
+one data word. The number of GPIOs in one "row" is dependent on the width of the
+WB data bus.
+
+If for example, the data bus is 64-bits wide, eight GPIO configuration bytes -
+and thus eight GPIOs - are configured in one go. There is no way to specify
+which GPIO in a row is configured, so the programmer has to keep the current
+state of the configuration as part of the code (essentially a shadow register).
+
+The diagram below shows the layout of the configuration byte, and how it fits
+within a 64-bit data word.
+
+[[!img gpio_csr_example.jpg size="600x"]]
+
+If the block is created with more GPIOs than can fit in a single data word,
+the next set of GPIOs can be accessed by incrementing the address.
+For example, if 16 GPIOs are instantiated and 64-bit data bus is used, GPIOs
+0-7 are accessed via address 0, whereas GPIOs 8-15 are accessed by address 8
+(TODO: DOES ADDRESS COUNT WORDS OR BYTES?)
+
+## Example Memory Map
+[[!img gpio_memory_example.jpg size="600x"]]
+
+The diagrams above show the difference in memory layout between 16-GPIO block implemented with 64-bit and 32-bit WB data buses. The 64-bit case shows there are two rows with eight GPIOs in each, and it will take two writes (assuming simple WB write) to completely configure all 16 GPIOs. The 32-bit on the other hand has four address rows, and so will take four write transactions.
+
+64-bit:
+
+* 0x00 - Configure GPIOs 0-7
+* 0x01 - Configure GPIOs 8-15
+
+32-bit:
+
+* 0x00 - Configure GPIOs 0-3
+* 0x01 - Configure GPIOs 4-7
+* 0x02 - Configure GPIOs 8-11
+* 0x03 - Configure GPIOs 12-15
+
+## Sim commands for single GPIO - IN PROGRESS
+* gpio_config - Set the CSR (only the first GPIO is currently configured).
+* gpio_rd_csr - Read the current CSR state and parse (only first GPIO).
+* gpio_rd_input - Read the current input.
+* gpio_set_out - Set the output to given value.
+* gpio_set_in_pad - Set the input signals for the block (external,
+not controlled by WB)
+* gpio_rd_out - (TODO)
+
+## Test
+The current test does the following:
+
+* Set the bank select to a random value between 0 and 15 (unless the
+"use_random" argument is set to false)
+* Set oe (all GPIOs are outputs)
+* Set GPIO outputs sequentially
+* Set external GPIO inputs sequentially and clear
+
+
projects / libreriscv.git / blobdiff