Documentation/getting_started/gpio.md

   1 # Configuring a mainboard's GPIOs in coreboot
   2
   3 ## Introduction
   4
   5 Every mainboard needs to appropriately configure its General Purpose Inputs /
   6 Outputs (GPIOs). There are many facets of this issue, including which boot
   7 stage a GPIO might need to be configured.
   8
   9 ## Boot stages
  10
  11 Typically, coreboot does most of its non-memory related initialization work in
  12 ramstage, when DRAM is available for use. Hence, the bulk of a mainboard's GPIOs
  13 are configured in this stage. However, some boards might need a few GPIOs
  14 configured before that; think of memory strapping pins which indicate what kind
  15 of DRAM is installed. These pins might need to be read before initializing the
  16 memory, so these GPIOs are then typically configured in bootblock or romstage.
  17
  18 ## Configuration
  19
  20 Most mainboards will have a ``gpio.c`` file in their mainboard directory. This
  21 file typically contains tables which describe the configuration of the GPIO
  22 registers. Since these registers could be different on a per-SoC or per
  23 SoC-family basis, you may need to consult the datasheet for your SoC to find out
  24 how to appropriately set these registers. In addition, some mainboards are
  25 based on a baseboard/variant model, where several variant mainboards may share a
  26 lot of their circuitry and ICs and the commonality between the boards is
  27 collected into a virtual ``baseboard.`` In that case, the GPIOs which are shared
  28 between multiple boards are placed in the baseboard's ``gpio.c`` file, while the
  29 ones that are board-specific go into each variant's ``gpio.c`` file.
  30
  31 ## Intel SoCs
  32
  33 Many newer Intel SoCs share a common IP block for GPIOs, and that commonality
  34 has been taken advantage of in coreboot, which has a large set of macros that
  35 can be used to describe the configuration of each GPIO pad. This file lives in
  36 ``src/soc/intel/common/block/include/intelblocks/gpio_defs.h``.
  37
  38 ### Older Intel SoCs
  39
  40 Baytrail and Braswell, for example, simply expect the mainboard to supply a
  41 callback, `mainboard_get_gpios` which returns an array of `struct soc_gpio`
  42 objects, defining the configuration of each pin.
  43
  44 ### AMD SoCs
  45
  46 Some AMD SoCs use a list of `struct soc_amd_gpio` objects to define the
  47 register values configuring each pin, similar to Intel.
  48
  49 ### Register details
  50
  51 GPIO configuration registers typically control properties such as:
  52 1. Input / Output
  53 2. Pullups / Pulldowns
  54 3. Termination
  55 4. Tx / Rx Disable
  56 5. Which reset signal to use
  57 6. Native Function / IO
  58 7. Interrupts
  59     * IRQ routing (e.g. on x86, APIC, SCI, SMI)
  60     * Edge or Level Triggered
  61     * Active High or Active Low
  62 8. Debouncing
  63
  64 ## Configuring GPIOs for pre-ramstage
  65
  66 coreboot provides for several SoC-specific and mainboard-specific callbacks at
  67 specific points in time, such as bootblock-early, bootblock, romstage entry,
  68 pre-silicon init, pre-RAM init, or post-RAM init. The GPIOs that are
  69 configured in either bootblock or romstage, depending on when they are needed,
  70 are denoted the "early" GPIOs. Some mainboard will use
  71 ``bootblock_mainboard_init()`` to configure their early GPIOs, and this is
  72 probably a good place to start. Many mainboards will declare their GPIO
  73 configuration as structs, i.e. (Intel),
  74
  75 ```C
  76 struct pad_config {
  77     /* offset of pad within community */
  78         int             pad;
  79     /* Pad config data corresponding to DW0, DW1,.... */
  80         uint32_t        pad_config[GPIO_NUM_PAD_CFG_REGS];
  81 };
  82 ```
  83
  84 and will usually place these in an array, one for each pad to be configured.
  85 Mainboards using Intel SoCs can use a library which combines common
  86 configurations together into a set of macros, e.g.,
  87
  88 ```C
  89     /* Native function configuration */
  90     #define PAD_CFG_NF(pad, pull, rst, func)
  91     /* General purpose output, no pullup/down. */
  92     #define PAD_CFG_GPO(pad, val, rst)
  93     /* General purpose output, with termination specified */
  94     #define PAD_CFG_TERM_GPO(pad, val, pull, rst)
  95     /* General purpose output, no pullup/down. */
  96     #define PAD_CFG_GPO_GPIO_DRIVER(pad, val, rst, pull)
  97     /* General purpose input */
  98     #define PAD_CFG_GPI(pad, pull, rst)
  99 ```
 100 etc.
 101
 102 ## Configuring GPIOs for ramstage and beyond...
 103
 104 In ramstage, most mainboards will configure the rest of their GPIOs for the
 105 function they will be performing while the device is active. The goal is the
 106 same as above in bootblock; another ``static const`` array is created, and the
 107 rest of the GPIO registers are programmed.
 108
 109 In the baseboard/variant model described above, the baseboard will provide the
 110 configuration for the GPIOs which are configured identically between variants,
 111 and will provide a mechanism for a variant to override the baseboard's
 112 configuration. This is usually done via two tables: the baseboard table and the
 113 variant's override table.
 114
 115 This configuration is often hooked into the mainboard's `enable_dev` callback,
 116 defined in its `struct chip_operations`.
 117
 118 ## Unconnected and unused pads
 119
 120 In digital electronics, it is generally recommended to tie unconnected GPIOs to
 121 a defined signal like VCC or GND by setting their direction to output, adding an
 122 external pull resistor or configuring an internal pull resistor. This is done to
 123 prevent floating of the pin state, which can cause various issues like EMI,
 124 higher power usage due to continuously switching logic, etc.
 125
 126 On Intel PCHs from Sunrise Point onwards, termination of unconnected GPIOs is
 127 explicitly not required, when the input buffer is disabled by setting the bit
 128 `GPIORXDIS` which effectively disconnects the pad from the internal logic. All
 129 pads defaulting to GPIO mode have this bit set. However, in the mainboard's
 130 GPIO configuration the macro `PAD_NC(pad, NONE)` can be used to explicitly
 131 configure a pad as unconnected.
 132
 133 In case there are no schematics available for a board and the vendor set a
 134 pad to something like `GPIORXDIS=1`, `GPIOTXDIS=1` with an internal pull
 135 resistor, an unconnected or otherwise unused pad can be assumed. In this case it
 136 is recommended to keep the pull resistor, because the external circuit might
 137 rely on it.
 138
 139 Unconnected pads defaulting to a native function (input and output) usually
 140 don't need to be configured as GPIO with the `GPIORXDIS` bit set. For clarity
 141 and documentation purpose the macro may be used as well for them.
 142
 143 Some pads configured as native input function explicitly require external
 144 pull-ups when being unused, according to the PDGs:
 145 - eDP_HPD
 146 - SMBCLK/SMBDATA
 147 - SML0CLK/SML0DATA/SML0ALERT
 148 - SATAGP*
 149
 150 When the board was designed correctly, nothing needs to be done for them
 151 explicitly, while using `PAD_NC(pad, NONE)` can act as documentation. If such a
 152 pad is missing the external pull resistor due to bad board design, the pad
 153 should be configured with `PAD_NC(pad, NONE)` anyway to disconnect it
 154 internally.
 155
 156 ## Potential issues (gotchas!)
 157
 158 There are a couple of configurations that you need to especially careful about,
 159 as they can have a large impact on your mainboard.
 160
 161 The first is configuring a pin as an output, when it was designed to be an
 162 input. There is a real risk in this case of short-circuiting a component which
 163 could cause catastrophic failures, up to and including your mainboard!
 164
 165 ### Intel SoCs
 166
 167 As per Intel Platform Controller Hub (PCH) EDS since Skylake, a GPIO PAD register
 168 supports four different types of GPIO reset as:
 169
 170 ```eval_rst
 171 +------------------------+----------------+-------------+-------------+
 172 |                        |                |         PAD Reset ?       |
 173 + PAD Reset Config       + Platform Reset +-------------+-------------+
 174 |                        |                |     GPP     |     GPD     |
 175 +========================+================+=============+=============+
 176 | | 00 - Power Good      |  Warm Reset    |     N       |    N        |
 177 | | (GPP: RSMRST,        +----------------+-------------+-------------+
 178 | | GPD: DSW_PWROK)      |  Cold Reset    |     N       |    N        |
 179 |                        +----------------+-------------+-------------+
 180 |                        |  S3/S4/S5      |     N       |    N        |
 181 |                        +----------------+-------------+-------------+
 182 |                        |  Global Reset  |     N       |    N        |
 183 |                        +----------------+-------------+-------------+
 184 |                        |  Deep Sx       |     Y       |    N        |
 185 |                        +----------------+-------------+-------------+
 186 |                        |  G3            |     Y       |    Y        |
 187 +------------------------+----------------+-------------+-------------+
 188 | 01 - Deep              |  Warm Reset    |     Y       |    Y        |
 189 |                        +----------------+-------------+-------------+
 190 |                        |  Cold Reset    |     Y       |    Y        |
 191 |                        +----------------+-------------+-------------+
 192 |                        |  S3/S4/S5      |     N       |    N        |
 193 |                        +----------------+-------------+-------------+
 194 |                        |  Global Reset  |     Y       |    Y        |
 195 |                        +----------------+-------------+-------------+
 196 |                        |  Deep Sx       |     Y       |    Y        |
 197 |                        +----------------+-------------+-------------+
 198 |                        |  G3            |     Y       |    Y        |
 199 +------------------------+----------------+-------------+-------------+
 200 | 10 - Host Reset/PLTRST |  Warm Reset    |     Y       |    Y        |
 201 |                        +----------------+-------------+-------------+
 202 |                        |  Cold Reset    |     Y       |    Y        |
 203 |                        +----------------+-------------+-------------+
 204 |                        |  S3/S4/S5      |     Y       |    Y        |
 205 |                        +----------------+-------------+-------------+
 206 |                        |  Global Reset  |     Y       |    Y        |
 207 |                        +----------------+-------------+-------------+
 208 |                        |  Deep Sx       |     Y       |    Y        |
 209 |                        +----------------+-------------+-------------+
 210 |                        |  G3            |     Y       |    Y        |
 211 +------------------------+----------------+-------------+-------------+
 212 | | 11 - Resume Reset    |  Warm Reset    |     n/a     |    N        |
 213 | | (GPP: Reserved,      +----------------+-------------+-------------+
 214 | | GPD: RSMRST)         |  Cold Reset    |     n/a     |    N        |
 215 |                        +----------------+-------------+-------------+
 216 |                        |  S3/S4/S5      |     n/a     |    N        |
 217 |                        +----------------+-------------+-------------+
 218 |                        |  Global Reset  |     n/a     |    N        |
 219 |                        +----------------+-------------+-------------+
 220 |                        |  Deep Sx       |     n/a     |    Y        |
 221 |                        +----------------+-------------+-------------+
 222 |                        |  G3            |     n/a     |    Y        |
 223 +------------------------+----------------+-------------+-------------+
 224 ```
 225
 226 Each GPIO Community has a Pad Configuration Lock register for a GPP allowing locking
 227 specific register fields in the PAD configuration register.
 228
 229 The Pad Config Lock registers reset type is default hardcoded to **Power Good** and
 230 it's **not** configurable by GPIO PAD DW0.PadRstCfg. Hence, it may appear that for a GPP,
 231 the Pad Reset Config (DW0 Bit 31) is configured differently from `Power Good`.
 232
 233 This would create confusion where the Pad configuration is returned to its `default`
 234 value but remains `locked`, this would prevent software to reprogram the GPP.
 235 Additionally, this means software can't rely on GPIOs being reset by PLTRST# or Sx entry.
 236
 237 Hence, as per GPIO BIOS Writers Guide (BWG) it's recommended to change the Pad Reset
 238 Configuration for lock GPP as `Power Good` so that pad configuration and lock bit are
 239 always in sync and can be reset at the same time.
 240
 241 ## Soft Straps
 242
 243 Soft straps, that can be configured by the vendor in the Intel Flash Image Tool
 244 (FIT), can influence some pads' default mode. It is possible to select either a
 245 native function or GPIO mode for some pads on non-server SoCs, while on server
 246 SoCs most pads can be controlled. Thus, it is generally recommended to always
 247 configure all pads and don't just rely on the defaults mentioned in the
 248 datasheet(s) which might not reflect what the vendor configured.
 249
 250 ## Pad-related known issues and workarounds
 251
 252 ### LPC_CLKRUNB blocks S0ix states when board uses eSPI
 253
 254 When using eSPI, the pad implementing `LPC_CLKRUNB` must be set to GPIO mode.
 255 Other pin settings i.e. Rx path enable/disable, Tx path enable/disable, pull up
 256 enable/disable etc are ignored. Leaving this pin in native mode will keep the
 257 LPC Controller awake and prevent S0ix entry. This issues is know at least on
 258 Apollolake and Geminilake.