mbed library sources

Dependents:   Encrypted my_mbed lklk CyaSSL_DTLS_Cellular ... more

Superseded

This library was superseded by mbed-dev - https://os.mbed.com/users/mbed_official/code/mbed-dev/.

Development branch of the mbed library sources. This library is kept in synch with the latest changes from the mbed SDK and it is not guaranteed to work.

If you are looking for a stable and tested release, please import one of the official mbed library releases:

Import librarymbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

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?

UserRevisionLine numberNew 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 */