uart.h

Go to the documentation of this file.

#ifndef UART_H
#define UART_H
/**********************************************************************/
/*
 * Copyright (c) 2013-2015, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. 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.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``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 AUTHOR 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.
 *
 * This file is part of the EVE platform.
 */

/**
 * @file
 * @brief Abstract UART driver header.
 *
 * @author: PE, SE, Jetro AS
 */ /*******************************************************************/

#include <core/clk.h>
#include <core/pm.h>
#include <core/uwork.h>
#include <dev/data-buffer.h>
#include <hal/nrf_uarte.h>
#include <lib/assert.h>

/**
 * \defgroup uart UART driver
 * \ingroup abstract
 * \{
 *
 * Abstract UART driver header.
 *
 * This UART driver provides common interface to various UART block(s).
 * Functionality included:
 * - Init and disable of Uart driver.
 * - Handling RX interrupts with timeout after rx-data pause (ex. pause after an received message)
 */

/***********************************************************************
 * Global defines
***********************************************************************/
/** UART flow control settings */
enum uart_flow_control_t
{
  UART_FLOW_CONTROL_DISABLED = NRF_UARTE_HWFC_DISABLED, //!< Flow control OFF
  UART_FLOW_CONTROL_CTSRTS   = NRF_UARTE_HWFC_ENABLED, //!< HW flow control
  UART_FLOW_CONTROL_XONXOFF  = 2, //!< SW flow control
};

/** UART parity settings */
enum uart_parity_t
{
  UART_PARITY_NONE    = NRF_UARTE_PARITY_EXCLUDED, //!< No parity bit
  UART_PARITY_EVEN    = NRF_UARTE_PARITY_INCLUDED, //!< Parity bit is on. Calculate even parity.
  UART_PARITY_ODD     = 1, //!< Parity bit is on. Calculate odd parity.
  UART_PARITY_FORCED1 = 2, //!< Parity bit is on and always 1.
  UART_PARITY_FORCED0 = 3, //!< Parity bit is on and always 0.
};
CTASSERT(UART_PARITY_NONE < UART_PARITY_ODD);
CTASSERT(UART_PARITY_EVEN > UART_PARITY_FORCED0);
CTASSERT(UART_PARITY_NONE < (1 << 4));
CTASSERT(UART_PARITY_EVEN < (1 << 4));

/** UART stop bits settings */
enum uart_stops_t
{
  UART_STOP_1 = 0, //!< One stop bit
  UART_STOP_2 = 1, //!< Two stop bits
};

/** Status of finished Rx operation */
enum uart_rx_status_t
{
  UART_RX_OK,               //!< Receiving completed successfully
  UART_RX_TIMEOUT,          //!< Timeout while receiving (long delay after the last char received, typically 4 chars pause)
  UART_RX_ERROR_OVERRUN,    //!< Buffer overrun while receiving
  UART_RX_ERROR_PARITY,     //!< Parity error while receiving
  UART_RX_ERROR_FRAMING,    //!< Frame error (no stop bit) while receiving
  UART_RX_ERROR_BREAK,      //!< Break received
  UART_RX_CANCELLED,        //!< Rx was aborted by UartCancelRx()
};

enum
{
  UART_RX_TIMEOUT_DEFAULT = 0,            //!< No Rx timeout: check buffer and return immedialely
  UART_RX_TIMEOUT_INFINITE = 0xFFFFFFFF,  //!< No Rx timeout: wait forever
};

/** Length of one UART word. */
enum uart_wordlen_t
{
  UART_WORDLEN_DEFAULT = 0, //!< default word length (8 bit)
  UART_WORDLEN_5 = 5,       //!< 5 bit word length
  UART_WORDLEN_6 = 6,       //!< 6 bit word length
  UART_WORDLEN_7 = 7,       //!< 7 bit word length
  UART_WORDLEN_8 = 8,       //!< 8 bit word length
};

struct uart_t;

