RTOS enabled i2c-driver based on the official i2c-C-api.

Dependencies:   mbed-rtos

Fork of mbed-RtosI2cDriver by Helmut Schmücker

I2cRtosDriver

Overview

  • Based on RTOS
    • Less busy wait waste of CPU cycles
    • ... but some waste of CPU cycles by context switches
    • Frees up to 80% of CPU resources
  • Fixes the bug described in https://mbed.org/forum/bugs-suggestions/topic/4128/
  • Spends minimal time in interrupt context
  • Supports I2C Master and Slave mode
  • Interface compatible to official I2C lib
  • Supports LPC1768 and LPC11U24.
  • Reuses parts of the official I2C implementation
  • The test and example programs work quite well and the results look promising. But this is by no means a thoroughly regression tested library. There might be some surprises left.
  • If you want to avoid the RTOS overhead MODI2C might be a better choice.

Usage

  • In existing projects simply replace in the I2C interface class declaration the official type by one of the adapters I2CMasterRtos or I2CSlaveRtos described below. The behavior should be the same.
  • You can also use the I2CDriver interface directly.
  • You can create several instances of I2CMasterRtos, I2CSlaveRtos and I2CDriver. The interface classes are lightweight and work in parallel.
  • See also the tests/examples in I2CDriverTest01.h - I2CDriverTest05.h
  • The I2CDriver class is the central interface
    • I2CDriver provides a "fat" API for I2C master and slave access
    • It supports on the fly changes between master and slave mode.
    • All requests are blocking. Other threads might do their work while the calling thread waits for the i2c requests to be completed.
    • It ensures mutual exclusive access to the I2C HW.
      • This is realized by a static RTOS mutex for each I2C channel. The mutex is taken by the calling thread on any call of an I2CDriver-function.
      • Thus accesses are prioritized automatically by the priority of the calling user threads.
      • Once having access to the interface the requests are performed with high priority and cannot be interrupted by other threads.
      • Optionally the interface can be locked manually. Useful if one wants to perform a sequence of commands without interruption.
  • I2CMasterRtos and I2CSlaveRtos provide an interface compatible to the official mbed I2C interface. Additionally
    • the constructors provide parameters for defining the frequency and the slave address
    • I2CMasterRtos provides a function to read data from a given slave register
    • In contrast to the original interface the I2CSlaveRtos::receive() function is blocking, i.e it returns, when the master sends a request to the listening slave. There is no need to poll the receive status in a loop. Optionally a timeout value can be passed to the function.
    • The stop function provides a timeout mechanism and returns the status. Thus if someone on the bus inhibits the creation of a stop condition by keeping the scl or the sda line low the mbed master won't get freezed.
    • The interface adapters are implemented as object adapters, i.e they hold an I2CDriver-instance, to which they forward the user requests by simple inline functions. The overhead is negligible.

Design

The i2c read and write sequences have been realized in an interrupt service routine. The communicaton between the calling thread and the ISR is realized by a simple static transfer struct and a semaphore ... see i2cRtos_api.c
The start and stop functions still use the busy wait approach. They are not entered that frequently and usually they take less than 12µs at 100kHz bus speed. At 400kHz even less time is consumed. Thus there wouldn't be much benefit if one triggers the whole interrupt/task wait/switch sequence for that short period of time.

Performance

The following performance data have been measured with the small test applications in I2CDriverTest01.h and I2CDriverTest04.h . In these applications a high priority thread, triggered at a rate of 1kHz, reads on each trigger a data packet of given size with given I2C bus speed from a SRF08 ultra sonic ranger or a MPU6050 accelerometer/gyro. At the same time the main thread - running at a lower priority - counts in an endless loop adjacent increments of the mbed's µs-ticker API and calculates a duty cycle from this. These duty cycle measurements are shown in the table below together with the time measured for one read sequence (write address+register; write address and read x byte of data). The measurements have been performed with the ISR/RTOS approach used by this driver and with the busy wait approach used by the official mbed I2C implementation. The i2c implementation can be selected via #define PREFIX in I2CDriver.cpp.

  • The time for one read cycle is almost the same for both approaches
  • At full load the duty cycle of the low priority thread drops almost to zero for the busy wait approach, whereas with the RTOS/ISR enabled driver it stays at 80%-90% on the LPC1768 and above 65% on the LPC11U24.
  • => Especially at low bus speeds and/or high data transfer loads the driver is able to free a significant amount of CPU time.
