Change in coreboot[master]: documentation: Add documentation on setting up mainboard GPIOs
Tim Wawrzynczak has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/37802 )
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
documentation: Add documentation on setting up mainboard GPIOs
The new documentation describes typical ways that mainboards will set up their GPIOs, as well as the distinction between "early" and "normal" GPIOs. It also describes the typical properties that GPIO configuration will cover.
Change-Id: I279eec4ed2bb0248a2bdb363fb73b40b8272267f Signed-off-by: Tim Wawrzynczak twawrzynczak@chromium.org --- A Documentation/gpio.md 1 file changed, 120 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/02/37802/1
diff --git a/Documentation/gpio.md b/Documentation/gpio.md new file mode 100644 index 0000000..9ce0635 --- /dev/null +++ b/Documentation/gpio.md @@ -0,0 +1,120 @@ +# Configuring a mainboard's GPIOs in coreboot + +## Introduction + +Every mainboard needs to appropriately configure its General Purpose Inputs / +Outputs (GPIOs). There are many facets of this issue, including which boot +stage a GPIO might need to be configured. + +## Boot stages + +Typically, coreboot does most of its non-memory related initialization work in +ramstage, when DRAM is available for use. Hence, the bulk of a mainboard's +GPIOs are configured in this stage. However, some boards might need a few GPIOs +configured before that; think of memory strapping pins which indicate what kind +of DRAM is installed. These pins might need to be read before an SoC's memory +training step, so these GPIOs are then typically configured in bootblock or +romstage. + +## Configuration + +Most mainboards will have a ``gpio.c`` file in their mainboard directory. This +file typically contains tables which describe the configuration of the GPIO +registers. Since these registers could be different on a per-SoC or per +SoC-family basis, you may need to consult the datasheet for your SoC to find out +how to appropriately set these registers. In addition, some mainboards are +based on a baseboard/variant model, where several variant mainboards may share a +lot of their circuitry and ICs and the commonality between the boards is +collected into a virtual ``baseboard.`` In that case, the GPIOs which are shared +between multiple boards are placed in the baseboard's ``gpio.c` file, while the +ones that are board-specific go into each variant's ``gpio.c`` file. + +## Intel SoCs + +Many newer Intel SoCs share a common IP block for GPIOs, and that commonality +has been taken advantage of in coreboot, which has a large set of macros that +can be used to describe the configuration of each GPIO pad. This file lives in +``src/soc/intel/common/block/include/intelblocks/gpio_defs.h``. + +### Older Intel SoCs +Baytrail and Braswell, for example, simply expect the mainboard to supply a +callback, `mainboard_get_gpios` which returns a list of `struct soc_gpio` +objects, defining the configuration of each pin. + +### AMD SoCs +Some AMD SoCs use a list of `struct soc_amd_gpio` objects to define the +register values configuring each pin, similar to Intel. + +### Register details + +GPIO configuration registers typically control properties such as: +1. Input / Output +2. Pullups / Pulldowns +3. Termination +4. Tx / Rx Disable +5. Which reset signal to use +6. Native Function / IO +7. Interrupts + * IRQ routing (e.g. on x86, APIC, SCI, SMI) + * Edge or Level Triggered + * Active High or Active Low +8. Debouncing + +## Configuring GPIOs for pre-ramstage + +coreboot provides for several SoC-specific and mainboard-specific callbacks at +specific points in time, such as bootblock-early, bootblock, romstage entry, +pre-silicon init, pre-RAM init, post-RAM init, etc. The GPIOs that are +configured in either bootblock or romstage, depending on when they are needed, +are denoted the "early" GPIOs. Some mainboard will use +``bootblock_mainboard_init()`` to configure their early GPIOs, and this is +probably a good place to start. Many mainboards will declare their GPIO +configuration as structs, i.e. (Intel), + +```C +struct pad_config { + /* offset of pad within community */ + int pad; + /* Pad config data corresponding to DW0, DW1,.... */ + uint32_t pad_config[GPIO_NUM_PAD_CFG_REGS]; +}; +``` + +and will usually place these in an array, one for each pad to be configured. +Intel SoCs can use a library which combines common configurations together +into a set of macros, e.g., + +```C + /* Native function configuration */ + #define PAD_CFG_NF(pad, pull, rst, func) + /* + * Set native function with RX Level/Edge configuration and disable + * input/output buffer if necessary + */ + #define PAD_CFG_NF_BUF_TRIG(pad, pull, rst, func, bufdis, trig) + /* General purpose output, no pullup/down. */ + #define PAD_CFG_GPO(pad, val, rst) + /* General purpose output, with termination specified */ + #define PAD_CFG_TERM_GPO(pad, val, pull, rst) + /* General purpose output, no pullup/down. */ + #define PAD_CFG_GPO_GPIO_DRIVER(pad, val, rst, pull) + /* General purpose input */ + #define PAD_CFG_GPI(pad, pull, rst) +``` +etc. + +## Configuring GPIOs for ramstage and beyond... + +In ramstage, most mainboards will configure the rest of their GPIOs for the +function they will be performing while the device is active. The goal is the +same as above in bootblock; another ``static const`` array is created, and the +rest of the GPIO registers are programmed. + +In the baseboard/variant model described above, the baseboard will provide the +configuration for the GPIOs which are configured identically between variants, +and will provide a mechanism for a variant to override the baseboard's +configuration. This is usually done via two tables: the baseboard table and the +variant's override table. + +This configuration is often hooked into the mainboard's `enable_dev` callback, +defined in its `struct chip_operations`.
Justin TerAvest has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37802 )
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
Patch Set 1:
(4 comments)
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md File Documentation/gpio.md:
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md@40 PS1, Line 40: Baytrail and Braswell, for example, simply expect the mainboard to supply a nit: need blank line after markdown header lines
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md@67 PS1, Line 67: pre-silicon init, pre-RAM init, post-RAM init, etc. The GPIOs that are you can drop the etc here
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md@84 PS1, Line 84: Intel SoCs can use a library which combines common configurations together Mainboards using Intel SoCs?
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md@119 PS1, Line 119: This configuration is often hooked into the mainboard's `enable_dev` callback, Is this not consistent across all boards? Maybe we should make it uniform across boards.
Patrick Rudolph has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37802 )
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
Patch Set 1:
(1 comment)
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md File Documentation/gpio.md:
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md@1 PS1, Line 1: # Configuring a mainboard's GPIOs in coreboot you need to reference this file from an existing markdown
Tim Wawrzynczak has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37802 )
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
Patch Set 1:
(5 comments)
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md File Documentation/gpio.md:
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md@1 PS1, Line 1: # Configuring a mainboard's GPIOs in coreboot
you need to reference this file from an existing markdown
Oh yes. I'm thinking in the getting_started directory.
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md@40 PS1, Line 40: Baytrail and Braswell, for example, simply expect the mainboard to supply a
nit: need blank line after markdown header lines
Done
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md@67 PS1, Line 67: pre-silicon init, pre-RAM init, post-RAM init, etc. The GPIOs that are
you can drop the etc here
Done
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md@84 PS1, Line 84: Intel SoCs can use a library which combines common configurations together
Mainboards using Intel SoCs?
Done
https://review.coreboot.org/c/coreboot/+/37802/1/Documentation/gpio.md@119 PS1, Line 119: This configuration is often hooked into the mainboard's `enable_dev` callback,
Is this not consistent across all boards? Maybe we should make it uniform across boards.
Some (older?) southbridges have a setup_pch_gpios() function called in romstage or early_init.
Hello Justin TerAvest, Paul Menzel, build bot (Jenkins), Nico Huber, Furquan Shaikh, Patrick Georgi,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/37802
to look at the new patch set (#2).
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
documentation: Add documentation on setting up mainboard GPIOs
The new documentation describes typical ways that mainboards will set up their GPIOs, as well as the distinction between "early" and "normal" GPIOs. It also describes the typical properties that GPIO configuration will cover.
Change-Id: I279eec4ed2bb0248a2bdb363fb73b40b8272267f Signed-off-by: Tim Wawrzynczak twawrzynczak@chromium.org --- A Documentation/getting_started/gpio.md M Documentation/getting_started/index.md 2 files changed, 123 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/02/37802/2
Nico Huber has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37802 )
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
Patch Set 2:
Shouldn't we call it "pin" or "pad" configuration? I know, in coreboot we still refer to it as GPIO config. But it might confuse new people that expect this to be about dedicated GPIO pins.
Also, GPIO is sometimes confused with pins available to the platform user, while in coreboot it's mostly about pins controlled by the firmware.
Angel Pons has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37802 )
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
Patch Set 2: Code-Review+1
(2 comments)
Nice work, thanks!
There's something that is missing and should really be there: what happens when you configure a GPIO as output but is wired as an input? You risk short-circuiting something!
Another risk: setting an unconnected GPIO as an input without any pulls makes it end up floating, which is undesired.
https://review.coreboot.org/c/coreboot/+/37802/2/Documentation/getting_start... File Documentation/getting_started/gpio.md:
https://review.coreboot.org/c/coreboot/+/37802/2/Documentation/getting_start... PS2, Line 15: before an SoC's memory : training step before initializing the memory
https://review.coreboot.org/c/coreboot/+/37802/2/Documentation/getting_start... PS2, Line 42: a list an array
Tim Wawrzynczak has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37802 )
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
Patch Set 2:
(2 comments)
Patch Set 2: Code-Review+1
(2 comments)
Nice work, thanks!
There's something that is missing and should really be there: what happens when you configure a GPIO as output but is wired as an input? You risk short-circuiting something!
Another risk: setting an unconnected GPIO as an input without any pulls makes it end up floating, which is undesired.
That's a good idea, I'll add a section of "gotchas"
https://review.coreboot.org/c/coreboot/+/37802/2/Documentation/getting_start... File Documentation/getting_started/gpio.md:
https://review.coreboot.org/c/coreboot/+/37802/2/Documentation/getting_start... PS2, Line 15: before an SoC's memory : training step
before initializing the memory
Done
https://review.coreboot.org/c/coreboot/+/37802/2/Documentation/getting_start... PS2, Line 42: a list
an array
Done
Hello Justin TerAvest, Angel Pons, Paul Menzel, build bot (Jenkins), Nico Huber, Furquan Shaikh, Patrick Georgi,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/37802
to look at the new patch set (#3).
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
documentation: Add documentation on setting up mainboard GPIOs
The new documentation describes typical ways that mainboards will set up their GPIOs, as well as the distinction between "early" and "normal" GPIOs. It also describes the typical properties that GPIO configuration will cover.
Change-Id: I279eec4ed2bb0248a2bdb363fb73b40b8272267f Signed-off-by: Tim Wawrzynczak twawrzynczak@chromium.org --- A Documentation/getting_started/gpio.md M Documentation/getting_started/index.md 2 files changed, 137 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/02/37802/3
Tim Wawrzynczak has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37802 )
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
Patch Set 3:
Ping! Any other comments?
Justin TerAvest has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/37802 )
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
Patch Set 3: Code-Review+2
Patrick Georgi has submitted this change. ( https://review.coreboot.org/c/coreboot/+/37802 )
Change subject: documentation: Add documentation on setting up mainboard GPIOs ......................................................................
documentation: Add documentation on setting up mainboard GPIOs
The new documentation describes typical ways that mainboards will set up their GPIOs, as well as the distinction between "early" and "normal" GPIOs. It also describes the typical properties that GPIO configuration will cover.
Change-Id: I279eec4ed2bb0248a2bdb363fb73b40b8272267f Signed-off-by: Tim Wawrzynczak twawrzynczak@chromium.org Reviewed-on: https://review.coreboot.org/c/coreboot/+/37802 Tested-by: build bot (Jenkins) no-reply@coreboot.org Reviewed-by: Justin TerAvest teravest@chromium.org --- A Documentation/getting_started/gpio.md M Documentation/getting_started/index.md 2 files changed, 137 insertions(+), 0 deletions(-)
Approvals: build bot (Jenkins): Verified Justin TerAvest: Looks good to me, approved
diff --git a/Documentation/getting_started/gpio.md b/Documentation/getting_started/gpio.md new file mode 100644 index 0000000..26939ce --- /dev/null +++ b/Documentation/getting_started/gpio.md @@ -0,0 +1,136 @@ +# Configuring a mainboard's GPIOs in coreboot + +## Introduction + +Every mainboard needs to appropriately configure its General Purpose Inputs / +Outputs (GPIOs). There are many facets of this issue, including which boot +stage a GPIO might need to be configured. + +## Boot stages + +Typically, coreboot does most of its non-memory related initialization work in +ramstage, when DRAM is available for use. Hence, the bulk of a mainboard's GPIOs +are configured in this stage. However, some boards might need a few GPIOs +configured before that; think of memory strapping pins which indicate what kind +of DRAM is installed. These pins might need to be read before initializing the +memory, so these GPIOs are then typically configured in bootblock or romstage. + +## Configuration + +Most mainboards will have a ``gpio.c`` file in their mainboard directory. This +file typically contains tables which describe the configuration of the GPIO +registers. Since these registers could be different on a per-SoC or per +SoC-family basis, you may need to consult the datasheet for your SoC to find out +how to appropriately set these registers. In addition, some mainboards are +based on a baseboard/variant model, where several variant mainboards may share a +lot of their circuitry and ICs and the commonality between the boards is +collected into a virtual ``baseboard.`` In that case, the GPIOs which are shared +between multiple boards are placed in the baseboard's ``gpio.c` file, while the +ones that are board-specific go into each variant's ``gpio.c`` file. + +## Intel SoCs + +Many newer Intel SoCs share a common IP block for GPIOs, and that commonality +has been taken advantage of in coreboot, which has a large set of macros that +can be used to describe the configuration of each GPIO pad. This file lives in +``src/soc/intel/common/block/include/intelblocks/gpio_defs.h``. + +### Older Intel SoCs + +Baytrail and Braswell, for example, simply expect the mainboard to supply a +callback, `mainboard_get_gpios` which returns an array of `struct soc_gpio` +objects, defining the configuration of each pin. + +### AMD SoCs + +Some AMD SoCs use a list of `struct soc_amd_gpio` objects to define the +register values configuring each pin, similar to Intel. + +### Register details + +GPIO configuration registers typically control properties such as: +1. Input / Output +2. Pullups / Pulldowns +3. Termination +4. Tx / Rx Disable +5. Which reset signal to use +6. Native Function / IO +7. Interrupts + * IRQ routing (e.g. on x86, APIC, SCI, SMI) + * Edge or Level Triggered + * Active High or Active Low +8. Debouncing + +## Configuring GPIOs for pre-ramstage + +coreboot provides for several SoC-specific and mainboard-specific callbacks at +specific points in time, such as bootblock-early, bootblock, romstage entry, +pre-silicon init, pre-RAM init, or post-RAM init. The GPIOs that are +configured in either bootblock or romstage, depending on when they are needed, +are denoted the "early" GPIOs. Some mainboard will use +``bootblock_mainboard_init()`` to configure their early GPIOs, and this is +probably a good place to start. Many mainboards will declare their GPIO +configuration as structs, i.e. (Intel), + +```C +struct pad_config { + /* offset of pad within community */ + int pad; + /* Pad config data corresponding to DW0, DW1,.... */ + uint32_t pad_config[GPIO_NUM_PAD_CFG_REGS]; +}; +``` + +and will usually place these in an array, one for each pad to be configured. +Mainboards using Intel SoCs can use a library which combines common +configurations together into a set of macros, e.g., + +```C + /* Native function configuration */ + #define PAD_CFG_NF(pad, pull, rst, func) + /* + * Set native function with RX Level/Edge configuration and disable + * input/output buffer if necessary + */ + #define PAD_CFG_NF_BUF_TRIG(pad, pull, rst, func, bufdis, trig) + /* General purpose output, no pullup/down. */ + #define PAD_CFG_GPO(pad, val, rst) + /* General purpose output, with termination specified */ + #define PAD_CFG_TERM_GPO(pad, val, pull, rst) + /* General purpose output, no pullup/down. */ + #define PAD_CFG_GPO_GPIO_DRIVER(pad, val, rst, pull) + /* General purpose input */ + #define PAD_CFG_GPI(pad, pull, rst) +``` +etc. + +## Configuring GPIOs for ramstage and beyond... + +In ramstage, most mainboards will configure the rest of their GPIOs for the +function they will be performing while the device is active. The goal is the +same as above in bootblock; another ``static const`` array is created, and the +rest of the GPIO registers are programmed. + +In the baseboard/variant model described above, the baseboard will provide the +configuration for the GPIOs which are configured identically between variants, +and will provide a mechanism for a variant to override the baseboard's +configuration. This is usually done via two tables: the baseboard table and the +variant's override table. + +This configuration is often hooked into the mainboard's `enable_dev` callback, +defined in its `struct chip_operations`. + +## Potential issues (gotchas!) + +There are a couple of configurations that you need to especially careful about, +as they can have a large impact on your mainboard. + +The first is configuring a pin as an output, when it was designed to be an +input. There is a real risk in this case of short-circuiting a component which +could cause catastrophic failures, up to and including your mainboard! + +The other configuration option to watch out for deals with unconnected GPIOs. +If no pullup or pulldown is declared with these, they may end up "floating", +i.e., not at logical high or logical low. This can cause problems such as +unwanted power consumption or not reading the pin correctly, if it was intended +to be strapped. diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md index 52d873e..9b9ac7f 100644 --- a/Documentation/getting_started/index.md +++ b/Documentation/getting_started/index.md @@ -7,3 +7,4 @@ * [Gerrit Guidelines](gerrit_guidelines.md) * [Documentation License](license.md) * [Writing Documentation](writing_documentation.md) +* [Setting up GPIOs](gpio.md)
-
Angel Pons (Code Review) -
Justin TerAvest (Code Review)
-
Nico Huber (Code Review)
-
Patrick Georgi (Code Review)
-
Patrick Rudolph (Code Review)
-
Tim Wawrzynczak (Code Review)