1 /**
2 * \file
3 *
4 * \brief I2C Common Driver for SAMB
5 *
6 * Copyright (c) 2015-2016 Atmel Corporation. All rights reserved.
7 *
8 * \asf_license_start
9 *
10 * \page License
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions are met:
14 *
15 * 1. Redistributions of source code must retain the above copyright notice,
16 * this list of conditions and the following disclaimer.
17 *
18 * 2. Redistributions in binary form must reproduce the above copyright notice,
19 * this list of conditions and the following disclaimer in the documentation
20 * and/or other materials provided with the distribution.
21 *
22 * 3. The name of Atmel may not be used to endorse or promote products derived
23 * from this software without specific prior written permission.
24 *
25 * 4. This software may only be redistributed and used in connection with an
26 * Atmel microcontroller product.
27 *
28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38 * POSSIBILITY OF SUCH DAMAGE.
39 *
40 * \asf_license_stop
41 *
42 */
43 /*
44 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
45 */
46 #ifndef I2C_COMMON_H_INCLUDED
47 #define I2C_COMMON_H_INCLUDED
48
49 #include <compiler.h>
50 #include <system_sam_b.h>
51 #include <gpio.h>
52
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
56
57 /**
58 * \if (I2C_MASTER_MODE && I2C_SLAVE_MODE)
59 * \defgroup asfdoc_samb_i2c_group SAM I2C Driver (I2C)
60 * \elseif I2C_MASTER_MODE
61 * \defgroup asfdoc_samb_i2c_group SAM I2C Master Mode Driver (I2C)
62 * \elseif I2C_SLAVE_MODE
63 * \defgroup asfdoc_samb_i2c_group SAM I2C Slave Mode Driver (I2C)
64 * \endif
65 *
66 * This driver for Atmel® | SMART SAM devices provides an interface for the configuration
67 * and management of the device's I<SUP>2</SUP>C module, for the transfer
68 * of data via an I<SUP>2</SUP>C bus. The following driver API modes are covered
69 * by this manual:
70 *
71 * \if I2C_MASTER_MODE
72 * - Master Mode Polled APIs
73 * \endif
74 * \if I2C_MASTER_CALLBACK_MODE
75 * - Master Mode Callback APIs
76 * \endif
77 * \if I2C_SLAVE_MODE
78 * - Slave Mode Polled APIs
79 * \endif
80 * \if I2C_SLAVE_CALLBACK_MODE
81 * - Slave Mode Callback APIs
82 * \endif
83 *
84 * The following peripheral is used by this module:
85 * - Serial Communication Interface
86 *
87 * The following devices can use this module:
88 * - Atmel | SMART SAM B11
89 *
90 * The outline of this documentation is as follows:
91 * - \ref asfdoc_samb_i2c_prerequisites
92 * - \ref asfdoc_samb_i2c_overview
93 * - \ref asfdoc_samb_i2c_special_considerations
94 * - \ref asfdoc_samb_i2c_extra
95 * - \ref asfdoc_samb_i2c_examples
96 * - \ref asfdoc_samb_i2c_api_overview
97 *
98 * \section asfdoc_samb_i2c_prerequisites Prerequisites
99 * There are no prerequisites.
100 *
101 * \section asfdoc_samb_i2c_overview Module Overview
102 *
103 * The outline of this section is as follows:
104 * - \ref asfdoc_samb_i2c_functional_desc
105 * - \ref asfdoc_samb_i2c_bus_topology
106 * - \ref asfdoc_samb_i2c_transactions
107 * - \ref asfdoc_samb_i2c_multi_master
108 * - \ref asfdoc_samb_i2c_bus_states
109 *
110 * \subsection asfdoc_samb_i2c_functional_desc Functional Description
111 * The I<SUP>2</SUP>C provides a simple two-wire bidirectional bus consisting of a
112 * wired-AND type serial clock line (SCL) and a wired-AND type serial data line
113 * (SDA).
114 *
115 * The I<SUP>2</SUP>C bus provides a simple, but efficient method of interconnecting
116 * multiple master and slave devices. An arbitration mechanism is provided for
117 * resolving bus ownership between masters, as only one master device may own
118 * the bus at any given time. The arbitration mechanism relies on the wired-AND
119 * connections to avoid bus drivers short-circuiting.
120 *
121 * A unique address is assigned to all slave devices connected to the bus. A
122 * device can contain both master and slave logic, and can emulate multiple
123 * slave devices by responding to more than one address.
124 *
125 * \subsection asfdoc_samb_i2c_bus_topology Bus Topology
126 * The I<SUP>2</SUP>C bus topology is illustrated in
127 * \ref asfdoc_samb_i2c_bus_topology_figure "the figure below". The pull-up
128 * resistors (Rs) will provide a high level on the bus lines when none of the
129 * I<SUP>2</SUP>C devices are driving the bus. These are optional, and can be
130 * replaced with a constant current source.
131 *
132 * \anchor asfdoc_samb_i2c_bus_topology_figure
133 * \image html bus_topology.svg "I2C Bus Topology" Width=100%
134 *
135 * \subsection asfdoc_samb_i2c_transactions Transactions
136 * The I<SUP>2</SUP>C standard defines three fundamental transaction formats:
137 * - Master Write
138 * - The master transmits data packets to the slave after addressing it
139 * - Master Read
140 * - The slave transmits data packets to the master after being addressed
141 * - Combined Read/Write
142 * - A combined transaction consists of several write and read transactions
143 *
144 * A data transfer starts with the master issuing a \b Start condition on the
145 * bus, followed by the address of the slave together with a bit to indicate
146 * whether the master wants to read from or write to the slave.
147 * The addressed slave must respond to this by sending an \b ACK back to the
148 * master.
149 *
150 * After this, data packets are sent from the master or slave, according to the
151 * read/write bit. Each packet must be acknowledged (ACK) or not
152 * acknowledged (NACK) by the receiver.
153 *
154 * If a slave responds with a NACK, the master must assume that the slave
155 * cannot receive any more data and cancel the write operation.
156 *
157 * The master completes a transaction by issuing a \b Stop condition.
158 *
159 * A master can issue multiple \b Start conditions during a transaction; this
160 * is then called a \b Repeated \b Start condition.
161 *
162 * \subsubsection asfdoc_samb_i2c_address_packets Address Packets
163 * The slave address consists of seven bits. The 8<SUP>th</SUP> bit in the transfer
164 * determines the data direction (read or write). An address packet always
165 * succeeds a \b Start or \b Repeated \b Start condition. The 8<SUP>th</SUP> bit is handled
166 * in the driver, and the user will only have to provide the 7-bit address.
167 *
168 * \subsubsection asfdoc_samb_i2c_data_packets Data Packets
169 * Data packets are nine bits long, consisting of one 8-bit data byte, and an
170 * acknowledgement bit. Data packets follow either an address packet or another
171 * data packet on the bus.
172 *
173 * \subsubsection asfdoc_samb_i2c_trans_examples Transaction Examples
174 * The gray bits in the following examples are sent from master to slave, and
175 * the white bits are sent from slave to master.
176 * Example of a read transaction is shown in
177 * \ref asfdoc_samb_i2c_trans_examples_i2c_read "the figure below". Here, the
178 * master first issues a \b Start condition and gets ownership of the bus. An
179 * address packet with the direction flag set to read is then sent and
180 * acknowledged by the slave. Then the slave sends one data packet which is
181 * acknowledged by the master. The slave sends another packet, which is not
182 * acknowledged by the master and indicates that the master will terminate the
183 * transaction. In the end, the transaction is terminated by the master issuing
184 * a \b Stop condition.
185 *
186 * \anchor asfdoc_samb_i2c_trans_examples_i2c_read
187 * \image html i2c_read.svg "I2C Packet Read" Width=100%
188 *
189 * Example of a write transaction is shown in
190 * \ref asfdoc_samb_i2c_trans_examples_i2c_write "the figure below". Here, the
191 * master first issues a \b Start condition and gets ownership of the bus. An
192 * address packet with the dir flag set to write is then sent and acknowledged
193 * by the slave. Then the master sends two data packets, each acknowledged by
194 * the slave. In the end, the transaction is terminated by the master issuing
195 * a \b Stop condition.
196 *
197 * \anchor asfdoc_samb_i2c_trans_examples_i2c_write
198 * \image html i2c_write.svg "I2C Packet Write" Width=100%
199 *
200 * \subsubsection asfdoc_samb_i2c_repeated_start Repeated Start
201 * To issue a \b Repeated \b Start, the functions postfixed \c _no_stop must be
202 * used.
203 * These functions will not send a \b Stop condition when the transfer is done,
204 * thus the next transfer will start with a \b Repeated \b Start. To end the
205 * transaction, the functions without the \c _no_stop postfix must be used
206 * for the last read/write.
207 *
208 * \subsection asfdoc_samb_i2c_multi_master Multi Master
209 * In a multi master environment, arbitration of the bus is important, as only
210 * one master can own the bus at any point.
211 *
212 * \subsubsection asfdoc_samb_i2c_arbitration Arbitration
213 *
214 * \par Clock stretching
215 * The serial clock line is always driven by a master device. However, all
216 * devices connected to the bus are allowed stretch the low period of the clock
217 * to slow down the overall clock frequency or to insert wait states while
218 * processing data.
219 * Both master and slave can randomly stretch the clock, which will force the
220 * other device into a wait-state until the clock line goes high again.
221 *
222 * \par Arbitration on the data line
223 * If two masters start transmitting at the same time, they will both transmit
224 * until one master detects that the other master is pulling the data line low.
225 * When this is detected, the master not pulling the line low, will stop the
226 * transmission and wait until the bus is idle.
227 * As it is the master trying to contact the slave with the lowest address that
228 * will get the bus ownership, this will create an arbitration scheme always
229 * prioritizing the slaves with the lowest address in case of a bus collision.
230 *
231 * \subsubsection asfdoc_samb_i2c_clock_sync Clock Synchronization
232 * In situations where more than one master is trying to control the bus clock
233 * line at the same time, a clock synchronization algorithm based on the same
234 * principles used for clock stretching is necessary.
235 *
236 *
237 * \subsection asfdoc_samb_i2c_bus_states Bus States
238 * As the I<SUP>2</SUP>C bus is limited to one transaction at the time,
239 * a master that wants to perform a bus transaction must wait until the bus is
240 * free.
241 * Because of this, it is necessary for all masters in a multi-master system to
242 * know the current status of the bus to be able to avoid conflicts and to
243 * ensure data integrity.
244 * \li \b IDLE No activity on the bus (between a \b Stop and a new \b Start
245 * condition)
246 * \li \b BUSY If another master is driving the bus
247 *
248 * \section asfdoc_samb_i2c_special_considerations Special Considerations
249 * There are no special considerations related to this driver.
250 *
251 *
252 * \section asfdoc_samb_i2c_extra Extra Information
253 * For extra information, see \ref asfdoc_samb_i2c_extra_info_page.
254 * This includes:
255 * - \ref asfdoc_samb_i2c_acronyms
256 * - \ref asfdoc_samb_i2c_extra_dependencies
257 * - \ref asfdoc_samb_i2c_extra_errata
258 * - \ref asfdoc_samb_i2c_extra_history
259 *
260 * \section asfdoc_samb_i2c_examples Examples
261 *
262 * For a list of examples related to this driver, see
263 * \ref asfdoc_samb_i2c_exqsg.
264 *
265 * \section asfdoc_samb_i2c_api_overview API Overview
266 * @{
267 */
268
269
270 /** \brief Transfer direction
271 *
272 * For master: transfer direction or setting direction bit in address.
273 * For slave: direction of request from master.
274 */
275 enum i2c_transfer_direction {
276 /** Master write operation is in progress */
277 I2C_TRANSFER_WRITE = 0,
278 /** Master read operation is in progress */
279 I2C_TRANSFER_READ = 1,
280 };
281
282 /**
283 * \brief I2C module clock input
284 *
285 * I2C module clock.
286 *
287 */
288 enum i2c_clock_input {
289 /** source from clock input 0: 26MHz */
290 I2C_CLK_INPUT_0 = 0,
291 /** source from clock input 1: 13MHz */
292 I2C_CLK_INPUT_1,
293 /** source from clock input 2: 6.5MHz */
294 I2C_CLK_INPUT_2,
295 /** source from clock input 3: 3MHz */
296 I2C_CLK_INPUT_3,
297 };
298
299 /**
300 * \brief Wait for idle
301 *
302 * Wait for hardware module to sync
303 *
304 * \param[in] i2c_module Pointer to software module structure
305 */
i2c_wait_for_idle(I2c * const i2c_module)306 static inline void i2c_wait_for_idle(I2c *const i2c_module)
307 {
308 while (i2c_module->I2C_STATUS.bit.I2C_ACTIVE) {
309 /* Wait for I2C module to sync. */
310 }
311 }
312
313 /**
314 * \brief Enable driver instance
315 *
316 * This function enable driver instance
317 *
318 * \param[in,out] module Pointer to the driver instance to enable
319 *
320 */
i2c_enable(I2c * const i2c_module)321 static inline void i2c_enable(I2c *const i2c_module)
322 {
323 /* Wait for module to sync. */
324 i2c_wait_for_idle(i2c_module);
325 /* Enable module. */
326 i2c_module->I2C_MODULE_ENABLE.reg = (1 << I2C_MODULE_ENABLE_ENABLE_Pos);
327 }
328
329 /**
330 * \brief Disable driver instance
331 *
332 * This function disable driver instance
333 *
334 * \param[in,out] i2c_module Pointer to the driver instance to disable
335 *
336 */
i2c_disable(I2c * const i2c_module)337 static inline void i2c_disable(I2c *const i2c_module)
338 {
339 i2c_wait_for_idle(i2c_module);
340 i2c_module->I2C_MODULE_ENABLE.reg = 0;
341 }
342
343 /**
344 * \brief Flush the contents of both the Tx and Rx FIFOs
345 *
346 * This function flushes the contents of both the Tx and Rx FIFOs.
347 *
348 * \param[in,out] i2c_module Pointer to the driver instance
349 *
350 */
i2c_slave_flush_fifo(I2c * const i2c_module)351 static inline void i2c_slave_flush_fifo(I2c *const i2c_module)
352 {
353 i2c_wait_for_idle(i2c_module);
354 i2c_module->I2C_FLUSH.reg = 1;
355 }
356
357 /**
358 * \brief Enable or Disable slave rx interrupt
359 *
360 * This function enables or disables slave rx interrupt.
361 *
362 * \param[in,out] i2c_module Pointer to the driver
363 * \param[in] enable Enable or Disable
364 *
365 */
i2c_slave_rx_interrupt(I2c * const i2c_module,bool enable)366 static inline void i2c_slave_rx_interrupt(I2c *const i2c_module, bool enable)
367 {
368 if (enable) {
369 i2c_module->RX_INTERRUPT_MASK.bit.RX_FIFO_NOT_EMPTY_MASK = 1;
370 } else {
371 i2c_module->RX_INTERRUPT_MASK.bit.RX_FIFO_NOT_EMPTY_MASK = 0;
372 }
373 }
374
375 /**
376 * \brief Enable or Disable slave tx interrupt
377 *
378 * This function enables or disables slave tx interrupt.
379 *
380 * \param[in,out] i2c_module Pointer to the driver
381 * \param[in] enable Enable or Disable
382 *
383 */
i2c_slave_tx_interrupt(I2c * const i2c_module,bool enable)384 static inline void i2c_slave_tx_interrupt(I2c *const i2c_module, bool enable)
385 {
386 if (enable) {
387 i2c_module->TX_INTERRUPT_MASK.bit.TX_FIFO_NOT_FULL_MASK = 1;
388 i2c_module->RX_INTERRUPT_MASK.bit.NAK_MASK = 1;
389 } else {
390 i2c_module->TX_INTERRUPT_MASK.bit.TX_FIFO_NOT_FULL_MASK = 0;
391 i2c_module->RX_INTERRUPT_MASK.bit.NAK_MASK = 0;
392 }
393 }
394 /** @} */
395
396 #ifdef __cplusplus
397 }
398 #endif
399
400 /**
401 * \page asfdoc_samb_i2c_extra_info_page Extra Information for I2C Driver
402 *
403 * \section asfdoc_samb_i2c_acronyms Acronyms
404 * \ref asfdoc_samb_i2c_acronyms_table "Below" is a table listing the acronyms
405 * used in this module, along with their intended meanings.
406 *
407 * \anchor asfdoc_samb_i2c_acronyms_table
408 * <table>
409 * <caption>Acronyms</caption>
410 * <tr>
411 * <th>Acronym</th>
412 * <th>Description</th>
413 * </tr>
414 * <tr>
415 * <td>SDA</td>
416 * <td>Serial Data Line</td>
417 * </tr>
418 * <tr>
419 * <td>SCL</td>
420 * <td>Serial Clock Line</td>
421 * </tr>
422 * </table>
423 *
424 * \section asfdoc_samb_i2c_extra_dependencies Dependencies
425 * There are no dependencies related to this driver.
426 *
427 *
428 * \section asfdoc_samb_i2c_extra_errata Errata
429 * There are no errata related to this driver.
430 *
431 * \section asfdoc_samb_i2c_extra_history Module History
432 * \ref asfdoc_samb_i2c_extra_history_table "Below" is an overview of the
433 * module history, detailing enhancements and fixes made to the module since
434 * its first release. The current version of this corresponds to the newest
435 * version listed in
436 * \ref asfdoc_samb_i2c_extra_history_table "the table below".
437 *
438 * \anchor asfdoc_samb_i2c_extra_history_table
439 * <table>
440 * <caption>Module History</caption>
441 * <tr>
442 * <th>Changelog</th>
443 * </tr>
444 * <tr>
445 * <td>Initial Release</td>
446 * </tr>
447 * </table>
448 */
449
450 /**
451 * \page asfdoc_samb_i2c_exqsg Examples for I2C Driver
452 *
453 * This is a list of the available Quick Start guides (QSGs) and example
454 * applications for \ref asfdoc_samb_i2c_group. QSGs are simple examples with
455 * step-by-step instructions to configure and use this driver in a selection of
456 * use cases. Note that QSGs can be compiled as a standalone application or be
457 * added to the user application.
458 *
459 * \if I2C_MASTER_MODE
460 * - \subpage asfdoc_samb_i2c_master_basic_use_case "Quick Start Guide for the I2C Master module - Basic Use Case"
461 * \endif
462 * \if I2C_MASTER_CALLBACK_MODE
463 * - \subpage asfdoc_samb_i2c_master_callback_use_case "Quick Start Guide for the I2C Master module - Callback Use Case"
464 * \endif
465 * \if I2C_SLAVE_MODE
466 * - \subpage asfdoc_samb_i2c_slave_basic_use_case "Quick Start Guide for the I2C Slave module - Basic Use Case"
467 * \endif
468 * \if I2C_SLAVE_CALLBACK_MODE
469 * - \subpage asfdoc_samb_i2c_slave_callback_use_case "Quick Start Guide for the I2C Slave module - Callback Use Case"
470 * \endif
471 *
472 * \page asfdoc_samb_i2c_document_revision_history Document Revision History
473 *
474 * <table>
475 * <tr>
476 * <th>Doc. Rev.</td>
477 * <th>Date</td>
478 * <th>Comments</td>
479 * </tr>
480 * <tr>
481 * <td>A</td>
482 * <td>09/2015</td>
483 * <td>Initial release</td>
484 * </tr>
485 * </table>
486 */
487
488 #endif /* I2C_COMMON_H_INCLUDED */
489