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 icorrect, however
 133 the signals are correct.
 134
 135 # Simple GPIO extension
 136 ## Explanation
 137 The code from soc repo was taken and is being extended to support full gpio
 138 capability.
 139
 140 The simple GPIO module has a parameter specifying the number of I/O lines.
 141 For configuration, oe and bank select (capped at 4-bits or 16 banks, probably
 142 plenty for now) are available.
 143
 144 For simplicity, only one bank select parameter for the *WHOLE* GPIO block was
 145 implemented (I wasn't able to get an array of signals working with the list()
 146 function).
 147
 148 For separate access of outputs or input registers, the two bits of the second
 149 byte of the address have been used.
 150 As a result this simple block is limited to 256 GPIOs (which is probably fine).
 151
 152 ## Address map
 153
 154 * 0x0Y - Access (R/W) CSR of GPIO #Y
 155
 156 ## Configuration Word
 157 After a discussion with Luke on IRC (14th January 21), new layout of the 8-bit
 158 data word for configuring the GPIO (through CSR):
 159
 160 * bank_select[2:0] IO | PDEN PUEN IE OE
 161
 162 (This layout is not fixed in stone, and is trivial to update if there are
 163 better proposals.)
 164
 165 * Bank select switches the peripheral that gets to control the GPIO block.
 166 By default, bank 0 allows full configuration through the Wishbone Bus (from the CPU looks like memory-mapped IO).
 167 <--- TODO: create table of bank select options!
 168 * PDEN and PUEN are pull-up/down enables.
 169 * IE and OE are input/output path enables respectively (see the Ericson
 170 presentation for the GPIO diagram).
 171 * IO either shows the output state (if OE set), or the value of the input
 172 (IE set). To change the output value, write to this bit.
 173
 174 ## Planned Improvement
 175 A planned improvement is to fit multiple GPIO configurations within a single
 176 WB transaction. For a 64-bit wide data bus, 8 GPIOs could be configured
 177 simultaneously.
 178
 179 If the block is created with more GPIOs than can fit in a single data word,
 180 the next set of GPIOs can be accessed by incrementing the address.
 181 For example, if 16 GPIOs are instantiated, GPIOs 0-7 are accessed via
 182 address 0, whereas GPIOs 8-15 are accessed by address 8
 183 (TODO: DOES ADDRESS COUNT WORDS OR BYTES?)
 184
 185 ## Sim commands for single GPIO
 186 * gpio_configure - Set the CSR (only oe and bank select at the moment).
 187 * gpio_rd_csr - Read the current CSR state and parse (TODO).
 188 * gpio_rd_input - Read the current input.
 189 * gpio_set_out - Set the output to given value.
 190 * gpio_set_in_pad - Set the input signals for the block (external,
 191 not controlled by WB)
 192 * gpio_rd_out - (TODO)
 193
 194 ## Test
 195 The current test does the following:
 196
 197 * Set the bank select to a random value between 0 and 15 (unless the
 198 "use_random" argument is set to false)
 199 * Set oe (all GPIOs are outputs)
 200 * Set GPIO outputs sequentially
 201 * Set external GPIO inputs sequentially and clear
 202
 203 No asserts have been added yet as I was still developing the logic and the sim
 204 functions.
 205