UART.h

Go to the documentation of this file.

/*
 * Copyright (c) 2014-2019, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/* @} */

#ifndef ti_drivers_UART__include
#define ti_drivers_UART__include

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include <stddef.h>


#define UART_SUCCESS ((int32_t)(0))
#define UART_ERROR   (-((int32_t)1))

#define UART_ERRNO_BASE        (0)

#define UART_EINVAL            (UART_ERRNO_BASE-1)

#define UART_EINUSE            (UART_ERRNO_BASE-2)

#define UART_ENOTIMPL          (UART_ERRNO_BASE-3)

typedef struct  UART_Config_s          *UART_Handle;

typedef void        (*UART_Callback)    (UART_Handle handle, void *buf, size_t count);

#define UART_NO_WAIT       ((uint32_t)0U)
#define UART_WAIT_FOREVER  (~((uint32_t)0U))

typedef enum UART_TransferApiVer_s {
    UART_TRANSFER_API_VER_1 = 1,
    UART_TRANSFER_API_VER_2 = 2

} UART_TransferApiVer;

typedef enum UART_TransferStatus_s {
    UART_TRANSFER_STATUS_SUCCESS = 0,
    UART_TRANSFER_STATUS_TIMEOUT,     /* Time out error */
    UART_TRANSFER_STATUS_ERROR_BI,    /* Break condition error */
    UART_TRANSFER_STATUS_ERROR_FE,    /* Framing error */
    UART_TRANSFER_STATUS_ERROR_PE,    /* Parity error */
    UART_TRANSFER_STATUS_ERROR_OE,    /* Overrun error */
    UART_TRANSFER_STATUS_ERROR_OTH    /* Other error */

} UART_TransferStatus;

typedef struct UART_Transaction_s {
    /* User input (write-only) fields */
    void               *buf;        
    uint32_t            timeout;    
    /* User input (write-only) and output (read-only) fields */
    uint32_t            count;      
    /* User output (read-only) fields */
    UART_TransferStatus status;     
    /* Driver-use only fields */
} UART_Transaction;

typedef void        (*UART_Callback2)   (UART_Handle handle, UART_Transaction *transaction);

typedef enum UART_Mode_e {
    UART_MODE_BLOCKING,

    UART_MODE_CALLBACK,
} UART_Mode;

typedef enum UART_ReturnMode_e {
    UART_RETURN_FULL,

    UART_RETURN_NEWLINE
} UART_ReturnMode;

typedef enum UART_DataMode_e {
    UART_DATA_BINARY,  
    UART_DATA_TEXT     
} UART_DataMode;

typedef enum UART_Echo_e {
    UART_ECHO_OFF = 0,  
    UART_ECHO_ON = 1    
} UART_Echo;

typedef enum UART_LEN_e {
    UART_LEN_5 = 0,        
    UART_LEN_6 = 1,        
    UART_LEN_7 = 2,        
    UART_LEN_8 = 3,        
#ifdef PRU_ICSS_FW  // PRU UART FW SW IP only
    UART_LEN_9 = 4         
#endif
} UART_LEN;

typedef enum UART_STOP_e {
    UART_STOP_ONE = 0,     
    UART_STOP_TWO = 1,     
#ifdef PRU_ICSS_FW  // PRU UART FW SW IP only, currently unsupported by HW IP driver
    UART_STOP_ONEP5 = 2    
#endif
} UART_STOP;

typedef enum UART_PAR_e {
    UART_PAR_NONE = 0,  
    UART_PAR_EVEN = 1,  
    UART_PAR_ODD  = 2,  
    UART_PAR_ZERO = 3,  
    UART_PAR_ONE  = 4   
} UART_PAR;

typedef enum UART_FC_TYPE_e {
    UART_FC_NONE = 0,   
    UART_FC_HW   = 1    
} UART_FC_TYPE;