LPC17681byte/ms4byte/ms6byte/ms1byte/ms6byte/ms12byte/ms25byte/ms
SRF08@ 100kHz@ 100kHz@ 100kHz@ 400kHz@ 400kHz@ 400kHz@ 400kHz
rtos/ISRDC[%]91.791.090.593.391.990.386.8
t[µs]421714910141314518961
busy waitDC[%]57.127.78.185.868.748.23.8
t[µs]415710907128299503949
LPC17681byte/ms4byte/ms7byte/ms1byte/ms6byte/ms12byte/ms36byte/ms
MPU6050@ 100kHz@ 100kHz@ 100kHz@ 400kHz@ 400kHz@ 400kHz@ 400kHz
rtos/ISRDC[%]91.590.789.393.091.690.084.2
t[µs]415687959133254398977
busy waitDC[%]57.730.53.386.574.359.71.2
t[µs]408681953121243392974
LPC11U241byte/ms6byte/ms1byte/ms6byte/ms23byte/ms
SRF08@ 100kHz@ 100kHz@ 400kHz@ 400kHz@ 400kHz
rtos/ISRDC[%]79.277.581.178.771.4
t[µs]474975199374978
busy waitDC[%]51.82.480.5633.3
t[µs]442937156332928
LPC11U241byte/ms6byte/ms1byte/ms6byte/ms32byte/ms
MPU6050@ 100kHz@ 100kHz@ 400kHz@ 400kHz@ 400kHz
rtos/ISRDC[%]79.176.881.078.667.1
t[µs]466922188316985
busy waitDC[%]52.87.281.769.87.4
t[µs]433893143268895
Committer:
humlet
Date:
Fri May 10 20:38:35 2013 +0000
Revision:
13:530968937ccb
Parent:
7:04824382eafb
happyhappyjoyjoy

Who changed what in which revision?

