docs: correct and rewrite documentation regarding n/c / unused pads

Intel PDGs starting from Skylake / Sunrise Point state that, different
from the general recommendation in digital electronics, unconnected
GPIOs defaulting to GPIO mode do explicitly not require termination.

The reason for this is, that these GPIOs have the `GPIORXDIS` bit set,
which effectively disconnects the pad from the internal logic by
disabling the input buffer.

This bit - besides `GPIOTXDIS` - can also be set explicitly by using
the gpio macro `PAD_NC(pad, NONE)`.

In some cases, a pull resistor may be required due to bad board design
or when a vendor sets the RX/TX disable bits together with a pull
resistor and schematics are not available to check if the pad is really
unconnected or just unused. In this case the pull resistor should be
kept.

Pads defaulting to native functions usually don't need special handling.
However, when pads requiring external pull-ups are missing these due to
bad board design, they should be configured with `PAD_NC` to disconnect
them internally.

Rewrite the documentation to reflect these new findings.

Also clarify the comment in soc/intel gpio code accordingly.

Change-Id: Id01b197ebe8f2b8bb4ecf3d119ec2298b26d9be0
Signed-off-by: Michael Niewöhner <foss@mniewoehner.de>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/52139
Reviewed-by: Tim Crawford <tcrawford@system76.com>
Reviewed-by:  Felix Singer <felixsinger@posteo.net>
Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>

1 files changed, 38 insertions, 6 deletions

diff --git a/Documentation/getting_started/gpio.md b/Documentation/getting_started/gpio.md
index d4e8ca7df4..19e74eec11 100644
--- a/Documentation/getting_started/gpio.md
+++ b/Documentation/getting_started/gpio.md
@@ -115,6 +115,44 @@ variant's override table.
 This configuration is often hooked into the mainboard's `enable_dev` callback,
 defined in its `struct chip_operations`.
 
+## Unconnected and unused pads
+
+In digital electronics, it is generally recommended to tie unconnected GPIOs to
+a defined signal like VCC or GND by setting their direction to output, adding an
+external pull resistor or configuring an internal pull resistor. This is done to
+prevent floating of the pin state, which can cause various issues like EMI,
+higher power usage due to continuously switching logic, etc.
+
+On Intel PCHs from Sunrise Point onwards, termination of unconnected GPIOs is
+explicitly not required, when the input buffer is disabled by setting the bit
+`GPIORXDIS` which effectively disconnects the pad from the internal logic. All
+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.
+
+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:
+- eDP_HPD
+- SMBCLK/SMBDATA
+- SML0CLK/SML0DATA/SML0ALERT
+- SATAGP*
+
+If 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
+internally.
+
 ## Potential issues (gotchas!)
 
 There are a couple of configurations that you need to especially careful about,
@@ -124,12 +162,6 @@ 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.
-
 ## Pad-related known issues and workarounds
 
 ### LPC_CLKRUNB blocks S0ix states when board uses eSPI