/**
 **************************************************************************************************
 * @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.
 *
 * **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_t* pin = KED_GPIO.init(&config);
 *   KED_GPIO.set(pin, true);
 *   bool state = KED_GPIO.read(pin);
 *   KED_GPIO.toggle(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_GPIO_H_
#define KED_PERIPHERALS_GPIO_GPIO_H_

#include <stdbool.h>

/**
 * @brief Enumeration for GPIO functional modes.
 */
typedef enum {
    GPIO_MODE_DEFAULT,
    GPIO_MODE_INPUT,
    GPIO_MODE_OUTPUT,
    GPIO_MODE_ANALOG,
    GPIO_MODE_ALTERNATE
} gpio_mode_t;

/**
 * @brief Enumeration for GPIO direction settings.
 */
typedef enum {
    GPIO_DIRECTION_INPUT,
    GPIO_DIRECTION_OUTPUT
} gpio_direction_t;

/**
 * @brief Enumeration for GPIO drive configurations.
 */
typedef enum {
    GPIO_DRIVE_DEFAULT,
    GPIO_DRIVE_PUSH_PULL,
    GPIO_DRIVE_OPEN_DRAIN
} gpio_drive_t;

/**
 * @brief Enumeration for internal bias resistor settings.
 */
typedef enum {
    GPIO_BIAS_NONE,
    GPIO_BIAS_DISABLE,
    GPIO_BIAS_PULL_UP,
    GPIO_BIAS_PULL_DOWN
} gpio_bias_t;

/**
 * @brief Enumeration for GPIO speed settings.
 */
typedef enum {
    GPIO_SPEED_DEFAULT,
    GPIO_SPEED_LOW,
    GPIO_SPEED_MEDIUM,
    GPIO_SPEED_HIGH,
    GPIO_SPEED_VERY_HIGH
} gpio_speed_t;

/**
 * @brief Enumeration for enabling or disabling GPIO interrupts.
 */
typedef enum {
    GPIO_IRQ_DISABLED,
    GPIO_IRQ_ENABLED
} gpio_irq_t;

/**
 * @brief GPIO error status codes.
 */
typedef enum {
    GPIO_OK,
    GPIO_ERR_UNSUPPORTED_MODE,
    GPIO_ERR_LINE_BUSY,
    GPIO_ERR_NOT_AVAILABLE,
    GPIO_ERR_NO_PULL,
    GPIO_ERR_NOT_ANALOG,
    GPIO_ERR_UNKNOWN
} gpio_error_t;

/**
 * @brief Function pointer type for writing a logic level.
 */
typedef void (*gpio_write_fn)(bool value);

/**
 * @brief Function pointer type for reading a logic level.
 */
typedef bool (*gpio_read_fn)(void);

/**
 * @brief Function pointer type for toggling a GPIO pin.
 */
typedef void (*gpio_toggle_fn)(void);


/**
 * @brief Function pointer type for GPIO deinitialization.
 */
typedef void (*gpio_deinit_fn)(void);

/**
 * @brief Abstract GPIO handle with callback operations.
 */
typedef void (*gpio_error_fn)(gpio_error_t);

/**
 * @brief Abstract GPIO handle with callback operations.
 */
typedef struct {
    gpio_write_fn set;
    gpio_read_fn read;
    gpio_toggle_fn toggle;
    gpio_deinit_fn deinit;      /**< Deinitialization function pointer */
    gpio_error_fn on_error;     /**< Error handling callback */
} gpio_t;

/**
 * @brief Function pointer type for platform-specific GPIO initialization.
 */
typedef gpio_error_t (*gpio_init_fn)(gpio_t* gpio, const void* config);

#ifdef KED_USES_LINUX
/**
 * @brief Platform-specific GPIO configuration structure for Linux.
 */
typedef struct {
    const char* chipname;
    unsigned int line_offset;
    gpio_mode_t mode;
    gpio_direction_t direction;
    gpio_bias_t bias;
} gpio_config;
#endif

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

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

#endif /* KED_PERIPHERALS_GPIO_GPIO_H_ */