/**
 * The callback is called at completion of an asynchronous receive.
 *
 * @param Uart        UART to be used
 * @param CallbackData User-defined data
 * @param ...TODO
 */
typedef void (*uart_rx_callback_t)(const struct uart_t *Uart, void *CallbackData, enum uart_rx_status_t RxStatus);

/**
 * The callback is called at completion of an asynchronous transmit.
 *
 * @param Uart        UART to be used
 * @param CallbackData User-defined data
 */
typedef void (*uart_tx_callback_t)(const struct uart_t *Uart, void *CallbackData);

/**
 * The callback is called at completion of break sending.
 *
 * @param Uart        UART to be used
 * @param CallbackData User-defined data
 */
typedef void (*uart_break_callback_t)(const struct uart_t *Uart, void *CallbackData);


/**
 * UART driver virtual function types
 */
typedef void (*uart_init_t)(const struct uart_t *Uart);
typedef void (*uart_disable_t)(const struct uart_t *Uart);
typedef void (*uart_start_basic_tx_t)(const struct uart_t *Uart, uint8_t *DataSrc, uint16_t DataSize, uart_tx_callback_t Callback, void *CallbackData);
typedef void (*uart_start_ping_pong_tx_t)(const struct uart_t *Uart, uint8_t *PrimDataSrc, uint16_t PrimDataSize, uint8_t *AltDataSrc, uint16_t AltDataSize, uart_tx_callback_t Callback, void *CallbackData);
typedef void (*uart_refresh_ping_pong_tx_t)(const struct uart_t *Uart, uint8_t *DataSrc, uint16_t DataSize, bool Stop);
typedef void (*uart_start_basic_rx_t)(const struct uart_t *Uart, uint8_t *DataDest, uint16_t DataSize, uart_rx_callback_t Callback, void *CallbackData);
typedef void (*uart_start_ping_pong_rx_t)(const struct uart_t *Uart, uint8_t *PrimDataDest, uint16_t PrimDataSize, uint8_t *AltDataDest, uint16_t AltDataSize, uart_rx_callback_t Callback, void *CallbackData);
typedef void (*uart_refresh_ping_pong_rx_t)(const struct uart_t *Uart, uint8_t *DataDest, uint16_t DataSize, bool Stop);
typedef void (*uart_reset_fifo_t)(const struct uart_t* Uart, bool Tx, bool Rx);
typedef void (*uart_cancel_rx_t)(const struct uart_t *Uart);
typedef bool (*uart_is_busy_rx_t)(const struct uart_t *Uart);
typedef void (*uart_cancel_tx_t)(const struct uart_t *Uart);
typedef bool (*uart_is_busy_tx_t)(const struct uart_t *Uart);
typedef void (*uart_set_baudrate_t)(const struct uart_t *Uart);
typedef void (*uart_set_rx_timeouts_t)(const struct uart_t *Uart, uint32_t RxStartTimeoutUs, uint32_t RxStopTimeoutUs);
typedef void (*uart_send_break)(const struct uart_t *Uart, uart_break_callback_t Callback, void *CallbackData);
typedef void (*uart_set_rts)(const struct uart_t *Uart, bool Active);
typedef void (*uart_interrupt_handler_t)(const struct uart_t *Uart);

/**
 * UART driver run-time state
 */
