docs: add recommendation for gpios regarding soft straps

Soft straps, that can be configured by the vendor in the Intel Flash
Image Tool (FIT), can influence some pads' default state. It is possible
to select either a native function or GPIO mode for some pads on
non-server SoCs, while on server SoCs most pads can be controlled.

Thus, add a recommendation to always configure all pads for a board to
guarantee integrity between different board or vendor firmware revisions
where the soft straps might have been changed.

Change-Id: I33063a3f6a1c9cd5267d85f7da84deb554489a26
Signed-off-by: Michael Niewöhner <foss@mniewoehner.de>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/52297
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>

1 files changed, 16 insertions, 7 deletions

diff --git a/Documentation/getting_started/gpio.md b/Documentation/getting_started/gpio.md
index 19e74eec11..5d5623a5d9 100644
--- a/Documentation/getting_started/gpio.md
+++ b/Documentation/getting_started/gpio.md
@@ -130,24 +130,24 @@ pads defaulting to GPIO mode have this bit set. However, in the mainboard's
 GPIO configuration the macro `PAD_NC(pad, NONE)` can be used to explicitly
 configure a pad as unconnected.
 
-In case there are no schematics available for a board and the vendor sets a pad
-to something like `GPIORXDIS=1`, `GPIOTXDIS=1` with an internal pull resistor,
-an unconnected or otherwise unused pad can be assumed. In this case it is
-recommended to keep the pull resistor, because the external circuit might rely
-on it.
+In case there are no schematics available for a board and the vendor set a
+pad to something like `GPIORXDIS=1`, `GPIOTXDIS=1` with an internal pull
+resistor, an unconnected or otherwise unused pad can be assumed. In this case it
+is recommended to keep the pull resistor, because the external circuit might
+rely on it.
 
 Unconnected pads defaulting to a native function (input and output) usually
 don't need to be configured as GPIO with the `GPIORXDIS` bit set. For clarity
 and documentation purpose the macro may be used as well for them.
 
 Some pads configured as native input function explicitly require external
-pull-ups when unused, according to the PDGs:
+pull-ups when being unused, according to the PDGs:
 - eDP_HPD
 - SMBCLK/SMBDATA
 - SML0CLK/SML0DATA/SML0ALERT
 - SATAGP*
 
-If the board was designed correctly, nothing needs to be done for them
+When the board was designed correctly, nothing needs to be done for them
 explicitly, while using `PAD_NC(pad, NONE)` can act as documentation. If such a
 pad is missing the external pull resistor due to bad board design, the pad
 should be configured with `PAD_NC(pad, NONE)` anyway to disconnect it
@@ -162,6 +162,15 @@ 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!
 
+## Soft Straps
+
+Soft straps, that can be configured by the vendor in the Intel Flash Image Tool
+(FIT), can influence some pads' default mode. It is possible to select either a
+native function or GPIO mode for some pads on non-server SoCs, while on server
+SoCs most pads can be controlled. Thus, it is generally recommended to always
+configure all pads and don't just rely on the defaults mentioned in the
+datasheet(s) which might not reflect what the vendor configured.
+
 ## Pad-related known issues and workarounds
 
 ### LPC_CLKRUNB blocks S0ix states when board uses eSPI