Modified version of the official mbed lib providing a RTOS enabled i2c-driver based on the official i2c-C-api.

Dependencies:   mbed-rtos mbed-src

mbed-RtosI2cDriver

This version is obsolete!

Please use this one:
http://mbed.org/users/humlet/code/I2cRtosDriver/

Overview

  • Based on RTOS
    • No busy wait waste of CPU cycles
    • ... but still some waste of CPU cycles by context switches
  • Spends minimal time in interrupt context
  • Supports I2C Master and Slave mode
  • Interface compatible to official I2C lib
  • Supports LPC1768 and LPC11U24.
    • Performs fine on the LPC1768, see measurements below
    • OK it works for the LPC11U24, but the performance data doesn't look that promising.
  • Reuses the official I2C implementation
    • Implemented with a few tiny but rather intrusive add-ons to the official I2C C-API
    • Updates of the official I2C lib can be easily merged into this library. Merges should be rather trivial.
    • Requires a rebuild of the mbed library (builds within a few seconds)
    • Official I2C interface not usable in parallel
  • The test and example programs works quite well and the results look promising. But this is by no means a thoroughly regression tested library. There might be some surprises.

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.
  • The declaration has to be done in thread context, i.e. in a thread function or in main. A global declaration does not work.
  • Don't use the original I2C interface classes. They don't work anymore.
  • 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 test/example implementations in I2CDriverTest01.h and I2CDriverTest02.h

Design

Basic Idea

Each time the official I2C implementation has requested the I2C controller to perform an action, it enters a central busy wait loop (i2c_wait_SI(...) in i2c_api.c) and simply polls the I2C controller until it reports that it has completed the request. By running the I2C API on a RTOS thread and replacing the busy wait loop by an RTOS signal wait, the wasted CPU time can be made available for other threads ... apart from interrupt latency and task switching overhead.

"Hack" of the I2C-API

Unfortunately this busy wait loop is located down in the i2C-C-API in the platform dependent mbed-NXP lib. Because I was too lazy to clone the whole interface and wanted to be able to easily merge updates of the official implementation to the driver, I decided to simply tweak the official implementation. The changes are rather small. Instead of entering a busy wait loop, the function i2c_wait_SI(...) now enables the I2C interrupt and waits for a RTOS semaphore. This semaphore is given by a tiny ISR. The ISR just releases the semaphore and then immediately disables the i2c interrupt. The disabling is necessary because, before the interrupt is cleared, the I2C controller HW expects new requests, which have not been applied yet. The first implementation utilized RTOS signals, but measurements revealed, that semaphores are slightly faster.
A second busy wait loop in the i2c_stop function has not been touched. It is not entered that frequently and does only take 10µs at 100kHz bus speed. At 400kHz even less time is consumed. Thus there wouldn't be any benefit if one triggers the whole interrupt task wait/switch sequence for that short period of time.
BTW: Since the last re-base to the latest version of the mbed-NXP lib (rev 10 by emilmont) the change set of i2c_api.c looks awful. The diff tool reports 900 changed lines, which is nonsense. This seems to be a bug of the diff tool. In fact there are only three additional blocks of code compared to the original revision, one at the top defining two additional local static functions, one in the i2c_wait_SI(..) function replacing the busy wait and one at the bottom behind the i2c_slave_receive(...) function.

Driver interface

The I2CDriver class is the central component of this I2C interface

  • On creation it registers the ISR and starts the high priority driver thread that runs the I2C accesses (if not already running).
  • Communication between the calling user thread and the high priority driver thread is realized by a simple static transfer struct and RTOS signals.
    • All requests are blocking.
    • I did not see much added value for implementing a more complex non-blocking buffered access using the RTOS mail or queue feature.
  • I2CDriver provides "fat" API for I2C master and slave access
    • It supports on the fly changes from master to slave mode and vice versa.
    • It ensures mutual exclusive access to the I2C HW. This is realized by a static RTOS mutex for each I2C channel that is taken by the calling thread on each call of an interface 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. In fact the user thread inherits the high priority of the driver thread during I2C access. The user thread does not do very much in the function call, it sends request to the driver thread and then waits for the driver thread to complete the request. The priority inheritance ensures that the I2C device is freed as fast as possible and prevents dead locks.
    • The interface can be locked for other threads, in order to run a sequence of commands without interruption
    • All interface functions are blocking, i.e. they return when the requested I2C transaction is completed.
    • Multiple I2CDriver instances are allowed

