294 lines
12 KiB
C
294 lines
12 KiB
C
/* Copyright (c) 2015 Nordic Semiconductor. All Rights Reserved.
|
|
*
|
|
* The information contained herein is property of Nordic Semiconductor ASA.
|
|
* Terms and conditions of usage are described in detail in NORDIC
|
|
* SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
|
|
*
|
|
* Licensees are granted free, non-transferable use of the information. NO
|
|
* WARRANTY of ANY KIND is provided. This heading must NOT be removed from
|
|
* the file.
|
|
*
|
|
*/
|
|
|
|
/**@file
|
|
* @addtogroup nrf_uart UART driver and HAL
|
|
* @ingroup nrf_drivers
|
|
* @brief UART API.
|
|
* @details The UART driver provides APIs for utilizing the UART peripheral.
|
|
*
|
|
* @defgroup nrf_drv_uart UART driver
|
|
* @{
|
|
* @ingroup nrf_uart
|
|
*
|
|
* @brief UART driver.
|
|
*/
|
|
|
|
#ifndef NRF_DRV_UART_H
|
|
#define NRF_DRV_UART_H
|
|
|
|
#include "nrf_uart.h"
|
|
#ifdef NRF52
|
|
#include "nrf_uarte.h"
|
|
#endif
|
|
|
|
#include "sdk_errors.h"
|
|
#include "nrf_drv_config.h"
|
|
|
|
/**
|
|
* @brief Types of UART driver events.
|
|
*/
|
|
typedef enum
|
|
{
|
|
NRF_DRV_UART_EVT_TX_DONE, ///< Requested TX transfer completed.
|
|
NRF_DRV_UART_EVT_RX_DONE, ///< Requested RX transfer completed.
|
|
NRF_DRV_UART_EVT_ERROR, ///< Error reported by UART peripheral.
|
|
} nrf_drv_uart_evt_type_t;
|
|
|
|
/**@brief Structure for UART configuration. */
|
|
typedef struct
|
|
{
|
|
uint32_t pseltxd; ///< TXD pin number.
|
|
uint32_t pselrxd; ///< RXD pin number.
|
|
uint32_t pselcts; ///< CTS pin number.
|
|
uint32_t pselrts; ///< RTS pin number.
|
|
void * p_context; ///< Context passed to interrupt handler.
|
|
nrf_uart_hwfc_t hwfc; ///< Flow control configuration.
|
|
nrf_uart_parity_t parity; ///< Parity configuration.
|
|
nrf_uart_baudrate_t baudrate; ///< Baudrate.
|
|
uint8_t interrupt_priority; ///< Interrupt priority.
|
|
#ifdef NRF52
|
|
bool use_easy_dma;
|
|
#endif
|
|
} nrf_drv_uart_config_t;
|
|
|
|
/**@brief UART default configuration. */
|
|
#ifdef NRF52
|
|
#if !UART_LEGACY_SUPPORT
|
|
#define DEFAULT_CONFIG_USE_EASY_DMA true
|
|
#elif !UART_EASY_DMA_SUPPORT
|
|
#define DEFAULT_CONFIG_USE_EASY_DMA false
|
|
#else
|
|
#define DEFAULT_CONFIG_USE_EASY_DMA UART0_CONFIG_USE_EASY_DMA
|
|
#endif
|
|
#define NRF_DRV_UART_DEFAULT_CONFIG \
|
|
{ \
|
|
.pseltxd = UART0_CONFIG_PSEL_TXD, \
|
|
.pselrxd = UART0_CONFIG_PSEL_RXD, \
|
|
.pselcts = UART0_CONFIG_PSEL_CTS, \
|
|
.pselrts = UART0_CONFIG_PSEL_RTS, \
|
|
.p_context = NULL, \
|
|
.hwfc = UART0_CONFIG_HWFC, \
|
|
.parity = UART0_CONFIG_PARITY, \
|
|
.baudrate = UART0_CONFIG_BAUDRATE, \
|
|
.interrupt_priority = UART0_CONFIG_IRQ_PRIORITY, \
|
|
.use_easy_dma = DEFAULT_CONFIG_USE_EASY_DMA \
|
|
}
|
|
#else
|
|
#define NRF_DRV_UART_DEFAULT_CONFIG \
|
|
{ \
|
|
.pseltxd = UART0_CONFIG_PSEL_TXD, \
|
|
.pselrxd = UART0_CONFIG_PSEL_RXD, \
|
|
.pselcts = UART0_CONFIG_PSEL_CTS, \
|
|
.pselrts = UART0_CONFIG_PSEL_RTS, \
|
|
.p_context = NULL, \
|
|
.hwfc = UART0_CONFIG_HWFC, \
|
|
.parity = UART0_CONFIG_PARITY, \
|
|
.baudrate = UART0_CONFIG_BAUDRATE, \
|
|
.interrupt_priority = UART0_CONFIG_IRQ_PRIORITY \
|
|
}
|
|
#endif
|
|
|
|
/**@brief Structure for UART transfer completion event. */
|
|
typedef struct
|
|
{
|
|
uint8_t * p_data; ///< Pointer to memory used for transfer.
|
|
uint8_t bytes; ///< Number of bytes transfered.
|
|
} nrf_drv_uart_xfer_evt_t;
|
|
|
|
/**@brief Structure for UART error event. */
|
|
typedef struct
|
|
{
|
|
nrf_drv_uart_xfer_evt_t rxtx; ///< Transfer details includes number of bytes transfered.
|
|
uint32_t error_mask;///< Mask of error flags that generated the event.
|
|
} nrf_drv_uart_error_evt_t;
|
|
|
|
/**@brief Structure for UART event. */
|
|
typedef struct
|
|
{
|
|
nrf_drv_uart_evt_type_t type; ///< Event type.
|
|
union
|
|
{
|
|
nrf_drv_uart_xfer_evt_t rxtx; ///< Data provided for transfer completion events.
|
|
nrf_drv_uart_error_evt_t error;///< Data provided for error event.
|
|
} data;
|
|
} nrf_drv_uart_event_t;
|
|
|
|
/**
|
|
* @brief UART interrupt event handler.
|
|
*
|
|
* @param[in] p_event Pointer to event structure. Event is allocated on the stack so it is available
|
|
* only within the context of the event handler.
|
|
* @param[in] p_context Context passed to interrupt handler, set on initialization.
|
|
*/
|
|
typedef void (*nrf_uart_event_handler_t)(nrf_drv_uart_event_t * p_event, void * p_context);
|
|
|
|
/**
|
|
* @brief Function for initializing the UART driver.
|
|
*
|
|
* This function configures and enables UART. After this function GPIO pins are controlled by UART.
|
|
*
|
|
* @param[in] p_config Initial configuration. Default configuration used if NULL.
|
|
* @param[in] event_handler Event handler provided by the user. If not provided driver works in
|
|
* blocking mode.
|
|
*
|
|
* @retval NRF_SUCCESS If initialization was successful.
|
|
* @retval NRF_ERROR_INVALID_STATE If driver is already initialized.
|
|
*/
|
|
ret_code_t nrf_drv_uart_init(nrf_drv_uart_config_t const * p_config,
|
|
nrf_uart_event_handler_t event_handler);
|
|
|
|
/**
|
|
* @brief Function for uninitializing the UART driver.
|
|
*/
|
|
void nrf_drv_uart_uninit(void);
|
|
|
|
/**
|
|
* @brief Function for getting the address of a specific UART task.
|
|
*
|
|
* @param[in] task Task.
|
|
*
|
|
* @return Task address.
|
|
*/
|
|
__STATIC_INLINE uint32_t nrf_drv_uart_task_address_get(nrf_uart_task_t task);
|
|
|
|
/**
|
|
* @brief Function for getting the address of a specific UART event.
|
|
*
|
|
* @param[in] event Event.
|
|
*
|
|
* @return Event address.
|
|
*/
|
|
__STATIC_INLINE uint32_t nrf_drv_uart_event_address_get(nrf_uart_event_t event);
|
|
|
|
/**
|
|
* @brief Function for sending data over UART.
|
|
*
|
|
* If an event handler was provided in nrf_drv_uart_init() call, this function
|
|
* returns immediately and the handler is called when the transfer is done.
|
|
* Otherwise, the transfer is performed in blocking mode, i.e. this function
|
|
* returns when the transfer is finished. Blocking mode is not using interrupt so
|
|
* there is no context switching inside the function.
|
|
*
|
|
* @note Peripherals using EasyDMA (i.e. UARTE) require that the transfer buffers
|
|
* are placed in the Data RAM region. If they are not and UARTE instance is
|
|
* used, this function will fail with error code NRF_ERROR_INVALID_ADDR.
|
|
*
|
|
* @param[in] p_data Pointer to data.
|
|
* @param[in] length Number of bytes to send.
|
|
*
|
|
* @retval NRF_SUCCESS If initialization was successful.
|
|
* @retval NRF_ERROR_BUSY If driver is already transferring.
|
|
* @retval NRF_ERROR_FORBIDDEN If the transfer was aborted from a different context
|
|
* (blocking mode only, also see @ref nrf_drv_uart_rx_disable).
|
|
* @retval NRF_ERROR_INVALID_ADDR If p_data does not point to RAM buffer (UARTE only).
|
|
*/
|
|
ret_code_t nrf_drv_uart_tx(uint8_t const * const p_data, uint8_t length);
|
|
|
|
/**
|
|
* @brief Function for checking if UART is currently transmitting.
|
|
*
|
|
* @retval true If UART is transmitting.
|
|
* @retval false If UART is not transmitting.
|
|
*/
|
|
bool nrf_drv_uart_tx_in_progress(void);
|
|
|
|
/**
|
|
* @brief Function for aborting any ongoing transmission.
|
|
* @note @ref NRF_DRV_UART_EVT_TX_DONE event will be generated in non-blocking mode. Event will
|
|
* contain number of bytes sent until abort was called. If Easy DMA is not used event will be
|
|
* called from the function context. If Easy DMA is used it will be called from UART interrupt
|
|
* context.
|
|
*/
|
|
void nrf_drv_uart_tx_abort(void);
|
|
|
|
/**
|
|
* @brief Function for receiving data over UART.
|
|
*
|
|
* If an event handler was provided in the nrf_drv_uart_init() call, this function
|
|
* returns immediately and the handler is called when the transfer is done.
|
|
* Otherwise, the transfer is performed in blocking mode, i.e. this function
|
|
* returns when the transfer is finished. Blocking mode is not using interrupt so
|
|
* there is no context switching inside the function.
|
|
* The receive buffer pointer is double buffered in non-blocking mode. The secondary
|
|
* buffer can be set immediately after starting the transfer and will be filled
|
|
* when the primary buffer is full. The double buffering feature allows
|
|
* receiving data continuously.
|
|
*
|
|
* @note Peripherals using EasyDMA (i.e. UARTE) require that the transfer buffers
|
|
* are placed in the Data RAM region. If they are not and UARTE instance is
|
|
* used, this function will fail with error code NRF_ERROR_INVALID_ADDR.
|
|
* @param[in] p_data Pointer to data.
|
|
* @param[in] length Number of bytes to receive.
|
|
*
|
|
* @retval NRF_SUCCESS If initialization was successful.
|
|
* @retval NRF_ERROR_BUSY If the driver is already receiving
|
|
* (and the secondary buffer has already been set
|
|
* in non-blocking mode).
|
|
* @retval NRF_ERROR_FORBIDDEN If the transfer was aborted from a different context
|
|
* (blocking mode only, also see @ref nrf_drv_uart_rx_disable).
|
|
* @retval NRF_ERROR_INTERNAL If UART peripheral reported an error.
|
|
* @retval NRF_ERROR_INVALID_ADDR If p_data does not point to RAM buffer (UARTE only).
|
|
*/
|
|
ret_code_t nrf_drv_uart_rx(uint8_t * p_data, uint8_t length);
|
|
|
|
/**
|
|
* @brief Function for enabling receiver.
|
|
*
|
|
* UART has 6 byte long RX FIFO and it will be used to store incoming data. If user will not call
|
|
* UART receive function before FIFO is filled, overrun error will encounter. Enabling receiver
|
|
* without specifying RX buffer is supported only in UART mode (without Easy DMA). Receiver must be
|
|
* explicitly closed by the user @sa nrf_drv_uart_rx_disable. Function asserts if mode is wrong.
|
|
*/
|
|
void nrf_drv_uart_rx_enable(void);
|
|
|
|
/**
|
|
* @brief Function for disabling receiver.
|
|
*
|
|
* Function must be called to close the receiver after it has been explicitly enabled by
|
|
* @sa nrf_drv_uart_rx_enable. Feature is supported only in UART mode (without Easy DMA). Function
|
|
* asserts if mode is wrong.
|
|
*/
|
|
void nrf_drv_uart_rx_disable(void);
|
|
|
|
/**
|
|
* @brief Function for aborting any ongoing reception.
|
|
* @note @ref NRF_DRV_UART_EVT_RX_DONE event will be generated in non-blocking mode. Event will
|
|
* contain number of bytes received until abort was called. If Easy DMA is not used event will be
|
|
* called from the function context. If Easy DMA is used it will be called from UART interrupt
|
|
* context.
|
|
*/
|
|
void nrf_drv_uart_rx_abort(void);
|
|
|
|
/**
|
|
* @brief Function for reading error source mask. Mask contains values from @ref nrf_uart_error_mask_t.
|
|
* @note Function should be used in blocking mode only. In case of non-blocking mode error event is
|
|
* generated. Function clears error sources after reading.
|
|
*
|
|
* @retval Mask of reported errors.
|
|
*/
|
|
uint32_t nrf_drv_uart_errorsrc_get(void);
|
|
|
|
#ifndef SUPPRESS_INLINE_IMPLEMENTATION
|
|
__STATIC_INLINE uint32_t nrf_drv_uart_task_address_get(nrf_uart_task_t task)
|
|
{
|
|
return nrf_uart_task_address_get(NRF_UART0, task);
|
|
}
|
|
|
|
__STATIC_INLINE uint32_t nrf_drv_uart_event_address_get(nrf_uart_event_t event)
|
|
{
|
|
return nrf_uart_event_address_get(NRF_UART0, event);
|
|
}
|
|
#endif //SUPPRESS_INLINE_IMPLEMENTATION
|
|
#endif //NRF_DRV_UART_H
|
|
/** @} */
|