struct uart_state_t
{
  const struct uart_t* Uart;                 //!< Backpointer to the static configuration
  uint32_t Baudrate;                         //!< Current baudrate in bit/s.
  uint32_t RxStartTimeoutUs;                 //!< Current value for the max time the driver waits for the first symbol in a message
  uint32_t RxStopTimeoutUs;                  //!< Current value for the max time the driver waits for the next symbol in a message
  struct data_buffer_t RxBuffer[2];          //!< Receive buffer for asynchronous transfers
  uart_rx_callback_t RxCallback;             //!< RX completion callback
  void *RxCallbackData;                      //!< Data for the RX completion callback
  uint8_t RxBufIndex;                        //!< Index of the active RX buffer
  uint8_t RxStop;                            //!< Amount of RX buffers in the pipeline
  uint8_t RxCancelled;                       //!< RX is cancelled
  struct data_buffer_t TxBuffer[2];          //!< Transmit buffer for asynchronous transfers
  uart_tx_callback_t TxCallback;             //!< TX completion callback
  void *TxCallbackData;                      //!< Data for the TX completion callback
  uint8_t TxBufIndex;                        //!< Index of the active TX buffer
  uint8_t TxStop;                            //!< Amount of TX buffers in the pipeline
  uart_break_callback_t BreakCallback;       //!< Send Break completion callback
  void* BreakCallbackData;                   //!< Data for the Break send completion callback
  struct uwork_t SendBreakWork;              //!< timeout counter for Send Break
};

/**
 * UART driver virtual function table
 */
struct uart_api_t
{
  uart_init_t UartInit;
  uart_disable_t UartDisable;
  uart_start_basic_tx_t UartStartBasicTx;
  uart_start_ping_pong_tx_t UartStartPingPongTx;
  uart_refresh_ping_pong_tx_t UartRefreshPingPongTx;
  uart_start_basic_rx_t UartStartBasicRx;
  uart_start_ping_pong_rx_t UartStartPingPongRx;
  uart_refresh_ping_pong_rx_t UartRefreshPingPongRx;
  uart_reset_fifo_t UartResetFifo;
  uart_cancel_rx_t UartCancelRx;
  uart_is_busy_rx_t UartIsBusyRx;
  uart_cancel_tx_t UartCancelTx;
  uart_is_busy_tx_t UartIsBusyTx;
  uart_set_baudrate_t UartSetBaudrate;
  uart_set_rx_timeouts_t UartSetRxTimeouts;
  uart_send_break UartSendBreak;
  uart_set_rts UartSetRts;
};

/**
 * UART driver configuration data
 */
struct uart_t
{
  const void* Impl;               //!< Device specific configuration data
  struct uart_state_t* State;     //!< Address to struct with RAM variables used by the uart driver
  uint32_t Baudrate    : 20;      //!< Default baudrate in bit/s.
  uint32_t FlowControl :  2;      //!< @ref uart_flow_control_t
  uint32_t RtsInverse  :  1;      //!< Inverted RTS line (active 1)
  uint32_t Parity      :  4;      //!< @ref uart_parity_t
  uint32_t StopBits    :  1;      //!< @ref uart_stops_t
  uint32_t WordLength  :  4;      //!< @ref uart_wordlen_t
  uint32_t RxStartTimeoutUs;      //!< Default value for the max time the driver waits for the first symbol in a message
  uint32_t RxStopTimeoutUs;       //!< Default value for the max time the driver waits for the next symbol in a message
  const struct uart_api_t* Func;  //!< Virtual function table
};

#define UART_VCALL(Uart, Fn) (Uart)->Func->Fn

/**********************************************************************/
/**
 * @brief Name: UartInit\n
 * Initializes Uart
 *
 * @param Uart UART parameters to be used.
 * @return void
 ***********************************************************************/
static inline void UartInit(const struct uart_t *Uart)
{
  UART_VCALL(Uart, UartInit)(Uart);
}

/**********************************************************************/
/**
 * @brief Name: UartDisable\n
 * Disables UART
 *
 * @param Uart UART parameters to be used.
 * @return void
 ***********************************************************************/
static inline void UartDisable(const struct uart_t *Uart)
{
  UART_VCALL(Uart, UartDisable)(Uart);
}

/**********************************************************************/
/**
 * @brief Name: UartDmaBytesReceived\n
 * Will return number of received bytes for current DMA transfer.
 *
 * @param Uart UART parameters to be used.
 * @return     Number of received bytes for current DMA transfer
***********************************************************************/
static inline uint32_t UartDmaBytesReceived(const struct uart_t *Uart)
{
  struct uart_state_t *State = Uart->State;
  return State->RxBuffer[State->RxBufIndex].Pos;
}