I2C Master/Slave Interface Adapters

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 he 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 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 should be negligible.
  • I thought of inheriting from the original interfaces in order to be able to pass the adapters as references of the original I2C/I2CSlave types to I2C access classes or functions. But I have decided against this approach because of the virtual function call overhead.

Performance

The following performance data have been measured with the small test application in I2CDriverTest01.h. In this application 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; read x byte of data). The measurements have been performed with the RTOS wait as used by this driver and with the busy wait approach used by the official mbed I2C implementation. The wait method has been selected by setting #define I2CDRVRTOS in i2c_api.c.

LPC1768
  • SRF08
    • The time for one read cycle is almost the same for both approaches
    • At full load (6byte/100kHz and 25byte@400kHz) the duty cycle of the low priority thread drops almost to zero for the busy wait approach, whereas it stays at 82% / 61% with the RTOS enabled driver.
    • The SRF08 seems to apply some clock stretching.
  • MPU6050 FIFO read:
    • At 100kz results are compatible with the SRF08
    • At 400kHz the MPU performs much better
      • Busy wait: No clock stretching at all is visible on a scope. The clock signal does not show any gaps.
      • RTOS wait: Between each byte a pause of 6µs shows up. These gaps are probably caused by the ISR->driver thread context switch. Thus the RTOS driver needs some more time to complete a read cycle.
      • When using the RTOS driver at full load (30byte/ms@400kHz), still 56% of the CPU time is available for other threads. This is more than 3.3 times the 16.8% observed with he official i2c implementation.
  • => Especially at low bus speeds and/or high data transfer loads the driver is able to free a significant amount of CPU time.
  • Comparison: MODI2C claims to achieve an efficiency resulting in a duty cycle of 75% at 400kHz. Sounds much better. OK, it is expected to be more efficient, because it operates completely in interrupt context (25%) and does not suffer from any RTOS overhead. ... and some of the 75% the user might spend for busy wait checking that the non blocking commands have completed.
LPC17681byte/ms4byte/ms6byte/ms1byte/ms6byte/ms12byte/ms25byte/ms
SRF08@ 100kHz@ 100kHz@ 100kHz@ 400kHz@ 400kHz@ 400kHz@ 400kHz
rtosDC[%]88.184.582.189.583.876.761.4
waitt[µs]438734930160334541996
busyDC[%]54.625.15.483.466.145.30.28
waitt[µs]433733930144317530984
LPC17681byte/ms4byte/ms6byte/ms1byte/ms6byte/ms12byte/ms30byte/ms
MPU6050@ 100kHz@ 100kHz@ 100kHz@ 400kHz@ 400kHz@ 400kHz@ 400kHz
rtosDC[%]81.484.682.389.683.876.956.2
waitt[µs]430712894155298475999
busyDC[%]65.628.410.384.863.159.016.8
waitt[µs]430700880131249389816
LPC11U24
  • Here the results don't look that promising
  • At a bus speed of 100kHz a slightly higher duty cycle can be achieved for the low priority thread
  • At a bus speed of 400kHz the busy wait approach shows better results
  • Keep in mind that the RTOS lib consumes a significant amount of the 11U24's small memory
LPC11U241byte/ms4byte/ms1byte/ms6byte/ms16byte/ms
MPU6050@ 100kHz@ 100kHz@ 400kHz@ 400kHz@ 400kHz
rtosDC[%]36.127.735.424.63.0
waitt[µs]525-569836-880256465-512884-935
busyDC[%]32.610.441.034.621.6
waitt[µs]475-517749-790184303542-589

A second test application (I2CDriverTest01.h) makes the mbed LPC1768 talk to itself. The two I2C channels are directly connected and master/slave mode of the two I2C interfaces are changed on the fly. The communication has been tested to work synchronously and stable at 100kHz and 400kHz.

