sdk-ameba-v4.0c_180328/component/common/mbed/hal_ext/log_uart_api.h

//----------------------------------------------------------------------------//
/**
  ******************************************************************************
  * @file    log_uart_api.h
  * @author
  * @version
  * @brief   This file provides user interface for log uart 
  *  base on the functionalities provided by Realtek periphera.
  ******************************************************************************
  * @attention
  *
  * This module is a confidential and proprietary property of RealTek and
  * possession or use of this module requires written permission of RealTek.
  *
  * Copyright(c) 2016, Realtek Semiconductor Corporation. All rights reserved.
  ****************************************************************************** 
  */
#ifndef LOG_UART_API_H
#define LOG_UART_API_H

#if CONFIG_PLATFORM_8195A

#include "device.h"
#include "serial_api.h"
#include "hal_log_uart.h"

#ifdef __cplusplus
extern "C" {
#endif

/** @addtogroup log_uart LOG_UART
 *  @ingroup    hal
 *  @brief      log_uart functions
 *  @{
 */

///@name Ameba1 Only
///@{

/******************************************************
 *                 Type Definitions
 ******************************************************/
/** Log uart irq handler function pointer type
 *
 * @param id  : The argument for log uart interrupt handler
 * @param event   : The log uart interrupt indication ID. More details is shown in hal_log_uart.h
 */
typedef void (*loguart_irq_handler)(uint32_t id, LOG_UART_INT_ID event);
typedef struct log_uart_s log_uart_t;

/******************************************************
 *               Function Declarations
 ******************************************************/
/**
 * @brief  Initialize Realtek log uart.
 * 		   Initialize the required parts of the log uart.
 *   			i.e. baudrate, data bits, parity, etc.
 * @param[in]  obj: The address of log uart object.
 * @param[in]  baudrate: Baud rate of the log uart object. 
 * @param[in]  data_bits: Data bits of the log uart object.
 * @param[in]  parity: Parity type of the log uart object
                        - ParityNone,           - Do not use parity
                        - ParityOdd,            - Use odd parity
                        - ParityEven,           - Use even parity
                        - ParityForced1,        - Use even parity, the same as ParityEven
                        - ParityForced0         - Use odd parity, the same as ParityOdd
 * @param[in]  stop_bits: The number of stop bits for the log uart object.
 * @return 0 if initialization is successful, -1 otherwise
 */
int32_t log_uart_init(log_uart_t *obj, int baudrate, int data_bits, SerialParity parity, int stop_bits);

/**
 * @brief  Release the resources related to Realtek log uart.
 
 * @param[in]  obj: The address of log uart object.
 * @return None
 */
void log_uart_free(log_uart_t *obj);

/**
 * @brief  Set the baud rate of log uart.
 
 * @param[in]  obj: The address of log uart object.
 * @param[in]  baudrate: Baud rate of the log uart object.
 * @return None
 */
void log_uart_baud(log_uart_t *obj, int baudrate);

/**
 * @brief  Set parameters for log uart.
 *   			including data bits, parity type and stop bits
 
 * @param[in]  obj: The address of log uart object.
 * @param[in]  data_bits: Data bits of log uart object.
 * @param[in]  parity: Parity type of the log uart object
                        - ParityNone,           - Do not use parity
                        - ParityOdd,            - Use odd parity
                        - ParityEven,           - Use even parity
                        - ParityForced1,        - Use even parity, the same as ParityEven
                        - ParityForced0         - Use odd parity, the same as ParityOdd
 * @param[in]  stop_bits: The number of stop bits for the log uart object.
 * @return None
 */
void log_uart_format(log_uart_t *obj, int data_bits, SerialParity parity, int stop_bits);

/**
 * @brief  Set irq handler for log uart.
 * @param[in]  obj: The address of log uart object.
 * @param[in]  handler: The interrupt handler for log uart.
 * @param[in]  id: The argument for log uart interrupt handler.
 * @return None
 */
void log_uart_irq_handler(log_uart_t *obj, loguart_irq_handler handler, uint32_t id);

/**
 * @brief  Enable/disable the specific irq indication ID.
 * @param[in]  obj: The address of log uart object.
 * @param[in]  irq: The log uart interrupt indication ID which will be enabled/disabled.
 * @param[in]  enable: 1 enable, 0 disable
 * @return None
 */
void log_uart_irq_set(log_uart_t *obj, LOG_UART_INT_ID irq, uint32_t enable);

/**
 * @brief  Read one character from log uart.
           This function will block untill the log uart gets something to read 
 * @param[in]  obj: The address of log uart object.
 * @return the character read from log uart
 */
char log_uart_getc(log_uart_t *obj);

/**
 * @brief  Write one character to log uart.
           This function will block untill the data is successfully written to log uart
 * @param[in]  obj: The address of log uart object.
 * @param[in]  c: The one byte data to be written to log uart.
 * @return None
 */
void log_uart_putc(log_uart_t *obj, char c);

/**
 * @brief  Check whether log uart is ready to read data
 * @param[in]  obj: The address of log uart object.
 * @return 1 if there is data at log uart to be read, 0 otherwise
 */
int log_uart_readable(log_uart_t *obj);

/**
 * @brief  Check whether log uart is ready to write data
 * @param[in]  obj: The address of log uart object.
 * @return 1 if log uart is ready for writing, 0 otherwise
 */
int log_uart_writable(log_uart_t *obj);

/**
 * @brief  Clear both data at log uart
           This function will clear data in both TX FIFO and RX FIFO of log uart
 * @param[in]  obj: The address of log uart object.
 * @return None
 */
void log_uart_clear(log_uart_t *obj);

/**
 * @brief  Clear TX FIFO of log uart
 * @param[in]  obj: The address of log uart object.
 * @return None
 */
void log_uart_clear_tx(log_uart_t *obj);

/**
 * @brief  Clear RX FIFO of log uart
 * @param[in]  obj: The address of log uart object.
 * @return None
 */
void log_uart_clear_rx(log_uart_t *obj);

/**
 * @brief  Set break control for log uart
 * @param[in]  obj: The address of log uart object.
 * @return None
 */
void log_uart_break_set(log_uart_t *obj);

/**
 * @brief  Clear break control for log uart
 * @param[in]  obj: The address of log uart object.
 * @return None
 */
void log_uart_break_clear(log_uart_t *obj);

/**
 * @brief  Set the handler for complete TX
 * @param[in]  obj: The address of log uart object.
 * @param[in]  handler: The function which is called when log uart has finished transmitting data.
 * @param[in]  id: The parameter for handler.  
 * @return None
 */
void log_uart_tx_comp_handler(log_uart_t *obj, void *handler, uint32_t id);

/**
 * @brief  Set the handler for complete RX
 * @param[in]  obj: The address of log uart object.
 * @param[in]  handler: The function which is called when log uart has finished receving data
 * @param[in]  id: The parameter for handler.  
 * @return None
 */
void log_uart_rx_comp_handler(log_uart_t *obj, void *handler, uint32_t id);

/**
 * @brief  Set the handler for line status
 * @param[in]  obj: The address of log uart object.
 * @param[in]  handler: The function which is called when log uart gets an line status indication ID. 
 * @param[in]  id: The parameter for handler.  
 * @return None
 */
void log_uart_line_status_handler(log_uart_t *obj, void *handler, uint32_t id);

/**
 * @brief  Read data from log uart in blocking mode.
 * @param[in]  obj: The address of log uart object.
 * @param[out]  prxbuf: The buffer to store received data.
 * @param[in]  len: The maximum length of data to be read
 * @param[in]  timeout_ms: Blocking time in ms.
 * @return the length of received data in bytes
 */
int32_t log_uart_recv(log_uart_t *obj, char *prxbuf, uint32_t len, uint32_t timeout_ms);

/**
 * @brief  Send data to log uart in blocking mode
 * @param[in]  obj: The address of log uart object.
 * @param[in]  ptxbuf: Data buffer to be sent to log uart
 * @param[in]  len: Length of data to be sent to log uart
 * @param[in]  timeout_ms: Blocking time in ms.
 * @return the length of sent data in bytes
 */
int32_t log_uart_send(log_uart_t *obj, char *ptxbuf, uint32_t len, uint32_t timeout_ms);

/**
 * @brief  Read data from log uart in interrupt mode(Non-blocking)
 * @param[in]  obj: The address of log uart object.
 * @param[out]  prxbuf: The buffer to store received data.
 * @param[in]  len: The maximum length of data to be read
 * @return 0 if success
 */
int32_t log_uart_recv_stream(log_uart_t *obj, char *prxbuf, uint32_t len);

/**
 * @brief  Send data to log uart in interrupt mode(Non-blocking)
 * @param[in]  obj: The address of log uart object.
 * @param[in]  ptxbuf: Data buffer to be sent to log uart
 * @param[in]  len: Length of data to be sent to log uart
 * @return 0 if success
 */
int32_t log_uart_send_stream(log_uart_t *obj, char *ptxbuf, uint32_t len);

/**
 * @brief  Read data from log uart with a given timeout in interrupt mode(Non-blocking)
 * @param[in]  obj: The address of log uart object.
 * @param[out]  prxbuf: The buffer to store received data.
 * @param[in]  len: The maximum length of data to be read
 * @param[in]  timeout_ms: The timeout for reading data in ms
 * @param[in]  force_cs: User callback function 
 * @return the length in Byte of received data before timeout, or error (< 0)
 */
int32_t log_uart_recv_stream_timeout(log_uart_t *obj, char *prxbuf, uint32_t len,
                                        uint32_t timeout_ms, void *force_cs);

/**
 * @brief  Abort interrupt mode of sending data 
 * @param[in]  obj: The address of log uart object.
 * @return the length of data sent to log uart.
 */
int32_t log_uart_send_stream_abort(log_uart_t *obj);

/**
 * @brief  Abort interrupt mode of receiving data 
 * @param[in]  obj: The address of log uart object.
 * @return the length of data received from log uart.
 */
int32_t log_uart_recv_stream_abort(log_uart_t *obj);

/**
 * @brief  Disable log uart
 * @param[in]  obj: The address of log uart object.
 * @return None.
 */
void log_uart_disable(log_uart_t *obj);

/**
 * @brief  Enable log uart
 * @param[in]  obj: The address of log uart object.
 * @return None.
 */
void log_uart_enable(log_uart_t *obj);

/**
 * @brief  Read Line-Status register
 * @return value:
 *         - Bit 0: RX Data Ready
 *         - Bit 1: Overrun Error
 *         - Bit 2: Parity Error
 *         - Bit 3: Framing Error
 *         - Bit 4: Break Interrupt (received data input is held in 0 state for a longer than a full word tx time)
 *         - Bit 5: TX FIFO empty (THR empty)
 *         - Bit 6: TX FIFO empty (THR & TSR both empty)
 *         - Bit 7: Receiver FIFO Error (parity error, framing error or break indication) 
 */
uint8_t log_uart_raed_lsr(log_uart_t *obj);

/**
 * @brief  Read Modem-Status register
 * @return value:
 *         - Bit 0: DCTS, The CTS line has changed its state
 *         - Bit 1: DDSR, The DSR line has changed its state
 *         - Bit 2: TERI, RI line has changed its state from low to high state
 *         - Bit 3: DDCD, DCD line has changed its state
 *         - Bit 4: Complement of the CTS input 
 *         - Bit 5: Complement of the DSR input 
 *         - Bit 6: Complement of the RI input 
 *         - Bit 7: Complement of the DCD input  
 */
uint8_t log_uart_raed_msr(log_uart_t *obj);

///@}
/*\@}*/

#ifdef __cplusplus
}
#endif

#endif //CONFIG_PLATFORM_8195A

#endif  // end of "#ifndef LOG_UART_API_H"