/**********************************************************************/
/**
 * @brief Name: UartStartBasicTx\n
 * Transmit data using DMA transfer in basic mode.
 * Using primary DMA descriptor only.
 *
 * @param Uart UART parameters to be used.
 * @param DataSrc    Source address for DMA transfer
 * @param DataSize   Number of DMA transfer bytes. Range: 1 through 255
 * @param Callback   User-defined function to be called at completion
 * @param CallbackData User-defined data for the completion callback
 * @return void
***********************************************************************/
static inline void UartStartBasicTx(const struct uart_t *Uart,
                                    uint8_t *DataSrc, uint16_t DataSize,
                                    uart_tx_callback_t Callback, void *CallbackData)
{
  UART_VCALL(Uart, UartStartBasicTx)(Uart, DataSrc, DataSize, Callback, CallbackData);
}

/**********************************************************************/
/**
 * @brief Name: UartStartPingPongTx\n
 * Transmit data using DMA transfer in PingPong mode.
 * Will alternate between primary and alternate DMA descriptor
 *
 * @param Uart           UART parameters to be used.
 * @param PrimDataSrc    Source address for DMA transfer using primary descriptor
 * @param PrimDataSize   Number of DMA transfer bytes using primary descriptor. Range: 1 through 1024
 * @param AltDataSrc     Source address for DMA transfer using alternate descriptor
 * @param AltDataSize    Number of DMA transfer bytes using alternate descriptor. Range: 1 through 1024
 * @param Callback       User-defined function to be called at completion
 * @param CallbackData   User-defined data for the completion callback
 * @return void
***********************************************************************/
static inline void UartStartPingPongTx(const struct uart_t *Uart,
                                       uint8_t *PrimDataSrc, uint16_t PrimDataSize,
                                       uint8_t *AltDataSrc, uint16_t AltDataSize,
                                       uart_tx_callback_t Callback, void *CallbackData)
{
  UART_VCALL(Uart, UartStartPingPongTx)(Uart, PrimDataSrc, PrimDataSize,
                                        AltDataSrc, AltDataSize,
                                        Callback, CallbackData);
}

/**********************************************************************/
/**
 * @brief Name: UartRefreshPingPongTx\n
 * Refresh transmit of data using DMA transfer in PingPong mode.
 *
 * @param Uart        UART parameters to be used.
 * @param DataSrc     Source address for DMA transfer. NULL to leave descriptor as is.
 * @param DataSize    Number of DMA transfer bytes. Range: 1 through 1024
 * @param Stop        Indicate that DMA transfer shall stop after using this descriptor.
 * @return void
***********************************************************************/
static inline void UartRefreshPingPongTx(const struct uart_t *Uart,
                                         uint8_t *DataSrc, uint16_t DataSize,
                                         bool Stop)
{
  UART_VCALL(Uart, UartRefreshPingPongTx)(Uart, DataSrc, DataSize, Stop);
}

/**********************************************************************/
/**
 * @brief Name: UartGetTxBuffer\n
 * Returns the current TX buffer.
 *
 * @param Uart        UART parameters to be used.
 * @return            Pointer to the active TX buffer
***********************************************************************/
static inline struct data_buffer_t *UartGetTxBuffer(const struct uart_t *Uart)
{
  struct uart_state_t *State = Uart->State;
  return &State->TxBuffer[State->TxBufIndex];
}

/**********************************************************************/
/**
 * @brief Name: UartStartBasicRx\n
 * Receive data using DMA transfer in basic mode.
 * Using primary DMA descriptor only.
 *
 * @param Uart      UART parameters to be used.
 * @param DataDest  Destination address for DMA transfer
 * @param DataSize  Number of DMA transfer bytes. Range: 1 through 1024
 * @param Callback  User-defined function to be called at completion or timeout
 * @param CallbackData User-defined data for the completion callback
 * @return void
***********************************************************************/
static inline void UartStartBasicRx(const struct uart_t *Uart,
                                    uint8_t *DataDest, uint16_t DataSize,
                                    uart_rx_callback_t Callback, void *CallbackData)
{
  UART_VCALL(Uart, UartStartBasicRx)(Uart, DataDest, DataSize, Callback, CallbackData);
}

