KED/ked/peripherals/gpio/gpio.h

/**
 **************************************************************************************************
 * @file       pin.h
 * @author     Kerem Yollu & Edwin Koch
 * @date       24.04.2025
 * @version    0.0.1
 **************************************************************************************************
 * @brief Platform-independent GPIO interface for the KED library. For more details, see [KED Wiki - GPIO](https://wiki.kynsight.com/bin/view/Kynsight/Projects/KED/Peripherals/GPIO/).
 *
 * **Detailed Description :**
 * This header defines a hardware abstraction layer (HAL) for General Purpose I/O (GPIO)
 * that allows unified control of digital I/O pins across different platforms,
 * such as microcontrollers or embedded Linux systems (e.g., Raspberry Pi).
 *
 * The interface provides a driver table through which initialization,
 * read/write, and toggle operations can be performed in a platform-agnostic way.
 * Platform-specific implementations must define and populate the `KED_GPIO`
 * driver table with appropriate function pointers.
 *
 * Usage Example:
 * @code
 *   gpio_config cfg = { ... };
 *   gpio_t pin = ked_gpio_init(&cfg);
 *   ked_gpio_set(&pin, true);
 *   bool state = ked_gpio_read(&pin);
 *   ked_gpio_toggle(&pin);
 *   ked_gpio_deinit(&pin);
 * @endcode
 *
 * @todo
 * - 24.04.2025: Implement more function pointer to enhance available gpio operations
 * - 24.04.2025: Implement Defined States, Errors, Configuration Options
 **************************************************************************************************
 */
#ifndef KED_PERIPHERALS_GPIO_H_
#define KED_PERIPHERALS_GPIO_H_

#include <stdint.h>

/** GPIO Mode Types */
typedef enum {
    T_GPIO_MODE_DEFAULT,
    T_GPIO_MODE_INPUT,
    T_GPIO_MODE_OUTPUT,
    T_GPIO_MODE_ANALOG,
    T_GPIO_MODE_ALTERNATE
} gpio_function_t;

/** GPIO Direction (explicit) */
typedef enum {
    T_GPIO_DIRECTION_INPUT,
    T_GPIO_DIRECTION_OUTPUT
} gpio_direction_t;

/** Drive types for output pins */
typedef enum {
    T_GPIO_DRIVE_DEFAULT,
    T_GPIO_DRIVE_PUSH_PULL,
    T_GPIO_DRIVE_OPEN_DRAIN
} gpio_drive_t;

/** Pull-up/pull-down configurations */
typedef enum {
    T_GPIO_BIAS_DEFAULT,
    T_GPIO_BIAS_DISABLE,
    T_GPIO_BIAS_PULL_UP,
    T_GPIO_BIAS_PULL_DOWN
} gpio_bias_t;

/** Optional pin speed enumeration */
typedef enum {
    T_GPIO_SPEED_DEFAULT,
    T_GPIO_SPEED_LOW,
    T_GPIO_SPEED_MEDIUM,
    T_GPIO_SPEED_HIGH,
    T_GPIO_SPEED_VERY_HIGH
} gpio_speed_t;

/** Enable/disable pin interrupt */
typedef enum {
    T_GPIO_IRQ_DISABLED,
    T_GPIO_IRQ_ENABLED
} gpio_irq_t;

/** GPIO Status */
typedef enum {
    T_GPIO_STATUS_NOT_INIT,   /**< GPIO is not initialized */
    T_GPIO_STATUS_READY,      /**< GPIO is ready for use */
    T_GPIO_STATUS_BUSY,       /**< GPIO is currently in use */
    T_GPIO_STATUS_ERROR,      /**< GPIO encountered an error */
    T_GPIO_STATUS_UPDATING     /**< GPIO is currently being reconfigured */
} gpio_status_t;

/** GPIO error status codes */
typedef enum {
    T_GPIO_ERR_OK,						/*!< Suscess flag for the Init Function */
    T_GPIO_ERR_UNSUPPORTED_MODE,			/*!< Mode is either not valid orsupported by **Hardwaware** */
	T_GPIO_ERR_UNSUPPORTED_ALTERNATE,		/*!< Alternateive mode is unvalid */
    T_GPIO_ERR_BUS_BUSY,					/*!< The chosen GPIO BUS is already in Use */
    T_GPIO_ERR_NOT_AVAILABLE,				/*!< Pin does Not aloow GPIO functionalities or does not Exists */ 
    T_GPIO_ERR_NOT_BIASABLE,				/*!< No Pull-Up or Pull-Down Option are awailable */ 					
    T_GPIO_ERR_NO_INTERRUPT_SUPPORT,		/*!< This GPIO Doesn't allow interrupts */ 					
    T_GPIO_ERR_UNSUPPORTED_DRIVE,			/*!< This gate griving option is Unsupported (Pushpull, open drain etc..) */ 					
	T_GPIO_ERR_UNSUPPORTED_SPEED,			/*!< The choosen bus speed is not supported */
	T_GPIO_ERR_UNKNOWN					/*!< Goal Would be To never be Used, but can be helpful during Developpment */
} gpio_error_t;


/** GPIO configuration structure for Linux */
#ifdef KED_USES_LINUX
typedef struct {
    const char* chipname;
    unsigned int line_offset;
    gpio_function_t mode;
    gpio_direction_t direction;
    gpio_bias_t bias;
    gpio_status_t status;
} gpio_t;
#endif

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Initialize a GPIO pin.
 * @param gpio Pointer to target gpio_t object
 * @param config Pointer to configuration structure
 * @return gpio_error_t status
 */
gpio_error_t ked_gpio_init(const gpio_t* gpio);

/**
 * @brief Update configuration of an already initialized GPIO.
 *
 * This function allows changing selected configuration parameters such as direction,
 * bias, or other runtime-reconfigurable options without a full re-init.
 *
 * @param gpio Pointer to initialized gpio object
 * @param config Pointer to new configuration structure
 * @return gpio_error_t indicating success or failure of update
 */
gpio_error_t ked_gpio_update(gpio_t* gpio);

/**
 * @brief Deinitialize and release GPIO
 * @param gpio Pointer to initialized gpio object
 */
void ked_gpio_deinit(gpio_t* gpio);

/**
 * @brief Set GPIO output logic level
 * @param gpio Pointer to initialized gpio object
 * @param value True for HIGH, false for LOW
 */
void ked_gpio_set(gpio_t* gpio, uint8_t value);

/**
 * @brief Read the GPIO logic level
 * @param gpio Pointer to initialized gpio object
 * @return Logic level (true or false)
 */
uint8_t ked_gpio_read(gpio_t* gpio);

/**
 * @brief Toggle GPIO output state
 * @param gpio Pointer to initialized gpio object
 */
void ked_gpio_toggle(gpio_t* gpio);

void ked_gpio_handle_error(gpio_error_t err);

#ifdef __cplusplus
}
#endif

#endif /* KED_PERIPHERALS_GPIO_GPIO_H_ */