From 8c99719f0d9648215748e44ab73c3fa6471a457f Mon Sep 17 00:00:00 2001
From: crasbe <crasbe@gmail.com>
Date: Wed, 4 Jun 2025 15:51:30 +0200
Subject: [PATCH 1/2] drivers/gpio_ll: Add doc about gpio_get_port and
 gpio_get_pin_num

---
 drivers/include/periph/gpio_ll.h | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/drivers/include/periph/gpio_ll.h b/drivers/include/periph/gpio_ll.h
index 95eef47950..787ad278cd 100644
--- a/drivers/include/periph/gpio_ll.h
+++ b/drivers/include/periph/gpio_ll.h
@@ -17,6 +17,15 @@
  * @warning     This API is not stable yet and intended for internal use only
  *              as of now.
  *
+ * # General
+ *
+ * Ports and pin numbers are not always internally defined as the same numbers
+ * that you would expect them to be. Therefore it is highly recommended to call
+ * the low level functions like gpio_ll_init() or gpio_ll_query_conf() with the
+ * gpio_get_port() and gpio_get_pin_num() functions instead of directly setting
+ * port or pin numbers. Using the helper functions will assure reliable
+ * operation on all platforms and GPIO banks.
+ *
  * # Design Goals
  *
  * This API aims to provide low-level access to GPIOs with as little
@@ -821,11 +830,31 @@ static inline void gpio_ll_write(gpio_port_t port, uword_t state);
 
 /**
  * @brief   Extract the `gpio_port_t` from a `gpio_t`
+ *
+ * CPU specific implementation to return the GPIO port for a given
+ * GPIO pin.
+ *
+ * @param[in] pin GPIO pin structure, usually defined with the GPIO_PIN macro
+ *
+ * @return  GPIO port
+ *
  */
 static inline gpio_port_t gpio_get_port(gpio_t pin);
 
 /**
  * @brief   Extract the pin number from a `gpio_t`
+ *
+ * CPU specific implementation to return the internal pin number for a
+ * given GPIO pin.
+ *
+ * @note    The actual, internal pin numbers are not always directly related to
+ *          their name. For example on some microcontrollers as the nRF52,
+ *          the distinction between P0 and P1 pins is made by a bit that is set
+ *          in the pin numbers.
+ *
+ * @param[in] pin GPIO pin structure, usually defined with the GPIO_PIN macro
+ *
+ * @return  Internal pin number
  */
 static inline uint8_t gpio_get_pin_num(gpio_t pin);
 

From 6210aff940ffa5ec1d744bafbb492528a272a07d Mon Sep 17 00:00:00 2001
From: crasbe <crasbe@gmail.com>
Date: Wed, 4 Jun 2025 15:53:08 +0200
Subject: [PATCH 2/2] drivers/gpio: fix doc for gpio_irq_enable

---
 drivers/include/periph/gpio.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/include/periph/gpio.h b/drivers/include/periph/gpio.h
index 7b2a0ba2f8..61d980aeff 100644
--- a/drivers/include/periph/gpio.h
+++ b/drivers/include/periph/gpio.h
@@ -199,8 +199,8 @@ int gpio_init_int(gpio_t pin, gpio_mode_t mode, gpio_flank_t flank,
 /**
  * @brief   Enable pin interrupt if configured as interrupt source
  *
- *          Interrupts that would have occurred after @see gpio_irq_disable
- *          was called will be discarded.
+ * Interrupts that would have occurred after @see gpio_irq_disable
+ * was called will be discarded.
  *
  * @note    You have to add the module `periph_gpio_irq` to your project to
  *          enable this function