1 /* 2 * Copyright (c) 2015 - 2018, Nordic Semiconductor ASA 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, this 9 * list of conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 15 * 3. Neither the name of the copyright holder nor the names of its 16 * contributors may be used to endorse or promote products derived from this 17 * software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 23 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 * POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 #ifndef NRFX_TWIM_H__ 33 #define NRFX_TWIM_H__ 34 35 #include <nrfx.h> 36 #include <hal/nrf_twim.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** 43 * @defgroup nrfx_twim TWIM driver 44 * @{ 45 * @ingroup nrf_twim 46 * @brief TWIM peripheral driver. 47 */ 48 49 /** 50 * @brief Structure for the TWI master driver instance. 51 */ 52 typedef struct 53 { 54 NRF_TWIM_Type * p_twim; ///< Pointer to a structure with TWIM registers. 55 uint8_t drv_inst_idx; ///< Driver instance index. 56 } nrfx_twim_t; 57 58 /** 59 * @brief Macro for creating a TWI master driver instance. 60 */ 61 #define NRFX_TWIM_INSTANCE(id) \ 62 { \ 63 .p_twim = NRFX_CONCAT_2(NRF_TWIM, id), \ 64 .drv_inst_idx = NRFX_CONCAT_3(NRFX_TWIM, id, _INST_IDX), \ 65 } 66 67 enum { 68 #if NRFX_CHECK(NRFX_TWIM0_ENABLED) 69 NRFX_TWIM0_INST_IDX, 70 #endif 71 #if NRFX_CHECK(NRFX_TWIM1_ENABLED) 72 NRFX_TWIM1_INST_IDX, 73 #endif 74 #if NRFX_CHECK(NRFX_TWIM2_ENABLED) 75 NRFX_TWIM2_INST_IDX, 76 #endif 77 #if NRFX_CHECK(NRFX_TWIM3_ENABLED) 78 NRFX_TWIM3_INST_IDX, 79 #endif 80 NRFX_TWIM_ENABLED_COUNT 81 }; 82 83 /** 84 * @brief Structure for the TWI master driver instance configuration. 85 */ 86 typedef struct 87 { 88 uint32_t scl; ///< SCL pin number. 89 uint32_t sda; ///< SDA pin number. 90 nrf_twim_frequency_t frequency; ///< TWIM frequency. 91 uint8_t interrupt_priority; ///< Interrupt priority. 92 bool hold_bus_uninit; ///< Hold pull up state on gpio pins after uninit. 93 } nrfx_twim_config_t; 94 95 /** 96 * @brief TWI master driver instance default configuration. 97 */ 98 #define NRFX_TWIM_DEFAULT_CONFIG \ 99 { \ 100 .frequency = (nrf_twim_frequency_t)NRFX_TWIM_DEFAULT_CONFIG_FREQUENCY, \ 101 .scl = 31, \ 102 .sda = 31, \ 103 .interrupt_priority = NRFX_TWIM_DEFAULT_CONFIG_IRQ_PRIORITY, \ 104 .hold_bus_uninit = NRFX_TWIM_DEFAULT_CONFIG_HOLD_BUS_UNINIT, \ 105 } 106 107 #define NRFX_TWIM_FLAG_TX_POSTINC (1UL << 0) /**< TX buffer address incremented after transfer. */ 108 #define NRFX_TWIM_FLAG_RX_POSTINC (1UL << 1) /**< RX buffer address incremented after transfer. */ 109 #define NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER (1UL << 2) /**< Interrupt after each transfer is suppressed, and the event handler is not called. */ 110 #define NRFX_TWIM_FLAG_HOLD_XFER (1UL << 3) /**< Set up the transfer but do not start it. */ 111 #define NRFX_TWIM_FLAG_REPEATED_XFER (1UL << 4) /**< Flag indicating that the transfer will be executed multiple times. */ 112 #define NRFX_TWIM_FLAG_TX_NO_STOP (1UL << 5) /**< Flag indicating that the TX transfer will not end with a stop condition. */ 113 114 /** 115 * @brief TWI master driver event types. 116 */ 117 typedef enum 118 { 119 NRFX_TWIM_EVT_DONE, ///< Transfer completed event. 120 NRFX_TWIM_EVT_ADDRESS_NACK, ///< Error event: NACK received after sending the address. 121 NRFX_TWIM_EVT_DATA_NACK ///< Error event: NACK received after sending a data byte. 122 } nrfx_twim_evt_type_t; 123 124 /** 125 * @brief TWI master driver transfer types. 126 */ 127 typedef enum 128 { 129 NRFX_TWIM_XFER_TX, ///< TX transfer. 130 NRFX_TWIM_XFER_RX, ///< RX transfer. 131 NRFX_TWIM_XFER_TXRX, ///< TX transfer followed by RX transfer with repeated start. 132 NRFX_TWIM_XFER_TXTX ///< TX transfer followed by TX transfer with repeated start. 133 } nrfx_twim_xfer_type_t; 134 135 /** 136 * @brief Structure for a TWI transfer descriptor. 137 */ 138 typedef struct 139 { 140 nrfx_twim_xfer_type_t type; ///< Type of transfer. 141 uint8_t address; ///< Slave address. 142 size_t primary_length; ///< Number of bytes transferred. 143 size_t secondary_length; ///< Number of bytes transferred. 144 uint8_t * p_primary_buf; ///< Pointer to transferred data. 145 uint8_t * p_secondary_buf; ///< Pointer to transferred data. 146 } nrfx_twim_xfer_desc_t; 147 148 149 /**@brief Macro for setting the TX transfer descriptor. */ 150 #define NRFX_TWIM_XFER_DESC_TX(addr, p_data, length) \ 151 { \ 152 .type = NRFX_TWIM_XFER_TX, \ 153 .address = addr, \ 154 .primary_length = length, \ 155 .p_primary_buf = p_data, \ 156 } 157 158 /**@brief Macro for setting the RX transfer descriptor. */ 159 #define NRFX_TWIM_XFER_DESC_RX(addr, p_data, length) \ 160 { \ 161 .type = NRFX_TWIM_XFER_RX, \ 162 .address = addr, \ 163 .primary_length = length, \ 164 .p_primary_buf = p_data, \ 165 } 166 167 /**@brief Macro for setting the TXRX transfer descriptor. */ 168 #define NRFX_TWIM_XFER_DESC_TXRX(addr, p_tx, tx_len, p_rx, rx_len) \ 169 { \ 170 .type = NRFX_TWIM_XFER_TXRX, \ 171 .address = addr, \ 172 .primary_length = tx_len, \ 173 .secondary_length = rx_len, \ 174 .p_primary_buf = p_tx, \ 175 .p_secondary_buf = p_rx, \ 176 } 177 178 /**@brief Macro for setting the TXTX transfer descriptor. */ 179 #define NRFX_TWIM_XFER_DESC_TXTX(addr, p_tx, tx_len, p_tx2, tx_len2) \ 180 { \ 181 .type = NRFX_TWIM_XFER_TXTX, \ 182 .address = addr, \ 183 .primary_length = tx_len, \ 184 .secondary_length = tx_len2, \ 185 .p_primary_buf = p_tx, \ 186 .p_secondary_buf = p_tx2, \ 187 } 188 189 /** 190 * @brief Structure for a TWI event. 191 */ 192 typedef struct 193 { 194 nrfx_twim_evt_type_t type; ///< Event type. 195 nrfx_twim_xfer_desc_t xfer_desc; ///< Transfer details. 196 } nrfx_twim_evt_t; 197 198 /** 199 * @brief TWI event handler prototype. 200 */ 201 typedef void (* nrfx_twim_evt_handler_t)(nrfx_twim_evt_t const * p_event, 202 void * p_context); 203 204 /** 205 * @brief Function for initializing the TWI driver instance. 206 * 207 * @param[in] p_instance Pointer to the driver instance structure. 208 * @param[in] p_config Pointer to the structure with initial configuration. 209 * @param[in] event_handler Event handler provided by the user. If NULL, blocking mode is enabled. 210 * @param[in] p_context Context passed to event handler. 211 * 212 * @retval NRFX_SUCCESS If initialization was successful. 213 * @retval NRFX_ERROR_INVALID_STATE If the driver is in invalid state. 214 * @retval NRFX_ERROR_BUSY If some other peripheral with the same 215 * instance ID is already in use. This is 216 * possible only if @ref nrfx_prs module 217 * is enabled. 218 */ 219 nrfx_err_t nrfx_twim_init(nrfx_twim_t const * p_instance, 220 nrfx_twim_config_t const * p_config, 221 nrfx_twim_evt_handler_t event_handler, 222 void * p_context); 223 224 /** 225 * @brief Function for uninitializing the TWI instance. 226 * 227 * @param[in] p_instance Pointer to the driver instance structure. 228 */ 229 void nrfx_twim_uninit(nrfx_twim_t const * p_instance); 230 231 /** 232 * @brief Function for enabling the TWI instance. 233 * 234 * @param[in] p_instance Pointer to the driver instance structure. 235 */ 236 void nrfx_twim_enable(nrfx_twim_t const * p_instance); 237 238 /** 239 * @brief Function for disabling the TWI instance. 240 * 241 * @param[in] p_instance Pointer to the driver instance structure. 242 */ 243 void nrfx_twim_disable(nrfx_twim_t const * p_instance); 244 245 /** 246 * @brief Function for sending data to a TWI slave. 247 * 248 * The transmission will be stopped when an error occurs. If a transfer is ongoing, 249 * the function returns the error code @ref NRFX_ERROR_BUSY. 250 * 251 * @note Peripherals using EasyDMA (including TWIM) require the transfer buffers 252 * to be placed in the Data RAM region. If this condition is not met, 253 * this function will fail with the error code NRFX_ERROR_INVALID_ADDR. 254 * 255 * @param[in] p_instance Pointer to the driver instance structure. 256 * @param[in] address Address of a specific slave device (only 7 LSB). 257 * @param[in] p_data Pointer to a transmit buffer. 258 * @param[in] length Number of bytes to send. Maximum possible length is 259 * dependent on the used SoC (see the MAXCNT register 260 * description in the Product Specification). The driver 261 * checks it with assertion. 262 * @param[in] no_stop If set, the stop condition is not generated on the bus 263 * after the transfer has completed successfully (allowing 264 * for a repeated start in the next transfer). 265 * 266 * @retval NRFX_SUCCESS If the procedure was successful. 267 * @retval NRFX_ERROR_BUSY If the driver is not ready for a new transfer. 268 * @retval NRFX_ERROR_INTERNAL If an error was detected by hardware. 269 * @retval NRFX_ERROR_INVALID_ADDR If the provided buffer is not placed in the Data RAM region. 270 * @retval NRFX_ERROR_DRV_TWI_ERR_ANACK If NACK received after sending the address in polling mode. 271 * @retval NRFX_ERROR_DRV_TWI_ERR_DNACK If NACK received after sending a data byte in polling mode. 272 */ 273 nrfx_err_t nrfx_twim_tx(nrfx_twim_t const * p_instance, 274 uint8_t address, 275 uint8_t const * p_data, 276 size_t length, 277 bool no_stop); 278 279 /** 280 * @brief Function for reading data from a TWI slave. 281 * 282 * The transmission will be stopped when an error occurs. If a transfer is ongoing, 283 * the function returns the error code @ref NRFX_ERROR_BUSY. 284 * 285 * @param[in] p_instance Pointer to the driver instance structure. 286 * @param[in] address Address of a specific slave device (only 7 LSB). 287 * @param[in] p_data Pointer to a receive buffer. 288 * @param[in] length Number of bytes to be received. Maximum possible length 289 * is dependent on the used SoC (see the MAXCNT register 290 * description in the Product Specification). The driver 291 * checks it with assertion. 292 * 293 * @retval NRFX_SUCCESS If the procedure was successful. 294 * @retval NRFX_ERROR_BUSY If the driver is not ready for a new transfer. 295 * @retval NRFX_ERROR_INTERNAL If an error was detected by hardware. 296 * @retval NRFX_ERROR_DRV_TWI_ERR_ANACK If NACK received after sending the address in polling mode. 297 * @retval NRFX_ERROR_DRV_TWI_ERR_DNACK If NACK received after sending a data byte in polling mode. 298 */ 299 nrfx_err_t nrfx_twim_rx(nrfx_twim_t const * p_instance, 300 uint8_t address, 301 uint8_t * p_data, 302 size_t length); 303 304 /** 305 * @brief Function for preparing a TWI transfer. 306 * 307 * The following transfer types can be configured (@ref nrfx_twim_xfer_desc_t::type): 308 * - @ref NRFX_TWIM_XFER_TXRX<span></span>: Write operation followed by a read operation (without STOP condition in between). 309 * - @ref NRFX_TWIM_XFER_TXTX<span></span>: Write operation followed by a write operation (without STOP condition in between). 310 * - @ref NRFX_TWIM_XFER_TX<span></span>: Write operation (with or without STOP condition). 311 * - @ref NRFX_TWIM_XFER_RX<span></span>: Read operation (with STOP condition). 312 * 313 * @note TXRX and TXTX transfers are supported only in non-blocking mode. 314 * 315 * Additional options are provided using the flags parameter: 316 * - @ref NRFX_TWIM_FLAG_TX_POSTINC and @ref NRFX_TWIM_FLAG_RX_POSTINC<span></span>: Post-incrementation of buffer addresses. Supported only by TWIM. 317 * - @ref NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER<span></span>: No user event handler after transfer completion. In most cases, this also means no interrupt at the end of the transfer. 318 * - @ref NRFX_TWIM_FLAG_HOLD_XFER<span></span>: Driver is not starting the transfer. Use this flag if the transfer is triggered externally by PPI. Supported only by TWIM. 319 * Use @ref nrfx_twim_start_task_get to get the address of the start task. 320 * - @ref NRFX_TWIM_FLAG_REPEATED_XFER<span></span>: Prepare for repeated transfers. You can set up a number of transfers that will be triggered externally (for example by PPI). 321 * An example is a TXRX transfer with the options @ref NRFX_TWIM_FLAG_RX_POSTINC, @ref NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER, and @ref NRFX_TWIM_FLAG_REPEATED_XFER. 322 * After the transfer is set up, a set of transfers can be triggered by PPI that will read, for example, the same register of an 323 * external component and put it into a RAM buffer without any interrupts. @ref nrfx_twim_stopped_event_get can be used to get the 324 * address of the STOPPED event, which can be used to count the number of transfers. If @ref NRFX_TWIM_FLAG_REPEATED_XFER is used, 325 * the driver does not set the driver instance into busy state, so you must ensure that the next transfers are set up 326 * when TWIM is not active. Supported only by TWIM. 327 * - @ref NRFX_TWIM_FLAG_TX_NO_STOP<span></span>: No stop condition after TX transfer. 328 * 329 * @note 330 * Some flag combinations are invalid: 331 * - @ref NRFX_TWIM_FLAG_TX_NO_STOP with @ref nrfx_twim_xfer_desc_t::type different than @ref NRFX_TWIM_XFER_TX 332 * - @ref NRFX_TWIM_FLAG_REPEATED_XFER with @ref nrfx_twim_xfer_desc_t::type set to @ref NRFX_TWIM_XFER_TXTX 333 * 334 * If @ref nrfx_twim_xfer_desc_t::type is set to @ref NRFX_TWIM_XFER_TX and the @ref NRFX_TWIM_FLAG_TX_NO_STOP and @ref NRFX_TWIM_FLAG_REPEATED_XFER 335 * flags are set, two tasks must be used to trigger a transfer: TASKS_RESUME followed by TASKS_STARTTX. If no stop condition is generated, 336 * TWIM is in SUSPENDED state. Therefore, it must be resumed before the transfer can be started. 337 * 338 * @note Peripherals using EasyDMA (including TWIM) require the transfer buffers 339 * to be placed in the Data RAM region. If this condition is not met, 340 * this function will fail with the error code NRFX_ERROR_INVALID_ADDR. 341 * 342 * @param[in] p_instance Pointer to the driver instance structure. 343 * @param[in] p_xfer_desc Pointer to the transfer descriptor. 344 * @param[in] flags Transfer options (0 for default settings). 345 * 346 * @retval NRFX_SUCCESS If the procedure was successful. 347 * @retval NRFX_ERROR_BUSY If the driver is not ready for a new transfer. 348 * @retval NRFX_ERROR_NOT_SUPPORTED If the provided parameters are not supported. 349 * @retval NRFX_ERROR_INTERNAL If an error was detected by hardware. 350 * @retval NRFX_ERROR_INVALID_ADDR If the provided buffers are not placed in the Data RAM region. 351 * @retval NRFX_ERROR_DRV_TWI_ERR_ANACK If NACK received after sending the address. 352 * @retval NRFX_ERROR_DRV_TWI_ERR_DNACK If NACK received after sending a data byte. 353 */ 354 nrfx_err_t nrfx_twim_xfer(nrfx_twim_t const * p_instance, 355 nrfx_twim_xfer_desc_t const * p_xfer_desc, 356 uint32_t flags); 357 358 /** 359 * @brief Function for checking the TWI driver state. 360 * 361 * @param[in] p_instance TWI instance. 362 * 363 * @retval true If the TWI driver is currently busy performing a transfer. 364 * @retval false If the TWI driver is ready for a new transfer. 365 */ 366 bool nrfx_twim_is_busy(nrfx_twim_t const * p_instance); 367 368 369 /** 370 * @brief Function for returning the address of a TWIM start task. 371 * 372 * This function should be used if @ref nrfx_twim_xfer was called with the flag @ref NRFX_TWIM_FLAG_HOLD_XFER. 373 * In that case, the transfer is not started by the driver, but it must be started externally by PPI. 374 * 375 * @param[in] p_instance Pointer to the driver instance structure. 376 * @param[in] xfer_type Transfer type used in the last call of the @ref nrfx_twim_xfer function. 377 * 378 * @return Start task address (TX or RX) depending on the value of xfer_type. 379 */ 380 uint32_t nrfx_twim_start_task_get(nrfx_twim_t const * p_instance, nrfx_twim_xfer_type_t xfer_type); 381 382 /** 383 * @brief Function for returning the address of a STOPPED TWIM event. 384 * 385 * A STOPPED event can be used to detect the end of a transfer if the @ref NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER 386 * option is used. 387 * 388 * @param[in] p_instance Pointer to the driver instance structure. 389 * 390 * @return STOPPED event address. 391 */ 392 uint32_t nrfx_twim_stopped_event_get(nrfx_twim_t const * p_instance); 393 394 395 void nrfx_twim_0_irq_handler(void); 396 void nrfx_twim_1_irq_handler(void); 397 void nrfx_twim_2_irq_handler(void); 398 void nrfx_twim_3_irq_handler(void); 399 400 401 /** @} */ 402 403 #ifdef __cplusplus 404 } 405 #endif 406 407 #endif // NRFX_TWIM_H__ 408