typedef struct UART_Params_s {
    UART_Mode       readMode;           
    UART_Mode       writeMode;          
    uint32_t        readTimeout;        
    uint32_t        writeTimeout;       
    UART_Callback   readCallback;       
    UART_Callback   writeCallback;      
    UART_ReturnMode readReturnMode;     
    UART_DataMode   readDataMode;       
    UART_DataMode   writeDataMode;      
    UART_Echo       readEcho;           
    uint32_t        baudRate;           
    UART_LEN        dataLength;         
    UART_STOP       stopBits;           
    UART_PAR        parityType;         
    UART_Callback2  readCallback2;      
    UART_Callback2  writeCallback2;     
    UART_FC_TYPE    flowControlType;    
    uint8_t         hwFlowControlThr;   
    uint32_t        procChrTimeoutInt;  
    uint16_t        timeoutIntrVal;     
    uint32_t        timeoutBehavior;    
} UART_Params;

typedef void        (*UART_CloseFxn)          (UART_Handle handle);

typedef int32_t     (*UART_ControlFxn)        (UART_Handle handle,
                                               uint32_t cmd,
                                               void *arg);

typedef void        (*UART_InitFxn)           (UART_Handle handle);

typedef UART_Handle (*UART_OpenFxn)           (UART_Handle handle,
                                               const UART_Params *params);
typedef int32_t     (*UART_ReadFxn)           (UART_Handle handle, void *buffer,
                                               size_t size);

typedef int32_t     (*UART_ReadPollingFxn)    (UART_Handle handle, void *buffer,
                                               size_t size);

typedef void        (*UART_ReadCancelFxn)     (UART_Handle handle);

typedef int32_t     (*UART_WriteFxn)          (UART_Handle handle,
                                               const void *buffer,
                                               size_t size);

typedef int32_t     (*UART_WritePollingFxn)   (UART_Handle handle,
                                               const void *buffer,
                                               size_t size);

typedef void        (*UART_WriteCancelFxn)    (UART_Handle handle);

typedef int32_t     (*UART_ReadFxn2)          (UART_Handle handle,
                                               UART_Transaction *transaction);
typedef int32_t     (*UART_WriteFxn2)         (UART_Handle handle,
                                               UART_Transaction *transaction);

typedef struct UART_FxnTable_s {
    UART_CloseFxn           closeFxn;
    UART_ControlFxn         controlFxn;
    UART_InitFxn            uartInitFxn;
    UART_OpenFxn            openFxn;
    UART_ReadFxn            readFxn;
    UART_ReadPollingFxn     readPollingFxn;
    UART_ReadCancelFxn      readCancelFxn;
    UART_WriteFxn           writeFxn;
    UART_WritePollingFxn    writePollingFxn;
    UART_WriteCancelFxn     writeCancelFxn;
    UART_ReadFxn2           readFxn2;
    UART_WriteFxn2          writeFxn2;
    
} UART_FxnTable;

typedef struct UART_Config_s {
    UART_FxnTable const    *fxnTablePtr;

    void                   *object;

    void          const    *hwAttrs;
} UART_Config;

#define UART_MAX_CONFIG_CNT (14U)  
typedef UART_Config UART_config_list[UART_MAX_CONFIG_CNT];

extern void UART_close(UART_Handle uartHnd);

extern int32_t UART_control(UART_Handle uartHnd, uint32_t cmd, void *arg);

extern void UART_init(void);

extern UART_Handle UART_open(uint32_t idx, UART_Params *uartParams);

extern void UART_Params_init(UART_Params *uartParams);


extern int32_t UART_write(UART_Handle uartHnd, const void *buffer, size_t size);

extern int32_t UART_writePolling(UART_Handle uartHnd, const void *buffer,
                             size_t size);

extern void UART_writeCancel(UART_Handle handle);

extern int32_t UART_read(UART_Handle handle, void *buffer, size_t size);

extern int32_t UART_readPolling(UART_Handle handle, void *buffer, size_t size);

extern void UART_readCancel(UART_Handle handle);

extern int32_t UART_read2(UART_Handle handle, UART_Transaction *uartTrans);

extern int32_t UART_write2(UART_Handle handle, UART_Transaction *uartTrans);

extern void UART_transactionInit(UART_Transaction *uartTrans);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_UART__include */

/* @} */