1# Configuring a mainboard's GPIOs in coreboot 2 3## Introduction 4 5Every mainboard needs to appropriately configure its General Purpose Inputs / 6Outputs (GPIOs). There are many facets of this issue, including which boot 7stage a GPIO might need to be configured. 8 9## Boot stages 10 11Typically, coreboot does most of its non-memory related initialization work in 12ramstage, when DRAM is available for use. Hence, the bulk of a mainboard's GPIOs 13are configured in this stage. However, some boards might need a few GPIOs 14configured before that; think of memory strapping pins which indicate what kind 15of DRAM is installed. These pins might need to be read before initializing the 16memory, so these GPIOs are then typically configured in bootblock or romstage. 17 18## Configuration 19 20Most mainboards will have a ``gpio.c`` file in their mainboard directory. This 21file typically contains tables which describe the configuration of the GPIO 22registers. Since these registers could be different on a per-SoC or per 23SoC-family basis, you may need to consult the datasheet for your SoC to find out 24how to appropriately set these registers. In addition, some mainboards are 25based on a baseboard/variant model, where several variant mainboards may share a 26lot of their circuitry and ICs and the commonality between the boards is 27collected into a virtual ``baseboard.`` In that case, the GPIOs which are shared 28between multiple boards are placed in the baseboard's ``gpio.c`` file, while the 29ones that are board-specific go into each variant's ``gpio.c`` file. 30 31## Intel SoCs 32 33Many newer Intel SoCs share a common IP block for GPIOs, and that commonality 34has been taken advantage of in coreboot, which has a large set of macros that 35can 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 40Baytrail and Braswell, for example, simply expect the mainboard to supply a 41callback, `mainboard_get_gpios` which returns an array of `struct soc_gpio` 42objects, defining the configuration of each pin. 43 44### AMD SoCs 45 46Some AMD SoCs use a list of `struct soc_amd_gpio` objects to define the 47register values configuring each pin, similar to Intel. 48 49### Register details 50 51GPIO configuration registers typically control properties such as: 521. Input / Output 532. Pullups / Pulldowns 543. Termination 554. Tx / Rx Disable 565. Which reset signal to use 576. Native Function / IO 587. Interrupts 59 * IRQ routing (e.g. on x86, APIC, SCI, SMI) 60 * Edge or Level Triggered 61 * Active High or Active Low 628. Debouncing 63 64## Configuring GPIOs for pre-ramstage 65 66coreboot provides for several SoC-specific and mainboard-specific callbacks at 67specific points in time, such as bootblock-early, bootblock, romstage entry, 68pre-silicon init, pre-RAM init, or post-RAM init. The GPIOs that are 69configured in either bootblock or romstage, depending on when they are needed, 70are denoted the "early" GPIOs. Some mainboard will use 71``bootblock_mainboard_init()`` to configure their early GPIOs, and this is 72probably a good place to start. Many mainboards will declare their GPIO 73configuration as structs, i.e. (Intel), 74 75```C 76struct 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 84and will usually place these in an array, one for each pad to be configured. 85Mainboards using Intel SoCs can use a library which combines common 86configurations 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``` 100etc. 101 102## Configuring GPIOs for ramstage and beyond... 103 104In ramstage, most mainboards will configure the rest of their GPIOs for the 105function they will be performing while the device is active. The goal is the 106same as above in bootblock; another ``static const`` array is created, and the 107rest of the GPIO registers are programmed. 108 109In the baseboard/variant model described above, the baseboard will provide the 110configuration for the GPIOs which are configured identically between variants, 111and will provide a mechanism for a variant to override the baseboard's 112configuration. This is usually done via two tables: the baseboard table and the 113variant's override table. 114 115This configuration is often hooked into the mainboard's `enable_dev` callback, 116defined in its `struct chip_operations`. 117 118## Unconnected and unused pads 119 120In digital electronics, it is generally recommended to tie unconnected GPIOs to 121a defined signal like VCC or GND by setting their direction to output, adding an 122external pull resistor or configuring an internal pull resistor. This is done to 123prevent floating of the pin state, which can cause various issues like EMI, 124higher power usage due to continuously switching logic, etc. 125 126On Intel PCHs from Sunrise Point onwards, termination of unconnected GPIOs is 127explicitly not required, when the input buffer is disabled by setting the bit 128`GPIORXDIS` which effectively disconnects the pad from the internal logic. All 129pads defaulting to GPIO mode have this bit set. However, in the mainboard's 130GPIO configuration the macro `PAD_NC(pad, NONE)` can be used to explicitly 131configure a pad as unconnected. 132 133In case there are no schematics available for a board and the vendor set a 134pad to something like `GPIORXDIS=1`, `GPIOTXDIS=1` with an internal pull 135resistor, an unconnected or otherwise unused pad can be assumed. In this case it 136is recommended to keep the pull resistor, because the external circuit might 137rely on it. 138 139Unconnected pads defaulting to a native function (input and output) usually 140don't need to be configured as GPIO with the `GPIORXDIS` bit set. For clarity 141and documentation purpose the macro may be used as well for them. 142 143Some pads configured as native input function explicitly require external 144pull-ups when being unused, according to the PDGs: 145- eDP_HPD 146- SMBCLK/SMBDATA 147- SML0CLK/SML0DATA/SML0ALERT 148- SATAGP* 149 150When the board was designed correctly, nothing needs to be done for them 151explicitly, while using `PAD_NC(pad, NONE)` can act as documentation. If such a 152pad is missing the external pull resistor due to bad board design, the pad 153should be configured with `PAD_NC(pad, NONE)` anyway to disconnect it 154internally. 155 156## Potential issues (gotchas!) 157 158There are a couple of configurations that you need to especially careful about, 159as they can have a large impact on your mainboard. 160 161The first is configuring a pin as an output, when it was designed to be an 162input. There is a real risk in this case of short-circuiting a component which 163could cause catastrophic failures, up to and including your mainboard! 164 165### Intel SoCs 166 167As per Intel Platform Controller Hub (PCH) EDS since Skylake, a GPIO PAD register 168supports 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 226Each GPIO Community has a Pad Configuration Lock register for a GPP allowing locking 227specific register fields in the PAD configuration register. 228 229The Pad Config Lock registers reset type is default hardcoded to **Power Good** and 230it's **not** configurable by GPIO PAD DW0.PadRstCfg. Hence, it may appear that for a GPP, 231the Pad Reset Config (DW0 Bit 31) is configured differently from `Power Good`. 232 233This would create confusion where the Pad configuration is returned to its `default` 234value but remains `locked`, this would prevent software to reprogram the GPP. 235Additionally, this means software can't rely on GPIOs being reset by PLTRST# or Sx entry. 236 237Hence, as per GPIO BIOS Writers Guide (BWG) it's recommended to change the Pad Reset 238Configuration for lock GPP as `Power Good` so that pad configuration and lock bit are 239always in sync and can be reset at the same time. 240 241## Soft Straps 242 243Soft 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 245native function or GPIO mode for some pads on non-server SoCs, while on server 246SoCs most pads can be controlled. Thus, it is generally recommended to always 247configure all pads and don't just rely on the defaults mentioned in the 248datasheet(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 254When using eSPI, the pad implementing `LPC_CLKRUNB` must be set to GPIO mode. 255Other pin settings i.e. Rx path enable/disable, Tx path enable/disable, pull up 256enable/disable etc are ignored. Leaving this pin in native mode will keep the 257LPC Controller awake and prevent S0ix entry. This issues is know at least on 258Apollolake and Geminilake. 259