docs/pinmux/temp_pinmux_info.mdwn

   1 # Progress on Pinmux, IO Pads, and JTAG Boundary scan (Temporary page)
   2 (This is a temporary page for organising current work on the above.)
   3
   4 Links:
   5
   6 * Main page on pinmux: [[/docs/pinmux]]
   7 * <https://bugs.libre-soc.org/show_bug.cgi?id=50>
   8 * <https://git.libre-soc.org/?p=c4m-jtag.git>
   9 * <https://git.libre-soc.org/?p=soc.git;a=blob;f=src/soc/bus/simple_gpio.py;hb=HEAD>
  10 * <https://git.libre-soc.org/?p=pinmux.git;a=blob;f=src/spec/testing_stage1.py;hb=HEAD>
  11 * <https://git.libre-soc.org/?p=pinmux.git;a=blob;f=src/spec/simple_gpio.py;hb=HEAD>
  12 * ST Ericsson presentation on the GPIO subsystem: <https://ftp.libre-soc.org/Pin_Control_Subsystem_Overview.pdf>
  13 * Technical guide to JTAG: <https://www.corelis.com/education/tutorials/jtag-tutorial/jtag-technical-primer>
  14 * Presentation on JTAG: <http://www.facweb.iitkgp.ac.in/~isg/ADV-TESTING/SLIDES/5-JTAG.pdf>
  15 * Useful information on mandatory JTAG instructions: <https://www.corelis.com/education/tutorials/jtag-tutorial/jtag-technical-primer/#JTAG_Instructions>
  16 * IRC conversation on the 14th about GPIO improvement: <https://libre-soc.org/irclog/%23libre-soc.2022-01-14.log.html>
  17 * IRC conversation on the 16th about nmigen Records: <https://libre-soc.org/irclog/%23libre-soc.2022-01-16.log.html>
  18
  19 The tasks initially set out by Luke in 2019 (bug 50 description):
  20
  21 * peripheral multiplexing
  22 * SoC-to-peripheral interconnect auto-generation
  23 * auto-creation of peripheral memory-address locations and suitable linux header
  24 * auto-creation of linux kernel header files for GPIO pinmux layout
  25 * auto-creation of IO ring corona for ASICs
  26 * auto-generation and allocation of IRQs and IRQ connectivity
  27 * auto-generation of Technical Reference Manual sections
  28
  29 # Definitions
  30 Useful definitions required for understanding the undertaken tasks.
  31 See the main page for more indepth explanation on IO Pads, JTAG.
  32
  33 ## JTAG Boundary Scan (BS) chain
  34 Essentially a combination of a multiplexer and shift register.
  35 The BS chain allows core signals to connect straight to the ASIC pads,
  36 or allow an external JTAG device to individually control the core inputs
  37 and pad outputs via the shift register.
  38 ## Core
  39 Refers to peripherals coming from the ASIC (I2C, SPI, UART, GPIO, etc.).
  40  Core signals come from the the actual HDL of the peripherals,
  41 and connect to the JTAG Boundary Scan chain.
  42 ## Pad/s
  43 Refers to the ASIC pads which are routed out to the outside world.
  44 These pads are what a chip user can interact with directly (for good or bad...).
  45 ## Pinmux
  46 Pin multiplexer allows ASIC pads to support a range of functions
  47 (although only one at a time per pad).
  48 Each function is allocated to a "bank", and the selected bank
  49 can be configured by the user.
  50
  51 A pinmux is an absolute must when the amount of functionality
  52 (or peripheral signals) greatly exceed the available number
  53 of pins on a package.
  54 Also, pinmuxing allows to select packages with smaller pincounts,
  55 thus producing cheaper (and higher yield) chips.
  56
  57 For example: A pad can be I2C SDA on bank0, a GPIO on bank1,
  58 a UART RX on bank2. By setting the bank select to 1,
  59 the pad can act as a GPIO (input or output).
  60
  61 # Progress on code in "testing_stage1.py":
  62 ## Dummy pinset
  63 A test pinset that specifies which peripherals are to be added.
  64 In this case, four GPIOs, one UART,  one I2C.
  65
  66 ## Resource signal creation
  67 "create_resources()" function parses a given pinset
  68 (the dummy one in this case), and creates a resources list containing
  69 the peripherals (with nmigen subsignals such as sda, gpio_o/i/oe etc.).
  70
  71 Within this function, Resource.family(), JTAGResource(), UARTResource(),
  72 I2CResource() create the signals with correct direction (input/output/inout).
  73
  74 The returned "resources" list is used in....?
  75
  76 ## Blinker test module
  77 Contains a JTAG module from Chips4Makers (c4m-jtag).
  78 The JTAG module is the backbone of the Blinker test module,
  79 because from it the Boundary Scan chain is produced.
  80
  81 By using "jtag.request('i2c')" (or 'uart', 'gpio', etc.),
  82 the Boundary Scan chain is extended. The JTAG module then provides subsignals
  83 to connect to core as well as pad side.
  84
  85 I2C and UART are connected in a loopback configuration (input to output),
  86 allowing to test both signals at the same time. The GPIO output is an XOR of
  87 the GPIO input, and a test input controlled by sim (gpio_o_test).
  88 The oe signals are controlled by the sim using test input registers.
  89
  90 ## ASIC Platform
  91 Performs some magic with file template code.
  92 Resource list (dummy pinset) provided at instantiation is added to the internal
  93 resource list (?).
  94 More magic with configuring pins that are inputs/outputs/tristates.
  95 Core/Pad pins are connected to the appropriate JTAG pins.
  96
  97 ## Unit tests
  98 ### GPIO test
  99 For every output configuration of four GPIOs (16), go through each input
 100 configuration.
 101 Assert that signal states match the function in the Blinker class.
 102
 103 ### UART test
 104 Check TX matches RX when high and low.
 105
 106 ### I2C test
 107 Check SDA out and SCL out match SDA/SCL in.
 108 Check oe's by driving the test registers.
 109
 110 ### JTAG test BS chain
 111 The unit test has four test cases, two before the peripherals are exercised,
 112 and two after:
 113
 114 1. Send 0xFFFFF via TDI in EX_TEST mode
 115 1. Send 0xFFFFF via TDO in BS_SAMPLE mode
 116 1. Send 0x00000 via TDI in EX_TEST mode
 117 1. Send 0x00000 via TDI in BS_SAMPLE mode
 118
 119 The expected results are:
 120
 121 1. All core outputs high (as these set by JTAG BS), all pad inputs low
 122 (not asserted yet)
 123 1. All signals should be low (as JTAG TDI is ignored and all inputs low).
 124 1. All pad inputs and sim controlled input (output enables etc.) should be high.
 125 1. All signals should be high.
 126
 127 These test cases are performed by the "jtag_unit_test" with selected JTAG
 128  instructions (SAMPLE or EXTEST), data to send via TDI, and expected TDO data
 129 vector. The TDO and TDI data is compared using asserts.
 130
 131 NOTE: Currently the last test case's TDO data does not match the actual
 132 core/pad signal values. Not sure why the returned TDO is incorrect, however
 133 the signals are correct.
 134
 135 # Pinmux GPIO Block
 136 ## Diagram
 137 [[!img banked_gpio_block.jpg size="600x"]]
 138
 139 *(Diagram is missing the "ie" signal as part of the bundle of signals given to the peripherals, will be updated later)*
 140
 141 ## Explanation
 142 The simple GPIO module is multi-GPIO block integral to the pinmux system.
 143 To make the block flexible, it has a variable number of of I/Os based on an
 144 input parameter.
 145
 146 By default, the block is memory-mapped WB bus GPIO. The CPU
 147 core can just write the configuration word to the GPIO row address. From this
 148 perspective, it is no different to a conventional GPIO block.
 149
 150 ### Bank Select Options
 151 * bank 0 - WB bus has full control (GPIO peripheral)
 152 * bank 1,2,3 - WB bus only controls puen/pden, periphal gets o/oe/i/ie (Not
 153 fully specified how this should be arranged yet)
 154
 155 Bank select however, allows to switch over the control of the GPIO block to
 156 another peripheral. The peripheral will be given sole connectivity to the
 157 o/oe/i/ie signals, while additional parameters such as pull up/down will either
 158 be automatically configured (as the case for I2C), or will be configurable
 159 via the WB bus. *(This has not been implemented yet, so open to discussion)*
 160
 161 ## Configuration Word
 162 After a discussion with Luke on IRC (14th January 2022), new layout of the
 163 8-bit data word for configuring the GPIO (through CSR):
 164
 165 * oe - Output Enable (see the Ericson presentation for the GPIO diagram)
 166 * ie - Input Enable
 167 * puen - Pull-Up resistor enable
 168 * pden - Pull-Down resistor enable
 169 * i/o - When configured as output (oe set), this bit sets/clears output. When
 170 configured as input, shows the current state of input (read-only)
 171 * bank_sel[2:0] - Bank Select (only 4 banks used)
 172
 173 ### Simultaneous/Packed Configuration
 174 To make the configuration more efficient, multiple GPIOs can be configured with
 175 one data word. The number of GPIOs in one "row" is dependent on the width of the
 176 WB data bus.
 177
 178 If for example, the data bus is 64-bits wide, eight GPIO configuration bytes -
 179 and thus eight GPIOs - are configured in one go. There is no way to specify
 180 which GPIO in a row is configured, so the programmer has to keep the current
 181 state of the configuration as part of the code (essentially a shadow register).
 182
 183 The diagram below shows the layout of the configuration byte, and how it fits
 184 within a 64-bit data word.
 185
 186 [[!img gpio_csr_example.jpg size="600x"]]
 187
 188 If the block is created with more GPIOs than can fit in a single data word,
 189 the next set of GPIOs can be accessed by incrementing the address.
 190 For example, if 16 GPIOs are instantiated and 64-bit data bus is used, GPIOs
 191 0-7 are accessed via address 0, whereas GPIOs 8-15 are accessed by address 8
 192 (TODO: DOES ADDRESS COUNT WORDS OR BYTES?)
 193
 194 ## Example Memory Map
 195 [[!img gpio_memory_example.jpg size="600x"]]
 196
 197 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.
 198
 199 64-bit:
 200
 201 * 0x00 - Configure GPIOs  0-7
 202 * 0x01 - Configure GPIOs  8-15
 203
 204 32-bit:
 205
 206 * 0x00 - Configure GPIOs  0-3
 207 * 0x01 - Configure GPIOs  4-7
 208 * 0x02 - Configure GPIOs  8-11
 209 * 0x03 - Configure GPIOs 12-15
 210
 211 ## Sim commands for single GPIO - IN PROGRESS
 212 * gpio_config - Set the CSR (only the first GPIO is currently configured).
 213 * gpio_rd_csr - Read the current CSR state and parse (only first GPIO).
 214 * gpio_rd_input - Read the current input.
 215 * gpio_set_out - Set the output to given value.
 216 * gpio_set_in_pad - Set the input signals for the block (external,
 217 not controlled by WB)
 218 * gpio_rd_out - (TODO)
 219
 220 ## Test
 221 The current test does the following:
 222
 223 * Set the bank select to a random value between 0 and 15 (unless the
 224 "use_random" argument is set to false)
 225 * Set oe (all GPIOs are outputs)
 226 * Set GPIO outputs sequentially
 227 * Set external GPIO inputs sequentially and clear
 228
 229