/******************************************************************************
 * File:        MCU_UART.h
 * Component:   MCU_UART
 * Description: Public interface for the MCU UART driver component.
 *
 *              TX: SendByte (blocking), SendBuffer (non-blocking DMA/ISR),
 *                  SendBufferBlocking.
 *              RX: background ring buffer filled by ISR or DMA.
 *                  ReadByte / ReadBuffer read from the buffer (non-blocking).
 *
 * Layer:       MCU (hardware abstraction)
 *****************************************************************************/

#ifndef MCU_UART_H
#define MCU_UART_H

#include "STD_TYPES.h"

/* ------------------------------------------------------------------------ */
/*                      CONFIGURATION VALUE TYPES                           */
/* ------------------------------------------------------------------------ */

typedef enum
{
    MCU_UART_PARITY_NONE = 0U,
    MCU_UART_PARITY_EVEN,
    MCU_UART_PARITY_ODD
} MCU_UART_tenuParity;

typedef enum
{
    MCU_UART_DATA_BITS_5 = 5U,
    MCU_UART_DATA_BITS_6 = 6U,
    MCU_UART_DATA_BITS_7 = 7U,
    MCU_UART_DATA_BITS_8 = 8U
} MCU_UART_tenuDataBits;

typedef enum
{
    MCU_UART_STOP_BITS_1 = 1U,
    MCU_UART_STOP_BITS_2 = 2U
} MCU_UART_tenuStopBits;

typedef enum
{
    MCU_UART_ASYNC_DMA = 0U,
    MCU_UART_ASYNC_ISR
} MCU_UART_tenuAsyncMode;

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

typedef struct
{
    u8                     u8TxPin;
    u8                     u8RxPin;
    u32                    u32BaudRate;
    MCU_UART_tenuDataBits  enuDataBits;
    MCU_UART_tenuStopBits  enuStopBits;
    MCU_UART_tenuParity    enuParity;
    MCU_UART_tenuAsyncMode enuTxAsyncMode;
    STD_tpfCallbackFunc    pfTxCompleteCallback;
    MCU_UART_tenuAsyncMode enuRxAsyncMode;
} MCU_UART_tstrConfig;

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

STD_tenuResult MCU_UART_enuInit(void);

STD_tenuResult MCU_UART_enuSendByte(u8 u8Instance, u8 u8Byte);

STD_tenuResult MCU_UART_enuSendBuffer(u8 u8Instance, const u8 *pu8Data, u16 u16Length);

STD_tenuResult MCU_UART_enuSendBufferBlocking(u8 u8Instance, const u8 *pu8Data, u16 u16Length);

STD_tBool MCU_UART_bIsTxBusy(u8 u8Instance);

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

/**
 * @brief  Read one byte from the RX ring buffer (non-blocking).
 *
 * The ring buffer is filled in the background by ISR or DMA.
 * Returns immediately — STD_OK with the byte, or STD_NOK if empty.
 *
 * @param  u8Instance  UART instance index.
 * @param  pu8Byte     Pointer to store the received byte.
 * @return STD_OK                   byte read,
 *         STD_NULL_POINTER_ERROR   if pu8Byte is NULL,
 *         STD_NOK                  if ring buffer is empty.
 */
STD_tenuResult MCU_UART_enuReadByte(u8 u8Instance, u8 *pu8Byte);

/**
 * @brief  Read up to u16MaxLength bytes from the RX ring buffer (non-blocking).
 *
 * Copies as many bytes as are currently available (up to u16MaxLength)
 * into pu8Data. Reports the actual number of bytes read via pu16Read.
 * Returns immediately even if fewer than u16MaxLength bytes are available.
 *
 * @param  u8Instance     UART instance index.
 * @param  pu8Data        Pointer to output buffer.
 * @param  u16MaxLength   Maximum bytes to read.
 * @param  pu16Read       Pointer to store actual bytes read. Must not be NULL.
 * @return STD_OK                   at least one byte read,
 *         STD_NULL_POINTER_ERROR   if pu8Data or pu16Read is NULL,
 *         STD_NOK                  if ring buffer is empty (zero bytes read).
 */
STD_tenuResult MCU_UART_enuReadBuffer(u8 u8Instance, u8 *pu8Data, u16 u16MaxLength, u16 *pu16Read);

/**
 * @brief  Check if the RX ring buffer has data.
 *
 * @param  u8Instance  UART instance index.
 * @return STD_TRUE if at least one byte available, STD_FALSE if empty.
 */
STD_tBool MCU_UART_bIsRxDataAvailable(u8 u8Instance);

#endif /* MCU_UART_H */