/******************************************************************************
 * File:        HAL_COM.h
 * Component:   HAL_COM
 * Description: Public interface for the HAL communication abstraction layer.
 *              Provides a transport-agnostic, multi-channel API for sending
 *              and receiving bytes. Each channel is independently configured
 *              with function pointers to an MCU-level driver (USB, UART,
 *              SPI, I2C, or any future transport that matches the function
 *              signatures).
 *
 *              Higher layers (e.g. APP_CLSW) call HAL_COM_* with a channel
 *              number and stay unaware of which physical transport is in use.
 *              Adding a new transport requires zero changes to this file or
 *              to HAL_COM_prg.c — only the config needs a new channel entry.
 *
 * Layer:       HAL (hardware abstraction, one level above MCU drivers)
 *****************************************************************************/

#ifndef HAL_COM_H
#define HAL_COM_H

#include "STD_TYPES.h"
#include "HAL_COM_cfg.h"

/* ------------------------------------------------------------------------ */
/*                   TRANSPORT FUNCTION POINTER TYPES                       */
/* ------------------------------------------------------------------------ */

/**
 * @brief  Generic send-byte function pointer type.
 *
 * Any MCU driver that can send a single byte and matches this signature
 * can be plugged into a HAL_COM channel. The u8Instance parameter
 * identifies the peripheral instance within that driver (e.g., UART0
 * vs UART1). Drivers that have only one instance (e.g., MCU_USB) use
 * a thin wrapper that ignores the parameter.
 *
 * @param  u8Instance  Peripheral instance index within the driver.
 * @param  u8Byte      The byte to transmit.
 * @return STD_tenuResult
 */
typedef STD_tenuResult (*HAL_COM_tpfSendByte)(u8 u8Instance, u8 u8Byte);

/**
 * @brief  Generic send-buffer function pointer type.
 *
 * Same concept as HAL_COM_tpfSendByte but for multi-byte transfers.
 *
 * @param  u8Instance  Peripheral instance index within the driver.
 * @param  pu8Data     Pointer to the byte buffer.
 * @param  u16Length   Number of bytes to transmit.
 * @return STD_tenuResult
 */
typedef STD_tenuResult (*HAL_COM_tpfSendBuffer)(u8 u8Instance, const u8 *pu8Data, u16 u16Length);

/**
 * @brief  Generic read-byte function pointer type (non-blocking).
 */
typedef STD_tenuResult (*HAL_COM_tpfReadByte)(u8 u8Instance, u8 *pu8Byte);

/**
 * @brief  Generic read-buffer function pointer type (non-blocking).
 */
typedef STD_tenuResult (*HAL_COM_tpfReadBuffer)(u8 u8Instance, u8 *pu8Data, u16 u16MaxLength, u16 *pu16Read);

/**
 * @brief  Generic RX-data-available check function pointer type.
 */
typedef STD_tBool (*HAL_COM_tpfIsRxDataAvailable)(u8 u8Instance);

/* ------------------------------------------------------------------------ */
/*                      CONFIGURATION STRUCTURE                             */
/* ------------------------------------------------------------------------ */

/**
 * @brief  Per-channel communication configuration.
 *
 * One entry per HAL_COM channel, stored in HAL_COM_astrChannelConfig[].
 * The array index is the channel number passed to all public functions.
 *
 * Each channel is wired to exactly one MCU-level transport by holding
 * function pointers to that driver's send functions + the instance index
 * to pass through. To route through a different transport, just change
 * the function pointers in the config — no code changes needed.
 */
typedef struct
{
    HAL_COM_tpfSendByte          pfSendByte;          /**< Driver's send-byte function        */
    HAL_COM_tpfSendBuffer        pfSendBuffer;        /**< Driver's send-buffer function      */
    HAL_COM_tpfReadByte          pfReadByte;          /**< Driver's read-byte function        */
    HAL_COM_tpfReadBuffer        pfReadBuffer;        /**< Driver's read-buffer function      */
    HAL_COM_tpfIsRxDataAvailable pfIsRxDataAvailable; /**< Driver's RX-available check        */
    u8                           u8Instance;          /**< Peripheral instance to pass through */
} HAL_COM_tstrChannelConfig;

/* ------------------------------------------------------------------------ */
/*                            PUBLIC API                                    */
/* ------------------------------------------------------------------------ */

/**
 * @brief  Initialize the HAL communication layer's own internal state.
 *
 * Does NOT initialize the underlying MCU drivers — SYS_ECU owns the init
 * sequence and calls each driver's enuInit() before calling this.
 *
 * @return STD_OK on success, STD_NOK on failure.
 */
STD_tenuResult HAL_COM_enuInit(void);

/**
 * @brief  Send a single byte through the specified channel.
 *
 * @param  u8Channel  Channel index (from HAL_COM_cfg.h channel enum).
 * @param  u8Byte     The byte to transmit.
 * @return STD_OK on success, STD_NOK on failure.
 */
STD_tenuResult HAL_COM_enuSendByte(u8 u8Channel, u8 u8Byte);

/**
 * @brief  Send a buffer through the specified channel.
 *
 * The underlying driver may be blocking or non-blocking depending on the
 * MCU driver wired to this channel. When non-blocking (e.g., MCU_UART
 * with DMA), the caller must keep the buffer valid until the transfer
 * completes.
 *
 * @param  u8Channel  Channel index.
 * @param  pu8Data    Pointer to the byte buffer. Must not be NULL.
 * @param  u16Length  Number of bytes to transmit.
 * @return STD_OK                   on success,
 *         STD_NULL_POINTER_ERROR   if pu8Data is NULL,
 *         STD_NOK                  on failure.
 */
STD_tenuResult HAL_COM_enuSendBuffer(u8 u8Channel, const u8 *pu8Data, u16 u16Length);

/**
 * @brief  Read one byte from the specified channel (non-blocking).
 */
STD_tenuResult HAL_COM_enuReadByte(u8 u8Channel, u8 *pu8Byte);

/**
 * @brief  Read up to u16MaxLength bytes from the specified channel (non-blocking).
 */
STD_tenuResult HAL_COM_enuReadBuffer(u8 u8Channel, u8 *pu8Data, u16 u16MaxLength, u16 *pu16Read);

/**
 * @brief  Check if the specified channel has RX data available.
 */
STD_tBool HAL_COM_bIsRxDataAvailable(u8 u8Channel);

#endif /* HAL_COM_H */