Helmut Schmücker / mbed-RtosI2cDriver

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

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.

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

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.

diff -r 04824382eafb -r 5be85bd4c5ba I2CDriver.cpp
--- a/I2CDriver.cpp	Sun Apr 28 15:08:04 2013 +0000
+++ b/I2CDriver.cpp	Tue Apr 30 19:12:57 2013 +0000
@@ -2,12 +2,15 @@
 #include "i2c_api.h"
 #include "error.h"
 
-#include "DigitalOut.h"
-
 using namespace mbed;
 using namespace rtos;
 
-DigitalOut osci(p12);
+extern "C"{
+osSemaphoreId i2cIsrDrvSem_1;
+osSemaphoreDef(i2cIsrDrvSem_1); 
+osSemaphoreId i2cIsrDrvSem_2;
+osSemaphoreDef(i2cIsrDrvSem_2); 
+}
 
 #define DRV_USR_SIG (1<<6)
 
@@ -19,23 +22,19 @@
 #if defined(TARGET_LPC1768)
 void I2CDriver::channel_0_ISR()
 {
-    osci.write(1);
-    osSignalSet( s_channels[0]->driver, I2C_ISR_DRV_SIG);
+    osSemaphoreRelease(i2cIsrDrvSem_1);
     NVIC_DisableIRQ(I2C1_IRQn);
-    osci.write(0);
 }
 #endif
 
 void I2CDriver::channel_1_ISR()
 {
-    osci.write(1);
-    osSignalSet( s_channels[1]->driver, I2C_ISR_DRV_SIG);
+    osSemaphoreRelease(i2cIsrDrvSem_2);
 #if defined(TARGET_LPC1768) || defined(TARGET_LPC2368)
     NVIC_DisableIRQ(I2C2_IRQn);
 #elif defined(TARGET_LPC11U24)
     NVIC_DisableIRQ(I2C_IRQn);
 #endif
-    osci.write(0);
 }
 
 
@@ -50,8 +49,16 @@
         if (sda==c_sdas[1] && scl==c_scls[1]) channel=1; //I2C_2 or I2C
         else error("I2CDriver: Invalid I2C pinns selected");
 
-    if(s_channels[channel]==0)
+    if(s_channels[channel]==0){
         new Thread(threadFun,(void *)channel,osPriorityRealtime,256);
+        if(channel==0){
+            i2cIsrDrvSem_1 = osSemaphoreCreate(osSemaphore(i2cIsrDrvSem_1), 1);
+            osSemaphoreWait(i2cIsrDrvSem_1,osWaitForever);
+        }else{
+            i2cIsrDrvSem_2 = osSemaphoreCreate(osSemaphore(i2cIsrDrvSem_2), 1);
+            osSemaphoreWait(i2cIsrDrvSem_2,osWaitForever);
+        }
+    }
     m_channel = s_channels[channel];
 }
 

diff -r 04824382eafb -r 5be85bd4c5ba I2CDriverTest01.h
--- a/I2CDriverTest01.h	Sun Apr 28 15:08:04 2013 +0000
+++ b/I2CDriverTest01.h	Tue Apr 30 19:12:57 2013 +0000
@@ -2,12 +2,15 @@
 #include "rtos.h"
 #include "I2CMasterRtos.h"
 #include "stdint.h"
+#include "DigitalOut.h"
 
 volatile int g_disco=0;
 volatile int g_len=0;
 volatile int g_freq=100000;
 volatile osThreadId i2cDrvThrdID;
 
+DigitalOut osci(p12);
+
 void highPrioCallBck(void const *args)
 {
     osSignalSet(i2cDrvThrdID, 1<<5);
@@ -22,7 +25,7 @@
     // trigger on srf08 ranging
     const char regNcmd[2]= {0x00,0x51};
     i2c.write(adr, regNcmd, 2);
-
+    osDelay(200);
     while(true) {
         i2c.frequency(g_freq);
         Thread::signal_wait(1<<5,osWaitForever);
@@ -30,7 +33,7 @@
         const char reg= 0x02;
         char result[64];
         uint32_t t1=us_ticker_read();
-        i2c.read(adr, reg, result, g_len, 1);
+        i2c.read(adr, reg, result, g_len);
         uint32_t dt=us_ticker_read()-t1;
         uint16_t tm=((static_cast<uint16_t>(result[0])<<8)|static_cast<uint16_t>(result[1]));
 
@@ -53,7 +56,7 @@
 #elif defined(TARGET_LPC11U24)
     const int nTest=5;
     const int freq[nTest]=  {1e5,   1e5,    4e5,   4e5,    4e5    };
-    const int len[nTest]=   {1,     4,      1,      6,     12};
+    const int len[nTest]=   {1,     4,      1,      6,     16};
 #endif
     for(int i=0; i<nTest; ++i) {
         g_freq = freq[i];
@@ -69,6 +72,7 @@
             tAct=us_ticker_read();
             if(tAct>tLast) {
                 if(tAct==tLast+1)++tMe;
+                osci.write(tAct&1);
             }
             tLast=tAct;
         } while(tAct-tStart<dt);

diff -r 04824382eafb -r 5be85bd4c5ba I2CDriverTest04.h
--- a/I2CDriverTest04.h	Sun Apr 28 15:08:04 2013 +0000
+++ b/I2CDriverTest04.h	Tue Apr 30 19:12:57 2013 +0000
@@ -49,11 +49,11 @@
 #if defined(TARGET_LPC1768)
     const int nTest=7;
     const int freq[nTest]=  {1e5,   1e5,    1e5,   4e5,    4e5,    4e5,    4e5};
-    const int len[nTest]=   {1,     4,      6,      1,     6,     12,      29};
+    const int len[nTest]=   {1,     4,      6,      1,     6,     12,      30};
 #elif defined(TARGET_LPC11U24)
     const int nTest=5;
     const int freq[nTest]=  {1e5,   1e5,    4e5,   4e5,    4e5    };
-    const int len[nTest]=   {1,     4,      1,      6,     12};
+    const int len[nTest]=   {1,     4,      1,      6,     16};
 #endif
     for(int i=0; i<nTest; ++i) {
         g_freq = freq[i];
@@ -69,6 +69,7 @@
             tAct=us_ticker_read();
             if(tAct>tLast) {
                 if(tAct==tLast+1)++tMe;
+                //tLast=tAct;
             }
             tLast=tAct;
         } while(tAct-tStart<dt);

diff -r 04824382eafb -r 5be85bd4c5ba mbed-NXP.lib
--- a/mbed-NXP.lib	Sun Apr 28 15:08:04 2013 +0000
+++ b/mbed-NXP.lib	Tue Apr 30 19:12:57 2013 +0000
@@ -1,1 +1,1 @@
-http://mbed.org/users/humlet/code/mbed-NXP/#5e7f2f37d75b
+http://mbed.org/users/humlet/code/mbed-NXP/#692b566d83bf

diff -r 04824382eafb -r 5be85bd4c5ba mbed-src.lib
--- a/mbed-src.lib	Sun Apr 28 15:08:04 2013 +0000
+++ b/mbed-src.lib	Tue Apr 30 19:12:57 2013 +0000
@@ -1,1 +1,1 @@
-http://mbed.org/users/humlet/code/mbed-src/#28ed2abfeb85
+http://mbed.org/users/humlet/code/mbed-src/#49923059ddc8