UserRevisionLine numberNew contents of line
humlet 3:967dde37e712 1 #ifndef I2CMASTERRTOS_H
humlet 3:967dde37e712 2 #define I2CMASTERRTOS_H
humlet 3:967dde37e712 3
humlet 3:967dde37e712 4 #include "I2CDriver.h"
humlet 3:967dde37e712 5
humlet 3:967dde37e712 6 namespace mbed
humlet 3:967dde37e712 7 {
humlet 3:967dde37e712 8
humlet 3:967dde37e712 9 /// I2C master interface to the RTOS-I2CDriver.
humlet 3:967dde37e712 10 /// The interface is compatible to the original mbed I2C class.
humlet 5:8a418c89e515 11 /// Provides an additonal "read from register"-function.
humlet 3:967dde37e712 12 class I2CMasterRtos
humlet 3:967dde37e712 13 {
humlet 3:967dde37e712 14 I2CDriver m_drv;
humlet 3:967dde37e712 15
humlet 3:967dde37e712 16 public:
humlet 3:967dde37e712 17 /** Create an I2C Master interface, connected to the specified pins
humlet 3:967dde37e712 18 *
humlet 3:967dde37e712 19 * @param sda I2C data line pin
humlet 3:967dde37e712 20 * @param scl I2C clock line pin
humlet 5:8a418c89e515 21 *
humlet 5:8a418c89e515 22 * @note Has to be created in a thread context, i.e. within the main or some other function. A global delaration does not work
humlet 3:967dde37e712 23 */
humlet 3:967dde37e712 24 I2CMasterRtos(PinName sda, PinName scl, int freq=100000):m_drv(sda,scl,freq) {}
humlet 3:967dde37e712 25
humlet 3:967dde37e712 26 /** Set the frequency of the I2C interface
humlet 3:967dde37e712 27 *
humlet 3:967dde37e712 28 * @param hz The bus frequency in hertz
humlet 3:967dde37e712 29 */
humlet 3:967dde37e712 30 void frequency(int hz) {
humlet 3:967dde37e712 31 m_drv.frequency(hz);
humlet 3:967dde37e712 32 }
humlet 3:967dde37e712 33
humlet 3:967dde37e712 34 /** Read from an I2C slave
humlet 3:967dde37e712 35 *
humlet 3:967dde37e712 36 * Performs a complete read transaction. The bottom bit of
humlet 3:967dde37e712 37 * the address is forced to 1 to indicate a read.
humlet 3:967dde37e712 38 *
humlet 3:967dde37e712 39 * @param address 8-bit I2C slave address [ addr | 1 ]
humlet 3:967dde37e712 40 * @param data Pointer to the byte-array to read data in to
humlet 3:967dde37e712 41 * @param length Number of bytes to read
humlet 3:967dde37e712 42 * @param repeated Repeated start, true - don't send stop at end
humlet 3:967dde37e712 43 *
humlet 3:967dde37e712 44 * @returns
humlet 3:967dde37e712 45 * 0 on success (ack),
humlet 3:967dde37e712 46 * non-0 on failure (nack)
humlet 3:967dde37e712 47 */
humlet 3:967dde37e712 48 int read(int address, char *data, int length, bool repeated = false) {
humlet 3:967dde37e712 49 return m_drv.readMaster( address, data, length, repeated);
humlet 3:967dde37e712 50 }
humlet 3:967dde37e712 51
humlet 3:967dde37e712 52 /** Read from a given I2C slave register
humlet 3:967dde37e712 53 *
humlet 3:967dde37e712 54 * Performs a complete write-register-read-data-transaction. The bottom bit of
humlet 3:967dde37e712 55 * the address is forced to 1 to indicate a read.
humlet 3:967dde37e712 56 *
humlet 3:967dde37e712 57 * @param address 8-bit I2C slave address [ addr | 1 ]
humlet 3:967dde37e712 58 * @param _register 8-bit regster address
humlet 3:967dde37e712 59 * @param data Pointer to the byte-array to read data in to
humlet 3:967dde37e712 60 * @param length Number of bytes to read
humlet 3:967dde37e712 61 * @param repeated Repeated start, true - don't send stop at end
humlet 3:967dde37e712 62 *
humlet 3:967dde37e712 63 * @returns
humlet 3:967dde37e712 64 * 0 on success (ack),
humlet 3:967dde37e712 65 * non-0 on failure (nack)
humlet 3:967dde37e712 66 */
humlet 7:04824382eafb 67 int read(int address, uint8_t _register, char* data, int length, bool repeated = false) {
humlet 3:967dde37e712 68 return m_drv.readMaster( address, _register, data, length, repeated);
humlet 3:967dde37e712 69 }
humlet 3:967dde37e712 70
humlet 3:967dde37e712 71 /** Read a single byte from the I2C bus
humlet 3:967dde37e712 72 *
humlet 3:967dde37e712 73 * @param ack indicates if the byte is to be acknowledged (1 = acknowledge)
humlet 3:967dde37e712 74 *
humlet 3:967dde37e712 75 * @returns
humlet 3:967dde37e712 76 * the byte read
humlet 3:967dde37e712 77 */
humlet 3:967dde37e712 78 int read(int ack) {
humlet 3:967dde37e712 79 return m_drv.readMaster(ack);
humlet 3:967dde37e712 80 }
humlet 3:967dde37e712 81
humlet 3:967dde37e712 82 /** Write to an I2C slave
humlet 3:967dde37e712 83 *
humlet 3:967dde37e712 84 * Performs a complete write transaction. The bottom bit of
humlet 3:967dde37e712 85 * the address is forced to 0 to indicate a write.
humlet 3:967dde37e712 86 *
humlet 3:967dde37e712 87 * @param address 8-bit I2C slave address [ addr | 0 ]
humlet 3:967dde37e712 88 * @param data Pointer to the byte-array data to send
humlet 3:967dde37e712 89 * @param length Number of bytes to send
humlet 3:967dde37e712 90 * @param repeated Repeated start, true - do not send stop at end
humlet 3:967dde37e712 91 *
humlet 3:967dde37e712 92 * @returns
humlet 3:967dde37e712 93 * 0 on success (ack),
humlet 3:967dde37e712 94 * non-0 on failure (nack)
humlet 3:967dde37e712 95 */
humlet 3:967dde37e712 96 int write(int address, const char *data, int length, bool repeated = false) {
humlet 3:967dde37e712 97 return m_drv.writeMaster(address, data, length, repeated);
humlet 3:967dde37e712 98 }
humlet 3:967dde37e712 99
humlet 3:967dde37e712 100 /** Write single byte out on the I2C bus
humlet 3:967dde37e712 101 *
humlet 3:967dde37e712 102 * @param data data to write out on bus
humlet 3:967dde37e712 103 *
humlet 3:967dde37e712 104 * @returns
humlet 3:967dde37e712 105 * '1' if an ACK was received,
humlet 3:967dde37e712 106 * '0' otherwise
humlet 3:967dde37e712 107 */
humlet 3:967dde37e712 108 int write(int data) {
humlet 3:967dde37e712 109 return m_drv.writeMaster(data);
humlet 3:967dde37e712 110 }
humlet 3:967dde37e712 111
humlet 3:967dde37e712 112 /** Creates a start condition on the I2C bus
humlet 3:967dde37e712 113 */
humlet 3:967dde37e712 114
humlet 13:530968937ccb 115 void start(void) {
humlet 3:967dde37e712 116 m_drv.startMaster();
humlet 3:967dde37e712 117 }
humlet 3:967dde37e712 118
humlet 13:530968937ccb 119 /// Creates a stop condition on the I2C bus
humlet 13:530968937ccb 120 /// If unsccessful because someone on the bus holds the scl line down it returns "false" after 23µs
humlet 13:530968937ccb 121 /// In normal operation the stop shouldn't take longer than 12µs @ 100kHz and 3-4µs @ 400kHz.
humlet 13:530968937ccb 122 bool stop(void) {
humlet 13:530968937ccb 123 return m_drv.stopMaster();
humlet 13:530968937ccb 124 }
humlet 13:530968937ccb 125
humlet 13:530968937ccb 126 /// Wait until the interface becomes available.
humlet 13:530968937ccb 127 ///
humlet 13:530968937ccb 128 /// Useful if you want to run a sequence of command without interrution by another thread.
humlet 13:530968937ccb 129 /// There's no need to call this function for running single request, because all driver functions
humlet 13:530968937ccb 130 /// will lock the device for exclusive access automatically.
humlet 13:530968937ccb 131 void lock() {
humlet 13:530968937ccb 132 m_drv.lock();
humlet 13:530968937ccb 133 }
humlet 13:530968937ccb 134
humlet 13:530968937ccb 135 /// Unlock the interface that has previously been locked by the same thread.
humlet 13:530968937ccb 136 void unlock() {
humlet 13:530968937ccb 137 m_drv.unlock();
humlet 3:967dde37e712 138 }
humlet 3:967dde37e712 139
humlet 3:967dde37e712 140 };
humlet 3:967dde37e712 141 }
humlet 3:967dde37e712 142
humlet 3:967dde37e712 143
humlet 3:967dde37e712 144 #endif