[PATCH] Proposal for new GPIO API and example implementation for STM32F4 BSP

[Duc Doan]

Dear all,

I am proposing a new GPIO API for RTEMS. The current API is kind of tailored to some specific hardware and therefore may require some overhead to make it fit for others. The one I am proposing is not finished but it is aimed to be simple and generic. It has some opaque type structures that need to be implemented by BSP. The functions include initialization, configuration, reading, writing, and toggle. I took inspiration from the Wiring framework. I also have an example implementation for the STM32F4 BSP.

I would love to get feedback from all of you.

Thank you,

Duc Doan

---
 bsps/arm/stm32f4/gpio/gpio.c |  39 +++++++++++
 bsps/include/bsp/gpio2.h     | 129 +++++++++++++++++++++++++++++++++++
 2 files changed, 168 insertions(+)
 create mode 100644 bsps/arm/stm32f4/gpio/gpio.c
 create mode 100644 bsps/include/bsp/gpio2.h

diff --git a/bsps/arm/stm32f4/gpio/gpio.c b/bsps/arm/stm32f4/gpio/gpio.c
new file mode 100644
index 0000000000..40aea3febd
--- /dev/null
+++ b/bsps/arm/stm32f4/gpio/gpio.c
@@ -0,0 +1,39 @@
+#include <bsp.h>
+#include <rtems.h>
+#include <bsp/gpio2.h>
+#include <stm32f4xx_hal.h>
+
+struct rtems_gpio_t {
+    GPIO_TypeDef *port;
+};
+
+struct rtems_gpio_pin_t {
+    uint16_t pin_mask;  
+};
+
+struct rtems_gpio_config_t {
+    GPIO_InitTypeDef *config;
+}
+
+__weak rtems_status_code rtems_gpio_initialize(void) {
+    return RTEMS_SUCCESSFUL;
+}
+
+rtems_status_code rtems_gpio_configure(rtems_gpio_t *gpiox, rtems_gpio_config_t *config) {
+    HAL_GPIO_Init(gpiox->port, config->config);
+    return RTEMS_SUCCESSFUL;
+}
+
+rtems_status_code rtems_gpio_write_pin(rtems_gpio_t *gpiox, rtems_gpio_pin_t *pin, rtems_gpio_pin_state value) {
+    HAL_GPIO_WritePin(gpiox->port, pin->pin_mask, value);
+    return RTEMS_SUCCESSFUL;
+}
+
+rtems_gpio_pin_state rtems_gpio_read_pin(rtems_gpio_t *gpiox, rtems_gpio_pin_t *pin) {
+    return HAL_GPIO_ReadPin(gpiox->port, pin->pin_mask);
+}
+
+rtems_status_code rtems_gpio_toggle_pin(rtems_gpio_t *gpiox, rtems_gpio_pin_t *pin) {
+    HAL_GPIO_TogglePin(gpiox->port, pin->pin_mask);
+    return RTEMS_SUCCESSFUL;
+}
diff --git a/bsps/include/bsp/gpio2.h b/bsps/include/bsp/gpio2.h
new file mode 100644
index 0000000000..ef10d1729a
--- /dev/null
+++ b/bsps/include/bsp/gpio2.h
@@ -0,0 +1,129 @@
+/**
+  * @file
+  *
+  * @ingroup rtems_gpio2
+  *
+  * @brief RTEMS GPIO new API definition.
+  */
+
+ /*
+  *  Copyright (c) 2022 Duc Doan <dtbpkmte at gmail.com>
+  *
+  *  The license and distribution terms for this file may be
+  *  found in the file LICENSE in this distribution or at
+  *  http://www.rtems.org/license/LICENSE.
+  */
+
+#ifndef LIBBSP_SHARED_GPIO2_H
+#define LIBBSP_SHARED_GPIO2_H
+
+#include <bsp.h>
+#include <rtems.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+/**
+ * @name GPIO data structures
+ *
+ * @{
+ */
+
+/**
+  * @brief GPIO bit set and reset enumeration.
+  */
+typedef enum {
+    RTEMS_GPIO_PIN_SET = 0,
+    RTEMS_GPIO_PIN_RESET
+} rtems_gpio_pin_state;
+
+/**
+  * @brief Opaque type for a GPIO object.
+  *        To be implemented by BSP.
+  * 
+  * @details This could represent the unit that owns GPIO pins. 
+  *          For example, it would be a port for ARM Cortex-M.
+  */
+typedef struct rtems_gpio_t rtems_gpio_t;
+
+/**
+  * @brief Opaque type for a GPIO pin object.
+  *        To be implemented by BSP.
+  */
+typedef struct rtems_gpio_pin_t rtems_gpio_pin_t;
+
+/**
+  * @brief Opaque type for configuration of a GPIO object.
+  *        To be implemented by BSP.
+  */
+typedef struct rtems_gpio_config_t;
+
+/** @} */
+
+/**
+  * @name GPIO Functions
+  *
+  * @{
+  */
+
+/**
+  * @brief Initialization for GPIO. To be implemented by User Application.
+  *
+  * @retval RTEMS_SUCCESSFUL GPIO successfully initialized.
+  * @retval RTEMS_UNSATISFIED Could not initialize GPIO object.
+  */
+extern rtems_status_code rtems_gpio_initialize(void);
+
+/**
+  * @brief Configures a GPIO object.
+  *        To be implemented by BSP.
+  *
+  * @param[in] gpiox The GPIO object to be configured.
+  * @param[in] config The GPIO configuration object.
+  *
+  * @retval RTEMS_SUCCESSFUL GPIO configured successfully.
+  * @retval RTEMS_UNSATISFIED Could not configure GPIO object.
+  */
+extern rtems_status_code rtems_gpio_configure(rtems_gpio_t *gpiox, rtems_gpio_config_t *config);
+
+/**
+  * @brief Writes a digital value to a pin/pins.
+  *
+  * @param[in] gpiox The GPIO object that owns the pin(s).
+  * @param[in] pin The GPIO pin number or pin mask to be written.
+  * @param[in] value The state to be written to the pin(s).
+  *
+  * @retval RTEMS_SUCCESSFUL Pin successfully written.
+  * @retval RTEMS_UNSATISFIED Could not write to pin(s).
+  */
+extern rtems_status_code rtems_gpio_write_pin(rtems_gpio_t *gpiox, rtems_gpio_pin_t *pin, rtems_gpio_pin_state value);
+
+/**
+  * @brief Reads the digital value of a pin/pins.
+  *
+  * @param[in] gpiox The GPIO object that owns the pin(s).
+  * @param[in] pin The GPIO pin(s) to be read.
+  *
+  * @retval The state of the pin(s).
+  */
+extern rtems_gpio_pin_state rtems_gpio_read_pin(rtems_gpio_t *gpiox, rtems_gpio_pin_t *pin);
+
+/**
+  * @brief Toggles the state of a GPIO pin/pins.
+  *
+  * @param[in] gpiox The GPIO object that owns the pin(s).
+  * @param[in] pin The GPIO pin(s) to be toggled.
+  *
+  * @retval RTEMS_SUCCESSFUL Pin(s) successfully toggled.
+  * @retval RTEMS_UNSATISFIED Could not toggle pin(s).
+  */
+extern rtems_status_code rtems_gpio_toggle_pin(rtems_gpio_t *gpiox, rtems_gpio_pin_t *pin);
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#endif /* LIBBSP_SHARED_GPIO2_H */
-- 
2.36.1