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
  17 The tasks initially set out by Luke in 2019 (bug 50 description):
  18
  19 * peripheral multiplexing
  20 * SoC-to-peripheral interconnect auto-generation
  21 * auto-creation of peripheral memory-address locations and suitable linux header
  22 * auto-creation of linux kernel header files for GPIO pinmux layout
  23 * auto-creation of IO ring corona for ASICs
  24 * auto-generation and allocation of IRQs and IRQ connectivity
  25 * auto-generation of Technical Reference Manual sections
  26
  27 # Definitions
  28 Useful definitions required for understanding the undertaken tasks.
  29 See the main page for more indepth explanation on IO Pads, JTAG.
  30
  31 ## JTAG Boundary Scan (BS) chain
  32 Essentially a combination of a multiplexer and shift register.
  33 The BS chain allows core signals to connect straight to the ASIC pads,
  34 or allow an external JTAG device to individually control the core inputs
  35 and pad outputs via the shift register.
  36 ## Core
  37 Refers to peripherals coming from the ASIC (I2C, SPI, UART, GPIO, etc.).
  38  Core signals come from the the actual HDL of the peripherals,
  39 and connect to the JTAG Boundary Scan chain.
  40 ## Pad/s
  41 Refers to the ASIC pads which are routed out to the outside world.
  42 These pads are what a chip user can interact with directly (for good or bad...).
  43 ## Pinmux
  44 Pin multiplexer allows ASIC pads to support a range of functions
  45 (although only one at a time per pad).
  46 Each function is allocated to a "bank", and the selected bank
  47 can be configured by the user.
  48
  49 A pinmux is an absolute must when the amount of functionality
  50 (or peripheral signals) greatly exceed the available number
  51 of pins on a package.
  52 Also, pinmuxing allows to select packages with smaller pincounts,
  53 thus producing cheaper (and higher yield) chips.
  54
  55 For example: A pad can be I2C SDA on bank0, a GPIO on bank1,
  56 a UART RX on bank2. By setting the bank select to 1,
  57 the pad can act as a GPIO (input or output).
  58
  59 # Progress on code in "testing_stage1.py":
  60 ## Dummy pinset
  61 A test pinset that specifies which peripherals are to be added.
  62 In this case, four GPIOs, one UART,  one I2C.
  63
  64 ## Resource signal creation
  65 "create_resources()" function parses a given pinset
  66 (the dummy one in this case), and creates a resources list containing
  67 the peripherals (with nmigen subsignals such as sda, gpio_o/i/oe etc.).
  68
  69 Within this function, Resource.family(), JTAGResource(), UARTResource(),
  70 I2CResource() create the signals with correct direction (input/output/inout).
  71
  72 The returned "resources" list is used in....?
  73
  74 ## Blinker test module
  75 Contains a JTAG module from Chips4Makers (c4m-jtag).
  76 The JTAG module is the backbone of the Blinker test module,
  77 because from it the Boundary Scan chain is produced.
  78
  79 By using "jtag.request('i2c')" (or 'uart', 'gpio', etc.),
  80 the Boundary Scan chain is extended. The JTAG module then provides subsignals
  81 to connect to core as well as pad side.
  82
  83 I2C and UART are connected in a loopback configuration (input to output),
  84 allowing to test both signals at the same time. The GPIO output is an XOR of
  85 the GPIO input, and a test input controlled by sim (gpio_o_test).
  86 The oe signals are controlled by the sim using test input registers.
  87
  88 ## ASIC Platform
  89 Performs some magic with file template code.
  90 Resource list (dummy pinset) provided at instantiation is added to the internal
  91 resource list (?).
  92 More magic with configuring pins that are inputs/outputs/tristates.
  93 Core/Pad pins are connected to the appropriate JTAG pins.
  94
  95 ## Unit tests
  96 ### GPIO test
  97 For every output configuration of four GPIOs (16), go through each input
  98 configuration.
  99 Assert that signal states match the function in the Blinker class.
 100
 101 ### UART test
 102 Check TX matches RX when high and low.
 103
 104 ### I2C test
 105 Check SDA out and SCL out match SDA/SCL in.
 106 Check oe's by driving the test registers.
 107
 108 ### JTAG test BS chain
 109 The unit test has four test cases, two before the peripherals are exercised,
 110 and two after:
 111
 112 1. Send 0xFFFFF via TDI in EX_TEST mode
 113 1. Send 0xFFFFF via TDO in BS_SAMPLE mode
 114 1. Send 0x00000 via TDI in EX_TEST mode
 115 1. Send 0x00000 via TDI in BS_SAMPLE mode
 116
 117 The expected results are:
 118
 119 1. All core outputs high (as these set by JTAG BS), all pad inputs low
 120 (not asserted yet)
 121 1. All signals should be low (as JTAG TDI is ignored and all inputs low).
 122 1. All pad inputs and sim controlled input (output enables etc.) should be high.
 123 1. All signals should be high.
 124
 125 These test cases are performed by the "jtag_unit_test" with selected JTAG
 126  instructions (SAMPLE or EXTEST), data to send via TDI, and expected TDO data
 127 vector. The TDO and TDI data is compared using asserts.
 128
 129 NOTE: Currently the last test case's TDO data does not match the actual
 130 core/pad signal values. Not sure why the returned TDO is icorrect, however
 131 the signals are correct.
 132
 133 # Simple GPIO extension
 134 ## Explanation
 135 The code from soc repo was taken and is being extended to support full gpio
 136 capability.
 137
 138 The simple GPIO module has a parameter specifying the number of I/O lines.
 139 For configuration, oe and bank select (capped at 4-bits or 16 banks, probably
 140 plenty for now) are available.
 141
 142 For simplicity, only one bank select parameter for the *WHOLE* GPIO block was
 143 implemented (I wasn't able to get an array of signals working with the list()
 144 function).
 145
 146 For separate access of outputs or input registers, the two bits of the second
 147 byte of the address have been used.
 148 As a result this simple block is limited to 256 GPIOs (which is probably fine).
 149
 150 ## Address map
 151
 152 * 0x0Y - Access (R/W) CSR of GPIO #Y
 153 * 0x1Y - Access (R/W) output of GPIO #Y
 154 * 0x2Y - Access (R) input of GPIO #Y
 155
 156 By using the functions mentioned below, the user doesn't need to know the extra
 157 addresses, just use "gpio_rd_input" etc. and the function will add the offset.
 158
 159 ## Configuration Word
 160 The proposed layout of the 16-bit data word for configuring the GPIO (through
 161 CSR):
 162
 163 * 0 0 0 INPUT | bank_select[3:0] | 0 PDEN PUEN ODEN | 0 IEN OE OUTPUT
 164
 165 (This layout is not fixed in stone, and is trivial to update if there are better
 166 proposals.)
 167
 168 * Bank select switches which bank the GPIO is connected to (*I'm not sure exactly
 169 what the architecture is meant to be, so this will probably change*)
 170 * PDEN and PUEN are pull-up/down enables, ODEN is open-drain output enable.
 171 * IEN and OEN are input/output path enables respectively (see the Ericson
 172 presentation for the GPIO diagram).
 173 * OUTPUT is the value driven by the output (R/W), INPUT is what's coming in (R).
 174
 175 When reading the CSR (default GPIO address), the user will receive everything:
 176 configuration, current input, and output states. The input/output states can
 177 also be queried separately if the address offsets are used.
 178
 179 ## Sim commands for single GPIO
 180 * gpio_configure - Set the CSR (only oe and bank select at the moment).
 181 * gpio_rd_csr - Read the current CSR state and parse (TODO).
 182 * gpio_rd_input - Read the current input.
 183 * gpio_set_out - Set the output to given value.
 184 * gpio_set_in_pad - Set the input signals for the block (external,
 185 not controlled by WB)
 186 * gpio_rd_out - (TODO)
 187
 188 ## Test
 189 The current test does the following:
 190
 191 * Set the bank select to a random value between 0 and 15 (unless the
 192 "use_random" argument is set to false)
 193 * Set oe (all GPIOs are outputs)
 194 * Set GPIO outputs sequentially
 195 * Set external GPIO inputs sequentially and clear
 196
 197 No asserts have been added yet as I was still developing the logic and the sim
 198 functions.
 199
 200 *Before I make anymore updates, please let me know if this GPIO block is heading
 201 in the right direction.*