1 /***************************************************************************//**
2 * \file cy_scb_i2c.h
3 * \version 3.10
4 *
5 * Provides I2C API declarations of the SCB driver.
6 *
7 ********************************************************************************
8 * \copyright
9 * Copyright 2016-2021 Cypress Semiconductor Corporation
10 * SPDX-License-Identifier: Apache-2.0
11 *
12 * Licensed under the Apache License, Version 2.0 (the "License");
13 * you may not use this file except in compliance with the License.
14 * You may obtain a copy of the License at
15 *
16 * http://www.apache.org/licenses/LICENSE-2.0
17 *
18 * Unless required by applicable law or agreed to in writing, software
19 * distributed under the License is distributed on an "AS IS" BASIS,
20 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21 * See the License for the specific language governing permissions and
22 * limitations under the License.
23 *******************************************************************************/
24
25 /**
26 * \addtogroup group_scb_i2c
27 * \{
28 * Driver API for I2C Bus Peripheral
29 *
30 * I2C - The Inter-Integrated Circuit (I2C) bus is an industry-standard.
31 *
32 * The functions and other declarations used in this part of the driver are in
33 * cy_scb_i2c.h. You can also include cy_pdl.h to get access
34 * to all functions and declarations in the PDL.
35 *
36 * The I2C peripheral driver provides an API to implement I2C slave, master,
37 * or master-slave devices based on the SCB hardware block.
38 * I2C devices based on SCB hardware are compatible with I2C
39 * Standard-mode, Fast-mode, and Fast-mode Plus specifications as defined in
40 * the I2C-bus specification.
41 *
42 * Features:
43 * * An industry-standard I2C bus interface
44 * * Supports slave, master, and master-slave operation
45 * * Supports standard data rates of 100/400/1000 kbps
46 * * Hardware Address Match, multiple addresses
47 * * Wake from Deep Sleep on Address Match
48 *
49 * \note
50 * I2C supports clock stretching. This occurs when a slave device is not capable
51 * of processing data, it holds the SCL line by driving a '0'. The master device monitors
52 * the SCL line and detects it when it cannot generate a positive clock pulse ('1') on the
53 * SCL line. It then reacts by delaying the generation of a positive edge on the SCL line,
54 * effectively synchronizing with the slave device that is stretching the clock.
55 * Clock stretching can occur in the case of externally clocked address matching until the
56 * internally clocked logic takes over. The largest reason for clock stretching is when the
57 * master tries to write to the slave and the slave's RX FIFO is full, the slave will then
58 * clock stretch until the FIFO is no longer full. For more information on FIFO size and clock
59 * stretching see the architecture TRM.
60 ********************************************************************************
61 * \section group_scb_i2c_configuration Configuration Considerations
62 ********************************************************************************
63 * The I2C driver configuration can be divided to number of sequential
64 * steps listed below:
65 * * \ref group_scb_i2c_config
66 * * \ref group_scb_i2c_pins
67 * * \ref group_scb_i2c_clock
68 * * \ref group_scb_i2c_data_rate
69 * * \ref group_scb_i2c_intr
70 * * \ref group_scb_i2c_enable
71 *
72 * \note
73 * I2C driver is built on top of the SCB hardware block. The SCB3 instance is
74 * used as an example for all code snippets. Modify the code to match your
75 * design.
76 *
77 ********************************************************************************
78 * \subsection group_scb_i2c_config Configure I2C
79 ********************************************************************************
80 * To set up the I2C driver, provide the configuration parameters in the
81 * \ref cy_stc_scb_i2c_config_t structure. Provide i2cMode to the select
82 * operation mode slave, master or master-slave. The useRxFifo and useTxFifo
83 * parameters specify if RX and TX FIFO is used during operation. Typically, both
84 * FIFOs should be enabled to reduce possibility of clock stretching. However,
85 * using RX FIFO has side effects that needs to be taken into account
86 * (see useRxFifo field description in \ref cy_stc_scb_i2c_config_t structure).
87 * For master modes, parameters lowPhaseDutyCycle, highPhaseDutyCycle and
88 * enableDigitalFilter can be used to define output data rate (refer to section
89 * \ref group_scb_i2c_data_rate for more information).
90 * For slave mode, provide the slaveAddress and slaveAddressMask. The other
91 * parameters are optional for operation.\n
92 * To initialize the driver, call \ref Cy_SCB_I2C_Init
93 * function providing a pointer to the populated \ref cy_stc_scb_i2c_config_t
94 * structure and the allocated \ref cy_stc_scb_i2c_context_t structure.
95 *
96 * \snippet scb/i2c_snippet/main.c I2C_CFG
97 *
98 * Set up I2C slave read and write buffer before enabling its
99 * operation using \ref Cy_SCB_I2C_SlaveConfigReadBuf and \ref
100 * Cy_SCB_I2C_SlaveConfigWriteBuf appropriately. Note that the master reads
101 * data from the slave read buffer and writes data into the slave write buffer.
102 *
103 * \snippet scb/i2c_snippet/main.c I2C_CFG_BUFFER
104 *
105 ********************************************************************************
106 * \subsection group_scb_i2c_pins Assign and Configure Pins
107 ********************************************************************************
108 * Only dedicated SCB pins can be used for I2C operation. The HSIOM
109 * register must be configured to connect dedicated SCB I2C pins to the
110 * SCB block. Also the I2C pins must be configured in Open-Drain, Drives Low mode
111 * (this pins configuration implies usage of external pull-up resistors):
112 *
113 * \snippet scb/i2c_snippet/main.c I2C_CFG_PINS
114 *
115 * \note
116 * The alternative pins configuration is Resistive Pull-ups which implies usage
117 * internal pull-up resistors. This configuration is not recommended because
118 * resistor value is fixed and cannot be used for all supported data rates.
119 * Refer to the device datasheet parameter RPULLUP for resistor value specifications.
120 *
121 ********************************************************************************
122 * \subsection group_scb_i2c_clock Assign Clock Divider
123 ********************************************************************************
124 * A clock source must be connected to the SCB block to oversample input and
125 * output signals, in this document this clock will be referred as clk_scb.
126 * You must use one of the 8-bit or 16-bit dividers. Use the \ref group_sysclk
127 * driver API to do this.
128 *
129 * \snippet scb/i2c_snippet/main.c I2C_CFG_ASSIGN_CLOCK
130 *
131 ********************************************************************************
132 * \subsection group_scb_i2c_data_rate Configure Data Rate
133 ********************************************************************************
134 * To get I2C slave operation with the desired data rate, the clk_scb must be
135 * fast enough to provide sufficient oversampling. Use the
136 * \ref group_sysclk driver API to do this.
137 *
138 * \snippet scb/i2c_snippet/main.c I2C_CFG_DATA_RATE_SLAVE
139 *
140 * To get I2C master operation with the desired data rate, the source clock
141 * frequency and SCL low and high phase duration must be configured. Use the
142 * \ref group_sysclk driver API to configure source clock frequency. Then call
143 * \ref Cy_SCB_I2C_SetDataRate to set the SCL low, high phase duration and
144 * digital filter. This function sets SCL low and high phase settings based on
145 * source clock frequency.
146 *
147 * \snippet scb/i2c_snippet/main.c I2C_CFG_DATA_RATE_MASTER
148 *
149 * Alternatively, the low, high phase and digital filter can be set directly
150 * using configuration structure \ref cy_stc_scb_i2c_config_t fields
151 * lowPhaseDutyCycle, highPhaseDutyCycle and enableDigitalFilter appropriately.\n
152 * <b>Refer to the technical reference manual (TRM) section I2C sub-section
153 * Oversampling and Bit Rate to get information how to configure I2C to run with
154 * the desired data rate.</b>
155 *
156 * \note
157 * For I2C slave, the analog filter is used for all supported data rates. \n
158 * For I2C master, the analog filter is used for Standard and Fast modes and the
159 * digital filter for Fast Plus mode.
160 *
161 ********************************************************************************
162 * \subsection group_scb_i2c_intr Configure Interrupt
163 ********************************************************************************
164 * The interrupt is mandatory for I2C operation. The exception is the when only
165 * the \ref group_scb_i2c_master_low_level_functions functions are used.
166 * The driver provides three interrupt functions: \ref Cy_SCB_I2C_Interrupt,
167 * \ref Cy_SCB_I2C_SlaveInterrupt, and \ref Cy_SCB_I2C_MasterInterrupt. One of
168 * these functions must be called in the interrupt handler for the selected SCB
169 * instance. Call \ref Cy_SCB_I2C_SlaveInterrupt when I2C is configured to
170 * operate as a slave, \ref Cy_SCB_I2C_MasterInterrupt when I2C is configured
171 * to operate as a master and \ref Cy_SCB_I2C_Interrupt when I2C is configured
172 * to operate as master and slave. Using the slave- or master-specific interrupt
173 * function allows reducing the flash consumed by the I2C driver. Also this
174 * interrupt must be enabled in the NVIC otherwise it will not work.
175 * \note
176 * The I2C driver documentation refers to the \ref Cy_SCB_I2C_Interrupt function
177 * when interrupt processing is mandatory for the operation. This is done to
178 * simplify the readability of the driver's documentation. The application should
179 * call the slave- or master-specific interrupt functions \ref Cy_SCB_I2C_SlaveInterrupt
180 * or \ref Cy_SCB_I2C_MasterInterrupt, when appropriate.
181 *
182 * \snippet scb/i2c_snippet/main.c I2C_INTR_A
183 * \snippet scb/i2c_snippet/main.c I2C_INTR_B
184 *
185 ********************************************************************************
186 * \subsection group_scb_i2c_enable Enable I2C
187 ********************************************************************************
188 * Finally, enable the I2C operation by calling \ref Cy_SCB_I2C_Enable. Then I2C
189 * slave starts respond to the assigned address and I2C master ready to execute
190 * transfers.
191 *
192 * \snippet scb/i2c_snippet/main.c I2C_ENABLE
193 *
194 * \section group_scb_i2c_use_cases Common Use Cases
195 *
196 ********************************************************************************
197 * \subsection group_scb_i2c_master_mode Master Operation
198 ********************************************************************************
199 * The master API is divided into two categories:
200 * \ref group_scb_i2c_master_high_level_functions and
201 * \ref group_scb_i2c_master_low_level_functions. Therefore, there are two
202 * methods for initiating I2C master transactions using either <b>Low-Level or
203 * High-Level</b> API. These two methods are described below. Only one method
204 * should be used at a time. <b>They should not be mixed.</b>
205 *
206 ********************************************************************************
207 * \subsubsection group_scb_i2c_master_hl Use High-Level Functions
208 ********************************************************************************
209 * Call \ref Cy_SCB_I2C_MasterRead or \ref Cy_SCB_I2C_MasterWrite to
210 * communicate with the slave. These functions do not block and only start a
211 * transaction. After a transaction starts, the \ref Cy_SCB_I2C_Interrupt
212 * handles further data transaction until its completion (successfully or
213 * with error occurring). To monitor the transaction,
214 * use \ref Cy_SCB_I2C_MasterGetStatus or register callback function using
215 * \ref Cy_SCB_I2C_RegisterEventCallback to be notified about
216 * \ref group_scb_i2c_macros_callback_events.
217 *
218 * \snippet scb/i2c_snippet/main.c I2C_MASTER_WRITE_READ_INT
219 *
220 ********************************************************************************
221 * \subsubsection group_scb_i2c_master_ll Use Low-Level Functions
222 ********************************************************************************
223 * Call \ref Cy_SCB_I2C_MasterSendStart to generate a start, send an address
224 * with the Read/Write direction bit, and receive acknowledgment. After the
225 * address is ACKed by the slave, the transaction can be continued by calling
226 * \ref Cy_SCB_I2C_MasterReadByte or \ref Cy_SCB_I2C_MasterWriteByte depending
227 * on its direction. These functions handle one byte per call. Therefore,
228 * they should be called for each byte in the transaction. Note that for the
229 * Read transaction, the last byte must be NAKed. To complete the current
230 * transaction, call \ref Cy_SCB_I2C_MasterSendStop or call
231 * \ref Cy_SCB_I2C_MasterSendReStart to complete the current transaction and
232 * start a new one. Typically, do a restart to change the transaction
233 * direction without releasing the bus from the master control.
234 * The Low-Level functions are blocking and do not require calling
235 * \ref Cy_SCB_I2C_Interrupt inside the interrupt handler. Using these
236 * functions requires extensive knowledge of the I2C protocol to execute
237 * transactions correctly.
238 *
239 * <b>Master Write Operation</b>
240 * \snippet scb/i2c_snippet/main.c I2C_MASTER_WRITE_MANUAL
241 *
242 * <b>Master Read Operation</b>
243 * \snippet scb/i2c_snippet/main.c I2C_MASTER_READ_MANUAL
244 *
245 ********************************************************************************
246 * \subsection group_scb_i2c_slave Slave Operation
247 ********************************************************************************
248 * Slave operation requires the \ref Cy_SCB_I2C_Interrupt be
249 * called inside the interrupt handler. The read and write buffers must
250 * be provided for the slave to enable communication with the master. Use
251 * \ref Cy_SCB_I2C_SlaveConfigReadBuf and \ref Cy_SCB_I2C_SlaveConfigWriteBuf
252 * for this purpose. Note that after transaction completion the buffer must be
253 * configured again. Otherwise, the same buffer is used starting from the point
254 * where the master stopped a previous transaction.
255 * For example: The read buffer is configured to be 10 bytes and the master reads
256 * 8 bytes. If the read buffer is not configured again, the next master read
257 * will start from the 9th byte.
258 * To monitor the transaction status, use \ref Cy_SCB_I2C_SlaveGetStatus or
259 * use \ref Cy_SCB_I2C_RegisterEventCallback to register a callback function
260 * to be notified about \ref group_scb_i2c_macros_callback_events.
261 *
262 * <b>Get Slave Events Notification</b>
263 * \snippet scb/i2c_snippet/main.c I2C_SLAVE_REG_CALLBACK
264 * \snippet scb/i2c_snippet/main.c I2C_SLAVE_NOTIFICATION
265 *
266 * <b>Polling Slave Completion Events</b>
267 * \snippet scb/i2c_snippet/main.c I2C_SLAVE_POLLING
268 *
269 * \note
270 * All slave API (except \ref Cy_SCB_I2C_SlaveAbortRead and
271 * \ref Cy_SCB_I2C_SlaveAbortWrite) <b>are not interrupt-protected</b> and to
272 * prevent a race condition, they should be protected from the I2C interruption
273 * in the place where they are called. The code snippet Polling Slave
274 * Completion Events above shows how to prevent a race condition when detect
275 * transfer completion and update I2C slave write buffer.
276 * The simple example of race condition is: application updates slave read
277 * buffer the I2C master starts read transfer. The I2C interrupts read buffer
278 * update and I2C interrupt loads current read buffer content in the TX FIFO .
279 * After I2C interrupt returns the application updates remaining part of the read
280 * buffer. As a result the mater read partly updated buffer.
281 *
282 ********************************************************************************
283 * \section group_scb_i2c_lp Low Power Support
284 ********************************************************************************
285 * The I2C driver provides callback functions to handle power mode transition.
286 * The callback \ref Cy_SCB_I2C_DeepSleepCallback must be called
287 * during execution of \ref Cy_SysPm_CpuEnterDeepSleep \ref Cy_SCB_I2C_HibernateCallback
288 * must be called during execution of \ref Cy_SysPm_SystemEnterHibernate. To trigger the
289 * callback execution, the callback must be registered before calling the
290 * power mode transition function. Refer to \ref group_syspm driver for more
291 * information about power mode transitions and callback registration.
292 *
293 * \note
294 * Only applicable for <b>rev-08 of the CY8CKIT-062-BLE</b>.
295 * For proper operation, when the I2C slave is configured to be a wakeup
296 * source from Deep Sleep mode, the \ref Cy_SCB_I2C_DeepSleepCallback must be
297 * copied and modified. Refer to the function description to get the details.
298 *
299 * \defgroup group_scb_i2c_macros Macros
300 * \defgroup group_scb_i2c_functions Functions
301 * \{
302 * \defgroup group_scb_i2c_general_functions General
303 * \defgroup group_scb_i2c_slave_functions Slave
304 * \defgroup group_scb_i2c_master_high_level_functions Master High-Level
305 * \defgroup group_scb_i2c_master_low_level_functions Master Low-Level
306 * \defgroup group_scb_i2c_interrupt_functions Interrupt
307 * \defgroup group_scb_i2c_low_power_functions Low Power Callbacks
308 * \}
309 * \defgroup group_scb_i2c_data_structures Data Structures
310 * \defgroup group_scb_i2c_enums Enumerated Types
311 */
312
313 #if !defined(CY_SCB_I2C_H)
314 #define CY_SCB_I2C_H
315
316 #include "cy_device.h"
317
318 #if (defined (CY_IP_MXSCB) || defined (CY_IP_MXS22SCB))
319
320 #include "cy_scb_common.h"
321
322 #if defined(__cplusplus)
323 extern "C" {
324 #endif
325
326 /*******************************************************************************
327 * Enumerated Types
328 *******************************************************************************/
329
330 /**
331 * \addtogroup group_scb_i2c_enums
332 * \{
333 */
334
335 /** I2C status codes */
336 typedef enum
337 {
338 /** Operation completed successfully */
339 CY_SCB_I2C_SUCCESS = 0U,
340
341 /** One or more of input parameters are invalid */
342 CY_SCB_I2C_BAD_PARAM = (CY_SCB_ID | CY_PDL_STATUS_ERROR | CY_SCB_I2C_ID | 1U),
343
344 /**
345 * The master is not ready to start a new transaction.
346 * Either the master is still processing a previous transaction or in the
347 * master-slave mode, the slave operation is in progress.
348 */
349 CY_SCB_I2C_MASTER_NOT_READY = (CY_SCB_ID | CY_PDL_STATUS_ERROR | CY_SCB_I2C_ID | 2U),
350
351 /**
352 * The master operation timed out before completing. Applicable only for
353 * the \ref group_scb_i2c_master_low_level_functions functions.
354 */
355 CY_SCB_I2C_MASTER_MANUAL_TIMEOUT = (CY_SCB_ID | CY_PDL_STATUS_ERROR | CY_SCB_I2C_ID | 3U),
356
357 /** The slave NACKed the address. Applicable only for the
358 * \ref group_scb_i2c_master_low_level_functions functions.
359 */
360 CY_SCB_I2C_MASTER_MANUAL_ADDR_NAK = (CY_SCB_ID | CY_PDL_STATUS_ERROR | CY_SCB_I2C_ID | 4U),
361
362 /** The slave NACKed the data byte. Applicable only for the
363 * \ref group_scb_i2c_master_low_level_functions.
364 */
365 CY_SCB_I2C_MASTER_MANUAL_NAK = (CY_SCB_ID | CY_PDL_STATUS_ERROR | CY_SCB_I2C_ID | 5U),
366
367 /**
368 * The master lost arbitration, the transaction was aborted. Applicable only
369 * for the \ref group_scb_i2c_master_low_level_functions functions.
370 */
371 CY_SCB_I2C_MASTER_MANUAL_ARB_LOST = (CY_SCB_ID | CY_PDL_STATUS_ERROR | CY_SCB_I2C_ID | 6U),
372
373 /**
374 * The master detected an erroneous start or stop, the transaction was
375 * aborted. Applicable only for the
376 * \ref group_scb_i2c_master_low_level_functions functions.
377 */
378 CY_SCB_I2C_MASTER_MANUAL_BUS_ERR = (CY_SCB_ID | CY_PDL_STATUS_ERROR | CY_SCB_I2C_ID | 7U),
379
380 /**
381 * The master transaction was aborted and the slave transaction is on-going
382 * because the slave was addressed before the master generated a start.
383 * Applicable only for the \ref group_scb_i2c_master_low_level_functions
384 * functions.
385 */
386 CY_SCB_I2C_MASTER_MANUAL_ABORT_START = (CY_SCB_ID | CY_PDL_STATUS_ERROR | CY_SCB_I2C_ID | 8U)
387 } cy_en_scb_i2c_status_t;
388
389 /** I2C Operation Modes */
390 typedef enum
391 {
392 CY_SCB_I2C_SLAVE = 1U, /**< Configures SCB for I2C Slave operation */
393 CY_SCB_I2C_MASTER = 2U, /**< Configures SCB for I2C Master operation */
394 CY_SCB_I2C_MASTER_SLAVE = 3U, /**< Configures SCB for I2C Master-Slave operation */
395 } cy_en_scb_i2c_mode_t;
396
397 /** I2C Transaction Direction */
398 typedef enum
399 {
400 CY_SCB_I2C_WRITE_XFER = 0U, /**< Current transaction is Write */
401 CY_SCB_I2C_READ_XFER = 1U, /**< Current transaction is Read */
402 } cy_en_scb_i2c_direction_t;
403
404 /** I2C Command ACK / NAK */
405 typedef enum
406 {
407 CY_SCB_I2C_ACK, /**< Send ACK to current byte */
408 CY_SCB_I2C_NAK, /**< Send NAK to current byte */
409 } cy_en_scb_i2c_command_t;
410 /** \} group_scb_i2c_enums */
411
412
413 /*******************************************************************************
414 * Type Definitions
415 *******************************************************************************/
416
417 /**
418 * \addtogroup group_scb_i2c_data_structures
419 * \{
420 */
421
422 /**
423 * Provides the typedef for the callback function called in the
424 * \ref Cy_SCB_I2C_Interrupt to notify the user about occurrences of
425 * \ref group_scb_i2c_macros_callback_events.
426 */
427 typedef void (* cy_cb_scb_i2c_handle_events_t)(uint32_t event);
428
429 /**
430 * Provides the typedef for the callback function called in the
431 * \ref Cy_SCB_I2C_Interrupt to notify the user about occurrences of
432 * \ref group_scb_i2c_macros_addr_callback_events.
433 * This callback must return a decision to ACK (continue transaction) or
434 * NAK (end transaction) the received address.
435 * Note if the slave is configured to accept an address in RX FIFO, it must read
436 * from it using the \ref Cy_SCB_ReadRxFifo function.
437 */
438 typedef cy_en_scb_i2c_command_t (* cy_cb_scb_i2c_handle_addr_t)(uint32_t event);
439
440 /** I2C configuration structure */
441 typedef struct cy_stc_scb_i2c_config
442 {
443 /** Specifies the mode of operation */
444 cy_en_scb_i2c_mode_t i2cMode;
445
446 /**
447 * The SCB provides an RX FIFO in hardware (consult the selected device
448 * datasheet to get the actual FIFO size). The useRxFifo field defines
449 * how the driver firmware reads data from the RX FIFO:
450 * * If this option is enabled, the hardware is configured to automatically
451 * ACK incoming data, and interrupt is enabled to take data out of the RX
452 * FIFO when it has some number of bytes (typically, when it is half full).
453 * * If this option is disabled, the interrupt is enabled to take data out of
454 * the RX FIFO when a byte is available. Also, hardware does not
455 * automatically ACK the data. Firmware must tell the hardware to ACK
456 * the byte (so each byte requires interrupt processing).
457 * \n <b>Typically, this option should be enabled</b> to configure hardware to
458 * automatically ACK incoming data. Otherwise hardware might not get the command
459 * to ACK or NACK a byte fast enough, and clock stretching is applied
460 * (the transaction is delayed) until the command is set. When this option is
461 * enabled, the number of interrupts required to process the transaction
462 * is significantly reduced because several bytes are handled at once.
463 * \n <b>However, there is a side effect:</b>
464 * * For master mode, the drawback is that the master may receive more
465 * data than desired due to the interrupt latency. An interrupt fires
466 * when the second-to-last byte has been received. This interrupt tells
467 * the hardware to stop receiving data. If the latency of this interrupt
468 * is longer than one transaction of the byte on the I2C bus, then the
469 * hardware automatically ACKs the following bytes until the interrupt
470 * is serviced or the RX FIFO becomes full.
471 * * For slave mode, the drawback is that the slave only NACKs
472 * the master when the RX FIFO becomes full, NOT when the slave write
473 * firmware buffer becomes full.
474 * \n In either master or slave mode, all received extra bytes are dropped.
475 * \note The useRxFifo option is not available if acceptAddrInFifo is true.
476 */
477 bool useRxFifo;
478
479 /**
480 * The SCB provides a TX FIFO in hardware (consult the selected device
481 * datasheet to get the actual FIFO size). The useTxFifo option defines how the
482 * driver firmware loads data into the TX FIFO:
483 * * If this option is enabled, the TX FIFO is fully loaded with data and the
484 * interrupt is enabled to keep the TX FIFO loaded until the end of the transaction.
485 * * If this option is disabled, a single byte is loaded into the TX FIFO and
486 * the interrupt enabled to load the next byte when the TX FIFO becomes empty
487 * (so each byte requires interrupt processing).
488 * \n <b>Typically, this option should be enabled</b> to keep the TX FIFO loaded with
489 * data and reduce the probability of clock stretching. When there is no data
490 * to transfer, clock stretching is applied (the transaction is delayed) until
491 * the data is loaded. When this option is enabled, the number of interrupts required
492 * to process the transaction is significantly reduced because several
493 * bytes are handled at once.
494 * \n <b>The drawback of enabling useTxFifo</b> is that the abort operation clears
495 * the TX FIFO. The TX FIFO clear operation also clears the shift
496 * register. As a result the shifter may be cleared in the middle of a byte
497 * transaction, corrupting it. The remaining bits to transaction within the
498 * corrupted byte are complemented with 1s. If this is an issue,
499 * then do not enable this option.
500 */
501 bool useTxFifo;
502
503 /**
504 * The 7-bit right justified slave address, used only for the slave mode
505 */
506 uint8_t slaveAddress;
507
508 /**
509 * The slave address mask is used to mask bits of the slave address during
510 * the address match procedure (it is used only for the slave mode).
511 * Bit 0 of the address mask corresponds to the
512 * read/write direction bit and is always a do not care in the address match
513 * therefore must be set 0. Bit value 0 - excludes bit from address
514 * comparison. Bit value 1 - the bit needs to match with the corresponding
515 * bit of the I2C slave address.
516 */
517 uint8_t slaveAddressMask;
518
519 /**
520 * True - the slave address is accepted in the RX FIFO, false - the slave
521 * addresses are not accepted in the RX FIFO
522 */
523 bool acceptAddrInFifo;
524
525 /**
526 * True - accept the general call address; false - ignore the general
527 * call address.
528 */
529 bool ackGeneralAddr;
530
531 /**
532 * When set, the slave will wake the device from Deep Sleep on an address
533 * match (the device datasheet must be consulted to determine which SCBs
534 * support this mode)
535 */
536 bool enableWakeFromSleep;
537
538 /**
539 * Enables a digital 3-tap median filter to be applied to the inputs
540 * of filter glitches on the lines.
541 */
542 bool enableDigitalFilter;
543
544 /**
545 * The number of SCB clock cycles in the low phase of SCL. Only applicable
546 * in master modes. The valid range is 7 to 16.
547 */
548 uint32_t lowPhaseDutyCycle;
549
550 /**
551 * The number of SCB clock cycles in the high phase of SCL. Only applicable
552 * in master modes. The valid range is 5 to 16.
553 */
554 uint32_t highPhaseDutyCycle;
555
556 } cy_stc_scb_i2c_config_t;
557
558 /** I2C context structure.
559 * All fields for the context structure are internal. Firmware never reads or
560 * writes these values. Firmware allocates the structure and provides the
561 * address of the structure to the driver in function calls. Firmware must
562 * ensure that the defined instance of this structure remains in scope
563 * while the drive is in use.
564 */
565 typedef struct cy_stc_scb_i2c_context
566 {
567 /** \cond INTERNAL */
568 bool useRxFifo; /**< Stores RX FIFO configuration */
569 bool useTxFifo; /**< Stores TX FIFO configuration */
570
571 volatile uint32_t state; /**< The driver state */
572
573 volatile uint32_t masterStatus; /**< The master status */
574 bool masterPause; /**< Stores how the master ends the transaction */
575 bool masterRdDir; /**< The direction of the master transaction */
576
577 uint8_t *masterBuffer; /**< The pointer to the master buffer (either for a transmit or a receive operation) */
578 uint32_t masterBufferSize; /**< The current master buffer size */
579 volatile uint32_t masterBufferIdx; /**< The current location in the master buffer */
580 volatile uint32_t masterNumBytes; /**< The number of bytes to send or receive */
581
582 volatile uint32_t slaveStatus; /**< The slave status */
583 volatile bool slaveRdBufEmpty; /**< Tracks slave Read buffer empty event */
584
585 uint8_t *slaveTxBuffer; /**< The pointer to the slave transmit buffer (a master reads from it) */
586 uint32_t slaveTxBufferSize; /**< The current slave transmit buffer size */
587 volatile uint32_t slaveTxBufferIdx; /**< The current location in the slave buffer */
588 volatile uint32_t slaveTxBufferCnt; /**< The number of transferred bytes */
589
590 uint8_t *slaveRxBuffer; /**< The pointer to the slave receive buffer (a master writes into it) */
591 uint32_t slaveRxBufferSize; /**< The current slave receive buffer size */
592 volatile uint32_t slaveRxBufferIdx; /**< The current location in the slave buffer */
593
594 /**
595 * The pointer to an event callback that is called when any of
596 * \ref group_scb_i2c_macros_callback_events occurs
597 */
598 cy_cb_scb_i2c_handle_events_t cbEvents;
599
600 /**
601 * The pointer to an address callback that is called when any of
602 * \ref group_scb_i2c_macros_addr_callback_events occurs (applicable only
603 * for the slave)
604 */
605 cy_cb_scb_i2c_handle_addr_t cbAddr;
606
607 /** \endcond */
608 } cy_stc_scb_i2c_context_t;
609
610 /** The I2C Master transfer structure */
611 typedef struct cy_stc_scb_i2c_master_xfer_config
612 {
613 /** The 7-bit right justified slave address to communicate with */
614 uint8_t slaveAddress;
615
616 /**
617 * The pointer to the buffer for data to read from the slave or
618 * data to write into the slave
619 */
620 uint8_t *buffer;
621
622 /** The size of the buffer */
623 uint32_t bufferSize;
624
625 /**
626 * The transfer operation is pending - the stop condition will not
627 * be generated.
628 * A new transfer starts from start condition and ends
629 * with or without stop condition. The stop condition releases I2C
630 * bus from master control. When stop is not generated master keeps
631 * bus control (transfer is pending) and can issue the next transfer
632 * using restart condition instead of start. The I2C driver
633 * automatically generates start or restart condition depends on
634 * current state.
635 * Note if master lost arbitration during transfer it stops control
636 * the bus and does not send/receive data or generate stop condition - the
637 * transfer ends.
638 */
639 bool xferPending;
640 } cy_stc_scb_i2c_master_xfer_config_t;
641 /** \} group_scb_i2c_data_structures */
642
643
644 /*******************************************************************************
645 * Function Prototypes
646 *******************************************************************************/
647
648 /**
649 * \addtogroup group_scb_i2c_general_functions
650 * \{
651 */
652 cy_en_scb_i2c_status_t Cy_SCB_I2C_Init(CySCB_Type *base, cy_stc_scb_i2c_config_t const *config,
653 cy_stc_scb_i2c_context_t *context);
654 void Cy_SCB_I2C_DeInit(CySCB_Type *base);
655 __STATIC_INLINE void Cy_SCB_I2C_Enable(CySCB_Type *base);
656 void Cy_SCB_I2C_Disable(CySCB_Type *base, cy_stc_scb_i2c_context_t *context);
657
658 uint32_t Cy_SCB_I2C_SetDataRate(CySCB_Type *base, uint32_t dataRateHz, uint32_t scbClockHz);
659 uint32_t Cy_SCB_I2C_GetDataRate(CySCB_Type const *base, uint32_t scbClockHz);
660
661 __STATIC_INLINE void Cy_SCB_I2C_SlaveSetAddress(CySCB_Type *base, uint8_t addr);
662 __STATIC_INLINE uint32_t Cy_SCB_I2C_SlaveGetAddress(CySCB_Type const *base);
663 __STATIC_INLINE void Cy_SCB_I2C_SlaveSetAddressMask(CySCB_Type *base, uint8_t addrMask);
664 __STATIC_INLINE uint32_t Cy_SCB_I2C_SlaveGetAddressMask(CySCB_Type const *base);
665
666 __STATIC_INLINE bool Cy_SCB_I2C_IsBusBusy(CySCB_Type const *base);
667
668 __STATIC_INLINE void Cy_SCB_I2C_MasterSetLowPhaseDutyCycle (CySCB_Type *base, uint32_t clockCycles);
669 __STATIC_INLINE void Cy_SCB_I2C_MasterSetHighPhaseDutyCycle(CySCB_Type *base, uint32_t clockCycles);
670 #if (((defined (CY_IP_MXSCB_VERSION) && (CY_IP_MXSCB_VERSION>=3)) || defined (CY_IP_MXS22SCB)) || defined (CY_DOXYGEN))
671 void Cy_SCB_I2C_SetStretchThreshold(CySCB_Type const *base, uint32_t value);
672 uint32_t Cy_SCB_I2C_GetStretchCount(CySCB_Type const *base);
673 bool Cy_SCB_I2C_IsStretchDetected(CySCB_Type const *base);
674 bool Cy_SCB_I2C_IsSyncDetected(CySCB_Type const *base);
675 bool Cy_SCB_I2C_IsStretching(CySCB_Type const *base);
676 #endif /* CY_IP_MXSCB_VERSION */
677
678 /** \} group_scb_i2c_general_functions */
679
680 /**
681 * \addtogroup group_scb_i2c_slave_functions
682 * \{
683 */
684 void Cy_SCB_I2C_SlaveConfigReadBuf (CySCB_Type const *base, uint8_t *buffer, uint32_t size,
685 cy_stc_scb_i2c_context_t *context);
686 void Cy_SCB_I2C_SlaveAbortRead (CySCB_Type *base, cy_stc_scb_i2c_context_t *context);
687 void Cy_SCB_I2C_SlaveConfigWriteBuf(CySCB_Type const *base, uint8_t *buffer, uint32_t size,
688 cy_stc_scb_i2c_context_t *context);
689 void Cy_SCB_I2C_SlaveAbortWrite (CySCB_Type *base, cy_stc_scb_i2c_context_t *context);
690
691 uint32_t Cy_SCB_I2C_SlaveGetStatus (CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context);
692 uint32_t Cy_SCB_I2C_SlaveClearReadStatus (CySCB_Type const *base, cy_stc_scb_i2c_context_t *context);
693 uint32_t Cy_SCB_I2C_SlaveClearWriteStatus(CySCB_Type const *base, cy_stc_scb_i2c_context_t *context);
694
695 uint32_t Cy_SCB_I2C_SlaveGetReadTransferCount (CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context);
696 uint32_t Cy_SCB_I2C_SlaveGetWriteTransferCount(CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context);
697 /** \} group_scb_i2c_slave_functions */
698
699 /**
700 * \addtogroup group_scb_i2c_master_high_level_functions
701 * \{
702 */
703 cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterWrite(CySCB_Type *base, cy_stc_scb_i2c_master_xfer_config_t *xferConfig,
704 cy_stc_scb_i2c_context_t *context);
705 void Cy_SCB_I2C_MasterAbortWrite (CySCB_Type *base, cy_stc_scb_i2c_context_t *context);
706 cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterRead (CySCB_Type *base, cy_stc_scb_i2c_master_xfer_config_t* xferConfig,
707 cy_stc_scb_i2c_context_t *context);
708 void Cy_SCB_I2C_MasterAbortRead (CySCB_Type *base, cy_stc_scb_i2c_context_t *context);
709 uint32_t Cy_SCB_I2C_MasterGetStatus (CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context);
710 uint32_t Cy_SCB_I2C_MasterGetTransferCount (CySCB_Type const *base, cy_stc_scb_i2c_context_t const *context);
711 /** \} group_scb_i2c_master_low_high_functions */
712
713 /**
714 * \addtogroup group_scb_i2c_master_low_level_functions
715 * \{
716 */
717 cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterSendStart (CySCB_Type *base, uint32_t address, cy_en_scb_i2c_direction_t bitRnW,
718 uint32_t timeoutMs, cy_stc_scb_i2c_context_t *context);
719 cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterSendReStart(CySCB_Type *base, uint32_t address, cy_en_scb_i2c_direction_t bitRnW,
720 uint32_t timeoutMs, cy_stc_scb_i2c_context_t *context);
721 cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterSendStop (CySCB_Type *base,uint32_t timeoutMs, cy_stc_scb_i2c_context_t *context);
722 cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterReadByte (CySCB_Type *base, cy_en_scb_i2c_command_t ackNack, uint8_t *byte,
723 uint32_t timeoutMs, cy_stc_scb_i2c_context_t *context);
724 cy_en_scb_i2c_status_t Cy_SCB_I2C_MasterWriteByte (CySCB_Type *base, uint8_t byte, uint32_t timeoutMs,
725 cy_stc_scb_i2c_context_t *context);
726 /** \} group_scb_i2c_master_low_level_functions */
727
728 /**
729 * \addtogroup group_scb_i2c_interrupt_functions
730 * \{
731 */
732 void Cy_SCB_I2C_Interrupt (CySCB_Type *base, cy_stc_scb_i2c_context_t *context);
733 void Cy_SCB_I2C_SlaveInterrupt (CySCB_Type *base, cy_stc_scb_i2c_context_t *context);
734 void Cy_SCB_I2C_MasterInterrupt (CySCB_Type *base, cy_stc_scb_i2c_context_t *context);
735
736 __STATIC_INLINE void Cy_SCB_I2C_RegisterEventCallback(CySCB_Type const *base, cy_cb_scb_i2c_handle_events_t callback,
737 cy_stc_scb_i2c_context_t *context);
738 __STATIC_INLINE void Cy_SCB_I2C_RegisterAddrCallback (CySCB_Type const *base, cy_cb_scb_i2c_handle_addr_t callback,
739 cy_stc_scb_i2c_context_t *context);
740 /** \} group_scb_i2c_interrupt_functions */
741
742 /**
743 * \addtogroup group_scb_i2c_low_power_functions
744 * \{
745 */
746 cy_en_syspm_status_t Cy_SCB_I2C_DeepSleepCallback(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode);
747 cy_en_syspm_status_t Cy_SCB_I2C_HibernateCallback(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode);
748 /** \} group_scb_i2c_low_power_functions */
749
750
751 /*******************************************************************************
752 * API Constants
753 *******************************************************************************/
754
755 /**
756 * \addtogroup group_scb_i2c_macros
757 * \{
758 */
759
760 /**
761 * \defgroup group_scb_i2c_macros_slave_status I2C Slave Status
762 * Macros to check current I2C slave status returned by
763 * \ref Cy_SCB_I2C_SlaveGetStatus function. Each I2C slave status is encoded
764 * in a separate bit, therefore multiple bits may be set to indicate the
765 * current status.
766 * \{
767 */
768 /** There is a read transaction in progress */
769 #define CY_SCB_I2C_SLAVE_RD_BUSY (0x00000001UL)
770
771 /**
772 * All read data has been loaded into the TX FIFO, applicable only if
773 * the TX FIFO is used
774 */
775 #define CY_SCB_I2C_SLAVE_RD_IN_FIFO (0x00000002UL)
776
777 /**
778 * The master has finished reading data from the slave
779 */
780 #define CY_SCB_I2C_SLAVE_RD_CMPLT (0x00000004UL)
781
782 /**
783 * Set when the master tried to read more bytes than available in the configured
784 * read buffer. The slave is not able to finish the transaction and sends
785 * \ref CY_SCB_I2C_DEFAULT_TX.
786 */
787 #define CY_SCB_I2C_SLAVE_RD_UNDRFL (0x00000008UL)
788
789 /** There is a write transaction in progress */
790 #define CY_SCB_I2C_SLAVE_WR_BUSY (0x00000010UL)
791
792 /**
793 * The master has finished writing data into the slave
794 */
795 #define CY_SCB_I2C_SLAVE_WR_CMPLT (0x00000020UL)
796
797 /**
798 * The master attempted to write more bytes than space available in the
799 * configured Write buffer. Note that all subsequent bytes are dropped.
800 */
801 #define CY_SCB_I2C_SLAVE_WR_OVRFL (0x00000040UL)
802
803 /** The slave lost arbitration, and the transaction was aborted */
804 #define CY_SCB_I2C_SLAVE_ARB_LOST (0x00000080UL)
805
806 /**
807 * The slave captured an error on the bus during a master transaction (source
808 * of error is misplaced Start or Stop).
809 */
810 #define CY_SCB_I2C_SLAVE_BUS_ERR (0x00000100UL)
811 /** \} group_scb_i2c_macros_slave_status */
812
813 /**
814 * \defgroup group_scb_i2c_macros_master_status I2C Master Status
815 * Macros to check current I2C master status returned by
816 * \ref Cy_SCB_I2C_MasterGetStatus function. Each I2C master status is encoded
817 * in a separate bit, therefore multiple bits may be set to indicate the
818 * current status.
819 * \{
820 */
821
822 /**
823 * The master is busy executing operation started by \ref Cy_SCB_I2C_MasterRead
824 * or \ref Cy_SCB_I2C_MasterWrite
825 */
826 #define CY_SCB_I2C_MASTER_BUSY (0x00010000UL)
827
828 /**
829 * All Write data has been loaded into the TX FIFO
830 */
831 #define CY_SCB_I2C_MASTER_WR_IN_FIFO (0x00020000UL)
832
833 /** The slave NACKed the address. */
834 #define CY_SCB_I2C_MASTER_ADDR_NAK (0x00100000UL)
835
836 /** Write completed before all bytes were sent (last byte was NAKed)
837 */
838 #define CY_SCB_I2C_MASTER_DATA_NAK (0x00200000UL)
839
840 /** The master lost arbitration, the transaction was aborted */
841 #define CY_SCB_I2C_MASTER_ARB_LOST (0x00400000UL)
842
843 /**
844 * The master detected an erroneous start or stop, the transaction was aborted
845 */
846 #define CY_SCB_I2C_MASTER_BUS_ERR (0x00800000UL)
847
848 /**
849 * The master transaction was aborted and the slave transaction is on-going
850 * because the slave was addressed before the master generated a start
851 */
852 #define CY_SCB_I2C_MASTER_ABORT_START (0x01000000UL)
853 /** \} group_scb_i2c_macros_master_status */
854
855 /**
856 * \defgroup group_scb_i2c_macros_callback_events I2C Callback Events
857 * \{
858 * Macros to check I2C events passed by \ref cy_cb_scb_i2c_handle_events_t callback.
859 * Each event is encoded in a separate bit, and therefore it is possible to
860 * notify about multiple events.
861 */
862 /**
863 * Indicates that the slave was addressed and the master wants to read data.
864 * This event can be used to configure the slave Read buffer.
865 */
866 #define CY_SCB_I2C_SLAVE_READ_EVENT (0x00000001UL)
867
868 /**
869 * Indicates that the slave was addressed and the master wants to write data.
870 * This event can be used to configure the slave Write buffer.
871 */
872 #define CY_SCB_I2C_SLAVE_WRITE_EVENT (0x00000002UL)
873
874 /**
875 * All slave data from the configured Read buffer has been loaded into the
876 * TX FIFO. The content of the Read buffer can be modified. Applicable only
877 * if the TX FIFO is used.
878 */
879 #define CY_SCB_I2C_SLAVE_RD_IN_FIFO_EVENT (0x00000004UL)
880
881 /**
882 * The master has read all data out of the configured Read buffer.
883 * This event can be used to configure the next Read buffer. If the buffer
884 * remains empty, the \ref CY_SCB_I2C_DEFAULT_TX bytes are returned to the master.
885 */
886 #define CY_SCB_I2C_SLAVE_RD_BUF_EMPTY_EVENT (0x00000008UL)
887
888 /**
889 * Indicates the master completed reading from the slave (set by the master NAK
890 * or Stop)
891 */
892 #define CY_SCB_I2C_SLAVE_RD_CMPLT_EVENT (0x00000010UL)
893
894 /**
895 * Indicates the master completed writing to the slave (set by the master Stop
896 * or Restart)
897 */
898 #define CY_SCB_I2C_SLAVE_WR_CMPLT_EVENT (0x00000020UL)
899
900 /**
901 * Indicates the I2C hardware detected an error.
902 * Check \ref Cy_SCB_I2C_SlaveGetStatus to determine the source of the error.
903 */
904 #define CY_SCB_I2C_SLAVE_ERR_EVENT (0x00000040UL)
905
906 /**
907 * All data specified by \ref Cy_SCB_I2C_MasterWrite has been loaded
908 * into the TX FIFO. The content of the master write buffer can be modified.
909 * Applicable only if the TX FIFO is used.
910 */
911 #define CY_SCB_I2C_MASTER_WR_IN_FIFO_EVENT (0x00010000UL)
912
913 /** The master write started by \ref Cy_SCB_I2C_MasterWrite is complete */
914 #define CY_SCB_I2C_MASTER_WR_CMPLT_EVENT (0x00020000UL)
915
916 /** The master read started by \ref Cy_SCB_I2C_MasterRead is complete */
917 #define CY_SCB_I2C_MASTER_RD_CMPLT_EVENT (0x00040000UL)
918
919 /**
920 * Indicates the I2C hardware has detected an error. It occurs together with
921 * \ref CY_SCB_I2C_MASTER_RD_CMPLT_EVENT or \ref CY_SCB_I2C_MASTER_WR_CMPLT_EVENT
922 * depends on the direction of the transfer.
923 * Check \ref Cy_SCB_I2C_MasterGetStatus to determine the source of the error.
924 */
925 #define CY_SCB_I2C_MASTER_ERR_EVENT (0x00080000UL)
926 /** \} group_scb_i2c_macros_callback_events */
927
928 /**
929 * \defgroup group_scb_i2c_macros_addr_callback_events I2C Address Callback Events
930 * Macros to check I2C address events passed by \ref cy_cb_scb_i2c_handle_addr_t callback.
931 * Each event is encoded in a separate bit and therefore it is possible to
932 * notify about multiple events.
933 * \{
934 */
935 /**
936 * Indicates the slave was addressed by the general call address
937 */
938 #define CY_SCB_I2C_GENERAL_CALL_EVENT (0x01UL)
939
940 /**
941 * The slave address is in the RX FIFO.
942 * Note that the address must be read from the RX FIFO using the
943 * \ref Cy_SCB_ReadRxFifo function.
944 */
945 #define CY_SCB_I2C_ADDR_IN_FIFO_EVENT (0x02UL)
946 /** \} group_scb_i2c_macros_addr_callback_events */
947
948 /**
949 * This value is returned by the slave when there is no data in the
950 * Read buffer
951 */
952 #define CY_SCB_I2C_DEFAULT_TX (0xFFUL)
953
954
955 /*******************************************************************************
956 * Internal Constants
957 *******************************************************************************/
958
959 /** \cond INTERNAL */
960
961 /* Slave statuses */
962 #define CY_SCB_I2C_SLAVE_RD_CLEAR (CY_SCB_I2C_SLAVE_RD_CMPLT | CY_SCB_I2C_SLAVE_RD_IN_FIFO | \
963 CY_SCB_I2C_SLAVE_RD_UNDRFL | CY_SCB_I2C_SLAVE_ARB_LOST | \
964 CY_SCB_I2C_SLAVE_BUS_ERR)
965
966 #define CY_SCB_I2C_SLAVE_WR_CLEAR (CY_SCB_I2C_SLAVE_WR_CMPLT | CY_SCB_I2C_SLAVE_WR_OVRFL | \
967 CY_SCB_I2C_SLAVE_ARB_LOST | CY_SCB_I2C_SLAVE_BUS_ERR)
968
969 /* Master error statuses */
970 #define CY_SCB_I2C_MASTER_ERR (CY_SCB_I2C_MASTER_ABORT_START | CY_SCB_I2C_MASTER_ADDR_NAK | \
971 CY_SCB_I2C_MASTER_DATA_NAK | CY_SCB_I2C_MASTER_BUS_ERR | \
972 CY_SCB_I2C_MASTER_ARB_LOST)
973
974 /* Master interrupt masks */
975 #define CY_SCB_I2C_MASTER_INTR (CY_SCB_MASTER_INTR_I2C_ARB_LOST | CY_SCB_MASTER_INTR_I2C_BUS_ERROR | \
976 CY_SCB_MASTER_INTR_I2C_NACK | CY_SCB_MASTER_INTR_I2C_STOP)
977
978 #define CY_SCB_I2C_MASTER_INTR_ALL (CY_SCB_I2C_MASTER_INTR | CY_SCB_MASTER_INTR_I2C_ACK)
979
980 #define CY_SCB_I2C_MASTER_INTR_ERR (CY_SCB_MASTER_INTR_I2C_BUS_ERROR | CY_SCB_MASTER_INTR_I2C_ARB_LOST)
981
982 #define CY_SCB_I2C_MASTER_INTR_CMPLT (CY_SCB_I2C_MASTER_INTR_ERR | CY_SCB_MASTER_INTR_I2C_STOP)
983
984 /* Master statuses. */
985 #define CY_SCB_I2C_MASTER_TX_BYTE_DONE (CY_SCB_MASTER_INTR_I2C_ACK | CY_SCB_MASTER_INTR_I2C_NACK | \
986 CY_SCB_MASTER_INTR_I2C_BUS_ERROR | CY_SCB_MASTER_INTR_I2C_ARB_LOST)
987
988 #define CY_SCB_I2C_MASTER_RX_BYTE_DONE (CY_SCB_MASTER_INTR_I2C_BUS_ERROR | CY_SCB_MASTER_INTR_I2C_ARB_LOST)
989
990 #define CY_SCB_I2C_MASTER_STOP_DONE (CY_SCB_MASTER_INTR_I2C_STOP | \
991 CY_SCB_MASTER_INTR_I2C_BUS_ERROR | CY_SCB_MASTER_INTR_I2C_ARB_LOST)
992
993 #define CY_SCB_I2C_MASTER_TIMEOUT_DONE (0x80000000UL)
994
995 /* The slave interrupt mask */
996 #define CY_SCB_I2C_SLAVE_INTR (CY_SCB_SLAVE_INTR_I2C_ADDR_MATCH | CY_SCB_SLAVE_INTR_I2C_GENERAL_ADDR | \
997 CY_SCB_SLAVE_INTR_I2C_STOP | CY_SCB_SLAVE_INTR_I2C_BUS_ERROR | \
998 CY_SCB_SLAVE_INTR_I2C_ARB_LOST)
999
1000 #define CY_SCB_I2C_SLAVE_INTR_NO_STOP (CY_SCB_I2C_SLAVE_INTR & (uint32_t) ~CY_SCB_SLAVE_INTR_I2C_STOP)
1001
1002 #define CY_SCB_I2C_SLAVE_INTR_ADDR (CY_SCB_SLAVE_INTR_I2C_ADDR_MATCH | CY_SCB_SLAVE_INTR_I2C_GENERAL_ADDR)
1003
1004 #define CY_SCB_I2C_SLAVE_ADDR_DONE (CY_SCB_I2C_SLAVE_INTR_ADDR)
1005
1006 #define CY_SCB_I2C_SLAVE_INTR_NO_ADDR (CY_SCB_I2C_SLAVE_INTR & (uint32_t) ~CY_SCB_I2C_SLAVE_INTR_ADDR)
1007
1008 #define CY_SCB_I2C_SLAVE_INTR_TX (CY_SCB_TX_INTR_LEVEL | CY_SCB_TX_INTR_UNDERFLOW)
1009
1010 #define CY_SCB_I2C_SLAVE_INTR_ERROR (CY_SCB_SLAVE_INTR_I2C_BUS_ERROR | CY_SCB_SLAVE_INTR_I2C_ARB_LOST)
1011
1012 /* I2C states */
1013 #define CY_SCB_I2C_IDLE (0x10000000UL)
1014 #define CY_SCB_I2C_IDLE_MASK (0x10000000UL)
1015
1016 /* Master states */
1017 #define CY_SCB_I2C_MASTER_ACTIVE (0x00100000UL)
1018 #define CY_SCB_I2C_MASTER_WAIT (0x10100000UL)
1019 #define CY_SCB_I2C_MASTER_RX0 (0x00110000UL)
1020 #define CY_SCB_I2C_MASTER_RX1 (0x00120000UL)
1021 #define CY_SCB_I2C_MASTER_ADDR (0x10130000UL)
1022 #define CY_SCB_I2C_MASTER_TX (0x00140000UL)
1023 #define CY_SCB_I2C_MASTER_TX_DONE (0x00150000UL)
1024 #define CY_SCB_I2C_MASTER_STOP (0x00160000UL)
1025 #define CY_SCB_I2C_MASTER_WAIT_STOP (0x00170000UL)
1026 #define CY_SCB_I2C_MASTER_CMPLT (0x00180000UL)
1027
1028 /* Slave states */
1029 #define CY_SCB_I2C_SLAVE_ACTIVE (0x00001000UL)
1030 #define CY_SCB_I2C_SLAVE_RX_MASK (0x00001001UL)
1031 #define CY_SCB_I2C_SLAVE_RX (0x00001001UL)
1032 #define CY_SCB_I2C_SLAVE_TX (0x00001002UL)
1033
1034 /* FIFO size */
1035 #define CY_SCB_I2C_FIFO_SIZE CY_SCB_FIFO_SIZE
1036 #define CY_SCB_I2C_HALF_FIFO_SIZE (CY_SCB_FIFO_SIZE / 2UL)
1037
1038 #define CY_SCB_I2C_DEFAULT_RETURN (0xFFUL)
1039
1040 /* Convert the timeout in milliseconds to microseconds */
1041 #define CY_SCB_I2C_CONVERT_TIMEOUT_TO_US(timeoutMs) ((timeoutMs) * 1000UL)
1042
1043 /* I2C data rates max (Hz): standard, fast and fast plus modes */
1044 #define CY_SCB_I2C_STD_DATA_RATE (100000U)
1045 #define CY_SCB_I2C_FST_DATA_RATE (400000U)
1046 #define CY_SCB_I2C_FSTP_DATA_RATE (1000000U)
1047
1048 /* Slave clock limits */
1049 #define CY_SCB_I2C_SLAVE_STD_CLK_MIN (1550000U)
1050 #define CY_SCB_I2C_SLAVE_STD_CLK_MAX (12800000U)
1051 #define CY_SCB_I2C_SLAVE_FST_CLK_MIN (7820000U)
1052 #define CY_SCB_I2C_SLAVE_FST_CLK_MAX (15380000U)
1053 #define CY_SCB_I2C_SLAVE_FSTP_CLK_MIN (15840000U)
1054 #define CY_SCB_I2C_SLAVE_FSTP_CLK_MAX (89000000U)
1055
1056 /* Master clock (Hz) and duty cycle limits for standard mode */
1057 #define CY_SCB_I2C_MASTER_STD_CLK_MIN (1550000U)
1058 #define CY_SCB_I2C_MASTER_STD_CLK_MAX (3200000U)
1059 #define CY_SCB_I2C_MASTER_STD_LOW_PHASE_MIN (8U)
1060 #define CY_SCB_I2C_MASTER_STD_HIGH_PHASE_MIN (8U)
1061
1062 /* Master clock (Hz) and duty cycle limits for fast mode */
1063 #define CY_SCB_I2C_MASTER_FST_CLK_MIN (7820000U)
1064 #define CY_SCB_I2C_MASTER_FST_CLK_MAX (10000000U)
1065 #define CY_SCB_I2C_MASTER_FST_LOW_PHASE_MIN (13U)
1066 #define CY_SCB_I2C_MASTER_FST_HIGH_PHASE_MIN (8U)
1067
1068 /* Master clock (Hz) and duty cycle limits for fast plus mode */
1069 #define CY_SCB_I2C_MASTER_FSTP_CLK_MIN (14320000U)
1070 #define CY_SCB_I2C_MASTER_FSTP_CLK_MAX (25800000U)
1071 #define CY_SCB_I2C_MASTER_FSTP_LOW_PHASE_MIN (9U)
1072 #define CY_SCB_I2C_MASTER_FSTP_HIGH_PHASE_MIN (6U)
1073
1074 /* SCL low and high time in ns. Takes into account tF and tR */
1075 #define CY_SCB_I2C_MASTER_STD_SCL_LOW (5000U) /* tLOW + tF = 4700 + 300 */
1076 #define CY_SCB_I2C_MASTER_STD_SCL_HIGH (5000U) /* tHIGH + tR = 4000 + 1000 */
1077 #define CY_SCB_I2C_MASTER_FST_SCL_LOW (1600U) /* tLOW + tF = 1300 + 300 */
1078 #define CY_SCB_I2C_MASTER_FST_SCL_HIGH (900U) /* tHIGH + tR = 600 + 300 */
1079 #define CY_SCB_I2C_MASTER_FSTP_SCL_LOW (620U) /* tLOW + tF = 500 + 120 */
1080 #define CY_SCB_I2C_MASTER_FSTP_SCL_HIGH (380U) /* tHIGH + tR = 260 + 120 */
1081
1082 /* Master duty cycle limits */
1083 #define CY_SCB_I2C_LOW_PHASE_MAX (16U)
1084 #define CY_SCB_I2C_HIGH_PHASE_MAX (16U)
1085 #define CY_SCB_I2C_DUTY_CYCLE_MAX (CY_SCB_I2C_LOW_PHASE_MAX + CY_SCB_I2C_HIGH_PHASE_MAX)
1086
1087 /* Analog filter settings. */
1088 #define CY_SCB_I2C_ENABLE_ANALOG_FITLER (CY_SCB_I2C_CFG_DEF_VAL)
1089 #define CY_SCB_I2C_DISABLE_ANALOG_FITLER (CY_SCB_I2C_CFG_DEF_VAL & \
1090 (uint32_t) ~(SCB_I2C_CFG_SDA_IN_FILT_SEL_Msk | \
1091 SCB_I2C_CFG_SCL_IN_FILT_SEL_Msk))
1092
1093 #define CY_SCB_I2C_IS_MODE_VALID(mode) ( (CY_SCB_I2C_SLAVE == (mode)) || \
1094 (CY_SCB_I2C_MASTER == (mode)) || \
1095 (CY_SCB_I2C_MASTER_SLAVE == (mode)) )
1096
1097 #define CY_SCB_I2C_IS_RW_BIT_VALID(dir) ( (CY_SCB_I2C_WRITE_XFER == (dir)) || \
1098 (CY_SCB_I2C_READ_XFER == (dir)) )
1099
1100 #define CY_SCB_I2C_IS_RESPONSE_VALID(cmd) ( (CY_SCB_I2C_ACK == (cmd)) || \
1101 (CY_SCB_I2C_NAK == (cmd)) )
1102
1103 #define CY_SCB_I2C_IS_ADDR_MASK_VALID(mask) ( (0U == ((mask) & 0x01U)) )
1104
1105 #define CY_SCB_I2C_IS_PHASE_OVERSAMPLE_VALID(phaseOvs) ((phaseOvs) <= 16U)
1106
1107 #define CY_SCB_I2C_IS_DATA_RATE_VALID(dataRateHz) ( ((dataRateHz) > 0UL) && \
1108 ((dataRateHz) <= CY_SCB_I2C_FSTP_DATA_RATE) )
1109
1110 #define CY_SCB_I2C_IS_TIMEOUT_VALID(timeoutMs) ( (timeoutMs) <= (0xFFFFFFFFUL / 1000UL) )
1111 #define CY_SCB_I2C_IS_LOW_PHASE_CYCLES_VALID(clockCycles) ( ((clockCycles) >= 7UL) && ((clockCycles) <= 16UL) )
1112 #define CY_SCB_I2C_IS_HIGH_PHASE_CYCLES_VALID(clockCycles) ( ((clockCycles) >= 5UL) && ((clockCycles) <= 16UL) )
1113 #if((defined (CY_IP_MXSCB_VERSION) && (CY_IP_MXSCB_VERSION>=3)) || defined (CY_IP_MXS22SCB))
1114 #define CY_SCB_I2C_STRETCH_THRESHOLD_VALUE_VALID(value) ( (value) <= SCB_I2C_STRETCH_CTRL_STRETCH_THRESHOLD_Msk )
1115 #endif /* CY_IP_MXSCB_VERSION */
1116
1117 /** \endcond */
1118
1119 /** \} group_scb_i2c_macros */
1120
1121
1122 /*******************************************************************************
1123 * In-line Function Implementation
1124 *******************************************************************************/
1125
1126 /**
1127 * \addtogroup group_scb_i2c_general_functions
1128 * \{
1129 */
1130
1131 /*******************************************************************************
1132 * Function Name: Cy_SCB_I2C_Enable
1133 ****************************************************************************//**
1134 *
1135 * Enables the SCB block for the I2C operation
1136 *
1137 * \param base
1138 * The pointer to the I2C SCB instance.
1139 * \note
1140 * Ensure SCB is initialized with \ref Cy_SCB_I2C_Init before calling this function
1141 *
1142 *******************************************************************************/
Cy_SCB_I2C_Enable(CySCB_Type * base)1143 __STATIC_INLINE void Cy_SCB_I2C_Enable(CySCB_Type *base)
1144 {
1145 SCB_CTRL(base) |= SCB_CTRL_ENABLED_Msk;
1146 }
1147
1148
1149 /*******************************************************************************
1150 * Function Name: Cy_SCB_I2C_IsBusBusy
1151 ****************************************************************************//**
1152 *
1153 * Checks whether the I2C bus is busy.
1154 *
1155 * \param base
1156 * The pointer to the I2C SCB instance.
1157 *
1158 * \return
1159 * A bus status: busy or not busy.
1160 *
1161 * \note
1162 * After the SCB block is enabled or reset, the valid bus busy-status returns
1163 * after half of the SCL period.
1164 *
1165 *******************************************************************************/
Cy_SCB_I2C_IsBusBusy(CySCB_Type const * base)1166 __STATIC_INLINE bool Cy_SCB_I2C_IsBusBusy(CySCB_Type const *base)
1167 {
1168 return _FLD2BOOL(SCB_I2C_STATUS_BUS_BUSY, SCB_I2C_STATUS(base));
1169 }
1170
1171
1172 /*******************************************************************************
1173 * Function Name: Cy_SCB_I2C_SlaveSetAddress
1174 ****************************************************************************//**
1175 *
1176 * Sets the slave address for the I2C slave.
1177 *
1178 * \param base
1179 * The pointer to the I2C SCB instance.
1180 *
1181 * \param addr
1182 * The 7-bit right justified slave address.
1183 *
1184 *******************************************************************************/
Cy_SCB_I2C_SlaveSetAddress(CySCB_Type * base,uint8_t addr)1185 __STATIC_INLINE void Cy_SCB_I2C_SlaveSetAddress(CySCB_Type *base, uint8_t addr)
1186 {
1187 CY_ASSERT_L2(CY_SCB_IS_I2C_ADDR_VALID(addr));
1188
1189 CY_REG32_CLR_SET(SCB_RX_MATCH(base), SCB_RX_MATCH_ADDR, ((uint32_t)((uint32_t) addr << 1UL)));
1190 }
1191
1192
1193 /*******************************************************************************
1194 * Function Name: Cy_SCB_I2C_SlaveGetAddress
1195 ****************************************************************************//**
1196 *
1197 * Returns the slave address of the I2C slave.
1198 *
1199 * \param base
1200 * The pointer to the I2C SCB instance.
1201 *
1202 * \return
1203 * The 7-bit right justified slave address.
1204 *
1205 *******************************************************************************/
Cy_SCB_I2C_SlaveGetAddress(CySCB_Type const * base)1206 __STATIC_INLINE uint32_t Cy_SCB_I2C_SlaveGetAddress(CySCB_Type const *base)
1207 {
1208 return (_FLD2VAL(SCB_RX_MATCH_ADDR, SCB_RX_MATCH(base)) >> 1UL);
1209 }
1210
1211
1212 /*******************************************************************************
1213 * Function Name: Cy_SCB_I2C_SlaveSetAddressMask
1214 ****************************************************************************//**
1215 *
1216 * Sets the slave address mask for the I2C slave. The LSBit must always be 0.
1217 * In all other bit positions a 1 indicates that the incoming address must match
1218 * the corresponding bit in the slave address. A 0 in the mask means that the
1219 * incoming address does not need to match.
1220 * Example Slave Address = 0x0C. Slave Address Mask = 0x08. This means that the
1221 * hardware will accept both 0x08 and 0x0C as valid addresses.
1222 *
1223 * \param base
1224 * The pointer to the I2C SCB instance.
1225 *
1226 * \param addrMask
1227 * The 8-bit address mask, the upper 7 bits correspond to the slave address.
1228 * LSBit must always be 0.
1229 *
1230 *******************************************************************************/
Cy_SCB_I2C_SlaveSetAddressMask(CySCB_Type * base,uint8_t addrMask)1231 __STATIC_INLINE void Cy_SCB_I2C_SlaveSetAddressMask(CySCB_Type *base, uint8_t addrMask)
1232 {
1233 CY_ASSERT_L2(CY_SCB_I2C_IS_ADDR_MASK_VALID(addrMask));
1234
1235 CY_REG32_CLR_SET(SCB_RX_MATCH(base), SCB_RX_MATCH_MASK, ((uint32_t) addrMask));
1236 }
1237
1238
1239 /*******************************************************************************
1240 * Function Name: Cy_SCB_I2C_SlaveGetAddressMask
1241 ****************************************************************************//**
1242 *
1243 * Returns the slave address mask.
1244 *
1245 * \param base
1246 * The pointer to the I2C SCB instance.
1247 *
1248 * \return
1249 * The 8-bit address mask, the upper 7 bits correspond to the slave address.
1250 * LSBit must always be 0.
1251 *
1252 *******************************************************************************/
Cy_SCB_I2C_SlaveGetAddressMask(CySCB_Type const * base)1253 __STATIC_INLINE uint32_t Cy_SCB_I2C_SlaveGetAddressMask(CySCB_Type const *base)
1254 {
1255 return _FLD2VAL(SCB_RX_MATCH_MASK, SCB_RX_MATCH(base));
1256 }
1257
1258
1259 /*******************************************************************************
1260 * Function Name: Cy_SCB_I2C_MasterSetLowPhaseDutyCycle
1261 ****************************************************************************//**
1262 *
1263 * This function sets the number of SCB clock cycles in the low phase of SCL.
1264 * If \ref Cy_SCB_I2C_SetDataRate is called after this function, the values
1265 * specified in this function are overwritten.
1266 *
1267 * \param base
1268 * The pointer to the I2C SCB instance.
1269 *
1270 * \param clockCycles
1271 * The number of SCB clock cycles in the low phase of SCL.
1272 * The valid range is 7 to 16.
1273 *
1274 * \note
1275 * This function should be used at your own risk. Changing the number of clock
1276 * cycles in a phase of SCL may violate the I2C specification. Make this
1277 * change only while the block is disabled.
1278 *
1279 *******************************************************************************/
Cy_SCB_I2C_MasterSetLowPhaseDutyCycle(CySCB_Type * base,uint32_t clockCycles)1280 __STATIC_INLINE void Cy_SCB_I2C_MasterSetLowPhaseDutyCycle(CySCB_Type *base, uint32_t clockCycles)
1281 {
1282 CY_ASSERT_L2(CY_SCB_I2C_IS_LOW_PHASE_CYCLES_VALID(clockCycles));
1283
1284 CY_REG32_CLR_SET(SCB_I2C_CTRL(base), SCB_I2C_CTRL_LOW_PHASE_OVS, (clockCycles - 1UL));
1285 }
1286
1287
1288 /*******************************************************************************
1289 * Function Name: Cy_SCB_I2C_MasterSetHighPhaseDutyCycle
1290 ****************************************************************************//**
1291 *
1292 * This function sets the number of SCB clock cycles in the high phase of SCL.
1293 * If \ref Cy_SCB_I2C_SetDataRate is called after this function, the values
1294 * specified in this function get overwritten.
1295 *
1296 * \param base
1297 * The pointer to the I2C SCB instance.
1298 *
1299 * \param clockCycles
1300 * The number of SCB clock cycles in the high phase of SCL.
1301 * The valid range is 5 to 16.
1302 *
1303 * \note
1304 * This function should be used at your own risk. Changing the number of clock
1305 * cycles in a phase of SCL may violate the I2C specification. Make this
1306 * change only while the block is disabled.
1307 *
1308 *******************************************************************************/
Cy_SCB_I2C_MasterSetHighPhaseDutyCycle(CySCB_Type * base,uint32_t clockCycles)1309 __STATIC_INLINE void Cy_SCB_I2C_MasterSetHighPhaseDutyCycle(CySCB_Type *base, uint32_t clockCycles)
1310 {
1311 CY_ASSERT_L2(CY_SCB_I2C_IS_HIGH_PHASE_CYCLES_VALID(clockCycles));
1312
1313 CY_REG32_CLR_SET(SCB_I2C_CTRL(base), SCB_I2C_CTRL_HIGH_PHASE_OVS, (clockCycles - 1UL));
1314 }
1315 /** \} group_scb_i2c_general_functions */
1316
1317 /**
1318 * \addtogroup group_scb_i2c_interrupt_functions
1319 * \{
1320 */
1321
1322 /*******************************************************************************
1323 * Function Name: Cy_SCB_I2C_RegisterEventCallback
1324 ****************************************************************************//**
1325 *
1326 * Registers a callback function that notifies that
1327 * \ref group_scb_i2c_macros_callback_events occurred in the
1328 * \ref Cy_SCB_I2C_Interrupt.
1329 *
1330 * \param base
1331 * The pointer to the I2C SCB instance.
1332 *
1333 * \param callback
1334 * The pointer to a callback function.
1335 * See \ref cy_cb_scb_i2c_handle_events_t for the function prototype.
1336 *
1337 * \param context
1338 * The pointer to context structure \ref cy_stc_scb_i2c_context_t allocated by
1339 * the user. The structure is used while the I2C operation for internal
1340 * configuration and data retention. The user should not modify anything in
1341 * this structure.
1342 *
1343 * \note
1344 * To remove the callback, pass NULL as the pointer to the callback function.
1345 *
1346 *******************************************************************************/
Cy_SCB_I2C_RegisterEventCallback(CySCB_Type const * base,cy_cb_scb_i2c_handle_events_t callback,cy_stc_scb_i2c_context_t * context)1347 __STATIC_INLINE void Cy_SCB_I2C_RegisterEventCallback(CySCB_Type const *base,
1348 cy_cb_scb_i2c_handle_events_t callback, cy_stc_scb_i2c_context_t *context)
1349 {
1350 /* Suppress a compiler warning about unused variables */
1351 (void) base;
1352
1353 context->cbEvents = callback;
1354 }
1355
1356
1357 /*******************************************************************************
1358 * Function Name: Cy_SCB_I2C_RegisterAddrCallback
1359 ****************************************************************************//**
1360 *
1361 * Registers a callback function that notifies that
1362 * \ref group_scb_i2c_macros_addr_callback_events occurred in the
1363 * \ref Cy_SCB_I2C_Interrupt.
1364 *
1365 * \param base
1366 * The pointer to the I2C SCB instance.
1367 *
1368 * \param callback
1369 * The pointer to a callback function.
1370 * See \ref cy_cb_scb_i2c_handle_addr_t for the function prototype.
1371 *
1372 * \param context
1373 * The pointer to context structure \ref cy_stc_scb_i2c_context_t allocated by
1374 * the user. The structure is used during the I2C operation for internal
1375 * configuration and data retention. The user should not modify anything in
1376 * this structure.
1377 *
1378 * \note
1379 * To remove the callback, pass NULL as the pointer to a callback function.
1380 *
1381 *******************************************************************************/
Cy_SCB_I2C_RegisterAddrCallback(CySCB_Type const * base,cy_cb_scb_i2c_handle_addr_t callback,cy_stc_scb_i2c_context_t * context)1382 __STATIC_INLINE void Cy_SCB_I2C_RegisterAddrCallback(CySCB_Type const *base,
1383 cy_cb_scb_i2c_handle_addr_t callback, cy_stc_scb_i2c_context_t *context)
1384 {
1385 /* Suppress a compiler warning about unused variables */
1386 (void) base;
1387
1388 context->cbAddr = callback;
1389 }
1390 /** \} group_scb_i2c_interrupt_functions */
1391
1392 #if defined(__cplusplus)
1393 }
1394 #endif
1395
1396 /** \} group_scb_i2c */
1397
1398 #endif /* (defined (CY_IP_MXSCB) || defined (CY_IP_MXS22SCB)) */
1399
1400 #endif /* (CY_SCB_I2C_H) */
1401
1402 /* [] END OF FILE */
1403