Committer:
humlet
Date:
Tue Apr 30 19:12:57 2013 +0000
Revision:
8:5be85bd4c5ba
Parent:
7:04824382eafb
alpha2

Who changed what in which revision?

UserRevisionLine numberNew contents of line
humlet 7:04824382eafb 1 #include "mbed.h"
humlet 7:04824382eafb 2 #include "rtos.h"
humlet 7:04824382eafb 3 #include "I2CMasterRtos.h"
humlet 7:04824382eafb 4 #include "stdint.h"
humlet 7:04824382eafb 5
humlet 7:04824382eafb 6 const int dataReadySig = 1<<5;
humlet 7:04824382eafb 7 osThreadId mainThreadID = 0;
humlet 7:04824382eafb 8 char data[64];
humlet 7:04824382eafb 9 int16_t fifo[16];
humlet 7:04824382eafb 10 const int i2cAdr = 0x68<<1;
humlet 7:04824382eafb 11 int fifoAdr = 0x72;
humlet 7:04824382eafb 12
humlet 7:04824382eafb 13 //Serial pc(USBTX, USBRX);
humlet 7:04824382eafb 14
humlet 7:04824382eafb 15 void configMPU6050(I2CMasterRtos& i2c);
humlet 7:04824382eafb 16 void config(I2CMasterRtos& i2c);
humlet 7:04824382eafb 17
humlet 7:04824382eafb 18
humlet 7:04824382eafb 19 void dataReadyIsr()
humlet 7:04824382eafb 20 {
humlet 7:04824382eafb 21 osSignalSet(mainThreadID, dataReadySig);
humlet 7:04824382eafb 22 }
humlet 7:04824382eafb 23
humlet 7:04824382eafb 24 void readModWrite(I2CMasterRtos& i2c, uint8_t reg, uint8_t dta)
humlet 7:04824382eafb 25 {
humlet 7:04824382eafb 26
humlet 7:04824382eafb 27 char rd1;
humlet 7:04824382eafb 28 int rStat1 = i2c.read(i2cAdr, reg, &rd1, 1);
humlet 7:04824382eafb 29 char data[2];
humlet 7:04824382eafb 30 data[0]=(char)reg;
humlet 7:04824382eafb 31 data[1]=(char)dta;
humlet 7:04824382eafb 32 char rd2;
humlet 7:04824382eafb 33 int wStat = i2c.write(i2cAdr, data, 2);
humlet 7:04824382eafb 34 osDelay(500);
humlet 7:04824382eafb 35 int rStat2 = i2c.read(i2cAdr, reg, &rd2, 1);
humlet 7:04824382eafb 36 printf("%2d%2d%2d %2x <- %2x => %2x -> %2x \n", rStat1, wStat, rStat2, reg, dta, rd1, rd2);
humlet 7:04824382eafb 37 }
humlet 7:04824382eafb 38
humlet 7:04824382eafb 39
humlet 7:04824382eafb 40 int doit()
humlet 7:04824382eafb 41 {
humlet 7:04824382eafb 42 //pc.baud(115200);
humlet 7:04824382eafb 43 mainThreadID = osThreadGetId();
humlet 7:04824382eafb 44
humlet 7:04824382eafb 45 I2CMasterRtos i2c(p28, p27,400000);
humlet 7:04824382eafb 46 osDelay(500);
humlet 7:04824382eafb 47
humlet 7:04824382eafb 48 printf("Initialize ... \n");
humlet 7:04824382eafb 49 config(i2c);
humlet 7:04824382eafb 50
humlet 7:04824382eafb 51 printf("Action!\n");
humlet 7:04824382eafb 52
humlet 7:04824382eafb 53 InterruptIn dataReadyIrq(p8);
humlet 7:04824382eafb 54 dataReadyIrq.mode(PullNone);
humlet 7:04824382eafb 55 dataReadyIrq.rise(&dataReadyIsr);
humlet 7:04824382eafb 56
humlet 7:04824382eafb 57 /*
humlet 7:04824382eafb 58 data[0]=0x6a; // pwr 1 reg
humlet 7:04824382eafb 59 data[1]=(1<<6)|(1<<2); // fifo on
humlet 7:04824382eafb 60 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 61
humlet 7:04824382eafb 62 data[0]=0x38; // irq conf reg
humlet 7:04824382eafb 63 data[1]=1; // irq on data ready
humlet 7:04824382eafb 64 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 65 */
humlet 7:04824382eafb 66 //fifoAdr = 0x3b;
humlet 7:04824382eafb 67 char devNull;
humlet 7:04824382eafb 68 while(1) {
humlet 7:04824382eafb 69 osSignalWait(dataReadySig, 1000); // osWaitForever
humlet 7:04824382eafb 70 i2c.read(i2cAdr,fifoAdr,data,2);
humlet 7:04824382eafb 71 i2c.read(i2cAdr,fifoAdr+2,data+2,12);
humlet 7:04824382eafb 72 i2c.read(i2cAdr,0x3a,&devNull,1);
humlet 7:04824382eafb 73 for(int i=0; i<7; i++) {
humlet 7:04824382eafb 74 fifo[i] = (data[2*i]<<8) | data[2*i+1];
humlet 7:04824382eafb 75 printf("%8d",fifo[i]);
humlet 7:04824382eafb 76 }
humlet 7:04824382eafb 77 printf(" %x\n",devNull);
humlet 7:04824382eafb 78
humlet 7:04824382eafb 79 }
humlet 7:04824382eafb 80 return 0;
humlet 7:04824382eafb 81 }
humlet 7:04824382eafb 82
humlet 7:04824382eafb 83 static void config(I2CMasterRtos& i2c)
humlet 7:04824382eafb 84 {
humlet 7:04824382eafb 85 uint8_t ncfg=32;
humlet 7:04824382eafb 86 uint8_t regs[ncfg];
humlet 7:04824382eafb 87 uint8_t vals[ncfg];
humlet 7:04824382eafb 88 int cnt=0;
humlet 7:04824382eafb 89 regs[cnt]=0x6b;
humlet 7:04824382eafb 90 vals[cnt++]=(1<<7); // pwr 1 reg //: device reset
humlet 7:04824382eafb 91 regs[cnt]=0x6b;
humlet 7:04824382eafb 92 vals[cnt++]=1; // pwr 1 reg // clock from x gyro all pwr sav modes off
humlet 7:04824382eafb 93 regs[cnt]=0x19;
humlet 7:04824382eafb 94 vals[cnt++]=199; // sample rate divider reg // sapmle rate = gyro rate / (1+x)
humlet 7:04824382eafb 95 regs[cnt]=0x1a;
humlet 7:04824382eafb 96 vals[cnt++]=1;// conf reg // no ext frame sync / dig low pass set to 1 => 1kHz Sampling with ~200Hz bandwidth DLPF
humlet 7:04824382eafb 97 regs[cnt]=0x1b;
humlet 7:04824382eafb 98 vals[cnt++]=0;// gyro conf reg // no test mode and gyro range 250°/s
humlet 7:04824382eafb 99 regs[cnt]=0x1c;
humlet 7:04824382eafb 100 vals[cnt++]=0;// accl conf reg // no test mode and accl range 2g
humlet 7:04824382eafb 101 regs[cnt]=0x23;
humlet 7:04824382eafb 102 vals[cnt++]=0xf<<3;// fifo conf reg // accl + all gyro -> fifo
humlet 7:04824382eafb 103 regs[cnt]=0x37;
humlet 7:04824382eafb 104 vals[cnt++]=(0<<7)|(0<<6)|(0<<5)|(0<<4); // irq conf reg // act high | 0:pupu 1:opnDrn| pulse | clear on any read
humlet 7:04824382eafb 105 regs[cnt]=0x38;
humlet 7:04824382eafb 106 vals[cnt++]=1|(1<<4); // irq conf reg // irq on data ready
humlet 7:04824382eafb 107 regs[cnt]=0x6a;
humlet 7:04824382eafb 108 vals[cnt++]=(1<<2); // pwr 1 reg // fifo reset
humlet 7:04824382eafb 109 regs[cnt]=0x6a;
humlet 7:04824382eafb 110 vals[cnt++]=(1<<6); // pwr 1 reg // fifo on
humlet 7:04824382eafb 111
humlet 7:04824382eafb 112 /*
humlet 7:04824382eafb 113 readModWrite(i2c, regs[0], vals[0]);
humlet 7:04824382eafb 114 char reset=0xff;
humlet 7:04824382eafb 115 while(reset&(1<<7)) {
humlet 7:04824382eafb 116 osDelay(100);
humlet 7:04824382eafb 117 i2c.read(i2cAdr,0x6b,&reset,1,1);
humlet 7:04824382eafb 118 }
humlet 7:04824382eafb 119 */
humlet 7:04824382eafb 120 for(int i=0; i<cnt; i++)
humlet 7:04824382eafb 121 readModWrite(i2c, regs[i], vals[i]);
humlet 7:04824382eafb 122 }
humlet 7:04824382eafb 123
humlet 7:04824382eafb 124 static void configMPU6050(I2CMasterRtos& i2c)
humlet 7:04824382eafb 125 {
humlet 7:04824382eafb 126
humlet 7:04824382eafb 127 data[0]=0x6b; // pwr 1 reg
humlet 7:04824382eafb 128 data[1]=1<<7; // device reset
humlet 7:04824382eafb 129 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 130 char reset=0xff;
humlet 7:04824382eafb 131 while(reset&(1<<7)) {
humlet 7:04824382eafb 132 osDelay(100);
humlet 7:04824382eafb 133 i2c.read(i2cAdr,0x6b,&reset,1,1);
humlet 7:04824382eafb 134 }
humlet 7:04824382eafb 135
humlet 7:04824382eafb 136 data[0]=0x19; // sample rate divider reg
humlet 7:04824382eafb 137 data[1]=99; // sapmle rate = gyro rate / (1+x)
humlet 7:04824382eafb 138 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 139
humlet 7:04824382eafb 140 data[0]=0x1a; // conf reg
humlet 7:04824382eafb 141 data[1]=1; // no ext frame sync / dig low pass set to 1 => 1kHz Sampling with ~200Hz bandwidth DLPF
humlet 7:04824382eafb 142 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 143
humlet 7:04824382eafb 144 data[0]=0x1b; // gyro conf reg
humlet 7:04824382eafb 145 data[1]=0; // no test mode and gyro range 250°/s
humlet 7:04824382eafb 146 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 147
humlet 7:04824382eafb 148 data[0]=0x1c; // accl conf reg
humlet 7:04824382eafb 149 data[1]=0; // no test mode and accl range 2g
humlet 7:04824382eafb 150 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 151
humlet 7:04824382eafb 152 data[0]=0x23; // fifo conf reg
humlet 7:04824382eafb 153 data[1]=0xf<<3; // accl + all gyro -> fifo
humlet 7:04824382eafb 154 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 155
humlet 7:04824382eafb 156 data[0]=0x37; // irq conf reg
humlet 7:04824382eafb 157 data[1]=(1<<7)|(0<<6)|(0<<5)|(1<<4); // act high | pupu | pulse | clear on any read
humlet 7:04824382eafb 158 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 159
humlet 7:04824382eafb 160 /*
humlet 7:04824382eafb 161 data[0]=0x38; // irq conf reg
humlet 7:04824382eafb 162 data[1]=1; // irq on data ready
humlet 7:04824382eafb 163 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 164
humlet 7:04824382eafb 165 data[0]=0x6a; // pwr 1 reg
humlet 7:04824382eafb 166 data[1]=(1<<6); // fifo on
humlet 7:04824382eafb 167 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 168 */
humlet 7:04824382eafb 169 data[0]=0x6b; // pwr 1 reg
humlet 7:04824382eafb 170 data[1]=1; // clock from x gyro all pwr sav modes off
humlet 7:04824382eafb 171 i2c.write(i2cAdr,data,2,1);
humlet 7:04824382eafb 172 }
humlet 7:04824382eafb 173