mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_TY51822R3/TOOLCHAIN_GCC_ARM/nrf_drv_spi.h@172:65be27845400, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 20:53:29 2019 +0000
Revision:
172:65be27845400
Parent:
171:3a7713b1edbc 
mbed library release version 165

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AnnaBridge 146:22da6e220af6 1 /*
AnnaBridge 146:22da6e220af6 2 * Copyright (c) 2015 Nordic Semiconductor ASA
AnnaBridge 146:22da6e220af6 3 * All rights reserved.
AnnaBridge 146:22da6e220af6 4 *
AnnaBridge 146:22da6e220af6 5 * Redistribution and use in source and binary forms, with or without modification,
AnnaBridge 146:22da6e220af6 6 * are permitted provided that the following conditions are met:
AnnaBridge 146:22da6e220af6 7 *
AnnaBridge 146:22da6e220af6 8 * 1. Redistributions of source code must retain the above copyright notice, this list
AnnaBridge 146:22da6e220af6 9 * of conditions and the following disclaimer.
AnnaBridge 146:22da6e220af6 10 *
AnnaBridge 146:22da6e220af6 11 * 2. Redistributions in binary form, except as embedded into a Nordic Semiconductor ASA
AnnaBridge 146:22da6e220af6 12 * integrated circuit in a product or a software update for such product, must reproduce
AnnaBridge 146:22da6e220af6 13 * the above copyright notice, this list of conditions and the following disclaimer in
AnnaBridge 146:22da6e220af6 14 * the documentation and/or other materials provided with the distribution.
AnnaBridge 146:22da6e220af6 15 *
AnnaBridge 146:22da6e220af6 16 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its contributors may be
AnnaBridge 146:22da6e220af6 17 * used to endorse or promote products derived from this software without specific prior
AnnaBridge 146:22da6e220af6 18 * written permission.
AnnaBridge 146:22da6e220af6 19 *
AnnaBridge 146:22da6e220af6 20 * 4. This software, with or without modification, must only be used with a
AnnaBridge 146:22da6e220af6 21 * Nordic Semiconductor ASA integrated circuit.
AnnaBridge 146:22da6e220af6 22 *
AnnaBridge 146:22da6e220af6 23 * 5. Any software provided in binary or object form under this license must not be reverse
AnnaBridge 146:22da6e220af6 24 * engineered, decompiled, modified and/or disassembled.
AnnaBridge 146:22da6e220af6 25 *
AnnaBridge 146:22da6e220af6 26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
AnnaBridge 146:22da6e220af6 27 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
AnnaBridge 146:22da6e220af6 28 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
AnnaBridge 146:22da6e220af6 29 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
AnnaBridge 146:22da6e220af6 30 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
AnnaBridge 146:22da6e220af6 31 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
AnnaBridge 146:22da6e220af6 32 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
AnnaBridge 146:22da6e220af6 33 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
AnnaBridge 146:22da6e220af6 34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
AnnaBridge 146:22da6e220af6 35 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
AnnaBridge 146:22da6e220af6 36 *
AnnaBridge 146:22da6e220af6 37 */
AnnaBridge 146:22da6e220af6 38
AnnaBridge 146:22da6e220af6 39
AnnaBridge 146:22da6e220af6 40 /**@file
AnnaBridge 146:22da6e220af6 41 * @addtogroup nrf_spi Serial peripheral interface (SPI)
AnnaBridge 146:22da6e220af6 42 * @ingroup nrf_drivers
AnnaBridge 146:22da6e220af6 43 * @brief Serial peripheral interface (SPI) APIs.
AnnaBridge 146:22da6e220af6 44 *
AnnaBridge 146:22da6e220af6 45 *
AnnaBridge 146:22da6e220af6 46 * @addtogroup nrf_spi_master SPI master HAL and driver
AnnaBridge 146:22da6e220af6 47 * @ingroup nrf_spi
AnnaBridge 146:22da6e220af6 48 * @brief SPI master APIs.
AnnaBridge 146:22da6e220af6 49 */
AnnaBridge 146:22da6e220af6 50
AnnaBridge 146:22da6e220af6 51 #ifndef NRF_DRV_SPI_H__
AnnaBridge 146:22da6e220af6 52 #define NRF_DRV_SPI_H__
AnnaBridge 146:22da6e220af6 53
AnnaBridge 146:22da6e220af6 54 #include "nordic_common.h"
AnnaBridge 146:22da6e220af6 55 #include "nrf_drv_config.h"
AnnaBridge 146:22da6e220af6 56 #include "nrf_spi.h"
AnnaBridge 146:22da6e220af6 57 #include "nrf_spim.h"
AnnaBridge 146:22da6e220af6 58 #include "sdk_errors.h"
AnnaBridge 146:22da6e220af6 59
AnnaBridge 146:22da6e220af6 60 #if defined(NRF52)
AnnaBridge 146:22da6e220af6 61 #define NRF_DRV_SPI_PERIPHERAL(id) \
AnnaBridge 146:22da6e220af6 62 (CONCAT_3(SPI, id, _USE_EASY_DMA) == 1 ? \
AnnaBridge 146:22da6e220af6 63 (void *)CONCAT_2(NRF_SPIM, id) \
AnnaBridge 146:22da6e220af6 64 : (void *)CONCAT_2(NRF_SPI, id))
AnnaBridge 146:22da6e220af6 65 #define SPI2_IRQ SPIM2_SPIS2_SPI2_IRQn
AnnaBridge 146:22da6e220af6 66 #define SPI2_IRQ_HANDLER SPIM2_SPIS2_SPI2_IRQHandler
AnnaBridge 146:22da6e220af6 67 #else
AnnaBridge 146:22da6e220af6 68 #define NRF_DRV_SPI_PERIPHERAL(id) (void *)CONCAT_2(NRF_SPI, id)
AnnaBridge 146:22da6e220af6 69 #endif
AnnaBridge 146:22da6e220af6 70 #define SPI0_IRQ SPI0_TWI0_IRQn
AnnaBridge 146:22da6e220af6 71 #define SPI0_IRQ_HANDLER SPI0_TWI0_IRQHandler
AnnaBridge 146:22da6e220af6 72 #define SPI1_IRQ SPI1_TWI1_IRQn
AnnaBridge 146:22da6e220af6 73 #define SPI1_IRQ_HANDLER SPI1_TWI1_IRQHandler
AnnaBridge 146:22da6e220af6 74
AnnaBridge 146:22da6e220af6 75
AnnaBridge 146:22da6e220af6 76 /**
AnnaBridge 146:22da6e220af6 77 * @defgroup nrf_drv_spi_master SPI master driver
AnnaBridge 146:22da6e220af6 78 * @{
AnnaBridge 146:22da6e220af6 79 * @ingroup nrf_spi_master
AnnaBridge 146:22da6e220af6 80 *
AnnaBridge 146:22da6e220af6 81 * @brief Multi-instance SPI master driver.
AnnaBridge 146:22da6e220af6 82 */
AnnaBridge 146:22da6e220af6 83
AnnaBridge 146:22da6e220af6 84 /**
AnnaBridge 146:22da6e220af6 85 * @brief SPI master driver instance data structure.
AnnaBridge 146:22da6e220af6 86 */
AnnaBridge 146:22da6e220af6 87 typedef struct
AnnaBridge 146:22da6e220af6 88 {
AnnaBridge 146:22da6e220af6 89 void * p_registers; ///< Pointer to the structure with SPI/SPIM peripheral instance registers.
AnnaBridge 146:22da6e220af6 90 IRQn_Type irq; ///< SPI/SPIM peripheral instance IRQ number.
AnnaBridge 146:22da6e220af6 91 uint8_t drv_inst_idx; ///< Driver instance index.
AnnaBridge 146:22da6e220af6 92 bool use_easy_dma; ///< True if the peripheral with EasyDMA (SPIM) shall be used.
AnnaBridge 146:22da6e220af6 93 } nrf_drv_spi_t;
AnnaBridge 146:22da6e220af6 94
AnnaBridge 146:22da6e220af6 95 /**
AnnaBridge 146:22da6e220af6 96 * @brief Macro for creating an SPI master driver instance.
AnnaBridge 146:22da6e220af6 97 */
AnnaBridge 146:22da6e220af6 98 #define NRF_DRV_SPI_INSTANCE(id) \
AnnaBridge 146:22da6e220af6 99 { \
AnnaBridge 146:22da6e220af6 100 .p_registers = NRF_DRV_SPI_PERIPHERAL(id), \
AnnaBridge 146:22da6e220af6 101 .irq = CONCAT_3(SPI, id, _IRQ), \
AnnaBridge 146:22da6e220af6 102 .drv_inst_idx = CONCAT_3(SPI, id, _INSTANCE_INDEX), \
AnnaBridge 146:22da6e220af6 103 .use_easy_dma = CONCAT_3(SPI, id, _USE_EASY_DMA) \
AnnaBridge 146:22da6e220af6 104 }
AnnaBridge 146:22da6e220af6 105
AnnaBridge 146:22da6e220af6 106 /**
AnnaBridge 146:22da6e220af6 107 * @brief This value can be provided instead of a pin number for signals MOSI,
AnnaBridge 146:22da6e220af6 108 * MISO, and Slave Select to specify that the given signal is not used and
AnnaBridge 146:22da6e220af6 109 * therefore does not need to be connected to a pin.
AnnaBridge 146:22da6e220af6 110 */
AnnaBridge 146:22da6e220af6 111 #define NRF_DRV_SPI_PIN_NOT_USED 0xFF
AnnaBridge 146:22da6e220af6 112
AnnaBridge 146:22da6e220af6 113 /**
AnnaBridge 146:22da6e220af6 114 * @brief SPI data rates.
AnnaBridge 146:22da6e220af6 115 */
AnnaBridge 146:22da6e220af6 116 typedef enum
AnnaBridge 146:22da6e220af6 117 {
AnnaBridge 146:22da6e220af6 118 NRF_DRV_SPI_FREQ_125K = NRF_SPI_FREQ_125K, ///< 125 kbps.
AnnaBridge 146:22da6e220af6 119 NRF_DRV_SPI_FREQ_250K = NRF_SPI_FREQ_250K, ///< 250 kbps.
AnnaBridge 146:22da6e220af6 120 NRF_DRV_SPI_FREQ_500K = NRF_SPI_FREQ_500K, ///< 500 kbps.
AnnaBridge 146:22da6e220af6 121 NRF_DRV_SPI_FREQ_1M = NRF_SPI_FREQ_1M, ///< 1 Mbps.
AnnaBridge 146:22da6e220af6 122 NRF_DRV_SPI_FREQ_2M = NRF_SPI_FREQ_2M, ///< 2 Mbps.
AnnaBridge 146:22da6e220af6 123 NRF_DRV_SPI_FREQ_4M = NRF_SPI_FREQ_4M, ///< 4 Mbps.
AnnaBridge 146:22da6e220af6 124 NRF_DRV_SPI_FREQ_8M = NRF_SPI_FREQ_8M ///< 8 Mbps.
AnnaBridge 146:22da6e220af6 125 } nrf_drv_spi_frequency_t;
AnnaBridge 146:22da6e220af6 126
AnnaBridge 146:22da6e220af6 127 /**
AnnaBridge 146:22da6e220af6 128 * @brief SPI modes.
AnnaBridge 146:22da6e220af6 129 */
AnnaBridge 146:22da6e220af6 130 typedef enum
AnnaBridge 146:22da6e220af6 131 {
AnnaBridge 146:22da6e220af6 132 NRF_DRV_SPI_MODE_0 = NRF_SPI_MODE_0, ///< SCK active high, sample on leading edge of clock.
AnnaBridge 146:22da6e220af6 133 NRF_DRV_SPI_MODE_1 = NRF_SPI_MODE_1, ///< SCK active high, sample on trailing edge of clock.
AnnaBridge 146:22da6e220af6 134 NRF_DRV_SPI_MODE_2 = NRF_SPI_MODE_2, ///< SCK active low, sample on leading edge of clock.
AnnaBridge 146:22da6e220af6 135 NRF_DRV_SPI_MODE_3 = NRF_SPI_MODE_3 ///< SCK active low, sample on trailing edge of clock.
AnnaBridge 146:22da6e220af6 136 } nrf_drv_spi_mode_t;
AnnaBridge 146:22da6e220af6 137
AnnaBridge 146:22da6e220af6 138 /**
AnnaBridge 146:22da6e220af6 139 * @brief SPI bit orders.
AnnaBridge 146:22da6e220af6 140 */
AnnaBridge 146:22da6e220af6 141 typedef enum
AnnaBridge 146:22da6e220af6 142 {
AnnaBridge 146:22da6e220af6 143 NRF_DRV_SPI_BIT_ORDER_MSB_FIRST = NRF_SPI_BIT_ORDER_MSB_FIRST, ///< Most significant bit shifted out first.
AnnaBridge 146:22da6e220af6 144 NRF_DRV_SPI_BIT_ORDER_LSB_FIRST = NRF_SPI_BIT_ORDER_LSB_FIRST ///< Least significant bit shifted out first.
AnnaBridge 146:22da6e220af6 145 } nrf_drv_spi_bit_order_t;
AnnaBridge 146:22da6e220af6 146
AnnaBridge 146:22da6e220af6 147 /**
AnnaBridge 146:22da6e220af6 148 * @brief SPI master driver instance configuration structure.
AnnaBridge 146:22da6e220af6 149 */
AnnaBridge 146:22da6e220af6 150 typedef struct
AnnaBridge 146:22da6e220af6 151 {
AnnaBridge 146:22da6e220af6 152 uint8_t sck_pin; ///< SCK pin number.
AnnaBridge 146:22da6e220af6 153 uint8_t mosi_pin; ///< MOSI pin number (optional).
AnnaBridge 146:22da6e220af6 154 /**< Set to @ref NRF_DRV_SPI_PIN_NOT_USED
AnnaBridge 146:22da6e220af6 155 * if this signal is not needed. */
AnnaBridge 146:22da6e220af6 156 uint8_t miso_pin; ///< MISO pin number (optional).
AnnaBridge 146:22da6e220af6 157 /**< Set to @ref NRF_DRV_SPI_PIN_NOT_USED
AnnaBridge 146:22da6e220af6 158 * if this signal is not needed. */
AnnaBridge 146:22da6e220af6 159 uint8_t ss_pin; ///< Slave Select pin number (optional).
AnnaBridge 146:22da6e220af6 160 /**< Set to @ref NRF_DRV_SPI_PIN_NOT_USED
AnnaBridge 146:22da6e220af6 161 * if this signal is not needed. The driver
AnnaBridge 146:22da6e220af6 162 * supports only active low for this signal.
AnnaBridge 146:22da6e220af6 163 * If the signal should be active high,
AnnaBridge 146:22da6e220af6 164 * it must be controlled externally. */
AnnaBridge 146:22da6e220af6 165 uint8_t irq_priority; ///< Interrupt priority.
AnnaBridge 146:22da6e220af6 166 uint8_t orc; ///< Over-run character.
AnnaBridge 146:22da6e220af6 167 /**< This character is used when all bytes from the TX buffer are sent,
AnnaBridge 146:22da6e220af6 168 but the transfer continues due to RX. */
AnnaBridge 146:22da6e220af6 169 nrf_drv_spi_frequency_t frequency; ///< SPI frequency.
AnnaBridge 146:22da6e220af6 170 nrf_drv_spi_mode_t mode; ///< SPI mode.
AnnaBridge 146:22da6e220af6 171 nrf_drv_spi_bit_order_t bit_order; ///< SPI bit order.
AnnaBridge 146:22da6e220af6 172 } nrf_drv_spi_config_t;
AnnaBridge 146:22da6e220af6 173
AnnaBridge 146:22da6e220af6 174 /**
AnnaBridge 146:22da6e220af6 175 * @brief SPI master instance default configuration.
AnnaBridge 146:22da6e220af6 176 */
AnnaBridge 146:22da6e220af6 177 #define NRF_DRV_SPI_DEFAULT_CONFIG(id) \
AnnaBridge 146:22da6e220af6 178 { \
AnnaBridge 146:22da6e220af6 179 .sck_pin = CONCAT_3(SPI, id, _CONFIG_SCK_PIN), \
AnnaBridge 146:22da6e220af6 180 .mosi_pin = CONCAT_3(SPI, id, _CONFIG_MOSI_PIN), \
AnnaBridge 146:22da6e220af6 181 .miso_pin = CONCAT_3(SPI, id, _CONFIG_MISO_PIN), \
AnnaBridge 146:22da6e220af6 182 .ss_pin = NRF_DRV_SPI_PIN_NOT_USED, \
AnnaBridge 146:22da6e220af6 183 .irq_priority = CONCAT_3(SPI, id, _CONFIG_IRQ_PRIORITY), \
AnnaBridge 146:22da6e220af6 184 .orc = 0xFF, \
AnnaBridge 146:22da6e220af6 185 .frequency = NRF_DRV_SPI_FREQ_4M, \
AnnaBridge 146:22da6e220af6 186 .mode = NRF_DRV_SPI_MODE_0, \
AnnaBridge 146:22da6e220af6 187 .bit_order = NRF_DRV_SPI_BIT_ORDER_MSB_FIRST, \
AnnaBridge 146:22da6e220af6 188 }
AnnaBridge 146:22da6e220af6 189
AnnaBridge 146:22da6e220af6 190 #define NRF_DRV_SPI_FLAG_TX_POSTINC (1UL << 0) /**< TX buffer address incremented after transfer. */
AnnaBridge 146:22da6e220af6 191 #define NRF_DRV_SPI_FLAG_RX_POSTINC (1UL << 1) /**< RX buffer address incremented after transfer. */
AnnaBridge 146:22da6e220af6 192 #define NRF_DRV_SPI_FLAG_NO_XFER_EVT_HANDLER (1UL << 2) /**< Interrupt after each transfer is suppressed, and the event handler is not called. */
AnnaBridge 146:22da6e220af6 193 #define NRF_DRV_SPI_FLAG_HOLD_XFER (1UL << 3) /**< Set up the transfer but do not start it. */
AnnaBridge 146:22da6e220af6 194 #define NRF_DRV_SPI_FLAG_REPEATED_XFER (1UL << 4) /**< Flag indicating that the transfer will be executed multiple times. */
AnnaBridge 146:22da6e220af6 195
AnnaBridge 146:22da6e220af6 196 /**
AnnaBridge 146:22da6e220af6 197 * @brief Single transfer descriptor structure.
AnnaBridge 146:22da6e220af6 198 */
AnnaBridge 146:22da6e220af6 199 typedef struct
AnnaBridge 146:22da6e220af6 200 {
AnnaBridge 146:22da6e220af6 201 uint8_t const * p_tx_buffer; ///< Pointer to TX buffer.
AnnaBridge 146:22da6e220af6 202 uint8_t tx_length; ///< TX buffer length.
AnnaBridge 146:22da6e220af6 203 uint8_t * p_rx_buffer; ///< Pointer to RX buffer.
AnnaBridge 146:22da6e220af6 204 uint8_t rx_length; ///< RX buffer length.
AnnaBridge 146:22da6e220af6 205 }nrf_drv_spi_xfer_desc_t;
AnnaBridge 146:22da6e220af6 206
AnnaBridge 146:22da6e220af6 207
AnnaBridge 146:22da6e220af6 208 /**
AnnaBridge 146:22da6e220af6 209 * @brief Macro for setting up single transfer descriptor.
AnnaBridge 146:22da6e220af6 210 *
AnnaBridge 146:22da6e220af6 211 * This macro is for internal use only.
AnnaBridge 146:22da6e220af6 212 */
AnnaBridge 146:22da6e220af6 213 #define NRF_DRV_SPI_SINGLE_XFER(p_tx, tx_len, p_rx, rx_len) \
AnnaBridge 146:22da6e220af6 214 { \
AnnaBridge 146:22da6e220af6 215 .p_tx_buffer = (uint8_t const *)(p_tx), \
AnnaBridge 146:22da6e220af6 216 .tx_length = (tx_len), \
AnnaBridge 146:22da6e220af6 217 .p_rx_buffer = (p_rx), \
AnnaBridge 146:22da6e220af6 218 .rx_length = (rx_len), \
AnnaBridge 146:22da6e220af6 219 }
AnnaBridge 146:22da6e220af6 220
AnnaBridge 146:22da6e220af6 221 /**
AnnaBridge 146:22da6e220af6 222 * @brief Macro for setting duplex TX RX transfer.
AnnaBridge 146:22da6e220af6 223 */
AnnaBridge 146:22da6e220af6 224 #define NRF_DRV_SPI_XFER_TRX(p_tx_buf, tx_length, p_rx_buf, rx_length) \
AnnaBridge 146:22da6e220af6 225 NRF_DRV_SPI_SINGLE_XFER(p_tx_buf, tx_length, p_rx_buf, rx_length)
AnnaBridge 146:22da6e220af6 226
AnnaBridge 146:22da6e220af6 227 /**
AnnaBridge 146:22da6e220af6 228 * @brief Macro for setting TX transfer.
AnnaBridge 146:22da6e220af6 229 */
AnnaBridge 146:22da6e220af6 230 #define NRF_DRV_SPI_XFER_TX(p_buf, length) \
AnnaBridge 146:22da6e220af6 231 NRF_DRV_SPI_SINGLE_XFER(p_buf, length, NULL, 0)
AnnaBridge 146:22da6e220af6 232
AnnaBridge 146:22da6e220af6 233 /**
AnnaBridge 146:22da6e220af6 234 * @brief Macro for setting RX transfer.
AnnaBridge 146:22da6e220af6 235 */
AnnaBridge 146:22da6e220af6 236 #define NRF_DRV_SPI_XFER_RX(p_buf, length) \
AnnaBridge 146:22da6e220af6 237 NRF_DRV_SPI_SINGLE_XFER(NULL, 0, p_buf, length)
AnnaBridge 146:22da6e220af6 238
AnnaBridge 146:22da6e220af6 239 /**
AnnaBridge 146:22da6e220af6 240 * @brief SPI master driver event types, passed to the handler routine provided
AnnaBridge 146:22da6e220af6 241 * during initialization.
AnnaBridge 146:22da6e220af6 242 */
AnnaBridge 146:22da6e220af6 243 typedef enum
AnnaBridge 146:22da6e220af6 244 {
AnnaBridge 146:22da6e220af6 245 NRF_DRV_SPI_EVENT_DONE, ///< Transfer done.
AnnaBridge 146:22da6e220af6 246 } nrf_drv_spi_evt_type_t;
AnnaBridge 146:22da6e220af6 247
AnnaBridge 146:22da6e220af6 248 typedef struct
AnnaBridge 146:22da6e220af6 249 {
AnnaBridge 146:22da6e220af6 250 nrf_drv_spi_evt_type_t type; ///< Event type.
AnnaBridge 146:22da6e220af6 251 union
AnnaBridge 146:22da6e220af6 252 {
AnnaBridge 146:22da6e220af6 253 nrf_drv_spi_xfer_desc_t done; ///< Event data for DONE event.
AnnaBridge 146:22da6e220af6 254 } data;
AnnaBridge 146:22da6e220af6 255 } nrf_drv_spi_evt_t;
AnnaBridge 146:22da6e220af6 256
AnnaBridge 146:22da6e220af6 257 /**
AnnaBridge 146:22da6e220af6 258 * @brief SPI master driver event handler type.
AnnaBridge 146:22da6e220af6 259 */
AnnaBridge 146:22da6e220af6 260 typedef void (*nrf_drv_spi_handler_t)(nrf_drv_spi_evt_t const * p_event);
AnnaBridge 146:22da6e220af6 261
AnnaBridge 146:22da6e220af6 262
AnnaBridge 146:22da6e220af6 263 /**
AnnaBridge 146:22da6e220af6 264 * @brief Function for initializing the SPI master driver instance.
AnnaBridge 146:22da6e220af6 265 *
AnnaBridge 146:22da6e220af6 266 * This function configures and enables the specified peripheral.
AnnaBridge 146:22da6e220af6 267 *
AnnaBridge 146:22da6e220af6 268 * @param[in] p_instance Pointer to the instance structure.
AnnaBridge 146:22da6e220af6 269 * @param[in] p_config Pointer to the structure with the initial configuration.
AnnaBridge 146:22da6e220af6 270 * If NULL, the default configuration is used.
AnnaBridge 146:22da6e220af6 271 * @param handler Event handler provided by the user. If NULL, transfers
AnnaBridge 146:22da6e220af6 272 * will be performed in blocking mode.
AnnaBridge 146:22da6e220af6 273 *
AnnaBridge 146:22da6e220af6 274 * @retval NRF_SUCCESS If initialization was successful.
AnnaBridge 146:22da6e220af6 275 * @retval NRF_ERROR_INVALID_STATE If the driver was already initialized.
AnnaBridge 146:22da6e220af6 276 * @retval NRF_ERROR_BUSY If some other peripheral with the same
AnnaBridge 146:22da6e220af6 277 * instance ID is already in use. This is
AnnaBridge 146:22da6e220af6 278 * possible only if PERIPHERAL_RESOURCE_SHARING_ENABLED
AnnaBridge 146:22da6e220af6 279 * is set to a value other than zero.
AnnaBridge 146:22da6e220af6 280 */
AnnaBridge 146:22da6e220af6 281 ret_code_t nrf_drv_spi_init(nrf_drv_spi_t const * const p_instance,
AnnaBridge 146:22da6e220af6 282 nrf_drv_spi_config_t const * p_config,
AnnaBridge 146:22da6e220af6 283 nrf_drv_spi_handler_t handler);
AnnaBridge 146:22da6e220af6 284
AnnaBridge 146:22da6e220af6 285 /**
AnnaBridge 146:22da6e220af6 286 * @brief Function for uninitializing the SPI master driver instance.
AnnaBridge 146:22da6e220af6 287 *
AnnaBridge 146:22da6e220af6 288 * @param[in] p_instance Pointer to the instance structure.
AnnaBridge 146:22da6e220af6 289 */
AnnaBridge 146:22da6e220af6 290 void nrf_drv_spi_uninit(nrf_drv_spi_t const * const p_instance);
AnnaBridge 146:22da6e220af6 291
AnnaBridge 146:22da6e220af6 292 /**
AnnaBridge 146:22da6e220af6 293 * @brief Function for starting the SPI data transfer.
AnnaBridge 146:22da6e220af6 294 *
AnnaBridge 146:22da6e220af6 295 * If an event handler was provided in the @ref nrf_drv_spi_init call, this function
AnnaBridge 146:22da6e220af6 296 * returns immediately and the handler is called when the transfer is done.
AnnaBridge 146:22da6e220af6 297 * Otherwise, the transfer is performed in blocking mode, which means that this function
AnnaBridge 146:22da6e220af6 298 * returns when the transfer is finished.
AnnaBridge 146:22da6e220af6 299 *
AnnaBridge 146:22da6e220af6 300 * @note Peripherals using EasyDMA (for example, SPIM) require the transfer buffers
AnnaBridge 146:22da6e220af6 301 * to be placed in the Data RAM region. If they are not and an SPIM instance is
AnnaBridge 146:22da6e220af6 302 * used, this function will fail with the error code NRF_ERROR_INVALID_ADDR.
AnnaBridge 146:22da6e220af6 303 *
AnnaBridge 146:22da6e220af6 304 * @param[in] p_instance Pointer to the instance structure.
AnnaBridge 146:22da6e220af6 305 * @param[in] p_tx_buffer Pointer to the transmit buffer. Can be NULL
AnnaBridge 146:22da6e220af6 306 * if there is nothing to send.
AnnaBridge 146:22da6e220af6 307 * @param tx_buffer_length Length of the transmit buffer.
AnnaBridge 146:22da6e220af6 308 * @param[in] p_rx_buffer Pointer to the receive buffer. Can be NULL
AnnaBridge 146:22da6e220af6 309 * if there is nothing to receive.
AnnaBridge 146:22da6e220af6 310 * @param rx_buffer_length Length of the receive buffer.
AnnaBridge 146:22da6e220af6 311 *
AnnaBridge 146:22da6e220af6 312 * @retval NRF_SUCCESS If the operation was successful.
AnnaBridge 146:22da6e220af6 313 * @retval NRF_ERROR_BUSY If a previously started transfer has not finished
AnnaBridge 146:22da6e220af6 314 * yet.
AnnaBridge 146:22da6e220af6 315 * @retval NRF_ERROR_INVALID_ADDR If the provided buffers are not placed in the Data
AnnaBridge 146:22da6e220af6 316 * RAM region.
AnnaBridge 146:22da6e220af6 317 */
AnnaBridge 146:22da6e220af6 318 ret_code_t nrf_drv_spi_transfer(nrf_drv_spi_t const * const p_instance,
AnnaBridge 146:22da6e220af6 319 uint8_t const * p_tx_buffer,
AnnaBridge 146:22da6e220af6 320 uint8_t tx_buffer_length,
AnnaBridge 146:22da6e220af6 321 uint8_t * p_rx_buffer,
AnnaBridge 146:22da6e220af6 322 uint8_t rx_buffer_length);
AnnaBridge 146:22da6e220af6 323
AnnaBridge 146:22da6e220af6 324
AnnaBridge 146:22da6e220af6 325 /**
AnnaBridge 146:22da6e220af6 326 * @brief Function for starting the SPI data transfer with additional option flags.
AnnaBridge 146:22da6e220af6 327 *
AnnaBridge 146:22da6e220af6 328 * Function enables customizing the transfer by using option flags.
AnnaBridge 146:22da6e220af6 329 *
AnnaBridge 146:22da6e220af6 330 * Additional options are provided using the flags parameter:
AnnaBridge 146:22da6e220af6 331 *
AnnaBridge 146:22da6e220af6 332 * - @ref NRF_DRV_SPI_FLAG_TX_POSTINC and @ref NRF_DRV_SPI_FLAG_RX_POSTINC<span></span>:
AnnaBridge 146:22da6e220af6 333 * Post-incrementation of buffer addresses. Supported only by SPIM.
AnnaBridge 146:22da6e220af6 334 * - @ref NRF_DRV_SPI_FLAG_HOLD_XFER<span></span>: Driver is not starting the transfer. Use this
AnnaBridge 146:22da6e220af6 335 * flag if the transfer is triggered externally by PPI. Supported only by SPIM. Use
AnnaBridge 146:22da6e220af6 336 * @ref nrf_drv_twi_start_task_get to get the address of the start task.
AnnaBridge 146:22da6e220af6 337 * - @ref NRF_DRV_SPI_FLAG_NO_XFER_EVT_HANDLER<span></span>: No user event handler after transfer
AnnaBridge 146:22da6e220af6 338 * completion. This also means no interrupt at the end of the transfer. Supported only by SPIM.
AnnaBridge 146:22da6e220af6 339 * If @ref NRF_DRV_SPI_FLAG_NO_XFER_EVT_HANDLER is used, the driver does not set the instance into
AnnaBridge 146:22da6e220af6 340 * busy state, so you must ensure that the next transfers are set up when SPIM is not active.
AnnaBridge 146:22da6e220af6 341 * @ref nrf_drv_spi_end_event_get function can be used to detect end of transfer. Option can be used
AnnaBridge 146:22da6e220af6 342 * together with @ref NRF_DRV_SPI_FLAG_REPEATED_XFER to prepare a sequence of SPI transfers
AnnaBridge 146:22da6e220af6 343 * without interruptions.
AnnaBridge 146:22da6e220af6 344 * - @ref NRF_DRV_SPI_FLAG_REPEATED_XFER<span></span>: Prepare for repeated transfers. You can set
AnnaBridge 146:22da6e220af6 345 * up a number of transfers that will be triggered externally (for example by PPI). An example is
AnnaBridge 146:22da6e220af6 346 * a TXRX transfer with the options @ref NRF_DRV_SPI_FLAG_RX_POSTINC,
AnnaBridge 146:22da6e220af6 347 * @ref NRF_DRV_SPI_FLAG_NO_XFER_EVT_HANDLER, and @ref NRF_DRV_SPI_FLAG_REPEATED_XFER. After the
AnnaBridge 146:22da6e220af6 348 * transfer is set up, a set of transfers can be triggered by PPI that will read, for example,
AnnaBridge 146:22da6e220af6 349 * the same register of an external component and put it into a RAM buffer without any interrupts.
AnnaBridge 146:22da6e220af6 350 * @ref nrf_drv_spi_end_event_get can be used to get the address of the END event, which can be
AnnaBridge 146:22da6e220af6 351 * used to count the number of transfers. If @ref NRF_DRV_SPI_FLAG_REPEATED_XFER is used,
AnnaBridge 146:22da6e220af6 352 * the driver does not set the instance into busy state, so you must ensure that the next
AnnaBridge 146:22da6e220af6 353 * transfers are set up when SPIM is not active. Supported only by SPIM.
AnnaBridge 146:22da6e220af6 354 * @note Function is intended to be used only in non-blocking mode.
AnnaBridge 146:22da6e220af6 355 *
AnnaBridge 146:22da6e220af6 356 * @param p_instance SPI instance.
AnnaBridge 146:22da6e220af6 357 * @param p_xfer_desc Pointer to the transfer descriptor.
AnnaBridge 146:22da6e220af6 358 * @param flags Transfer options (0 for default settings).
AnnaBridge 146:22da6e220af6 359 *
AnnaBridge 146:22da6e220af6 360 * @retval NRF_SUCCESS If the procedure was successful.
AnnaBridge 146:22da6e220af6 361 * @retval NRF_ERROR_BUSY If the driver is not ready for a new transfer.
AnnaBridge 146:22da6e220af6 362 * @retval NRF_ERROR_NOT_SUPPORTED If the provided parameters are not supported.
AnnaBridge 146:22da6e220af6 363 * @retval NRF_ERROR_INVALID_ADDR If the provided buffers are not placed in the Data
AnnaBridge 146:22da6e220af6 364 * RAM region.
AnnaBridge 146:22da6e220af6 365 */
AnnaBridge 146:22da6e220af6 366 ret_code_t nrf_drv_spi_xfer(nrf_drv_spi_t const * const p_instance,
AnnaBridge 146:22da6e220af6 367 nrf_drv_spi_xfer_desc_t const * p_xfer_desc,
AnnaBridge 146:22da6e220af6 368 uint32_t flags);
AnnaBridge 146:22da6e220af6 369
AnnaBridge 146:22da6e220af6 370 /**
AnnaBridge 146:22da6e220af6 371 * @brief Function for returning the address of a SPIM start task.
AnnaBridge 146:22da6e220af6 372 *
AnnaBridge 146:22da6e220af6 373 * This function should be used if @ref nrf_drv_spi_xfer was called with the flag @ref NRF_DRV_SPI_FLAG_HOLD_XFER.
AnnaBridge 146:22da6e220af6 374 * In that case, the transfer is not started by the driver, but it must be started externally by PPI.
AnnaBridge 146:22da6e220af6 375 *
AnnaBridge 146:22da6e220af6 376 * @param[in] p_instance SPI instance.
AnnaBridge 146:22da6e220af6 377 *
AnnaBridge 146:22da6e220af6 378 * @return Start task address.
AnnaBridge 146:22da6e220af6 379 */
AnnaBridge 146:22da6e220af6 380 uint32_t nrf_drv_spi_start_task_get(nrf_drv_spi_t const * p_instance);
AnnaBridge 146:22da6e220af6 381
AnnaBridge 146:22da6e220af6 382 /**
AnnaBridge 146:22da6e220af6 383 * @brief Function for returning the address of a END SPIM event.
AnnaBridge 146:22da6e220af6 384 *
AnnaBridge 146:22da6e220af6 385 * A END event can be used to detect the end of a transfer if the @ref NRF_DRV_SPI_FLAG_NO_XFER_EVT_HANDLER
AnnaBridge 146:22da6e220af6 386 * option is used.
AnnaBridge 146:22da6e220af6 387 *
AnnaBridge 146:22da6e220af6 388 * @param[in] p_instance SPI instance.
AnnaBridge 146:22da6e220af6 389 *
AnnaBridge 146:22da6e220af6 390 * @return END event address.
AnnaBridge 146:22da6e220af6 391 */
AnnaBridge 146:22da6e220af6 392 uint32_t nrf_drv_spi_end_event_get(nrf_drv_spi_t const * p_instance);
AnnaBridge 146:22da6e220af6 393
AnnaBridge 146:22da6e220af6 394 void nrf_drv_spi_abort(nrf_drv_spi_t const * p_instance);
AnnaBridge 146:22da6e220af6 395
AnnaBridge 146:22da6e220af6 396 #endif // NRF_DRV_SPI_H__
AnnaBridge 146:22da6e220af6 397
AnnaBridge 146:22da6e220af6 398 /** @} */