text: /**
   * Copyright (c) 2016 - 2019, Nordic Semiconductor ASA
   *
   * 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, except as embedded into a Nordic
   *    Semiconductor ASA integrated circuit in a product or a software update for
   *    such product, 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. Neither the name of Nordic Semiconductor ASA nor the names of its
   *    contributors may be used to endorse or promote products derived from this
   *    software without specific prior written permission.
   *
   * 4. This software, with or without modification, must only be used with a
   *    Nordic Semiconductor ASA integrated circuit.
   *
   * 5. Any software provided in binary form under this license must not be reverse
   *    engineered, decompiled, modified and/or disassembled.
   *
   * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
   * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
   * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
   * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA 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.
   *
   */
  #ifndef NRF_SERIAL_H__
  #define NRF_SERIAL_H__
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  #include <stdint.h>
  #include <stdbool.h>
  
  #include "nrf_drv_uart.h"
  #include "nrf_queue.h"
  #include "nrf_mtx.h"
  #include "app_timer.h"
  
  /**@file
   *
   * @defgroup nrf_serial Serial port abstraction layer
   * @{
   * @ingroup app_common
   *
   * @brief Serial module interface.
   * @details This module is more sophisticated than @ref nrf_drv_uart. It internally uses
   * mutex, queues, and app_timer. You can configure it to work in three different modes
   * (polling, interrupt, DMA). API can be configured to work in synchronous mode. Both read and write
   * methods have a timeout parameter. Asynchronous mode is available by passing 0 as the
   * timeout parameter.
   * @warning Do not use synchronous API (timeout_ms parameter > 0) in IRQ
   *          context. It may lead to a deadlock because the timeout interrupt cannot
   *          preempt the current IRQ context.
   */
  
  typedef struct nrf_serial_s nrf_serial_t;
  
  /**
   * @brief Serial port mode.
   * */
  typedef enum {
      NRF_SERIAL_MODE_POLLING,    /**< Polling mode.*/
      NRF_SERIAL_MODE_IRQ,        /**< Interrupt mode.*/
      NRF_SERIAL_MODE_DMA,        /**< DMA mode.*/
  } nrf_serial_mode_t;
  
  
  
  /**
   * @brief Creates an instance of @ref nrf_drv_uart_config_t.
   *
   * @param _name         Instance name.
   * @param _rx_pin       RX pin number.
   * @param _tx_pin       TX pin number.
   * @param _rts_pin      RTS pin number.
   * @param _cts_pin      CTS pin number.
   * @param _flow_control Flow control enable/disable (@ref nrf_uart_hwfc_t).
   * @param _parity       Parity enable/disable (@ref nrf_uart_parity_t).
   * @param _baud_rate    Baud rate (@ref nrf_uart_baudrate_t).
   * @param _irq_prio     Interrupt priority.
   *
   * */
  #define NRF_SERIAL_DRV_UART_CONFIG_DEF(_name,            \
                                         _rx_pin,          \
                                         _tx_pin,          \
                                         _rts_pin,         \
                                         _cts_pin,         \
                                         _flow_control,    \
                                         _parity,          \
                                         _baud_rate,       \
                                         _irq_prio)        \
      static const nrf_drv_uart_config_t _name = {         \
              .pselrxd = _rx_pin,                          \
              .pseltxd = _tx_pin,                          \
              .pselrts = _rts_pin,                         \
              .pselcts = _cts_pin,                         \
              .hwfc = _flow_control,                       \
              .parity = _parity,                           \
              .baudrate = _baud_rate,                      \
              .interrupt_priority = _irq_prio,             \
      }
  
  /**
   * @brief Serial port RX and TX queues.
   *
   * @note Use the @ref NRF_SERIAL_QUEUES_DEF macro to create an instance of this
   *       structure.
   * */
  typedef struct {
      nrf_queue_t const * p_rxq;    //!< Receive queue handle.
      nrf_queue_t const * p_txq;    //!< Transmit queue handle.
  } nrf_serial_queues_t;
  
  /**
   * @brief Creates an instance of serial port queues.
   *
   * @param _name     Instance name.
   * @param _tx_size  TX queue size.
   * @param _rx_size  RX queue size.
   * */
  #define NRF_SERIAL_QUEUES_DEF(_name, _tx_size, _rx_size)                       \
      NRF_QUEUE_DEF(uint8_t, _name##_rxq, _rx_size, NRF_QUEUE_MODE_NO_OVERFLOW); \
      NRF_QUEUE_DEF(uint8_t, _name##_txq, _tx_size, NRF_QUEUE_MODE_NO_OVERFLOW); \
      static const nrf_serial_queues_t _name = {                                 \
          .p_rxq = &_name##_rxq,                                                 \
          .p_txq = &_name##_txq,                                                 \
      }
  
  /**
   * @brief Serial buffers. Data slices used by @ref nrf_drv_uart_tx and
   *        @ref nrf_drv_uart_rx.
   *
   * @note Use the @ref NRF_SERIAL_BUFFERS_DEF macro to create an instance of this
   *       structure.
   * */
  typedef struct {
      void * p_txb;     //!< TX buffer.
      void * p_rxb;     //!< RX buffer.
      uint8_t tx_size;  //!< TX buffer size.
      uint8_t rx_size;  //!< RX buffer size.
  } nrf_serial_buffers_t;
  
  /**
   * @brief Creates an instance of serial port buffers.
   *
   * @param _name     Instance name.
   * @param _tx_size  TX buffer size.
   * @param _rx_size  RX buffer size.
   * */
  #define NRF_SERIAL_BUFFERS_DEF(_name, _tx_size, _rx_size)           \
      STATIC_ASSERT((_tx_size) <= UINT8_MAX);                         \
      STATIC_ASSERT((_rx_size) <= UINT8_MAX);                         \
      static uint8_t _name##_txb[_tx_size];                           \
      static uint8_t _name##_rxb[_rx_size];                           \
      static const nrf_serial_buffers_t _name = {                     \
          .p_txb = _name##_txb,                                       \
          .p_rxb = _name##_rxb,                                       \
          .tx_size = sizeof(_name##_txb),                             \
          .rx_size = sizeof(_name##_rxb),                             \
      }
  
  /**
   * @brief Events generated by this module.
   * */
  typedef enum {
      NRF_SERIAL_EVENT_TX_DONE,   //!< Chunk of data has been sent.
      NRF_SERIAL_EVENT_RX_DATA,   //!< New chunk of data has been received.
      NRF_SERIAL_EVENT_DRV_ERR,   //!< Internal driver error.
      NRF_SERIAL_EVENT_FIFO_ERR,  //!< RX FIFO overrun.
  } nrf_serial_event_t;
  
  /**
   * @brief Event handler type.
   * */
  typedef void (*nrf_serial_evt_handler_t)(struct nrf_serial_s const * p_serial,
                                           nrf_serial_event_t event);
  
  /**
   * @brief Sleep handler type.
   * */
  typedef void (*nrf_serial_sleep_handler_t)(void);
  
  /**
   * @brief Configuration of UART serial interface.
   *
   * @note Use the @ref NRF_SERIAL_CONFIG_DEF macro to create an instance of this
   *       structure.
   *
   */
  typedef struct {
      nrf_serial_mode_t mode;         //!< Serial port mode.
  
      nrf_serial_queues_t const *  p_queues;      //!< Serial port queues.
      nrf_serial_buffers_t const * p_buffers;     //!< DMA buffers.
      nrf_serial_evt_handler_t     ev_handler;    //!< Event handler.
      nrf_serial_sleep_handler_t   sleep_handler; //!< Sleep mode handler.
  } nrf_serial_config_t;
  
  /**
   * @brief Creates an instance of serial port configuration.
   *
   * @param _name       Instance name.
   * @param _mode       Serial port mode.
   * @param _queues     Serial port queues. NULL can be passed in @ref NRF_SERIAL_MODE_POLLING mode.
   * @param _buffers    Serial port buffers. NULL can be passed in @ref NRF_SERIAL_MODE_POLLING mode.
   * @param _ev_handler Serial port event handler. NULL can be passed in any mode.
   * @param _sleep      Serial port sleep handler. NULL can be passed in any mode.
   * */
  #define NRF_SERIAL_CONFIG_DEF(_name, _mode, _queues, _buffers, _ev_handler, _sleep)  \
      static const nrf_serial_config_t _name = {                                       \
          .mode = _mode,                                                               \
          .p_queues = _queues,                                                         \
          .p_buffers = _buffers,                                                       \
          .ev_handler = _ev_handler,                                                   \
          .sleep_handler = _sleep,                                                     \
      }
  
  #define NRF_SERIAL_RX_ENABLED_FLAG (1u << 0)    //!< Receiver enable flag.
  #define NRF_SERIAL_TX_ENABLED_FLAG (1u << 1)    //!< Transmitter enable flag.
  
  /**
   * @brief Serial port context. Contains all data structures that need
   *        to be stored in RAM memory.
   * */
  typedef struct {
      nrf_serial_config_t const * p_config;   //!< Serial port configuration.
  
      nrf_mtx_t write_lock;   //!< Write operation lock.
      nrf_mtx_t read_lock;    //!< Read operation lock.
  
      uint8_t flags;         //!< Transmitter/receiver enable flags.
  } nrf_serial_ctx_t;
  
  /**
   * @brief Serial port instance declaration.
   *
   * @note Use @ref NRF_SERIAL_UART_DEF macro to create an instance of this
   *       structure.
   * */
  struct nrf_serial_s {
      nrf_drv_uart_t instance;   //!< Driver instance.
      nrf_serial_ctx_t * p_ctx;  //!< Driver context.
  
      app_timer_id_t const * p_tx_timer;  //!< TX timeout timer.
      app_timer_id_t const * p_rx_timer;  //!< RX timeout timer.
  };
  
  /**
   * @brief Creates an instance of a serial port.
   *
   * @param _name             Instance name.
   * @param _instance_number  Driver instance number (@ref NRF_DRV_UART_INSTANCE).
   * */
  #define NRF_SERIAL_UART_DEF(_name, _instance_number)                        \
      APP_TIMER_DEF(_name##_rx_timer);                                        \
      APP_TIMER_DEF(_name##_tx_timer);                                        \
      static nrf_serial_ctx_t _name##_ctx;                                    \
      static const nrf_serial_t _name = {                                     \
          .instance = NRF_DRV_UART_INSTANCE(_instance_number),                \
          .p_ctx = &_name##_ctx,                                              \
          .p_tx_timer = &_name##_tx_timer,                                    \
          .p_rx_timer = &_name##_rx_timer,                                    \
      }
  
  
  /**
   * @brief Maximum value of timeout. API might be blocked indefinitely if this value is
   *        not set.*/
  #define NRF_SERIAL_MAX_TIMEOUT UINT32_MAX
  
  /**
   * @brief Function for initializing a serial port. Serial port can be initialized
   *        in various modes that are defined by nrf_serial_mode_t.
   * - NRF_SERIAL_MODE_POLLING - Simple polling mode. API calls will be
   *                           synchronous. There is no need to define queues or buffers.
   *                           No events will be generated.
   * - NRF_SERIAL_MODE_IRQ - Interrupt mode. API can be set to work in synchronous or
   *                       asynchronous mode. Queues and buffers must be passed
   *                       during initialization. Events will be generated if
   *                       a non NULL handler is passed as the ev_handler parameter.
   * - NRF_SERIAL_MODE_DMA - Similar to @ref NRF_SERIAL_MODE_IRQ. Uses EasyDMA.
   *
   *
   * @param p_serial          Serial port instance.
   * @param p_drv_uart_config UART driver configuration. Cannot be NULL.
   * @param p_config          Serial port configuration. Cannot be NULL. This object must be created
   *                          using the @ref NRF_SERIAL_CONFIG_DEF macro.
   *
   * @return Standard error code.
   * */
  ret_code_t nrf_serial_init(nrf_serial_t const * p_serial,
                             nrf_drv_uart_config_t const * p_drv_uart_config,
                             nrf_serial_config_t const * p_config);
  
  
  /**
   * @brief Function for uninitializing a serial port.
   *
   * @param p_serial  Serial port instance.
   *
   * @return Standard error code.
   * */
  ret_code_t nrf_serial_uninit(nrf_serial_t const * p_serial);
  
  
  /**
   * @brief Function for writing to a serial port.
   *
   * @param p_serial   Serial port instance.
   * @param p_data     Transmit buffer pointer.
   * @param size       Transmit buffer size.
   * @param p_written  Amount of data actually written to the serial port.
   *                   NULL pointer can be passed.
   * @param timeout_ms Operation timeout, in milliseconds. Pass 0 to operate in
   *                   non blocking mode.
   *
   * @return Standard error code.
   * */
  ret_code_t nrf_serial_write(nrf_serial_t const * p_serial,
                              void const * p_data,
                              size_t size,
                              size_t * p_written,
                              uint32_t timeout_ms);
  
  /**
   * @brief Function for reading from a serial port.
   *
   * @param p_serial   Serial port instance.
   * @param p_data     Receive buffer pointer.
   * @param size       Receive buffer size.
   * @param p_read     Amount of data actually read from the serial port.
   *                   NULL pointer can be passed.
   * @param timeout_ms Operation timeout, in milliseconds. Pass 0 to operate in
   *                   non blocking mode.
   *
   * @return Standard error code.
   * */
  ret_code_t nrf_serial_read(nrf_serial_t const * p_serial,
                             void * p_data,
                             size_t size,
                             size_t * p_read,
                             uint32_t timeout_ms);
  
  /**
   * @brief Function for flushing a serial port TX queue.
   *
   * @param p_serial   Serial port instance.
   * @param timeout_ms Operation timeout, in milliseconds. Pass 0 to operate in
   *                   non blocking mode.
   * @return Standard error code.
   * */
  ret_code_t nrf_serial_flush(nrf_serial_t const * p_serial, uint32_t timeout_ms);
  
  
  /**
   * @brief Function for aborting a serial port transmission.
   * Aborts the current ongoing transmission and resets TX FIFO.
   *
   * @param p_serial  Serial port instance.
   *
   * @return Standard error code.
   * */
  ret_code_t nrf_serial_tx_abort(nrf_serial_t const * p_serial);
  
  /**
   * @brief Function for draining the serial port receive RX FIFO.
   * Drains HW FIFO and resets RX FIFO.
   *
   * @param p_serial  Serial port instance.
   *
   * @return Standard error code.
   * */
  ret_code_t nrf_serial_rx_drain(nrf_serial_t const * p_serial);
  
  /** @} */
  
  #ifdef __cplusplus
  }
  #endif
  
  #endif /* NRF_SERIAL_H__ */
  