/**********************************************************************/
/**
 * @brief Name: UartStartPingPongRx\n
 * Receive data using DMA transfer in PingPong mode.
 * Will alternate between primary and alternate DMA descriptor
 *
 * @param Uart           UART parameters to be used.
 * @param PrimDataDest   Destination address for DMA transfer using primary descriptor
 * @param PrimDataSize   Number of DMA transfer bytes using primary descriptor. Range: 1 through 1024
 * @param AltDataDest    Destination address for DMA transfer using alternate descriptor
 * @param AltDataSize    Number of DMA transfer bytes using alternate descriptor. Range: 1 through 1024
 * @param Callback       User-defined function to be called at completion or timeout
 * @param CallbackData   User-defined data for the completion callback
 * @return void
***********************************************************************/
static inline void UartStartPingPongRx(const struct uart_t *Uart,
                             uint8_t *PrimDataDest, uint16_t PrimDataSize,
                             uint8_t *AltDataDest, uint16_t AltDataSize,
                             uart_rx_callback_t Callback, void *CallbackData)
{
  UART_VCALL(Uart, UartStartPingPongRx)(Uart, PrimDataDest, PrimDataSize,
                                        AltDataDest, AltDataSize,
                                        Callback, CallbackData);
}

/**********************************************************************/
/**
 * @brief Name: UartRefreshPingPongRx\n
 * Refresh of receive data using DMA transfer in PingPong mode.
 * Will alternate between primary and alternate DMA descriptor
 *
 * @param Uart           UART parameters to be used.
 * @param DataDest       Destination address for DMA transfer. NULL to leave descriptor as is.
 * @param DataSize       Number of DMA transfer bytes using primary descriptor. Range: 1 through 1024
 * @param Stop           Indicate that DMA transfer shall stop after using this descriptor.
 * @return void
***********************************************************************/
static inline void UartRefreshPingPongRx(const struct uart_t *Uart,
                                         uint8_t *DataDest, uint16_t DataSize,
                                         bool Stop)
{
  UART_VCALL(Uart, UartRefreshPingPongRx)(Uart, DataDest, DataSize, Stop);
}

/**********************************************************************/
/**
 * @brief Name: UartGetRxBuffer\n
 * Returns the current RX buffer.
 *
 * @param Uart        UART parameters to be used.
 * @return            Pointer to the active RX buffer
***********************************************************************/
static inline const struct data_buffer_t *UartGetRxBuffer(const struct uart_t *Uart)
{
  struct uart_state_t *State = Uart->State;
  return &State->RxBuffer[State->RxBufIndex];
}

/**********************************************************************/
/**
 * @brief Name: UartResetFifo\n
 * Resets FIFO buffer for Tx or Rx or both.\n
 * NB: Resetting Rx FIFO stops receiving
 *
 * @param Uart      UART parameters to be used.
 * @param Tx        Set to TRUE to reset Tx FIFO.
 * @param Rx        Set to TRUE to reset Rx FIFO.
 * @return void
***********************************************************************/
static inline void UartResetFifo(const struct uart_t* Uart, bool Tx, bool Rx)
{
  UART_VCALL(Uart, UartResetFifo)(Uart, Tx, Rx);
}

/**********************************************************************/
/**
 * @brief Name: UartCancelRx\n
 * Shuts down DMA, flushes FIFO and disables RX interrupts for the UART
 *
 * @param Uart      UART parameters to be used.
 * @return void
***********************************************************************/
static inline void UartCancelRx(const struct uart_t *Uart)
{
  UART_VCALL(Uart, UartCancelRx)(Uart);
}

