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_TWI_H__
33 #define NRFX_TWI_H__
34
35 #include <nrfx.h>
36 #include <nrfx_twi_twim.h>
37 #include <hal/nrf_twi.h>
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 /**
44 * @defgroup nrfx_twi TWI driver
45 * @{
46 * @ingroup nrf_twi
47 * @brief Two Wire Interface master (TWI) peripheral driver.
48 */
49
50 /**
51 * @brief Structure for the TWI master driver instance.
52 */
53 typedef struct
54 {
55 NRF_TWI_Type * p_twi; ///< Pointer to a structure with TWI registers.
56 uint8_t drv_inst_idx; ///< Index of the driver instance. For internal use only.
57 } nrfx_twi_t;
58
59 /** @brief Macro for creating a TWI master driver instance. */
60 #define NRFX_TWI_INSTANCE(id) \
61 { \
62 .p_twi = NRFX_CONCAT_2(NRF_TWI, id), \
63 .drv_inst_idx = NRFX_CONCAT_3(NRFX_TWI, id, _INST_IDX), \
64 }
65
66 #ifndef __NRFX_DOXYGEN__
67 enum {
68 #if NRFX_CHECK(NRFX_TWI0_ENABLED)
69 NRFX_TWI0_INST_IDX,
70 #endif
71 #if NRFX_CHECK(NRFX_TWI1_ENABLED)
72 NRFX_TWI1_INST_IDX,
73 #endif
74 NRFX_TWI_ENABLED_COUNT
75 };
76 #endif
77
78 /** @brief Structure for the configuration of the TWI master driver instance. */
79 typedef struct
80 {
81 uint32_t scl; ///< SCL pin number.
82 uint32_t sda; ///< SDA pin number.
83 nrf_twi_frequency_t frequency; ///< TWI frequency.
84 uint8_t interrupt_priority; ///< Interrupt priority.
85 bool hold_bus_uninit; ///< Hold pull up state on GPIO pins after uninit.
86 } nrfx_twi_config_t;
87
88 /**
89 * @brief TWI master driver instance default configuration.
90 *
91 * This configuration sets up TWI with the following options:
92 * - clock frequency: 100 kHz
93 * - disable bus holding after uninit
94 *
95 * @param[in] _pin_scl SCL pin.
96 * @param[in] _pin_sda SDA pin.
97 */
98 #define NRFX_TWI_DEFAULT_CONFIG(_pin_scl, _pin_sda) \
99 { \
100 .scl = _pin_scl, \
101 .sda = _pin_sda, \
102 .frequency = NRF_TWI_FREQ_100K, \
103 .interrupt_priority = NRFX_TWI_DEFAULT_CONFIG_IRQ_PRIORITY, \
104 .hold_bus_uninit = false, \
105 }
106
107 /** @brief Flag indicating that the interrupt after each transfer will be suppressed, and the event handler will not be called. */
108 #define NRFX_TWI_FLAG_NO_XFER_EVT_HANDLER (1UL << 2)
109 /** @brief Flag indicating that the TX transfer will not end with a stop condition. */
110 #define NRFX_TWI_FLAG_TX_NO_STOP (1UL << 5)
111 /** @brief Flag indicating that the transfer will be suspended. */
112 #define NRFX_TWI_FLAG_SUSPEND (1UL << 6)
113
114 /** @brief TWI master driver event types. */
115 typedef enum
116 {
117 NRFX_TWI_EVT_DONE, ///< Transfer completed event.
118 NRFX_TWI_EVT_ADDRESS_NACK, ///< Error event: NACK received after sending the address.
119 NRFX_TWI_EVT_DATA_NACK, ///< Error event: NACK received after sending a data byte.
120 NRFX_TWI_EVT_OVERRUN, ///< Error event: The unread data is replaced by new data.
121 NRFX_TWI_EVT_BUS_ERROR ///< Error event: An unexpected transition occurred on the bus.
122 } nrfx_twi_evt_type_t;
123
124 /** @brief TWI master driver transfer types. */
125 typedef enum
126 {
127 NRFX_TWI_XFER_TX, ///< TX transfer.
128 NRFX_TWI_XFER_RX, ///< RX transfer.
129 NRFX_TWI_XFER_TXRX, ///< TX transfer followed by RX transfer with repeated start.
130 NRFX_TWI_XFER_TXTX ///< TX transfer followed by TX transfer with repeated start.
131 } nrfx_twi_xfer_type_t;
132
133 /** @brief Structure for a TWI transfer descriptor. */
134 typedef struct
135 {
136 nrfx_twi_xfer_type_t type; ///< Type of transfer.
137 uint8_t address; ///< Slave address.
138 size_t primary_length; ///< Number of bytes transferred.
139 size_t secondary_length; ///< Number of bytes transferred.
140 uint8_t * p_primary_buf; ///< Pointer to transferred data.
141 uint8_t * p_secondary_buf; ///< Pointer to transferred data.
142 } nrfx_twi_xfer_desc_t;
143
144
145 /** @brief Macro for setting the TX transfer descriptor. */
146 #define NRFX_TWI_XFER_DESC_TX(addr, p_data, length) \
147 { \
148 .type = NRFX_TWI_XFER_TX, \
149 .address = (addr), \
150 .primary_length = (length), \
151 .secondary_length = 0, \
152 .p_primary_buf = (p_data), \
153 .p_secondary_buf = NULL, \
154 }
155
156 /** @brief Macro for setting the RX transfer descriptor. */
157 #define NRFX_TWI_XFER_DESC_RX(addr, p_data, length) \
158 { \
159 .type = NRFX_TWI_XFER_RX, \
160 .address = (addr), \
161 .primary_length = (length), \
162 .secondary_length = 0, \
163 .p_primary_buf = (p_data), \
164 .p_secondary_buf = NULL, \
165 }
166
167 /** @brief Macro for setting the TX-RX transfer descriptor. */
168 #define NRFX_TWI_XFER_DESC_TXRX(addr, p_tx, tx_len, p_rx, rx_len) \
169 { \
170 .type = NRFX_TWI_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 TX-TX transfer descriptor. */
179 #define NRFX_TWI_XFER_DESC_TXTX(addr, p_tx, tx_len, p_tx2, tx_len2) \
180 { \
181 .type = NRFX_TWI_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 /** @brief Structure for a TWI event. */
190 typedef struct
191 {
192 nrfx_twi_evt_type_t type; ///< Event type.
193 nrfx_twi_xfer_desc_t xfer_desc; ///< Transfer details.
194 } nrfx_twi_evt_t;
195
196 /** @brief TWI event handler prototype. */
197 typedef void (* nrfx_twi_evt_handler_t)(nrfx_twi_evt_t const * p_event,
198 void * p_context);
199
200 /**
201 * @brief Function for initializing the TWI driver instance.
202 *
203 * @param[in] p_instance Pointer to the driver instance structure.
204 * @param[in] p_config Pointer to the structure with the initial configuration.
205 * @param[in] event_handler Event handler provided by the user. If NULL, blocking mode is enabled.
206 * @param[in] p_context Context passed to event handler.
207 *
208 * @retval NRFX_SUCCESS Initialization is successful.
209 * @retval NRFX_ERROR_INVALID_STATE The driver is in invalid state.
210 * @retval NRFX_ERROR_BUSY Some other peripheral with the same
211 * instance ID is already in use. This is
212 * possible only if @ref nrfx_prs module
213 * is enabled.
214 */
215 nrfx_err_t nrfx_twi_init(nrfx_twi_t const * p_instance,
216 nrfx_twi_config_t const * p_config,
217 nrfx_twi_evt_handler_t event_handler,
218 void * p_context);
219
220 /**
221 * @brief Function for uninitializing the TWI instance.
222 *
223 * @param[in] p_instance Pointer to the driver instance structure.
224 */
225 void nrfx_twi_uninit(nrfx_twi_t const * p_instance);
226
227 /**
228 * @brief Function for enabling the TWI instance.
229 *
230 * @param[in] p_instance Pointer to the driver instance structure.
231 */
232 void nrfx_twi_enable(nrfx_twi_t const * p_instance);
233
234 /**
235 * @brief Function for disabling the TWI instance.
236 *
237 * @param[in] p_instance Pointer to the driver instance structure.
238 */
239 void nrfx_twi_disable(nrfx_twi_t const * p_instance);
240
241 /**
242 * @brief Function for performing a TWI transfer.
243 *
244 * The following transfer types can be configured (@ref nrfx_twi_xfer_desc_t.type):
245 * - @ref NRFX_TWI_XFER_TXRX - Write operation followed by a read operation (without STOP condition in between).
246 * - @ref NRFX_TWI_XFER_TXTX - Write operation followed by a write operation (without STOP condition in between).
247 * - @ref NRFX_TWI_XFER_TX - Write operation (with or without STOP condition).
248 * - @ref NRFX_TWI_XFER_RX - Read operation (with STOP condition).
249 *
250 * @note TX-RX and TX-TX transfers are supported only in non-blocking mode.
251 *
252 * Additional options are provided using the flags parameter:
253 * - @ref NRFX_TWI_FLAG_NO_XFER_EVT_HANDLER - No user event handler after transfer completion. In most cases, this also means no interrupt at the end of the transfer.
254 * - @ref NRFX_TWI_FLAG_TX_NO_STOP - No stop condition after TX transfer.
255 * - @ref NRFX_TWI_FLAG_SUSPEND - Transfer will be suspended. This allows for combining multiple transfers into one transaction.
256 * Only transactions with the same direction can be combined. To finish the transaction, call the function without this flag.
257 *
258 * @note
259 * Some flag combinations are invalid:
260 * - @ref NRFX_TWI_FLAG_TX_NO_STOP with @ref nrfx_twi_xfer_desc_t.type different than @ref NRFX_TWI_XFER_TX
261 *
262 * @param[in] p_instance Pointer to the driver instance structure.
263 * @param[in] p_xfer_desc Pointer to the transfer descriptor.
264 * @param[in] flags Transfer options (0 for default settings).
265 *
266 * @retval NRFX_SUCCESS The procedure is successful.
267 * @retval NRFX_ERROR_BUSY The driver is not ready for a new transfer.
268 * @retval NRFX_ERROR_NOT_SUPPORTED The provided parameters are not supported.
269 * @retval NRFX_ERROR_INTERNAL An unexpected transition occurred on the bus.
270 * @retval NRFX_ERROR_INVALID_STATE Other direction of transaction is suspended on the bus.
271 * @retval NRFX_ERROR_DRV_TWI_ERR_OVERRUN The unread data is replaced by new data (TXRX and RX)
272 * @retval NRFX_ERROR_DRV_TWI_ERR_ANACK Negative acknowledgement (NACK) is received after sending
273 * the address in polling mode.
274 * @retval NRFX_ERROR_DRV_TWI_ERR_DNACK Negative acknowledgement (NACK) is received after sending
275 * a data byte in polling mode.
276 */
277 nrfx_err_t nrfx_twi_xfer(nrfx_twi_t const * p_instance,
278 nrfx_twi_xfer_desc_t const * p_xfer_desc,
279 uint32_t flags);
280
281 /**
282 * @brief Function for checking the TWI driver state.
283 *
284 * @param[in] p_instance TWI instance.
285 *
286 * @retval true The TWI driver is currently busy performing a transfer.
287 * @retval false The TWI driver is ready for a new transfer.
288 */
289 bool nrfx_twi_is_busy(nrfx_twi_t const * p_instance);
290
291 /**
292 * @brief Function for getting the transferred data count.
293 *
294 * @param[in] p_instance Pointer to the driver instance structure.
295 *
296 * @return Data count.
297 */
298 size_t nrfx_twi_data_count_get(nrfx_twi_t const * p_instance);
299
300 /**
301 * @brief Function for returning the address of a STOPPED TWI event.
302 *
303 * A STOPPED event can be used to detect the end of a transfer if the @ref NRFX_TWI_FLAG_NO_XFER_EVT_HANDLER
304 * option is used.
305 *
306 * @param[in] p_instance Pointer to the driver instance structure.
307 *
308 * @return STOPPED event address.
309 */
310 uint32_t nrfx_twi_stopped_event_get(nrfx_twi_t const * p_instance);
311
312 /**
313 * @brief Function for recovering the bus.
314 *
315 * This function checks if the bus is not stuck because of a slave holding the SDA line in the low state,
316 * and if needed it performs required number of pulses on the SCL line to make the slave release the SDA line.
317 * Finally, the function generates a STOP condition on the bus to put it into a known state.
318 *
319 * @note This function can be used only if the TWI driver is uninitialized.
320 *
321 * @param[in] scl_pin SCL pin number.
322 * @param[in] sda_pin SDA pin number.
323 *
324 * @retval NRFX_SUCCESS Bus recovery was successful.
325 * @retval NRFX_ERROR_INTERNAL Bus recovery failed.
326 */
327 NRFX_STATIC_INLINE nrfx_err_t nrfx_twi_bus_recover(uint32_t scl_pin, uint32_t sda_pin);
328
329 #ifndef NRFX_DECLARE_ONLY
nrfx_twi_bus_recover(uint32_t scl_pin,uint32_t sda_pin)330 NRFX_STATIC_INLINE nrfx_err_t nrfx_twi_bus_recover(uint32_t scl_pin, uint32_t sda_pin)
331 {
332 return nrfx_twi_twim_bus_recover(scl_pin, sda_pin);
333 }
334 #endif
335
336 /** @} */
337
338
339 void nrfx_twi_0_irq_handler(void);
340 void nrfx_twi_1_irq_handler(void);
341
342
343 #ifdef __cplusplus
344 }
345 #endif
346
347 #endif // NRFX_TWI_H__
348