1 /*
2 * Copyright (c) 2015 - 2020, 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 <nrfx_twi_twim.h>
37 #include <hal/nrf_twim.h>
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 /**
44 * @defgroup nrfx_twim TWIM driver
45 * @{
46 * @ingroup nrf_twim
47 * @brief Two Wire Interface Master with EasyDMA (TWIM) peripheral driver.
48 */
49
50 /** @brief Structure for the TWI master driver instance. */
51 typedef struct
52 {
53 NRF_TWIM_Type * p_twim; ///< Pointer to a structure with TWIM registers.
54 uint8_t drv_inst_idx; ///< Index of the driver instance. For internal use only.
55 } nrfx_twim_t;
56
57 /** @brief Macro for creating a TWI master driver instance. */
58 #define NRFX_TWIM_INSTANCE(id) \
59 { \
60 .p_twim = NRFX_CONCAT_2(NRF_TWIM, id), \
61 .drv_inst_idx = NRFX_CONCAT_3(NRFX_TWIM, id, _INST_IDX), \
62 }
63
64 #ifndef __NRFX_DOXYGEN__
65 enum {
66 #if NRFX_CHECK(NRFX_TWIM0_ENABLED)
67 NRFX_TWIM0_INST_IDX,
68 #endif
69 #if NRFX_CHECK(NRFX_TWIM1_ENABLED)
70 NRFX_TWIM1_INST_IDX,
71 #endif
72 #if NRFX_CHECK(NRFX_TWIM2_ENABLED)
73 NRFX_TWIM2_INST_IDX,
74 #endif
75 #if NRFX_CHECK(NRFX_TWIM3_ENABLED)
76 NRFX_TWIM3_INST_IDX,
77 #endif
78 NRFX_TWIM_ENABLED_COUNT
79 };
80 #endif
81
82 /** @brief Structure for the TWI master driver instance configuration. */
83 typedef struct
84 {
85 uint32_t scl; ///< SCL pin number.
86 uint32_t sda; ///< SDA pin number.
87 nrf_twim_frequency_t frequency; ///< TWIM frequency.
88 uint8_t interrupt_priority; ///< Interrupt priority.
89 bool hold_bus_uninit; ///< Hold pull up state on GPIO pins after uninit.
90 } nrfx_twim_config_t;
91
92 /**
93 * @brief TWIM driver default configuration.
94 *
95 * This configuration sets up TWIM with the following options:
96 * - clock frequency: 100 kHz
97 * - disable bus holding after uninit
98 *
99 * @param[in] _pin_scl SCL pin.
100 * @param[in] _pin_sda SDA pin.
101 */
102 #define NRFX_TWIM_DEFAULT_CONFIG(_pin_scl, _pin_sda) \
103 { \
104 .scl = _pin_scl, \
105 .sda = _pin_sda, \
106 .frequency = NRF_TWIM_FREQ_100K, \
107 .interrupt_priority = NRFX_TWIM_DEFAULT_CONFIG_IRQ_PRIORITY, \
108 .hold_bus_uninit = false, \
109 }
110
111 /** @brief Flag indicating that TX buffer address will be incremented after the transfer. */
112 #define NRFX_TWIM_FLAG_TX_POSTINC (1UL << 0)
113 /** @brief Flag indicating that RX buffer address will be incremented after the transfer. */
114 #define NRFX_TWIM_FLAG_RX_POSTINC (1UL << 1)
115 /** @brief Flag indicating that the interrupt after each transfer will be suppressed, and the event handler will not be called. */
116 #define NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER (1UL << 2)
117 /** @brief Flag indicating that the transfer will be set up, but not started. */
118 #define NRFX_TWIM_FLAG_HOLD_XFER (1UL << 3)
119 /** @brief Flag indicating that the transfer will be executed multiple times. */
120 #define NRFX_TWIM_FLAG_REPEATED_XFER (1UL << 4)
121 /** @brief Flag indicating that the TX transfer will not end with a stop condition. */
122 #define NRFX_TWIM_FLAG_TX_NO_STOP (1UL << 5)
123 /** @brief Flag indicating that checks for spurious STOP condition will not be performed. */
124 #define NRFX_TWIM_FLAG_NO_SPURIOUS_STOP_CHECK (1UL << 6)
125
126 /** @brief TWI master driver event types. */
127 typedef enum
128 {
129 NRFX_TWIM_EVT_DONE, ///< Transfer completed event.
130 NRFX_TWIM_EVT_ADDRESS_NACK, ///< Error event: NACK received after sending the address.
131 NRFX_TWIM_EVT_DATA_NACK, ///< Error event: NACK received after sending a data byte.
132 NRFX_TWIM_EVT_OVERRUN, ///< Error event: The unread data is replaced by new data.
133 NRFX_TWIM_EVT_BUS_ERROR ///< Error event: An unexpected transition occurred on the bus.
134 } nrfx_twim_evt_type_t;
135
136 /** @brief TWI master driver transfer types. */
137 typedef enum
138 {
139 NRFX_TWIM_XFER_TX, ///< TX transfer.
140 NRFX_TWIM_XFER_RX, ///< RX transfer.
141 NRFX_TWIM_XFER_TXRX, ///< TX transfer followed by RX transfer with repeated start.
142 NRFX_TWIM_XFER_TXTX ///< TX transfer followed by TX transfer with repeated start.
143 } nrfx_twim_xfer_type_t;
144
145 /** @brief Structure for a TWI transfer descriptor. */
146 typedef struct
147 {
148 nrfx_twim_xfer_type_t type; ///< Type of transfer.
149 uint8_t address; ///< Slave address.
150 size_t primary_length; ///< Number of bytes transferred.
151 size_t secondary_length; ///< Number of bytes transferred.
152 uint8_t * p_primary_buf; ///< Pointer to transferred data.
153 uint8_t * p_secondary_buf; ///< Pointer to transferred data.
154 } nrfx_twim_xfer_desc_t;
155
156
157 /** @brief Macro for setting the TX transfer descriptor. */
158 #define NRFX_TWIM_XFER_DESC_TX(addr, p_data, length) \
159 { \
160 .type = NRFX_TWIM_XFER_TX, \
161 .address = (addr), \
162 .primary_length = (length), \
163 .secondary_length = 0, \
164 .p_primary_buf = (p_data), \
165 .p_secondary_buf = NULL, \
166 }
167
168 /** @brief Macro for setting the RX transfer descriptor. */
169 #define NRFX_TWIM_XFER_DESC_RX(addr, p_data, length) \
170 { \
171 .type = NRFX_TWIM_XFER_RX, \
172 .address = (addr), \
173 .primary_length = (length), \
174 .secondary_length = 0, \
175 .p_primary_buf = (p_data), \
176 .p_secondary_buf = NULL, \
177 }
178
179 /** @brief Macro for setting the TX-RX transfer descriptor. */
180 #define NRFX_TWIM_XFER_DESC_TXRX(addr, p_tx, tx_len, p_rx, rx_len) \
181 { \
182 .type = NRFX_TWIM_XFER_TXRX, \
183 .address = (addr), \
184 .primary_length = (tx_len), \
185 .secondary_length = (rx_len), \
186 .p_primary_buf = (p_tx), \
187 .p_secondary_buf = (p_rx), \
188 }
189
190 /** @brief Macro for setting the TX-TX transfer descriptor. */
191 #define NRFX_TWIM_XFER_DESC_TXTX(addr, p_tx, tx_len, p_tx2, tx_len2) \
192 { \
193 .type = NRFX_TWIM_XFER_TXTX, \
194 .address = (addr), \
195 .primary_length = (tx_len), \
196 .secondary_length = (tx_len2), \
197 .p_primary_buf = (p_tx), \
198 .p_secondary_buf = (p_tx2), \
199 }
200
201 /** @brief Structure for a TWI event. */
202 typedef struct
203 {
204 nrfx_twim_evt_type_t type; ///< Event type.
205 nrfx_twim_xfer_desc_t xfer_desc; ///< Transfer details.
206 } nrfx_twim_evt_t;
207
208 /** @brief TWI event handler prototype. */
209 typedef void (* nrfx_twim_evt_handler_t)(nrfx_twim_evt_t const * p_event,
210 void * p_context);
211
212 /**
213 * @brief Function for initializing the TWI driver instance.
214 *
215 * @param[in] p_instance Pointer to the driver instance structure.
216 * @param[in] p_config Pointer to the structure with the initial configuration.
217 * @param[in] event_handler Event handler provided by the user. If NULL, blocking mode is enabled.
218 * @param[in] p_context Context passed to event handler.
219 *
220 * @retval NRFX_SUCCESS Initialization was successful.
221 * @retval NRFX_ERROR_INVALID_STATE The driver is in invalid state.
222 * @retval NRFX_ERROR_BUSY Some other peripheral with the same
223 * instance ID is already in use. This is
224 * possible only if @ref nrfx_prs module
225 * is enabled.
226 */
227 nrfx_err_t nrfx_twim_init(nrfx_twim_t const * p_instance,
228 nrfx_twim_config_t const * p_config,
229 nrfx_twim_evt_handler_t event_handler,
230 void * p_context);
231
232 /**
233 * @brief Function for uninitializing the TWI instance.
234 *
235 * @param[in] p_instance Pointer to the driver instance structure.
236 */
237 void nrfx_twim_uninit(nrfx_twim_t const * p_instance);
238
239 /**
240 * @brief Function for enabling the TWI instance.
241 *
242 * @param[in] p_instance Pointer to the driver instance structure.
243 */
244 void nrfx_twim_enable(nrfx_twim_t const * p_instance);
245
246 /**
247 * @brief Function for disabling the TWI instance.
248 *
249 * @param[in] p_instance Pointer to the driver instance structure.
250 */
251 void nrfx_twim_disable(nrfx_twim_t const * p_instance);
252
253 /**
254 * @brief Function for performing a TWI transfer.
255 *
256 * The following transfer types can be configured (@ref nrfx_twim_xfer_desc_t.type):
257 * - @ref NRFX_TWIM_XFER_TXRX - Write operation followed by a read operation (without STOP condition in between).
258 * - @ref NRFX_TWIM_XFER_TXTX - Write operation followed by a write operation (without STOP condition in between).
259 * - @ref NRFX_TWIM_XFER_TX - Write operation (with or without STOP condition).
260 * - @ref NRFX_TWIM_XFER_RX - Read operation (with STOP condition).
261 *
262 * @note TX-RX and TX-TX transfers are supported only in non-blocking mode.
263 *
264 * Additional options are provided using the flags parameter:
265 * - @ref NRFX_TWIM_FLAG_TX_POSTINC and @ref NRFX_TWIM_FLAG_RX_POSTINC - Post-incrementation of buffer addresses.
266 * - @ref NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER - No user event handler after the transfer completion. In most cases, this also means no interrupt at the end of the transfer.
267 * - @ref NRFX_TWIM_FLAG_HOLD_XFER - Driver is not starting the transfer. Use this flag if the transfer is triggered externally by PPI.
268 * Use @ref nrfx_twim_start_task_get to get the address of the start task.
269 * - @ref NRFX_TWIM_FLAG_REPEATED_XFER - Prepare for repeated transfers. You can set up a number of transfers that will be triggered externally (for example by PPI).
270 * 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.
271 * 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
272 * external component and put it into a RAM buffer without any interrupts. @ref nrfx_twim_stopped_event_get can be used to get the
273 * address of the STOPPED event, which can be used to count the number of transfers. If @ref NRFX_TWIM_FLAG_REPEATED_XFER is used,
274 * the driver does not set the driver instance into busy state, so you must ensure that the next transfers are set up
275 * when TWIM is not active.
276 * - @ref NRFX_TWIM_FLAG_TX_NO_STOP - No stop condition after the TX transfer.
277 * - @ref NRFX_TWIM_FLAG_NO_SPURIOUS_STOP_CHECK - Checks for spurious STOP conditions are disabled.
278 * Used together with @ref NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER can result in lower power consumption
279 * when transfers are triggered externally and CPU is sleeping.
280 * Use only with I2C standard-compliant slave devices.
281 *
282 * @note
283 * Some flag combinations are invalid:
284 * - @ref NRFX_TWIM_FLAG_TX_NO_STOP with @ref nrfx_twim_xfer_desc_t.type different than @ref NRFX_TWIM_XFER_TX
285 * - @ref NRFX_TWIM_FLAG_REPEATED_XFER with @ref nrfx_twim_xfer_desc_t.type set to @ref NRFX_TWIM_XFER_TXTX
286 *
287 * 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
288 * flags are set, two tasks must be used to trigger a transfer: TASKS_RESUME followed by TASKS_STARTTX. If no stop condition is generated,
289 * TWIM is in SUSPENDED state. Therefore, it must be resumed before the transfer can be started.
290 *
291 * @note Peripherals using EasyDMA (including TWIM) require the transfer buffers
292 * to be placed in the Data RAM region. If this condition is not met,
293 * this function will fail with the error code NRFX_ERROR_INVALID_ADDR.
294 *
295 * @param[in] p_instance Pointer to the driver instance structure.
296 * @param[in] p_xfer_desc Pointer to the transfer descriptor.
297 * @param[in] flags Transfer options (0 for default settings).
298 *
299 * @retval NRFX_SUCCESS The procedure is successful.
300 * @retval NRFX_ERROR_BUSY The driver is not ready for a new transfer.
301 * @retval NRFX_ERROR_NOT_SUPPORTED The provided parameters are not supported.
302 * @retval NRFX_ERROR_INTERNAL An unexpected transition occurred on the bus.
303 * @retval NRFX_ERROR_INVALID_ADDR The provided buffers are not placed in the Data RAM region.
304 * @retval NRFX_ERROR_DRV_TWI_ERR_OVERRUN The unread data is replaced by new data.
305 * @retval NRFX_ERROR_DRV_TWI_ERR_ANACK NACK is received after sending the address.
306 * @retval NRFX_ERROR_DRV_TWI_ERR_DNACK NACK is received after sending a data byte.
307 */
308 nrfx_err_t nrfx_twim_xfer(nrfx_twim_t const * p_instance,
309 nrfx_twim_xfer_desc_t const * p_xfer_desc,
310 uint32_t flags);
311
312 /**
313 * @brief Function for checking the TWI driver state.
314 *
315 * @param[in] p_instance TWI instance.
316 *
317 * @retval true The TWI driver is currently busy performing a transfer.
318 * @retval false The TWI driver is ready for a new transfer.
319 */
320 bool nrfx_twim_is_busy(nrfx_twim_t const * p_instance);
321
322
323 /**
324 * @brief Function for returning the address of a TWIM start task.
325 *
326 * This function is to be used if @ref nrfx_twim_xfer was called with the flag @ref NRFX_TWIM_FLAG_HOLD_XFER.
327 * In that case, the transfer is not started by the driver, but it must be started externally by PPI.
328 *
329 * @param[in] p_instance Pointer to the driver instance structure.
330 * @param[in] xfer_type Transfer type used in the last call of the @ref nrfx_twim_xfer function.
331 *
332 * @return Start task address (TX or RX) depending on the value of xfer_type.
333 */
334 uint32_t nrfx_twim_start_task_get(nrfx_twim_t const * p_instance, nrfx_twim_xfer_type_t xfer_type);
335
336 /**
337 * @brief Function for returning the address of a STOPPED TWIM event.
338 *
339 * A STOPPED event can be used to detect the end of a transfer if the @ref NRFX_TWIM_FLAG_NO_XFER_EVT_HANDLER
340 * option is used.
341 *
342 * @param[in] p_instance Pointer to the driver instance structure.
343 *
344 * @return STOPPED event address.
345 */
346 uint32_t nrfx_twim_stopped_event_get(nrfx_twim_t const * p_instance);
347
348 /**
349 * @brief Function for recovering the bus.
350 *
351 * This function checks if the bus is not stuck because of a slave holding the SDA line in the low state,
352 * and if needed it performs required number of pulses on the SCL line to make the slave release the SDA line.
353 * Finally, the function generates a STOP condition on the bus to put it into a known state.
354 *
355 * @note This function can be used only if the TWIM driver is uninitialized.
356 *
357 * @param[in] scl_pin SCL pin number.
358 * @param[in] sda_pin SDA pin number.
359 *
360 * @retval NRFX_SUCCESS Bus recovery was successful.
361 * @retval NRFX_ERROR_INTERNAL Bus recovery failed.
362 */
363 NRFX_STATIC_INLINE nrfx_err_t nrfx_twim_bus_recover(uint32_t scl_pin, uint32_t sda_pin);
364
365 #ifndef NRFX_DECLARE_ONLY
nrfx_twim_bus_recover(uint32_t scl_pin,uint32_t sda_pin)366 NRFX_STATIC_INLINE nrfx_err_t nrfx_twim_bus_recover(uint32_t scl_pin, uint32_t sda_pin)
367 {
368 return nrfx_twi_twim_bus_recover(scl_pin, sda_pin);
369 }
370 #endif
371
372 /** @} */
373
374 void nrfx_twim_0_irq_handler(void);
375 void nrfx_twim_1_irq_handler(void);
376 void nrfx_twim_2_irq_handler(void);
377 void nrfx_twim_3_irq_handler(void);
378
379
380 #ifdef __cplusplus
381 }
382 #endif
383
384 #endif // NRFX_TWIM_H__
385