/**
 **************************************************************************************************
 * @file       gpio.h
 * @author     Kerem Yollu & Edwin Koch
 * @date       24.04.2025
 * @version    0.0.1
 **************************************************************************************************
 * @brief Platform-independent GPIO interface for the KED library.
 *
 * **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 implementation uses a centralized internal function pointer table to map
 * platform-specific logic (e.g., Linux or STM32) to a unified interface.
 * Application code can use `ked_gpio_set()`, `ked_gpio_read()` etc. without dealing with callbacks.
 **************************************************************************************************
 
 */

#ifndef KED_PERIPHERALS_GPIO_H_
#define KED_PERIPHERALS_GPIO_H_

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/** 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;

/* === Function pointer types (used internally only) === */

typedef void         (*fn_ptr_gpio_write)(uint8_t value);
typedef uint8_t      (*fn_ptr_gpio_read)(void);
typedef void         (*fn_ptr_gpio_toggle)(void);
typedef void         (*fn_ptr_gpio_error)(gpio_error_t);
typedef gpio_error_t (*fn_ptr_gpio_update)(void);

/**
 * @brief Internal function pointer table used by platform implementations.
 */
typedef struct {
    fn_ptr_gpio_write   set;
    fn_ptr_gpio_read    read;
    fn_ptr_gpio_toggle  toggle;
    fn_ptr_gpio_update  update;
    fn_ptr_gpio_error   on_error;
} gpio_fn_ptr_t;

/* === Platform-specific types === */
typedef struct gpio_s gpio_t;
#ifdef KED_USES_LINUX
/** GPIO configuration structure for Linux */
struct gpio_s {
    const char* chipname;
    unsigned int line_offset;
    gpio_function_t mode;
    gpio_direction_t direction;
    gpio_bias_t bias;
    gpio_status_t status;
	const gpio_fn_ptr_t* func;
};
#endif

/* === Public API === */

/**
 * @brief Initialize a GPIO using the specified configuration.
 *
 * @param gpio Pointer to target gpio_t handle
 * @return GPIO_OK on success, or an appropriate gpio_error_t
 */
gpio_error_t ked_gpio_init(gpio_t* gpio);

/**
 * @brief Deinitialize and release resources associated with a GPIO pin.
 *
 * @param gpio Pointer to GPIO object
 */
void ked_gpio_deinit(gpio_t* gpio);

/* === Platform-agnostic GPIO control interface === */

#ifdef __cplusplus
}
#endif

#endif /* KED_PERIPHERALS_GPIO_H_ */