Diff: I2CDriver.h

Revision:

5:8a418c89e515

Parent:

3:967dde37e712

Child:

6:5b98c902a659

--- a/I2CDriver.h	Sat Apr 20 09:52:09 2013 +0000
+++ b/I2CDriver.h	Sat Apr 20 11:56:35 2013 +0000
@@ -10,11 +10,12 @@
 
 namespace mbed
 {
-/// class i2c driver
+/// I2C driver based on mbed RTOS and I2C-C-API.
+/// Supports Master and Slave mode
 class I2CDriver
 {
 public:
-
+    /// Status returned by the receiveSlave() function
     enum SlaveRxStatus {
         NoData         = 0,
         ReadAddressed  = 1,
@@ -22,10 +23,12 @@
         WriteAddressed = 3
     };
 
-    /** Create an I2C Master interface, connected to the specified pins
+    /** Create an I2C Master interface, connected to the specified pins.
      *
      *  @param sda I2C data line pin
      *  @param scl I2C clock line pin
+     *
+     *  @note Has to be created in a thread context, i.e. within the main or some other function. A global delaration does not work
      */
     I2CDriver(PinName sda, PinName scl, int hz=100000, int slaveAdr=0);
 
@@ -194,7 +197,7 @@
     }
 
 protected:
-
+    // commands sent from user to drive thread 
     enum Command {
         START,
         STOP,
@@ -207,7 +210,8 @@
         WRITE_BYTE,
         RECEIVE
     };
-
+    
+    // data transfer struct for communication between user and driver thread
     struct Transfer {
         Command cmd;
         int ret;
@@ -224,27 +228,36 @@
         osThreadId caller;
     };
 
+    // structure that holds handles/locks for accessing the I2C channels 
     struct Channel {
-        volatile osThreadId driver; // evillive: do we really need that volatile
+        osThreadId driver; 
         rtos::Mutex  mutex;
         volatile Transfer transfer;
     };
-
+    
+    // current frequency setting
     int m_freq;
+    // current slave address setting
     int m_slaveAdr;
-
+    
+    // the pin names fo the i2c channels
     static const PinName c_sdas[2];
     static const PinName c_scls[2];
 
+    // static storage for the I2C channel access objects  
     static Channel* s_channels[2];
-
+    
+    // i2c channel object of this driver interface, in fact just pointer
+    /// to one of the entries in s_channels
     Channel* m_channel;
-
+    
+    // ISRs  
     static void channel_0_ISR();
     static void channel_1_ISR();
-
+    
+    // the driver thread function
     static void threadFun(void const *args);
-
+    
     int sendNwait();
 };
 }