UART2.h

Go to the documentation of this file.

/*
 * Copyright (c) 2019-2023, 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       UART2.h
 *  @brief      <b>PRELIMINARY</b> UART driver interface
 *
 *  <b>WARNING</b> These APIs are <b>PRELIMINARY</b>, and subject to
 *  change in the next few months.
 *
 *  The UART2 driver is an updated version of the UART driver.  The name
 *  UART2 was given due to changes in the API, to support backwards
 *  compatibility with applications using the existing UART driver.
 *  Key differences between the UART and UART2 drivers:
 *      - UART2 has both RX and TX ring buffers for receiving/sending data.
 *      - UART2 uses DMA to transfer data between the UART FIFOs and the
 *        RX and TX ring buffers (in nonblocking mode). In blocking mode and
 *        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 UART2 APIs for reading and writing data have been made more
 *        posix-like.
 *      - UART2 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 UART2_EVENT_TX_FINISHED 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 UART2 driver, ensure that the correct driver library for your
 *  device is linked in and include this header file as follows:
 *  @code
 *  #include <ti/drivers/UART2.h>
 *  @endcode
 *
 *  This module serves as the main interface for applications.  Its purpose
 *  is to implement common code between the device specific implementations
 *  of UART2. Any device specific code that differs from the common code is
 *  called through functions prefaced with the "UART2_" naming convention.
 *  These functions are implemented in each device specific implementation.
 *
 *  @anchor ti_drivers_UART2_Overview
 *  # Overview
 *  A UART is used to translate data between the chip and a serial port.
 *  The UART2 driver simplifies reading and writing to any of the UART
 *  peripherals on the board, with multiple modes of operation and performance.
 *  These include blocking and nonblocking modes.
 *
 *  The UART2 driver interface provides device independent APIs, data types,
 *  and macros. The APIs in this driver serve as an interface to a typical RTOS
 *  application. The specific peripheral implementations are responsible for
 *  creating all the RTOS specific primitives to allow for thread-safe
 *  operation.
 *
 *  <hr>
 *  @anchor ti_drivers_UART2_Usage
 *  # Usage
 *
 *  This documentation provides a basic @ref ti_drivers_UART2_Synopsis
 *  "usage summary" and a set of @ref ti_drivers_UART2_Examples "examples"
 *  in the form of commented code fragments.  Detailed descriptions of the
 *  APIs are provided in subsequent sections.
 *
 *  @anchor ti_drivers_UART2_Synopsis
 *  ## Synopsis
 *  @anchor ti_drivers_UART2_Synopsis_Code
 *  @code
 *  // Import the UART2 driver definitions
 *  #include <ti/drivers/UART2.h>
 *
 *  // Initialize UART2 parameters
 *  UART2_Params params;
 *  UART2_Params_init(&params);
 *  params.baudRate = 9600;
 *  params.readMode = UART2_Mode_BLOCKING;
 *  params.writeMode = UART2_Mode_BLOCKING;
 *
 *  // Open the UART
 *  UART2_Handle uart;
 *  uart = UART2_open(CONFIG_UART0, &params);
 *
 *  // Enable receiver, inhibit low power mode
 *  UART2_rxEnable(uart);
 *
 *  // Read from the UART.
 *  size_t  bytesRead;
 *  uint8_t buffer[BUFSIZE];
 *  int32_t status;
 *  status = UART2_read(uart, buffer, BUFSIZE, &bytesRead);
 *
 *  // Write to the UART
 *  size_t  bytesWritten;
 *  status = UART2_write(uart, buffer, BUFSIZE, &bytesWritten);
 *
 *  // Close the UART
 *  UART2_close(uart);
 *  @endcode
 *
 *  <hr>
 *  @anchor ti_drivers_UART2_Examples
 *  # Examples
 *  The following code example opens a UART instance, reads
 *  a byte from the UART, and then writes the byte back to the UART.
 *
 *  @code
 *    char        input;
 *    UART2_Handle uart;
 *    UART2_Params uartParams;
 *
 *    // Open an instance of the UART2 driver
 *    UART2_Params_init(&uartParams);
 *    uartParams.baudRate = 115200;
 *    uart = UART2_open(CONFIG_UART0, &uartParams);
 *
 *    if (uart == NULL) {
 *        // UART2_open() failed
 *        while (1);
 *    }
 *
 *    // Enable receiver, inhibit low power mode
 *    UART2_rxEnable(uart);
 *
 *    // Loop forever echoing
 *    while (1) {
 *        status = UART2_read(uart, &input, 1, &bytesRead);
 *        status = UART2_write(uart, &input, 1, &bytesWritten);
 *    }
 *  @endcode
 *
 *  Details for the example code above are described in the following
 *  subsections.
 *
 *  ### Opening the UART2 Driver #
 *
 *  Opening a UART requires four steps:
 *  1.  Create and initialize a UART2_Params structure.
 *  2.  Fill in the desired parameters.
 *  3.  Call UART2_open(), passing the index of the UART in the UART2_config
 *      structure, and the address of the UART2_Params structure.  The
 *      UART2 instance is specified by the index in the UART2_config structure.
 *  4.  Check that the UART2 handle returned by UART2_open() is non-NULL,
 *      and save it.  The handle will be used to read and write to the
 *      UART you just opened.
 *
 *  Only one UART index can be used at a time; calling UART2_open() a second
 *  time with the same index previosly passed to UART2_open() will result in
 *  an error.  You can, though, re-use the index if the instance is closed
 *  via UART2_close().
 *  In the previous example code, CONFIG_UART0 is passed to UART2_open().
 *  This macro is defined in the example's ti_drivers_config.h file.
 *
 *
 *  ### Modes of Operation #
 *
 *  The UART driver can operate in blocking, nonblocking, or callback mode, by
 *  setting the writeMode and readMode parameters passed to UART2_open().
 *  If these parameters are not set, as in the example code, the UART2
 *  driver defaults to blocking mode.  Options for the writeMode and
 *  readMode parameters are #UART2_Mode_BLOCKING, #UART2_Mode_NONBLOCKING, and
 *  #UART2_Mode_CALLBACK:
 *
 *  - #UART2_Mode_BLOCKING uses a semaphore to block while data is being sent,
 *    or while waiting for some data to be received. The context of calling
 *    UART2_read() and UART2_write() in blocking mode must always be a Task.
 *    The UART2_write() call will block until all data has been transmitted
 *    onto the TX pin. The UART2_read() calls can be configured to
 *    have two different behaviors, using the #UART2_ReadReturnMode of the
 *    #UART2_Params.  In #UART2_ReadReturnMode_FULL (the default),
 *    UART2_read() will block until the requested number of bytes has been
 *    received.  In #UART2_ReadReturnMode_PARTIAL, UART2_read() will block
 *    until either the requested number of bytes has been received,
 *    or a UART hardware read timeout has occurred.  Using
 *    UART2_ReadReturnMode_PARTIAL is a good choice if the number of
 *    incoming data bytes is unknown.  In UART2_Mode_BLOCKING,
 *    UART2_read() will always return at least some data.
 *    UART2_readTimeout() can be used to specify a timeout in system
 *    clock ticks, to wait for data.
 *    UART2_readTimeout() will return when all data is received, or
 *    the specified timeout expires, or, if using the mode
 *    UART2_ReadReturnMode_PARTIAL, a hardware read timeout occurs,
 *    whichever happens first.
 *
 *  - #UART2_Mode_NONBLOCKING does not block waiting for data to be sent
 *    or received.  UART2_write() and UART2_read() will return immediately
 *    having transferred as much data as the driver can immediately accept
 *    or has available, respectively.  If no data can be accepted or
 *    received, UART2_write() and UART2_read() return UART2_STATUS_EAGAIN.
 *
 *  - #UART2_Mode_CALLBACK is nonblocking and UART2_read() and UART2_write()
 *    will return while data is being sent in the context of a hardware
 *    interrupt.  When all data has been read from, or written to the hardware
 *    FIFO, the UART2 driver will call the user's callback function, and the
 *    driver is ready to accept another read or write operation.
 *    @note When transmitting, it is therefore not guaranteed that all data has
 *    been shifted out to the TX pin when the write-callback is invoked. This is
 *    instead signalled by the UART2_EVENT_TX_FINISHED event.
 *    In some cases, the UART data transfer may have been cancelled,
 *    so the number of bytes sent/received are passed to the callback function.
 *    Your implementation of the callback function can use this information as needed.
 *    Since the user's callback may be called in the context of a hardware
 *    interrupt, the callback function must not make any RTOS blocking calls.
 *    The buffer passed to UART2_write() in UART2_Mode_CALLBACK must remain
 *    coherent until all the characters have been sent
 *    (ie until the tx callback has been called with a byte count equal to
 *    that passed to UART2_write()).
 *
 *  ### Enabling the Receiver #
 *
 *  The example code enables the collection of data into the RX ring buffer
 *  \a before the first call to UART2_read():
 *
 *  @code
 *  UART2_rxEnable(uart);
 *  @endcode
 *
 *  Note that this call is not necessary if the first UART2_read() is called
 *  in time to prevent the RX FIFO from overrun, or if flow control is used.
 *
 *  ### Reading and Writing Data #
 *
 *  The example code reads one byte frome the UART instance, and then writes
 *  one byte back to the same instance:
 *
 *  @code
 *  status = UART2_read(uart, &input, 1, &bytesRead);
 *  status = UART2_write(uart, &input, 1, &bytesWritten);
 *  @endcode
 *
 *  The UART2 driver allows full duplex data transfers. Therefore, it is
 *  possible to call UART2_read() and UART2_write() at the same time.
 *  It is not possible, however,
 *  to issue multiple concurrent operations in the same direction.
 *  For example, if one thread calls UART2_read(uart0, buffer0...),
 *  any other thread attempting UART2_read(uart0, buffer1...) will result in
 *  an error of UART2_STATUS_EINUSE, until all the data from the first
 *  UART2_read() has been transferred to buffer0. This applies to blocking,
 *  callback, and nonblocking modes. So applications must either synchronize
 *  UART2_read() (or UART2_write()) calls that use the same UART handle, or
 *  check for the UART2_STATUS_EINUSE return code indicating that a transfer is
 *  still ongoing.
 *
 *  <hr>
 *  @anchor ti_drivers_UART2_Configuration
 *  # Configuration
 *
 *  Refer to the @ref driver_configuration "Driver's Configuration" section
 *  for driver configuration information.
 *  <hr>
 *
 *  ============================================================================
 */

