UART2.h

Go to the documentation of this file.

/*
 * Copyright (c) 2019-2020, 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.
 *
 *  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 redirect the UART2 APIs to specific driver implementations
 *  which are specified using a pointer to a #UART2_FxnTable.
 *
 *  @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, non-blocking, and polling 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);
 *
 *  // 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);
 *    }
 *
 *    // 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, callback, or polling 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_CALLBACK, and
 *  #UART2_Mode_POLLING:
 *
 *  - #UART2_Mode_BLOCKING uses a semaphore to block while data is being sent.
 *    The context of calling UART2_read() and UART2_write() must be a Task when
 *    using #UART2_Mode_BLOCKING.  The UART2_write() or UART2_read() call
 *    will block until all data is sent or received, or an error occurs (e.g.,
 *    framing or FIFO overrun).  In #UART2_Mode_BLOCKING, 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 an error occurs, whichever happens
 *    first.
 *
 *  - #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 is not copied.
 *    The buffer 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()).
 *
 *  ### 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 (for
 *  either blocking or callback modes). 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 polling 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>

#ifdef __cplusplus
extern "C" {
#endif

#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_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 enum {
    UART2_Mode_BLOCKING,

    UART2_Mode_CALLBACK,

    UART2_Mode_POLLING
} 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_ReadReturnMode readReturnMode;  
    uint32_t        baudRate;        
    UART2_DataLen   dataLength;      
    UART2_StopBits  stopBits;        
    UART2_Parity    parityType;      
    void           *userArg;         
} UART2_Params;

typedef void (*UART2_CloseFxn) (UART2_Handle handle);

typedef void (*UART2_FlushRxFxn) (UART2_Handle handle);

typedef UART2_Handle (*UART2_OpenFxn) (uint_least8_t index, UART2_Params *params);

typedef int_fast16_t (*UART2_ReadFxn) (UART2_Handle handle,
        void *buffer, size_t size, size_t *bytesRead, uint32_t timeout);

typedef void (*UART2_ReadCancelFxn) (UART2_Handle handle);

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

typedef void (*UART2_WriteCancelFxn) (UART2_Handle handle);

typedef struct {
    UART2_CloseFxn        closeFxn;

    UART2_OpenFxn         openFxn;

    UART2_ReadFxn         readFxn;

    UART2_ReadCancelFxn   readCancelFxn;

    UART2_WriteFxn        writeFxn;

    UART2_WriteCancelFxn  writeCancelFxn;

    UART2_FlushRxFxn      flushRxFxn;
} UART2_FxnTable;

typedef struct UART2_Config_ {
    UART2_FxnTable const *fxnTablePtr;

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