/**********************************************************************/
/**
 * @brief Name: UartIsBusyRx\n
 * Returns busy status of the UART RX path
 *
 * @param Uart      UART parameters to be used.
 * @return          true if UART is receiving data
***********************************************************************/
static inline bool UartIsBusyRx(const struct uart_t *Uart)
{
  return UART_VCALL(Uart, UartIsBusyRx)(Uart);
}

/**********************************************************************/
/**
 * @brief Name: UartCancelTx\n
 * Shuts down DMA, flushes FIFO and disables TX interrupts for the UART
 *
 * @param Uart      UART parameters to be used.
***********************************************************************/
static inline void UartCancelTx(const struct uart_t *Uart)
{
  UART_VCALL(Uart, UartCancelTx)(Uart);
}

/**********************************************************************/
/**
 * @brief Name: UartIsBusyTx\n
 * Returns busy status of the UART TX path
 *
 * @param Uart      UART parameters to be used.
 * @return          true if UART is sending data
***********************************************************************/
static inline bool UartIsBusyTx(const struct uart_t *Uart)
{
  return UART_VCALL(Uart, UartIsBusyTx)(Uart);
}

/**********************************************************************/
/**
 * @brief Name: UartSetBaudrate\n
 * Sets new baudrate to the UART
 * Note that in many situation Rx timeout settings must be adjusted
 * simultaneously (use UartSetRxTimeouts function)
 *
 * @param Uart       UART parameters to be used.
 * @param Baudrate   New baudrate in bps.
 * @return void
 ***********************************************************************/
static inline void UartSetBaudrate(const struct uart_t *Uart, uint32_t Baudrate)
{
  Uart->State->Baudrate = Baudrate;
  UART_VCALL(Uart, UartSetBaudrate)(Uart);
}

/**********************************************************************/
/**
 * @brief Name: UartSetRxTimeouts\n
 * Sets timeout values for the UART
 * Calling code can use value UART_RX_TIMEOUT_DEFAULT as default value
 *
 * @param Uart      UART parameters to be used.
 * @param RxStartTimeoutUs Max time the driver will wait for the first symbol in the message.
 *                  UART_RX_TIMEOUT_DEFAULT can be used to set the timeout to default.
 *                  UART_RX_TIMEOUT_INFINITE can be used to disable the timeout.
 * @param RxStopTimeoutUs Max time the driver will wait for the next symbol in the message
 *                  UART_RX_TIMEOUT_DEFAULT can be used to set the timeout to default.
 *                  UART_RX_TIMEOUT_INFINITE can be used to disable the timeout.
 * @return void
***********************************************************************/
static inline void UartSetRxTimeouts(const struct uart_t *Uart,
                       uint32_t RxStartTimeoutUs, uint32_t RxStopTimeoutUs)
{
  UART_VCALL(Uart, UartSetRxTimeouts)(Uart, RxStartTimeoutUs, RxStopTimeoutUs);
}

/**********************************************************************/
/**
 * @brief Sends break (sets TX to logic 0 for a time of 1 byte transmission)
 *
 * @param Uart          UART parameters to be used.
 * @param Callback      Function to be called after the break signal is sent.
 * @param CallbackData  Pointer to the user data to be supplied as callback parameter.
 **********************************************************************/
static inline void UartSendBreak(const struct uart_t *Uart,
                                 uart_break_callback_t Callback, void *CallbackData)
{
  UART_VCALL(Uart, UartSendBreak)(Uart, Callback, CallbackData);
}

/**********************************************************************/
/**
 * @brief Manually drives RTS pin.
 *        HW flow control must be off to use this function.
 *
 * @param Uart      UART parameters to be used.
 * @param Active    TRUE: set RTS active (logic 0)
 *                  FALSE: set RTS passive (logical 1)
 **********************************************************************/
static inline void UartSetRts(const struct uart_t *Uart, bool Active)
{
  UART_VCALL(Uart, UartSetRts)(Uart, Active);
}

/** @} uart */

#endif // UART_H