#ifndef ti_drivers_UART2__include
#define ti_drivers_UART2__include

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

#include <ti/drivers/Power.h>

#include <ti/drivers/dpl/ClockP.h>
#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/dpl/SemaphoreP.h>
#include <ti/drivers/utils/RingBuf.h>

#ifdef __cplusplus
extern "C" {
#endif

#define UART2_FLOWCTRL_NONE 0

#define UART2_FLOWCTRL_HARDWARE 1

#define UART2_STATUS_SUCCESS (0)

#define UART2_STATUS_SREADTIMEOUT (1)

#define UART2_STATUS_EFRAMING (-1)

#define UART2_STATUS_EPARITY (-2)

#define UART2_STATUS_EBREAK (-4)

#define UART2_STATUS_EOVERRUN (-8)

#define UART2_STATUS_EINUSE (-9)

#define UART2_STATUS_EINVALID (-10)

#define UART2_STATUS_EFAIL (-11)

#define UART2_STATUS_EMEMORY (-12)

#define UART2_STATUS_ETIMEOUT (-13)

#define UART2_STATUS_ECANCELLED (-14)

#define UART2_STATUS_ENOTOPEN (-15)

#define UART2_STATUS_EAGAIN (-16)

#define UART2_EVENT_OVERRUN (0x08)

#define UART2_EVENT_BREAK (0x04)

#define UART2_EVENT_PARITY (0x02)

#define UART2_EVENT_FRAMING (0x01)

#define UART2_EVENT_TX_BEGIN (0x10)

#define UART2_EVENT_TX_FINISHED (0x20)

#define UART2_WAIT_FOREVER (~(0U))

typedef struct UART2_Config_ *UART2_Handle;

typedef void (*UART2_Callback)(UART2_Handle handle, void *buf, size_t count, void *userArg, int_fast16_t status);

typedef void (*UART2_EventCallback)(UART2_Handle handle, uint32_t event, uint32_t data, void *userArg);

typedef enum
{
    UART2_Mode_BLOCKING,

    UART2_Mode_CALLBACK,

    UART2_Mode_NONBLOCKING,
    /* Added for backwards compatibility. */
    UART2_Mode_POLLING = UART2_Mode_NONBLOCKING
} UART2_Mode;

typedef enum
{
    UART2_ReadReturnMode_FULL,

    UART2_ReadReturnMode_PARTIAL
} UART2_ReadReturnMode;

typedef enum
{
    UART2_DataLen_5 = 0, 
    UART2_DataLen_6 = 1, 
    UART2_DataLen_7 = 2, 
    UART2_DataLen_8 = 3  
} UART2_DataLen;

typedef enum
{
    UART2_StopBits_1 = 0, 
    UART2_StopBits_2 = 1  
} UART2_StopBits;

typedef enum
{
    UART2_Parity_NONE = 0, 
    UART2_Parity_EVEN = 1, 
    UART2_Parity_ODD  = 2, 
    UART2_Parity_ZERO = 3, 
    UART2_Parity_ONE  = 4  
} UART2_Parity;

typedef struct
{
    UART2_Mode readMode;                 
    UART2_Mode writeMode;                
    UART2_Callback readCallback;         
    UART2_Callback writeCallback;        
    UART2_EventCallback eventCallback;   
    uint32_t eventMask;                  
    UART2_ReadReturnMode readReturnMode; 
    uint32_t baudRate;                   
    UART2_DataLen dataLength;            
    UART2_StopBits stopBits;             
    UART2_Parity parityType;             
    void *userArg;                       
} UART2_Params;

#define UART2_BASE_OBJECT                                                                 \
    /* UART2 state variable */                                                            \
    struct                                                                                \
    {                                                                                     \
        uint32_t overrunCount;                             \
        UART2_Mode readMode;                                   \
        UART2_Mode writeMode;                                 \
        UART2_ReadReturnMode readReturnMode;         \
        bool opened;                                       \
        bool txEnabled;                               \
        bool rxEnabled;                                \
        bool rxCancelled;                                 \
        bool txCancelled;                                 \
        bool readTimedOut;                                      \
        bool writeTimedOut;                                    \
        bool overrunActive;                                 \
        bool inReadCallback;                               \
        bool readCallbackPending;                          \
        bool inWriteCallback;                              \
        bool writeCallbackPending;                         \
        bool readToRingbuf;                   \
    } state;                                                                              \
                                                                                          \
    HwiP_Struct hwi;                                     \
    uint32_t baudRate;                                          \
    UART2_DataLen dataLength;                                 \
    UART2_StopBits stopBits;                                    \
    UART2_Parity parityType;                              \
    int32_t rxStatus;                                                    \
    int32_t txStatus;                                                    \
    UART2_EventCallback eventCallback;                \
    uint32_t eventMask;                                   \
    void *userArg;                                 \
                                                                                          \
    /* UART read variables */                                                             \
    RingBuf_Object rxBuffer;                                   \
    bool readInUse;                                             \
    unsigned char *readBuf;                                    \
    size_t readSize;                                       \
    size_t readCount;                                 \
    size_t rxSize;                                  \
    size_t bytesRead;                                         \
    SemaphoreP_Struct readSem;                                 \
    UART2_Callback readCallback;                          \
                                                                                          \
    /* UART write variables */                                                            \
    RingBuf_Object txBuffer;                                  \
    volatile bool writeInUse;                           \
    const unsigned char *writeBuf;                             \
    size_t writeSize;                                      \
    size_t writeCount;                               \
    size_t txSize;                                    \
    size_t bytesWritten;                                   \
    SemaphoreP_Struct writeSem;                                \
    UART2_Callback writeCallback;                        \
                                                                                          \
    /* For Power management */                                                            \
    Power_Resource powerMgrId;                        \

typedef struct
{
    UART2_BASE_OBJECT
} UART2_Object;
#define UART2_BASE_HWATTRS                           \
            \
    uint32_t baseAddr;                               \
        \
    int intNum;                                      \
      \
    uint8_t intPriority;                             \
       \
    unsigned char *rxBufPtr;                         \
                          \
    size_t rxBufSize;                                \
       \
    unsigned char *txBufPtr;                         \
                          \
    size_t txBufSize;                                \
             \
    uint32_t flowControl;                            \
                    \
    uint32_t rxPin;                                  \
                    \
    uint32_t txPin;                                  \
   \
    uint32_t ctsPin;                                 \
 \
    uint32_t rtsPin;                                 \

typedef struct
{
    UART2_BASE_HWATTRS
} UART2_HWAttrs;
typedef struct UART2_Config_
{
    void *object;

    void const *hwAttrs;
} UART2_Config;

extern const UART2_Config UART2_config[];
extern const uint_least8_t UART2_count;

extern void UART2_close(UART2_Handle handle);

extern void UART2_flushRx(UART2_Handle handle);

extern size_t UART2_getRxCount(UART2_Handle handle);

extern UART2_Handle UART2_open(uint_least8_t index, UART2_Params *params);

extern void UART2_Params_init(UART2_Params *params);

extern int_fast16_t UART2_read(UART2_Handle handle, void *buffer, size_t size, size_t *bytesRead);

extern int_fast16_t __attribute__((weak))
UART2_readFull(UART2_Handle handle, void *buffer, size_t size, size_t *bytesRead);
extern int_fast16_t UART2_readTimeout(UART2_Handle handle,
                                      void *buffer,
                                      size_t size,
                                      size_t *bytesRead,
                                      uint32_t timeout);

extern void UART2_readCancel(UART2_Handle handle);

extern int_fast16_t UART2_write(UART2_Handle handle, const void *buffer, size_t size, size_t *bytesWritten);

extern void UART2_rxDisable(UART2_Handle handle);

extern void UART2_rxEnable(UART2_Handle handle);

extern int_fast16_t UART2_writeTimeout(UART2_Handle handle,
                                       const void *buffer,
                                       size_t size,
                                       size_t *bytesWritten,
                                       uint32_t timeout);

extern void UART2_writeCancel(UART2_Handle handle);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_UART2__include */