drivers/periph_gpio_ll: Improve documentation

The documentation on the state `GPIO_DISCONNECT` was a bit vague. The
API doc said it should disconnect the GPIO from all peripherals, the
test also tested them for being electrically disconnected.

The documentation in both the test and the API is extended to point out
that a GPIO indeed SHOULD be in high impedance state, but that user
MUST NOT expect that this requested is honored by every implementation
and for every GPIO pin.

In the test it is also pointed out that failing the test for a GPIO
in the `GPIO_DISCONNECT` state being electrically disconnected is for
some pins expected, and that the test should be just run again with
different GPIOs. The test intentionally tests for a feature not provided
by every GPIO pin rather than warning on a failure: The effort to just
flash and run the test again with different GPIOs is relatively low, but
it does confirm correct behavior of the API.

drivers/include/periph/gpio_ll.h

@@ -176,7 +176,13 @@ typedef enum {
      * @brief   Disconnect pin from all peripherals
      *
      * The implementation should aim to reduce power consumption of the pin
-     * when this state is entered, if this is feasible.
+     * when this state is entered, if this is feasible. For pins where it is
+     * possible and sensible, this should electrically disconnect them
+     * (high impedance).
+     *
+     * @warning If a given pin will not only be disconnected from peripherals
+     *          but also enter an high impedance state is implementation
+     *          defined and may differ from pin to pin.
      *
      * @note    Pull resistors can still be requested in this mode. This can be
      *          useful e.g. for keeping an UART TXD pin from emitting noise

tests/periph/gpio_ll/README.md

@@ -19,3 +19,11 @@ GPIO port is set via `PORT_IN`. Both `PORT_IN == PORT_OUT` and
 `PORT_IN != PORT_OUT` is valid. The input pin number within `PORT_IN` are set
 via `PIN_IN_0` and `PIN_IN_1`. `PIN_IN_0` has to be wired to `PIN_OUT_0`, and
 `PIN_IN_1` to `PIN_OUT_1`.
+
+## Expected Failures
+
+Implementations are allowed to not electrically disconnect GPIO pins in state
+`GPIO_DISCONNECT`. The test will however test for pins to be electrically
+disconnected. For every MCU supported by GPIO LL so far at least some pins can
+be electrically disconnected. You might need to change the GPIO pins tested
+if the test for disconnected GPIOs being also electrically disconnected.

tests/periph/gpio_ll/main.c

@@ -470,6 +470,18 @@ static void test_gpio_ll_init(void)
         is_supported = !(gpio_ll_read(port_in) & (1ULL << PIN_IN_0));
         printf_optional("Output can indeed be pulled LOW: %s\n",
                         noyes[is_supported]);
+        /* If this expects fails, try with a different pin. Often pins intended
+         * for use as UART, I2C, or hardware /CS on SPI cannot be configured
+         * as high impedance and will instead remain HIGH. An implementation
+         * is free to work around this e.g. by configuring these pins as
+         * input with the input buffer disabled or as analog input without
+         * routing them to the ADC, or just to restore the reset configuration
+         * and have them high.
+         *
+         * Even though this can fail on some pins, the `expect()` here should
+         * remain. Just test with a different pin that can be configured as
+         * high impedance to confirm that this functionality does work where
+         * supported. */
         expect(is_supported);
     }
     else {
@@ -482,6 +494,10 @@ static void test_gpio_ll_init(void)
         is_supported = (gpio_ll_read(port_in) & (1ULL << PIN_IN_0));
         printf_optional("Output can indeed be pulled HIGH: %s\n",
                         noyes[is_supported]);
+        /* May also fail for some pins, if the reset configuration of the
+         * pin results in LOW output. Do not comment this out, but rather
+         * try with a different pin to confirm that this functionality does
+         * work where supported */
         expect(is_supported);
     }
     else {