mbed library sources
Fork of mbed-src by
targets/hal/TARGET_Atmel/TARGET_SAM21/drivers/sercom/i2c/i2c_common.h@592:a274ee790e56, 2015-07-17 (annotated)
- Committer:
- mbed_official
- Date:
- Fri Jul 17 09:15:10 2015 +0100
- Revision:
- 592:a274ee790e56
- Parent:
- 579:53297373a894
Synchronized with git revision e7144f83a8d75df80c4877936b6ffe552b0be9e6
Full URL: https://github.com/mbedmicro/mbed/commit/e7144f83a8d75df80c4877936b6ffe552b0be9e6/
More API implementation for SAMR21
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
mbed_official | 579:53297373a894 | 1 | #ifndef I2C_COMMON_H_INCLUDED |
mbed_official | 579:53297373a894 | 2 | #define I2C_COMMON_H_INCLUDED |
mbed_official | 579:53297373a894 | 3 | |
mbed_official | 579:53297373a894 | 4 | #include <compiler.h> |
mbed_official | 579:53297373a894 | 5 | #include <sercom.h> |
mbed_official | 579:53297373a894 | 6 | |
mbed_official | 579:53297373a894 | 7 | #ifdef __cplusplus |
mbed_official | 579:53297373a894 | 8 | extern "C" { |
mbed_official | 579:53297373a894 | 9 | #endif |
mbed_official | 579:53297373a894 | 10 | |
mbed_official | 579:53297373a894 | 11 | /** |
mbed_official | 579:53297373a894 | 12 | * \if (I2C_MASTER_MODE && I2C_SLAVE_MODE) |
mbed_official | 579:53297373a894 | 13 | * \defgroup asfdoc_sam0_sercom_i2c_group SAM I2C Driver (SERCOM I2C) |
mbed_official | 579:53297373a894 | 14 | * \elseif I2C_MASTER_MODE |
mbed_official | 579:53297373a894 | 15 | * \defgroup asfdoc_sam0_sercom_i2c_group SAM I2C Master Mode Driver (SERCOM I2C) |
mbed_official | 579:53297373a894 | 16 | * \elseif I2C_SLAVE_MODE |
mbed_official | 579:53297373a894 | 17 | * \defgroup asfdoc_sam0_sercom_i2c_group SAM I2C Slave Mode Driver (SERCOM I2C) |
mbed_official | 579:53297373a894 | 18 | * \endif |
mbed_official | 579:53297373a894 | 19 | * |
mbed_official | 579:53297373a894 | 20 | * This driver for Atmel庐 | SMART SAM devices provides an interface for the configuration |
mbed_official | 579:53297373a894 | 21 | * and management of the device's SERCOM I<SUP>2</SUP>C module, for the transfer |
mbed_official | 579:53297373a894 | 22 | * of data via an I<SUP>2</SUP>C bus. The following driver API modes are covered |
mbed_official | 579:53297373a894 | 23 | * by this manual: |
mbed_official | 579:53297373a894 | 24 | * |
mbed_official | 579:53297373a894 | 25 | * \if I2C_MASTER_MODE |
mbed_official | 579:53297373a894 | 26 | * - Master Mode Polled APIs |
mbed_official | 579:53297373a894 | 27 | * \endif |
mbed_official | 579:53297373a894 | 28 | * \if I2C_MASTER_CALLBACK_MODE |
mbed_official | 579:53297373a894 | 29 | * - Master Mode Callback APIs |
mbed_official | 579:53297373a894 | 30 | * \endif |
mbed_official | 579:53297373a894 | 31 | * \if I2C_SLAVE_MODE |
mbed_official | 579:53297373a894 | 32 | * - Slave Mode Polled APIs |
mbed_official | 579:53297373a894 | 33 | * \endif |
mbed_official | 579:53297373a894 | 34 | * \if I2C_SLAVE_CALLBACK_MODE |
mbed_official | 579:53297373a894 | 35 | * - Slave Mode Callback APIs |
mbed_official | 579:53297373a894 | 36 | * \endif |
mbed_official | 579:53297373a894 | 37 | * |
mbed_official | 579:53297373a894 | 38 | * The following peripheral is used by this module: |
mbed_official | 579:53297373a894 | 39 | * - SERCOM (Serial Communication Interface) |
mbed_official | 579:53297373a894 | 40 | * |
mbed_official | 579:53297373a894 | 41 | * The following devices can use this module: |
mbed_official | 579:53297373a894 | 42 | * - Atmel | SMART SAM D20/D21 |
mbed_official | 579:53297373a894 | 43 | * - Atmel | SMART SAM R21 |
mbed_official | 579:53297373a894 | 44 | * - Atmel | SMART SAM D10/D11 |
mbed_official | 579:53297373a894 | 45 | * - Atmel | SMART SAM L21 |
mbed_official | 579:53297373a894 | 46 | * |
mbed_official | 579:53297373a894 | 47 | * The outline of this documentation is as follows: |
mbed_official | 579:53297373a894 | 48 | * - \ref asfdoc_sam0_sercom_i2c_prerequisites |
mbed_official | 579:53297373a894 | 49 | * - \ref asfdoc_sam0_sercom_i2c_overview |
mbed_official | 579:53297373a894 | 50 | * - \ref asfdoc_sam0_sercom_i2c_special_considerations |
mbed_official | 579:53297373a894 | 51 | * - \ref asfdoc_sam0_sercom_i2c_extra |
mbed_official | 579:53297373a894 | 52 | * - \ref asfdoc_sam0_sercom_i2c_examples |
mbed_official | 579:53297373a894 | 53 | * - \ref asfdoc_sam0_sercom_i2c_api_overview |
mbed_official | 579:53297373a894 | 54 | * |
mbed_official | 579:53297373a894 | 55 | * \section asfdoc_sam0_sercom_i2c_prerequisites Prerequisites |
mbed_official | 579:53297373a894 | 56 | * There are no prerequisites. |
mbed_official | 579:53297373a894 | 57 | * |
mbed_official | 579:53297373a894 | 58 | * \section asfdoc_sam0_sercom_i2c_overview Module Overview |
mbed_official | 579:53297373a894 | 59 | * The outline of this section is as follows: |
mbed_official | 579:53297373a894 | 60 | * - \ref asfdoc_sam0_sercom_i2c_module_features |
mbed_official | 579:53297373a894 | 61 | * - \ref asfdoc_sam0_sercom_i2c_functional_desc |
mbed_official | 579:53297373a894 | 62 | * - \ref asfdoc_sam0_sercom_i2c_bus_topology |
mbed_official | 579:53297373a894 | 63 | * - \ref asfdoc_sam0_sercom_i2c_transactions |
mbed_official | 579:53297373a894 | 64 | * - \ref asfdoc_sam0_sercom_i2c_multi_master |
mbed_official | 579:53297373a894 | 65 | * - \ref asfdoc_sam0_sercom_i2c_bus_states |
mbed_official | 579:53297373a894 | 66 | * - \ref asfdoc_sam0_sercom_i2c_timeout |
mbed_official | 579:53297373a894 | 67 | * - \ref asfdoc_sam0_sercom_i2c_sleep_modes |
mbed_official | 579:53297373a894 | 68 | * |
mbed_official | 579:53297373a894 | 69 | * \subsection asfdoc_sam0_sercom_i2c_module_features Driver Feature Macro Definition |
mbed_official | 579:53297373a894 | 70 | * <table> |
mbed_official | 579:53297373a894 | 71 | * <tr> |
mbed_official | 579:53297373a894 | 72 | * <th>Driver Feature Macro</th> |
mbed_official | 579:53297373a894 | 73 | * <th>Supported devices</th> |
mbed_official | 579:53297373a894 | 74 | * </tr> |
mbed_official | 579:53297373a894 | 75 | * <tr> |
mbed_official | 579:53297373a894 | 76 | * <td>FEATURE_I2C_FAST_MODE_PLUS_AND_HIGH_SPEED</td> |
mbed_official | 579:53297373a894 | 77 | * <td>SAM D21/R21/D10/D11/L21</td> |
mbed_official | 579:53297373a894 | 78 | * </tr> |
mbed_official | 579:53297373a894 | 79 | * <tr> |
mbed_official | 579:53297373a894 | 80 | * <td>FEATURE_I2C_10_BIT_ADDRESS</td> |
mbed_official | 579:53297373a894 | 81 | * <td>SAM D21/R21/D10/D11/L21</td> |
mbed_official | 579:53297373a894 | 82 | * </tr> |
mbed_official | 579:53297373a894 | 83 | * <tr> |
mbed_official | 579:53297373a894 | 84 | * <td>FEATURE_I2C_SCL_STRETCH_MODE</td> |
mbed_official | 579:53297373a894 | 85 | * <td>SAM D21/R21/D10/D11/L21</td> |
mbed_official | 579:53297373a894 | 86 | * </tr> |
mbed_official | 579:53297373a894 | 87 | * <tr> |
mbed_official | 579:53297373a894 | 88 | * <td>FEATURE_I2C_SCL_EXTEND_TIMEOUT</td> |
mbed_official | 579:53297373a894 | 89 | * <td>SAM D21/R21/D10/D11/L21</td> |
mbed_official | 579:53297373a894 | 90 | * </tr> |
mbed_official | 579:53297373a894 | 91 | * </table> |
mbed_official | 579:53297373a894 | 92 | * \note The specific features are only available in the driver when the |
mbed_official | 579:53297373a894 | 93 | * selected device supports those features. |
mbed_official | 579:53297373a894 | 94 | * |
mbed_official | 579:53297373a894 | 95 | * \subsection asfdoc_sam0_sercom_i2c_functional_desc Functional Description |
mbed_official | 579:53297373a894 | 96 | * The I<SUP>2</SUP>C provides a simple two-wire bidirectional bus consisting of a |
mbed_official | 579:53297373a894 | 97 | * wired-AND type serial clock line (SCL) and a wired-AND type serial data line |
mbed_official | 579:53297373a894 | 98 | * (SDA). |
mbed_official | 579:53297373a894 | 99 | * |
mbed_official | 579:53297373a894 | 100 | * The I<SUP>2</SUP>C bus provides a simple, but efficient method of interconnecting |
mbed_official | 579:53297373a894 | 101 | * multiple master and slave devices. An arbitration mechanism is provided for |
mbed_official | 579:53297373a894 | 102 | * resolving bus ownership between masters, as only one master device may own |
mbed_official | 579:53297373a894 | 103 | * the bus at any given time. The arbitration mechanism relies on the wired-AND |
mbed_official | 579:53297373a894 | 104 | * connections to avoid bus drivers short-circuiting. |
mbed_official | 579:53297373a894 | 105 | * |
mbed_official | 579:53297373a894 | 106 | * A unique address is assigned to all slave devices connected to the bus. A |
mbed_official | 579:53297373a894 | 107 | * device can contain both master and slave logic, and can emulate multiple |
mbed_official | 579:53297373a894 | 108 | * slave devices by responding to more than one address. |
mbed_official | 579:53297373a894 | 109 | * |
mbed_official | 579:53297373a894 | 110 | * \subsection asfdoc_sam0_sercom_i2c_bus_topology Bus Topology |
mbed_official | 579:53297373a894 | 111 | * The I<SUP>2</SUP>C bus topology is illustrated in |
mbed_official | 579:53297373a894 | 112 | * \ref asfdoc_sam0_sercom_i2c_bus_topology_figure "the figure below". The pull-up |
mbed_official | 579:53297373a894 | 113 | * resistors (Rs) will provide a high level on the bus lines when none of the |
mbed_official | 579:53297373a894 | 114 | * I<SUP>2</SUP>C devices are driving the bus. These are optional, and can be |
mbed_official | 579:53297373a894 | 115 | * replaced with a constant current source. |
mbed_official | 579:53297373a894 | 116 | * |
mbed_official | 579:53297373a894 | 117 | * \anchor asfdoc_sam0_sercom_i2c_bus_topology_figure |
mbed_official | 579:53297373a894 | 118 | * \image html bus_topology.svg "I2C Bus Topology" Width=100% |
mbed_official | 579:53297373a894 | 119 | * |
mbed_official | 579:53297373a894 | 120 | * \subsection asfdoc_sam0_sercom_i2c_transactions Transactions |
mbed_official | 579:53297373a894 | 121 | * The I<SUP>2</SUP>C standard defines three fundamental transaction formats: |
mbed_official | 579:53297373a894 | 122 | * - Master Write |
mbed_official | 579:53297373a894 | 123 | * - The master transmits data packets to the slave after addressing it |
mbed_official | 579:53297373a894 | 124 | * - Master Read |
mbed_official | 579:53297373a894 | 125 | * - The slave transmits data packets to the master after being addressed |
mbed_official | 579:53297373a894 | 126 | * - Combined Read/Write |
mbed_official | 579:53297373a894 | 127 | * - A combined transaction consists of several write and read transactions |
mbed_official | 579:53297373a894 | 128 | * |
mbed_official | 579:53297373a894 | 129 | * A data transfer starts with the master issuing a \b Start condition on the |
mbed_official | 579:53297373a894 | 130 | * bus, followed by the address of the slave together with a bit to indicate |
mbed_official | 579:53297373a894 | 131 | * whether the master wants to read from or write to the slave. |
mbed_official | 579:53297373a894 | 132 | * The addressed slave must respond to this by sending an \b ACK back to the |
mbed_official | 579:53297373a894 | 133 | * master. |
mbed_official | 579:53297373a894 | 134 | * |
mbed_official | 579:53297373a894 | 135 | * After this, data packets are sent from the master or slave, according to the |
mbed_official | 579:53297373a894 | 136 | * read/write bit. Each packet must be acknowledged (ACK) or not |
mbed_official | 579:53297373a894 | 137 | * acknowledged (NACK) by the receiver. |
mbed_official | 579:53297373a894 | 138 | * |
mbed_official | 579:53297373a894 | 139 | * If a slave responds with a NACK, the master must assume that the slave |
mbed_official | 579:53297373a894 | 140 | * cannot receive any more data and cancel the write operation. |
mbed_official | 579:53297373a894 | 141 | * |
mbed_official | 579:53297373a894 | 142 | * The master completes a transaction by issuing a \b Stop condition. |
mbed_official | 579:53297373a894 | 143 | * |
mbed_official | 579:53297373a894 | 144 | * A master can issue multiple \b Start conditions during a transaction; this |
mbed_official | 579:53297373a894 | 145 | * is then called a \b Repeated \b Start condition. |
mbed_official | 579:53297373a894 | 146 | * |
mbed_official | 579:53297373a894 | 147 | * \subsubsection asfdoc_sam0_sercom_i2c_address_packets Address Packets |
mbed_official | 579:53297373a894 | 148 | * The slave address consists of seven bits. The 8<SUP>th</SUP> bit in the transfer |
mbed_official | 579:53297373a894 | 149 | * determines the data direction (read or write). An address packet always |
mbed_official | 579:53297373a894 | 150 | * succeeds a \b Start or \b Repeated \b Start condition. The 8<SUP>th</SUP> bit is handled |
mbed_official | 579:53297373a894 | 151 | * in the driver, and the user will only have to provide the 7-bit address. |
mbed_official | 579:53297373a894 | 152 | * |
mbed_official | 579:53297373a894 | 153 | * \subsubsection asfdoc_sam0_sercom_i2c_data_packets Data Packets |
mbed_official | 579:53297373a894 | 154 | * Data packets are nine bits long, consisting of one 8-bit data byte, and an |
mbed_official | 579:53297373a894 | 155 | * acknowledgement bit. Data packets follow either an address packet or another |
mbed_official | 579:53297373a894 | 156 | * data packet on the bus. |
mbed_official | 579:53297373a894 | 157 | * |
mbed_official | 579:53297373a894 | 158 | * \subsubsection asfdoc_sam0_sercom_i2c_trans_examples Transaction Examples |
mbed_official | 579:53297373a894 | 159 | * The gray bits in the following examples are sent from master to slave, and |
mbed_official | 579:53297373a894 | 160 | * the white bits are sent from slave to master. |
mbed_official | 579:53297373a894 | 161 | * Example of a read transaction is shown in |
mbed_official | 579:53297373a894 | 162 | * \ref asfdoc_sam0_sercom_i2c_trans_examples_i2c_read "the figure below". Here, the |
mbed_official | 579:53297373a894 | 163 | * master first issues a \b Start condition and gets ownership of the bus. An |
mbed_official | 579:53297373a894 | 164 | * address packet with the direction flag set to read is then sent and |
mbed_official | 579:53297373a894 | 165 | * acknowledged by the slave. Then the slave sends one data packet which is |
mbed_official | 579:53297373a894 | 166 | * acknowledged by the master. The slave sends another packet, which is not |
mbed_official | 579:53297373a894 | 167 | * acknowledged by the master and indicates that the master will terminate the |
mbed_official | 579:53297373a894 | 168 | * transaction. In the end, the transaction is terminated by the master issuing |
mbed_official | 579:53297373a894 | 169 | * a \b Stop condition. |
mbed_official | 579:53297373a894 | 170 | * |
mbed_official | 579:53297373a894 | 171 | * \anchor asfdoc_sam0_sercom_i2c_trans_examples_i2c_read |
mbed_official | 579:53297373a894 | 172 | * \image html i2c_read.svg "I2C Packet Read" Width=100% |
mbed_official | 579:53297373a894 | 173 | * |
mbed_official | 579:53297373a894 | 174 | * Example of a write transaction is shown in |
mbed_official | 579:53297373a894 | 175 | * \ref asfdoc_sam0_sercom_i2c_trans_examples_i2c_write "the figure below". Here, the |
mbed_official | 579:53297373a894 | 176 | * master first issues a \b Start condition and gets ownership of the bus. An |
mbed_official | 579:53297373a894 | 177 | * address packet with the dir flag set to write is then sent and acknowledged |
mbed_official | 579:53297373a894 | 178 | * by the slave. Then the master sends two data packets, each acknowledged by |
mbed_official | 579:53297373a894 | 179 | * the slave. In the end, the transaction is terminated by the master issuing |
mbed_official | 579:53297373a894 | 180 | * a \b Stop condition. |
mbed_official | 579:53297373a894 | 181 | * |
mbed_official | 579:53297373a894 | 182 | * \anchor asfdoc_sam0_sercom_i2c_trans_examples_i2c_write |
mbed_official | 579:53297373a894 | 183 | * \image html i2c_write.svg "I2C Packet Write" Width=100% |
mbed_official | 579:53297373a894 | 184 | * |
mbed_official | 579:53297373a894 | 185 | * \subsubsection asfdoc_sam0_sercom_i2c_packet_timeout Packet Timeout |
mbed_official | 579:53297373a894 | 186 | * When a master sends an I<SUP>2</SUP>C packet, there is no way of |
mbed_official | 579:53297373a894 | 187 | * being sure that a slave will acknowledge the packet. To avoid stalling the |
mbed_official | 579:53297373a894 | 188 | * device forever while waiting for an acknowledge, a user selectable timeout |
mbed_official | 579:53297373a894 | 189 | * is provided in the \ref i2c_master_config struct which |
mbed_official | 579:53297373a894 | 190 | * lets the driver exit a read or write operation after the specified time. |
mbed_official | 579:53297373a894 | 191 | * The function will then return the STATUS_ERR_TIMEOUT flag. |
mbed_official | 579:53297373a894 | 192 | * |
mbed_official | 579:53297373a894 | 193 | * This is also the case for the slave when using the functions postfixed |
mbed_official | 579:53297373a894 | 194 | * \c _wait. |
mbed_official | 579:53297373a894 | 195 | * |
mbed_official | 579:53297373a894 | 196 | * The time before the timeout occurs, will be the same as |
mbed_official | 579:53297373a894 | 197 | * for \ref asfdoc_sam0_sercom_i2c_unknown_bus_timeout "unknown bus state" timeout. |
mbed_official | 579:53297373a894 | 198 | * |
mbed_official | 579:53297373a894 | 199 | * \subsubsection asfdoc_sam0_sercom_i2c_repeated_start Repeated Start |
mbed_official | 579:53297373a894 | 200 | * To issue a \b Repeated \b Start, the functions postfixed \c _no_stop must be |
mbed_official | 579:53297373a894 | 201 | * used. |
mbed_official | 579:53297373a894 | 202 | * These functions will not send a \b Stop condition when the transfer is done, |
mbed_official | 579:53297373a894 | 203 | * thus the next transfer will start with a \b Repeated \b Start. To end the |
mbed_official | 579:53297373a894 | 204 | * transaction, the functions without the \c _no_stop postfix must be used |
mbed_official | 579:53297373a894 | 205 | * for the last read/write. |
mbed_official | 579:53297373a894 | 206 | * |
mbed_official | 579:53297373a894 | 207 | * \subsection asfdoc_sam0_sercom_i2c_multi_master Multi Master |
mbed_official | 579:53297373a894 | 208 | * In a multi master environment, arbitration of the bus is important, as only |
mbed_official | 579:53297373a894 | 209 | * one master can own the bus at any point. |
mbed_official | 579:53297373a894 | 210 | * |
mbed_official | 579:53297373a894 | 211 | * \subsubsection asfdoc_sam0_sercom_i2c_arbitration Arbitration |
mbed_official | 579:53297373a894 | 212 | * |
mbed_official | 579:53297373a894 | 213 | * \par Clock stretching |
mbed_official | 579:53297373a894 | 214 | * The serial clock line is always driven by a master device. However, all |
mbed_official | 579:53297373a894 | 215 | * devices connected to the bus are allowed stretch the low period of the clock |
mbed_official | 579:53297373a894 | 216 | * to slow down the overall clock frequency or to insert wait states while |
mbed_official | 579:53297373a894 | 217 | * processing data. |
mbed_official | 579:53297373a894 | 218 | * Both master and slave can randomly stretch the clock, which will force the |
mbed_official | 579:53297373a894 | 219 | * other device into a wait-state until the clock line goes high again. |
mbed_official | 579:53297373a894 | 220 | * |
mbed_official | 579:53297373a894 | 221 | * \par Arbitration on the data line |
mbed_official | 579:53297373a894 | 222 | * If two masters start transmitting at the same time, they will both transmit |
mbed_official | 579:53297373a894 | 223 | * until one master detects that the other master is pulling the data line low. |
mbed_official | 579:53297373a894 | 224 | * When this is detected, the master not pulling the line low, will stop the |
mbed_official | 579:53297373a894 | 225 | * transmission and wait until the bus is idle. |
mbed_official | 579:53297373a894 | 226 | * As it is the master trying to contact the slave with the lowest address that |
mbed_official | 579:53297373a894 | 227 | * will get the bus ownership, this will create an arbitration scheme always |
mbed_official | 579:53297373a894 | 228 | * prioritizing the slaves with the lowest address in case of a bus collision. |
mbed_official | 579:53297373a894 | 229 | * |
mbed_official | 579:53297373a894 | 230 | * \subsubsection asfdoc_sam0_sercom_i2c_clock_sync Clock Synchronization |
mbed_official | 579:53297373a894 | 231 | * In situations where more than one master is trying to control the bus clock |
mbed_official | 579:53297373a894 | 232 | * line at the same time, a clock synchronization algorithm based on the same |
mbed_official | 579:53297373a894 | 233 | * principles used for clock stretching is necessary. |
mbed_official | 579:53297373a894 | 234 | * |
mbed_official | 579:53297373a894 | 235 | * |
mbed_official | 579:53297373a894 | 236 | * \subsection asfdoc_sam0_sercom_i2c_bus_states Bus States |
mbed_official | 579:53297373a894 | 237 | * As the I<SUP>2</SUP>C bus is limited to one transaction at the time, |
mbed_official | 579:53297373a894 | 238 | * a master that wants to perform a bus transaction must wait until the bus is |
mbed_official | 579:53297373a894 | 239 | * free. |
mbed_official | 579:53297373a894 | 240 | * Because of this, it is necessary for all masters in a multi-master system to |
mbed_official | 579:53297373a894 | 241 | * know the current status of the bus to be able to avoid conflicts and to |
mbed_official | 579:53297373a894 | 242 | * ensure data integrity. |
mbed_official | 579:53297373a894 | 243 | * \li \b IDLE No activity on the bus (between a \b Stop and a new \b Start |
mbed_official | 579:53297373a894 | 244 | * condition) |
mbed_official | 579:53297373a894 | 245 | * \li \b OWNER If the master initiates a transaction successfully |
mbed_official | 579:53297373a894 | 246 | * \li \b BUSY If another master is driving the bus |
mbed_official | 579:53297373a894 | 247 | * \li \b UNKNOWN If the master has recently been enabled or connected to |
mbed_official | 579:53297373a894 | 248 | * the bus. Is forced to \b IDLE after given |
mbed_official | 579:53297373a894 | 249 | * \ref asfdoc_sam0_sercom_i2c_unknown_bus_timeout "timeout" when |
mbed_official | 579:53297373a894 | 250 | * the master module is enabled. |
mbed_official | 579:53297373a894 | 251 | * |
mbed_official | 579:53297373a894 | 252 | * The bus state diagram can be seen in |
mbed_official | 579:53297373a894 | 253 | * \ref asfdoc_sam0_sercom_i2c_bus_states_figure "the figure below". |
mbed_official | 579:53297373a894 | 254 | * \li S: Start condition |
mbed_official | 579:53297373a894 | 255 | * \li P: Stop condition |
mbed_official | 579:53297373a894 | 256 | * \li Sr: Repeated start condition |
mbed_official | 579:53297373a894 | 257 | * \anchor asfdoc_sam0_sercom_i2c_bus_states_figure |
mbed_official | 579:53297373a894 | 258 | * \image html bus_state_diagram.svg "I2C Bus State Diagram" Width=100% |
mbed_official | 579:53297373a894 | 259 | * |
mbed_official | 579:53297373a894 | 260 | * \subsection asfdoc_sam0_sercom_i2c_timeout Bus Timing |
mbed_official | 579:53297373a894 | 261 | * Inactive bus timeout for the master and SDA hold time is configurable in the |
mbed_official | 579:53297373a894 | 262 | * drivers. |
mbed_official | 579:53297373a894 | 263 | * |
mbed_official | 579:53297373a894 | 264 | * \subsubsection asfdoc_sam0_sercom_i2c_unknown_bus_timeout Unknown Bus State Timeout |
mbed_official | 579:53297373a894 | 265 | * When a master is enabled or connected to the bus, the bus state will be |
mbed_official | 579:53297373a894 | 266 | * unknown until either a given timeout or a stop command has occurred. The |
mbed_official | 579:53297373a894 | 267 | * timeout is configurable in the \ref i2c_master_config struct. |
mbed_official | 579:53297373a894 | 268 | * The timeout time will depend on toolchain and optimization level used, as |
mbed_official | 579:53297373a894 | 269 | * the timeout is a loop incrementing a value until it reaches the specified |
mbed_official | 579:53297373a894 | 270 | * timeout value. |
mbed_official | 579:53297373a894 | 271 | * |
mbed_official | 579:53297373a894 | 272 | * \subsubsection sda_hold SDA Hold Timeout |
mbed_official | 579:53297373a894 | 273 | * When using the I<SUP>2</SUP>C in slave mode, it will be important to |
mbed_official | 579:53297373a894 | 274 | * set a SDA hold time which assures that the master will be able to pick up |
mbed_official | 579:53297373a894 | 275 | * the bit sent from the slave. The SDA hold time makes sure that this is the |
mbed_official | 579:53297373a894 | 276 | * case by holding the data line low for a given period after the negative edge |
mbed_official | 579:53297373a894 | 277 | * on the clock. |
mbed_official | 579:53297373a894 | 278 | * |
mbed_official | 579:53297373a894 | 279 | * The SDA hold time is also available for the master driver, but is not a |
mbed_official | 579:53297373a894 | 280 | * necessity. |
mbed_official | 579:53297373a894 | 281 | * |
mbed_official | 579:53297373a894 | 282 | * \subsection asfdoc_sam0_sercom_i2c_sleep_modes Operation in Sleep Modes |
mbed_official | 579:53297373a894 | 283 | * The I<SUP>2</SUP>C module can operate in all sleep modes by setting |
mbed_official | 579:53297373a894 | 284 | * the run_in_standby Boolean in the \ref i2c_master_config or |
mbed_official | 579:53297373a894 | 285 | * \ref i2c_slave_config struct. |
mbed_official | 579:53297373a894 | 286 | * The operation in slave and master mode is shown in |
mbed_official | 579:53297373a894 | 287 | * \ref asfdoc_sam0_sercom_i2c_sleep_modes_table "the table below". |
mbed_official | 579:53297373a894 | 288 | * |
mbed_official | 579:53297373a894 | 289 | * \anchor asfdoc_sam0_sercom_i2c_sleep_modes_table |
mbed_official | 579:53297373a894 | 290 | * <table> |
mbed_official | 579:53297373a894 | 291 | * <caption>I<SUP>2</SUP>C Standby Operations</caption> |
mbed_official | 579:53297373a894 | 292 | * <tr> |
mbed_official | 579:53297373a894 | 293 | * <th>Run in standby</th> |
mbed_official | 579:53297373a894 | 294 | * <th>Slave</th> |
mbed_official | 579:53297373a894 | 295 | * <th>Master</th> |
mbed_official | 579:53297373a894 | 296 | * </tr> |
mbed_official | 579:53297373a894 | 297 | * <tr> |
mbed_official | 579:53297373a894 | 298 | * <td>false</td> |
mbed_official | 579:53297373a894 | 299 | * <td>Disabled, all reception is dropped</td> |
mbed_official | 579:53297373a894 | 300 | * <td>GCLK disabled when master is idle</td> |
mbed_official | 579:53297373a894 | 301 | * </tr> |
mbed_official | 579:53297373a894 | 302 | * <tr> |
mbed_official | 579:53297373a894 | 303 | * <td>true</td> |
mbed_official | 579:53297373a894 | 304 | * <td>Wake on address match when enabled</td> |
mbed_official | 579:53297373a894 | 305 | * <td>GCLK enabled while in sleep modes</td> |
mbed_official | 579:53297373a894 | 306 | * </tr> |
mbed_official | 579:53297373a894 | 307 | * </table> |
mbed_official | 579:53297373a894 | 308 | * |
mbed_official | 579:53297373a894 | 309 | * |
mbed_official | 579:53297373a894 | 310 | * \section asfdoc_sam0_sercom_i2c_special_considerations Special Considerations |
mbed_official | 579:53297373a894 | 311 | * |
mbed_official | 579:53297373a894 | 312 | * \if (I2C_MASTER_CALLBACK_MODE || I2C_SLAVE_CALLBACK_MODE) |
mbed_official | 579:53297373a894 | 313 | * \subsection asfdoc_sam0_sercom_i2c_common_interrupt Interrupt-driven Operation |
mbed_official | 579:53297373a894 | 314 | * While an interrupt-driven operation is in progress, subsequent calls to a |
mbed_official | 579:53297373a894 | 315 | * write or read operation will return the STATUS_BUSY flag, indicating that |
mbed_official | 579:53297373a894 | 316 | * only one operation is allowed at any given time. |
mbed_official | 579:53297373a894 | 317 | * |
mbed_official | 579:53297373a894 | 318 | * To check if another transmission can be initiated, the user can either call |
mbed_official | 579:53297373a894 | 319 | * another transfer operation, or use the |
mbed_official | 579:53297373a894 | 320 | * \ref i2c_master_get_job_status/\ref i2c_slave_get_job_status functions |
mbed_official | 579:53297373a894 | 321 | * depending on mode. |
mbed_official | 579:53297373a894 | 322 | * |
mbed_official | 579:53297373a894 | 323 | * If the user would like to get callback from operations while using the |
mbed_official | 579:53297373a894 | 324 | * interrupt-driven driver, the callback must be registered and then enabled |
mbed_official | 579:53297373a894 | 325 | * using the "register_callback" and "enable_callback" functions. |
mbed_official | 579:53297373a894 | 326 | * \else |
mbed_official | 579:53297373a894 | 327 | * There are no special considerations for this driver for the APIs listed in |
mbed_official | 579:53297373a894 | 328 | * this document. |
mbed_official | 579:53297373a894 | 329 | * \endif |
mbed_official | 579:53297373a894 | 330 | * |
mbed_official | 579:53297373a894 | 331 | * \section asfdoc_sam0_sercom_i2c_extra Extra Information |
mbed_official | 579:53297373a894 | 332 | * For extra information, see \ref asfdoc_sam0_sercom_i2c_extra_info_page. |
mbed_official | 579:53297373a894 | 333 | * This includes: |
mbed_official | 579:53297373a894 | 334 | * - \ref asfdoc_sam0_sercom_i2c_acronyms |
mbed_official | 579:53297373a894 | 335 | * - \ref asfdoc_sam0_sercom_i2c_extra_dependencies |
mbed_official | 579:53297373a894 | 336 | * - \ref asfdoc_sam0_sercom_i2c_extra_errata |
mbed_official | 579:53297373a894 | 337 | * - \ref asfdoc_sam0_sercom_i2c_extra_history |
mbed_official | 579:53297373a894 | 338 | * |
mbed_official | 579:53297373a894 | 339 | * \section asfdoc_sam0_sercom_i2c_examples Examples |
mbed_official | 579:53297373a894 | 340 | * |
mbed_official | 579:53297373a894 | 341 | * For a list of examples related to this driver, see |
mbed_official | 579:53297373a894 | 342 | * \ref asfdoc_sam0_sercom_i2c_exqsg. |
mbed_official | 579:53297373a894 | 343 | * |
mbed_official | 579:53297373a894 | 344 | * \section asfdoc_sam0_sercom_i2c_api_overview API Overview |
mbed_official | 579:53297373a894 | 345 | * @{ |
mbed_official | 579:53297373a894 | 346 | */ |
mbed_official | 579:53297373a894 | 347 | |
mbed_official | 579:53297373a894 | 348 | /** |
mbed_official | 579:53297373a894 | 349 | * \name Driver Feature Definition |
mbed_official | 579:53297373a894 | 350 | * Define SERCOM I<SUP>2</SUP>C driver features set according to different device family. |
mbed_official | 579:53297373a894 | 351 | * |
mbed_official | 579:53297373a894 | 352 | * \note The high speed mode and 10-bit address feature are not |
mbed_official | 579:53297373a894 | 353 | * supported by the driver now. |
mbed_official | 579:53297373a894 | 354 | * @{ |
mbed_official | 579:53297373a894 | 355 | */ |
mbed_official | 579:53297373a894 | 356 | #if (SAMD21) || (SAMR21) || (SAMD10) || (SAMD11) || (SAML21) ||defined(__DOXYGEN__) |
mbed_official | 579:53297373a894 | 357 | /** Fast mode plus and high speed support. */ |
mbed_official | 579:53297373a894 | 358 | # define FEATURE_I2C_FAST_MODE_PLUS_AND_HIGH_SPEED |
mbed_official | 579:53297373a894 | 359 | /** 10-bit address support. */ |
mbed_official | 579:53297373a894 | 360 | # define FEATURE_I2C_10_BIT_ADDRESS |
mbed_official | 579:53297373a894 | 361 | /** SCL stretch mode support. */ |
mbed_official | 579:53297373a894 | 362 | # define FEATURE_I2C_SCL_STRETCH_MODE |
mbed_official | 579:53297373a894 | 363 | /** SCL extend timeout support. */ |
mbed_official | 579:53297373a894 | 364 | # define FEATURE_I2C_SCL_EXTEND_TIMEOUT |
mbed_official | 579:53297373a894 | 365 | # define FEATURE_I2C_DMA_SUPPORT |
mbed_official | 579:53297373a894 | 366 | #endif |
mbed_official | 579:53297373a894 | 367 | /*@}*/ |
mbed_official | 579:53297373a894 | 368 | |
mbed_official | 579:53297373a894 | 369 | /** \brief Transfer direction |
mbed_official | 579:53297373a894 | 370 | * |
mbed_official | 579:53297373a894 | 371 | * For master: transfer direction or setting direction bit in address. |
mbed_official | 579:53297373a894 | 372 | * For slave: direction of request from master. |
mbed_official | 579:53297373a894 | 373 | */ |
mbed_official | 579:53297373a894 | 374 | enum i2c_transfer_direction { |
mbed_official | 579:53297373a894 | 375 | /** Master write operation is in progress. */ |
mbed_official | 579:53297373a894 | 376 | I2C_TRANSFER_WRITE = 0, |
mbed_official | 579:53297373a894 | 377 | /** Master read operation is in progress. */ |
mbed_official | 579:53297373a894 | 378 | I2C_TRANSFER_READ = 1, |
mbed_official | 579:53297373a894 | 379 | }; |
mbed_official | 579:53297373a894 | 380 | |
mbed_official | 579:53297373a894 | 381 | /** @} */ |
mbed_official | 579:53297373a894 | 382 | |
mbed_official | 579:53297373a894 | 383 | #ifdef __cplusplus |
mbed_official | 579:53297373a894 | 384 | } |
mbed_official | 579:53297373a894 | 385 | #endif |
mbed_official | 579:53297373a894 | 386 | |
mbed_official | 579:53297373a894 | 387 | /** |
mbed_official | 579:53297373a894 | 388 | * \page asfdoc_sam0_sercom_i2c_extra_info_page Extra Information for SERCOM I2C Driver |
mbed_official | 579:53297373a894 | 389 | * |
mbed_official | 579:53297373a894 | 390 | * \section asfdoc_sam0_sercom_i2c_acronyms Acronyms |
mbed_official | 579:53297373a894 | 391 | * \ref asfdoc_sam0_sercom_i2c_acronyms_table "Below" is a table listing the acronyms |
mbed_official | 579:53297373a894 | 392 | * used in this module, along with their intended meanings. |
mbed_official | 579:53297373a894 | 393 | * |
mbed_official | 579:53297373a894 | 394 | * \anchor asfdoc_sam0_sercom_i2c_acronyms_table |
mbed_official | 579:53297373a894 | 395 | * <table> |
mbed_official | 579:53297373a894 | 396 | * <caption>Acronyms</caption> |
mbed_official | 579:53297373a894 | 397 | * <tr> |
mbed_official | 579:53297373a894 | 398 | * <th>Acronym</th> |
mbed_official | 579:53297373a894 | 399 | * <th>Description</th> |
mbed_official | 579:53297373a894 | 400 | * </tr> |
mbed_official | 579:53297373a894 | 401 | * <tr> |
mbed_official | 579:53297373a894 | 402 | * <td>SDA</td> |
mbed_official | 579:53297373a894 | 403 | * <td>Serial Data Line</td> |
mbed_official | 579:53297373a894 | 404 | * </tr> |
mbed_official | 579:53297373a894 | 405 | * <tr> |
mbed_official | 579:53297373a894 | 406 | * <td>SCL</td> |
mbed_official | 579:53297373a894 | 407 | * <td>Serial Clock Line</td> |
mbed_official | 579:53297373a894 | 408 | * </tr> |
mbed_official | 579:53297373a894 | 409 | * <tr> |
mbed_official | 579:53297373a894 | 410 | * <td>SERCOM</td> |
mbed_official | 579:53297373a894 | 411 | * <td>Serial Communication Interface</td> |
mbed_official | 579:53297373a894 | 412 | * </tr> |
mbed_official | 579:53297373a894 | 413 | * <tr> |
mbed_official | 579:53297373a894 | 414 | * <td>DMA</td> |
mbed_official | 579:53297373a894 | 415 | * <td>Direct Memory Access</td> |
mbed_official | 579:53297373a894 | 416 | * </tr> |
mbed_official | 579:53297373a894 | 417 | * </table> |
mbed_official | 579:53297373a894 | 418 | * |
mbed_official | 579:53297373a894 | 419 | * \section asfdoc_sam0_sercom_i2c_extra_dependencies Dependencies |
mbed_official | 579:53297373a894 | 420 | * The I<SUP>2</SUP>C driver has the following dependencies: |
mbed_official | 579:53297373a894 | 421 | * \li \ref asfdoc_sam0_system_pinmux_group "System Pin Multiplexer Driver" |
mbed_official | 579:53297373a894 | 422 | * |
mbed_official | 579:53297373a894 | 423 | * |
mbed_official | 579:53297373a894 | 424 | * \section asfdoc_sam0_sercom_i2c_extra_errata Errata |
mbed_official | 579:53297373a894 | 425 | * There are no errata related to this driver. |
mbed_official | 579:53297373a894 | 426 | * |
mbed_official | 579:53297373a894 | 427 | * \section asfdoc_sam0_sercom_i2c_extra_history Module History |
mbed_official | 579:53297373a894 | 428 | * \ref asfdoc_sam0_sercom_i2c_extra_history_table "Below" is an overview of the |
mbed_official | 579:53297373a894 | 429 | * module history, detailing enhancements and fixes made to the module since |
mbed_official | 579:53297373a894 | 430 | * its first release. The current version of this corresponds to the newest |
mbed_official | 579:53297373a894 | 431 | * version listed in |
mbed_official | 579:53297373a894 | 432 | * \ref asfdoc_sam0_sercom_i2c_extra_history_table "the table below". |
mbed_official | 579:53297373a894 | 433 | * |
mbed_official | 579:53297373a894 | 434 | * \anchor asfdoc_sam0_sercom_i2c_extra_history_table |
mbed_official | 579:53297373a894 | 435 | * <table> |
mbed_official | 579:53297373a894 | 436 | * <caption>Module History</caption> |
mbed_official | 579:53297373a894 | 437 | * <tr> |
mbed_official | 579:53297373a894 | 438 | * <th>Changelog</th> |
mbed_official | 579:53297373a894 | 439 | * </tr> |
mbed_official | 579:53297373a894 | 440 | * <tr> |
mbed_official | 579:53297373a894 | 441 | * <td> |
mbed_official | 579:53297373a894 | 442 | * \li Added 10-bit addressing and high speed support in SAM D21 |
mbed_official | 579:53297373a894 | 443 | * \li Seperate structure i2c_packet into i2c_master_packet and i2c_slave packet |
mbed_official | 579:53297373a894 | 444 | * </td> |
mbed_official | 579:53297373a894 | 445 | * </tr> |
mbed_official | 579:53297373a894 | 446 | * <tr> |
mbed_official | 579:53297373a894 | 447 | * <td> |
mbed_official | 579:53297373a894 | 448 | * \li Added support for SCL stretch and extended timeout hardware features in SAM D21 |
mbed_official | 579:53297373a894 | 449 | * \li Added fast mode plus support in SAM D21 |
mbed_official | 579:53297373a894 | 450 | * </td> |
mbed_official | 579:53297373a894 | 451 | * </tr> |
mbed_official | 579:53297373a894 | 452 | * <tr> |
mbed_official | 579:53297373a894 | 453 | * <td>Fixed incorrect logical mask for determining if a bus error has |
mbed_official | 579:53297373a894 | 454 | * occurred in I<SUP>2</SUP>C Slave mode |
mbed_official | 579:53297373a894 | 455 | * </td> |
mbed_official | 579:53297373a894 | 456 | * </tr> |
mbed_official | 579:53297373a894 | 457 | * <tr> |
mbed_official | 579:53297373a894 | 458 | * <td>Initial Release</td> |
mbed_official | 579:53297373a894 | 459 | * </tr> |
mbed_official | 579:53297373a894 | 460 | * </table> |
mbed_official | 579:53297373a894 | 461 | */ |
mbed_official | 579:53297373a894 | 462 | |
mbed_official | 579:53297373a894 | 463 | /** |
mbed_official | 579:53297373a894 | 464 | * \page asfdoc_sam0_sercom_i2c_exqsg Examples for SERCOM I2C Driver |
mbed_official | 579:53297373a894 | 465 | * |
mbed_official | 579:53297373a894 | 466 | * This is a list of the available Quick Start guides (QSGs) and example |
mbed_official | 579:53297373a894 | 467 | * applications for \ref asfdoc_sam0_sercom_i2c_group. QSGs are simple examples with |
mbed_official | 579:53297373a894 | 468 | * step-by-step instructions to configure and use this driver in a selection of |
mbed_official | 579:53297373a894 | 469 | * use cases. Note that QSGs can be compiled as a standalone application or be |
mbed_official | 579:53297373a894 | 470 | * added to the user application. |
mbed_official | 579:53297373a894 | 471 | * |
mbed_official | 579:53297373a894 | 472 | * \if I2C_MASTER_MODE |
mbed_official | 579:53297373a894 | 473 | * - \subpage asfdoc_sam0_sercom_i2c_master_basic_use_case "Quick Start Guide for the I2C Master module - Basic Use Case" |
mbed_official | 579:53297373a894 | 474 | * \endif |
mbed_official | 579:53297373a894 | 475 | * \if I2C_MASTER_CALLBACK_MODE |
mbed_official | 579:53297373a894 | 476 | * - \subpage asfdoc_sam0_sercom_i2c_master_callback_use_case "Quick Start Guide for the I2C Master module - Callback Use Case" |
mbed_official | 579:53297373a894 | 477 | * - \subpage asfdoc_sam0_sercom_i2c_master_dma_use_case "Quick Start Guide for the I2C Master module - DMA Use Case" |
mbed_official | 579:53297373a894 | 478 | * \endif |
mbed_official | 579:53297373a894 | 479 | * \if I2C_SLAVE_MODE |
mbed_official | 579:53297373a894 | 480 | * - \subpage asfdoc_sam0_sercom_i2c_slave_basic_use_case "Quick Start Guide for the I2C Slave module - Basic Use Case" |
mbed_official | 579:53297373a894 | 481 | * \endif |
mbed_official | 579:53297373a894 | 482 | * \if I2C_SLAVE_CALLBACK_MODE |
mbed_official | 579:53297373a894 | 483 | * - \subpage asfdoc_sam0_sercom_i2c_slave_callback_use_case "Quick Start Guide for the I2C Slave module - Callback Use Case" |
mbed_official | 579:53297373a894 | 484 | * - \subpage asfdoc_sam0_sercom_i2c_slave_dma_use_case "Quick Start Guide for the I2C Slave module - DMA Use Case" |
mbed_official | 579:53297373a894 | 485 | * \endif |
mbed_official | 579:53297373a894 | 486 | * |
mbed_official | 579:53297373a894 | 487 | * \page asfdoc_sam0_sercom_i2c_document_revision_history Document Revision History |
mbed_official | 579:53297373a894 | 488 | * |
mbed_official | 579:53297373a894 | 489 | * <table> |
mbed_official | 579:53297373a894 | 490 | * <tr> |
mbed_official | 579:53297373a894 | 491 | * <th>Doc. Rev.</td> |
mbed_official | 579:53297373a894 | 492 | * <th>Date</td> |
mbed_official | 579:53297373a894 | 493 | * <th>Comments</td> |
mbed_official | 579:53297373a894 | 494 | * </tr> |
mbed_official | 579:53297373a894 | 495 | * <tr> |
mbed_official | 579:53297373a894 | 496 | * <td>E</td> |
mbed_official | 579:53297373a894 | 497 | * <td>11/2014</td> |
mbed_official | 579:53297373a894 | 498 | * <td>Added SAM L21 support.</td> |
mbed_official | 579:53297373a894 | 499 | * </tr> |
mbed_official | 579:53297373a894 | 500 | * <tr> |
mbed_official | 579:53297373a894 | 501 | * <td>D</td> |
mbed_official | 579:53297373a894 | 502 | * <td>12/2014</td> |
mbed_official | 579:53297373a894 | 503 | * <td>Added 10-bit addressing and high speed support in SAM D21 |
mbed_official | 579:53297373a894 | 504 | * Added SAM R21/D10/D11 support.</td> |
mbed_official | 579:53297373a894 | 505 | * </tr> |
mbed_official | 579:53297373a894 | 506 | * <tr> |
mbed_official | 579:53297373a894 | 507 | * <td>C</td> |
mbed_official | 579:53297373a894 | 508 | * <td>01/2014</td> |
mbed_official | 579:53297373a894 | 509 | * <td>Added the SAM D21 to the application note.</td> |
mbed_official | 579:53297373a894 | 510 | * </tr> |
mbed_official | 579:53297373a894 | 511 | * <tr> |
mbed_official | 579:53297373a894 | 512 | * <td>B</td> |
mbed_official | 579:53297373a894 | 513 | * <td>06/2013</td> |
mbed_official | 579:53297373a894 | 514 | * <td>Corrected documentation typos. Updated I<SUP>2</SUP>C Bus State Diagram.</td> |
mbed_official | 579:53297373a894 | 515 | * </tr> |
mbed_official | 579:53297373a894 | 516 | * <tr> |
mbed_official | 579:53297373a894 | 517 | * <td>A</td> |
mbed_official | 579:53297373a894 | 518 | * <td>06/2013</td> |
mbed_official | 579:53297373a894 | 519 | * <td>Initial release.</td> |
mbed_official | 579:53297373a894 | 520 | * </tr> |
mbed_official | 579:53297373a894 | 521 | * </table> |
mbed_official | 579:53297373a894 | 522 | */ |
mbed_official | 579:53297373a894 | 523 | |
mbed_official | 579:53297373a894 | 524 | #endif /* I2C_COMMON_H_INCLUDED */ |