UART.h

Go to the documentation of this file.

/*
 * Copyright (c) 2021, 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.
 */
/*!****************************************************************************
 *  @file       UART.h
 *
 *  @brief      UART driver interface.
 *
 *  @defgroup   UART Universal Asynchronous Receiver-Transmitter (UART)
 *
 *  The UART header file should be included in an application as follows:
 *  @code
 *  #include <ti/drivers/UART.h>
 *  @endcode
 *
 *  @anchor ti_drivers_UART_Overview
 *  # Overview
 *  UART has both RX and TX ring buffers for receiving/sending data.
 *  UART uses DMA to transfer data between the UART FIFOs and the
 *        RX and TX ring buffers in blocking mode. In callback mode,
 *        DMA will transfer data straight between the hardware
 *        FIFO and the source/destination buffer supplied by the application.
 *        NOTE: If the source-buffer for a TX operation resides in flash,
 *        the driver will constrain the flash to remain on during idle.
 *  The UART APIs for reading and writing data have been made more
 *        posix-like.
 *  UART provides for event notification, allowing the application
 *        to receive TX start and completion events, and RX error events.
 *        @note These events are synchronous to what can be observed on the data
 *        lines. A UART_STAT_TXFE_SET event will for example only occur
 *        after all data has been shifted from the hardware FIFO out onto the
 *        TX-pin. In contrast, read and write-callbacks are invoked when the
 *        driver has finished writing data into the hardware FIFO.
 *
 *  To use the UART driver, ensure that the correct driver library for your
 *  device is linked in and include this header file as follows:
 *  @code
 *  #include <ti/drivers/UART.h>
 *  @endcode
 *
 ******************************************************************************
 */
/* clang-format off */
#ifndef ti_drivers_uart_UART__include
#define ti_drivers_uart_UART__include

#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

#ifdef __cplusplus
extern "C" {
#endif
#include <ti/driverlib/dl_gpio.h>
#include <ti/driverlib/dl_uart_main.h>

#define UART_STATUS_SUCCESS (0)

#define UART_STATUS_SREADTIMEOUT (1)

#define UART_STATUS_EFRAMING (-1)

#define UART_STATUS_EPARITY (-2)

#define UART_STATUS_EBREAK (-4)

#define UART_STATUS_EOVERRUN (-8)

#define UART_STATUS_EINUSE (-9)

#define UART_STATUS_EINVALID (-10)

#define UART_STATUS_EFAIL (-11)

#define UART_STATUS_EMEMORY (-12)

#define UART_STATUS_ETIMEOUT (-13)

#define UART_STATUS_ECANCELLED (-14)

#define UART_STATUS_ENOTOPEN (-15)

#define UART_STATUS_EAGAIN (-16)

typedef struct UART_Config_ *UART_Handle;
typedef void (*UART_Callback)(UART_Handle handle, void *buf, size_t count,
    void *userArg, int_fast16_t status);

typedef void (*UART_EventCallback)(
    UART_Handle handle, uint32_t event, uint32_t data, void *userArg);

typedef enum {
    UART_Mode_BLOCKING = 0,

    UART_Mode_CALLBACK,

    UART_Mode_NONBLOCKING,
} UART_Mode;

typedef enum {
    UART_ReadReturnMode_FULL = 0,

    UART_ReadReturnMode_PARTIAL
} UART_ReadReturnMode;

typedef enum {
    UART_DataLen_5 = DL_UART_WORD_LENGTH_5_BITS, 
    UART_DataLen_6 = DL_UART_WORD_LENGTH_6_BITS, 
    UART_DataLen_7 = DL_UART_WORD_LENGTH_7_BITS, 
    UART_DataLen_8 = DL_UART_WORD_LENGTH_8_BITS  
} UART_DataLen;

typedef enum {
    UART_StopBits_1 = DL_UART_STOP_BITS_ONE, 
    UART_StopBits_2 = DL_UART_STOP_BITS_TWO  
} UART_StopBits;

typedef enum {
    UART_Parity_NONE = DL_UART_PARITY_NONE, 
    UART_Parity_EVEN = DL_UART_PARITY_EVEN, 
    UART_Parity_ODD  = DL_UART_PARITY_ODD,  
    UART_Parity_ZERO = DL_UART_PARITY_STICK_ZERO, 
    UART_Parity_ONE = DL_UART_PARITY_STICK_ONE 
} UART_Parity;

typedef struct {
    UART_Mode readMode;  
    UART_Mode writeMode; 
    UART_Callback readCallback;
    UART_Callback writeCallback;
    UART_EventCallback eventCallback;
    uint32_t eventMask;
    UART_ReadReturnMode readReturnMode; 
    uint32_t baudRate;                  
    UART_DataLen dataLength;            
    UART_StopBits stopBits;             
    UART_Parity parityType;             
    void *userArg; 
} UART_Params;

void UART_Params_init(UART_Params *params);

UART_Handle UART_open(uint_least8_t index, UART_Params *params);

void UART_close(UART_Handle handle);

int_fast16_t UART_read(UART_Handle handle, void *buf, size_t size, size_t *bytesRead);

int_fast16_t UART_write(UART_Handle handle, const void *buf, size_t size, size_t *bytesWritten);

int_fast16_t UART_readTimeout(UART_Handle handle, void *buf, size_t size, size_t *bytesRead, uint32_t timeout);

int_fast16_t UART_writeTimeout(UART_Handle handle, const void *buf, size_t size, size_t *bytesWritten, uint32_t timeout);

void UART_readCancel(UART_Handle handle);

void UART_writeCancel(UART_Handle handle);

void UART_rxDisable(UART_Handle handle);

void UART_rxEnable(UART_Handle handle);

void UART_flushRx(UART_Handle handle);

void UART_getRxCount(UART_Handle handle);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* ti_drivers_uart_UART__include */
/* clang-format on */