UART2.h

Go to the documentation of this file.

/*
 * Copyright (c) 2019-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       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.
 *      - 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.
 *
 *  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 non-blocking 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, non-blocking, 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 copied to
 *    the TX circular buffer.  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 non-blocking and UART2_read() and UART2_write()
 *    will return while data is being sent in the context of a hardware
 *    interrupt.  When the read or write finishes, the UART2 driver will call
 *    the user's callback function.  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 non-blocking 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/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;     /* total count of overruns */ \
        bool             opened:1;         /* Has the obj been opened */ \
        UART2_Mode       readMode;         /* Mode for read calls */ \
        UART2_Mode       writeMode;        /* Mode for write calls */ \
        UART2_ReadReturnMode readReturnMode:1; /* RX return mode (partial/full) */ \
        bool             txEnabled:1;      /* Flag set if ongoing transmit */ \
        bool             rxEnabled:1;      /* Flag set if ongoing receive */ \
        bool             rxCancelled:1;    /* Has the TX been canceled */ \
        bool             txCancelled:1;    /* Has the TX been canceled */ \
        bool             readTimedOut:1;   /* Has read timed out */ \
        bool             writeTimedOut:1;  /* Has write timed out */ \
        bool             overrunActive:1;  /* Is a RX overrun active */ \
        bool             inReadCallback:1; /* To avoid stack overflow */ \
        bool             readCallbackPending:1; /* To avoid stack overflow */ \
        bool             inWriteCallback:1; /* To avoid stack overflow */ \
        bool             writeCallbackPending:1; /* To avoid stack overflow */ \
    } state; \
    \
    HwiP_Struct          hwi;              /* Hwi object for interrupts */ \
    uint32_t             baudRate;         /* Baud rate for UART */ \
    UART2_DataLen        dataLength;       /* Data length for UART */ \
    UART2_StopBits       stopBits;         /* Stop bits for UART */ \
    UART2_Parity         parityType;       /* Parity bit type for UART */ \
    int32_t              rxStatus;         /* RX status */ \
    int32_t              txStatus;         /* TX status */ \
    UART2_EventCallback  eventCallback;    /* User supplied event callback */ \
    uint32_t             eventMask;        /* User supplied event mask */ \
    void                *userArg;          /* User supplied arg for callbacks */ \
    \
    /* UART read variables */ \
    RingBuf_Object       rxBuffer;         /* Receive ring buffer */ \
    bool                 readInUse;        /* Is a read() active */ \
    unsigned char       *readBuf;          /* Buffer data pointer */ \
    size_t               readSize;         /* Number of bytes to read */ \
    uint32_t             nReadTransfers;   /* Number of DMA transfers needed */ \
    size_t               readCount;        /* Number of bytes left to read */ \
    size_t               rxSize;           /* # of bytes to read in DMA xfer */ \
    size_t               bytesRead;        /* Number of bytes read */ \
    SemaphoreP_Struct    readSem;          /* UART read semaphore */ \
    ClockP_Struct        readTimeoutClk;   /* Clock object to for timeouts */ \
    UART2_Callback       readCallback;     /* Pointer to read callback */ \
    \
    /* UART write variables */ \
    RingBuf_Object       txBuffer;         /* Transmit ring buffer */ \
    volatile bool        writeInUse;       /* Flag to show ongoing write */ \
    const unsigned char *writeBuf;         /* Buffer data pointer */ \
    size_t               writeSize;        /* Number of bytes to write*/ \
    uint32_t             nWriteTransfers;  /* Number of DMA transfers needed */\
    size_t               writeCount;       /* Number of bytes left to write */ \
    size_t               txSize;           /* # of bytes to write with DMA */ \
    size_t               bytesWritten;     /* Number of bytes written */ \
    SemaphoreP_Struct    writeSem;         /* UART write semaphore*/ \
    ClockP_Struct        writeTimeoutClk;  /* Clock object to for timeouts */ \
    UART2_Callback       writeCallback;    /* Pointer to write callback */ \
    \
    /* For Power management */ \
    unsigned int         powerMgrId;       /* Determined from base address */ \

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 */