Merged Thomas' comments.

firmware/message_queue.c

@@ -2,7 +2,7 @@
  * \file message_queue.c
  * \brief A message queue used to exchange messages between two concurrent threads.
  * \author Thomas Stegemann
- * \version $Id: message_queue.c,v 1.1 2006/09/26 18:18:27 rschaten Exp $
+ * \version $Id: message_queue.c,v 1.2 2006/09/29 22:30:03 rschaten Exp $
  *
  * License: See documentation.
  */
@@ -13,22 +13,23 @@
 
 /** Structure of the global data of the queue */
 typedef struct S_messageQueue_GlobalData {
-    messageQueue_QueuedMessage queue[messageQueue_Size]; /**< the queue itself */
+    messageQueue_QueuedMessage queue[messageQueue_Size]; /**< the data elements of the queue */
     messageQueue_SizeType begin; /**< the current start of the queue */
-    messageQueue_SizeType end; /**< the current end of the queue */
+    messageQueue_SizeType end; /**< the current end of the queue, behind the last element */
 } messageQueue_GlobalData;
 
 /** Global data of the queue */
 static volatile messageQueue_GlobalData m_data;
 
 /**
- * Get the next entry fron the queue.
+ * increments an messageQueue index
- * \param value Number of the current entry.
+ * \param value position within the messageQueue
- * \return 0 if the value is larger than the queue, otherwise the next entry.
+ * \return the following position within the messageQueue
  */
 static inline messageQueue_SizeType messageQueue_next(messageQueue_SizeType value) {
     value++;
     if(value >= messageQueue_Size) {
+        /* messageQueue is used circular */
         value= 0;
     }
     return value;
@@ -57,8 +58,7 @@ Boolean messageQueue_isEmpty(void) {
 }
 
 /**
- * Test if the queue is full. If it is full, new entries will overwrite the
+ * Test if the queue is full.
- * first entries.
  * \return True if it is full, otherwise false.
  */
 Boolean messageQueue_isFull(void) {

firmware/pwm_channels.c

@@ -2,7 +2,7 @@
  * \file pwm_channels.c
  * \brief Manages the values of the displayed channels.
  * \author Thomas Stegemann
- * \version $Id: pwm_channels.c,v 1.1 2006/09/26 18:18:27 rschaten Exp $
+ * \version $Id: pwm_channels.c,v 1.2 2006/09/29 22:30:03 rschaten Exp $
  *
  * License: See documentation.
  */
@@ -41,9 +41,10 @@ void pwm_Channels_cleanup(void) {
  * \return Current message.
  */
 static pwm_Channels_Message pwm_Channels_Message_get(pwm_Channels_ChannelBrightness channels[CHANNELS]) {
-    int j;
+    int j; /* index of the current channel */
-    pwm_Channels_StepCounter i= 0;
+    pwm_Channels_StepCounter i= 0; /* index of the current step */
     pwm_Channels_Message message;
+    /* first step: switch on all channels at cycle 0 */
     message.step[i].field = 0;
     for (j = 0; j < CHANNELS; j++) {
         message.step[i].field |= channels[j].field;
@@ -52,14 +53,22 @@ static pwm_Channels_Message pwm_Channels_Message_get(pwm_Channels_ChannelBrightn
 
     for (j = 0; j < CHANNELS; j++) {
         if(channels[j].cycle == message.step[i].cycle) {
+            /* if cycle for this channel is reached
+               switch off channel in current step */
             message.step[i].field&= ~channels[j].field;
         } else {
+            /* need another step for this channel:
+               set end of the current step
+               use copy of current step for next step
+               and switch off this channel
+            */
             message.step[i].cycle= channels[j].cycle;
             i++;
             message.step[i]= message.step[i-1];
             message.step[i].field&= ~channels[j].field;
         }
     }
+    /* last step ends at pwm_Timer_Cycles_Max */
     message.step[i].cycle= pwm_Timer_Cycles_Max;
     return message;
 }
@@ -95,7 +104,7 @@ void pwm_Channels_show(pwm_Channels channels) {
     pwm_Channels_Message message;
     pwm_Channels_ChannelBrightness channel_brightness[CHANNELS];
     for (i = 0; i < CHANNELS; i++) {
-        channel_brightness[i].field = 1 << i; // 1 << i equals 2^i
+        channel_brightness[i].field = 1 << i; // 1 << i equals 2^i: the channel i, uses the bit i
         channel_brightness[i].cycle = pwm_Channels_BrightnessToCycles(channels.channel[i]);
     }
 

firmware/pwm_timer.c

@@ -2,7 +2,7 @@
  * \file pwm_timer.c
  * \brief Controls the actual PWM-output.
  * \author Thomas Stegemann
- * \version $Id: pwm_timer.c,v 1.1 2006/09/26 18:18:27 rschaten Exp $
+ * \version $Id: pwm_timer.c,v 1.2 2006/09/29 22:30:03 rschaten Exp $
  *
  * License: See documentation.
  */
@@ -106,7 +106,14 @@ SIGNAL(SIG_OUTPUT_COMPARE1A) {
     sei();
     do {
         if((m_data.step == pwm_Channels_StepCounter_Max) || (m_data.currentCycle == pwm_Timer_Cycles_Max)) {
+            /* end of current cycle reached*/ 
             if(m_data.readDone) {
+                /*
+                  message received
+                  start a new cycle with the new values
+                  swap active message and message for reading
+                  message for reading is free for further messages from queue
+                */
                 pwm_Channels_Message* pSwap= m_data.pActive;
                 m_data.pActive= m_data.pRead;
                 m_data.pRead=   pSwap;
@@ -115,14 +122,14 @@ SIGNAL(SIG_OUTPUT_COMPARE1A) {
                 m_data.step= 0;
                 sleep= 0;
             } else {
-                /* error could not read a new channels message in a whole cycle */
+                /* could not read a new channels message in a whole cycle */
-                /* wait a complete cycle for the next message */
+                /* restart the cycle with the old values */
-                //sleep= pwm_Timer_Cycles_Max;
                 m_data.currentCycle= 0;
                 m_data.step= 0;
                 sleep= 0;
             }
         } else {
+            /* process current step, go to next step */
             pwm_Timer_switchLed(m_data.pActive->step[m_data.step].field);
             sleep= m_data.pActive->step[m_data.step].cycle - m_data.currentCycle;
             m_data.currentCycle= m_data.pActive->step[m_data.step].cycle;
@@ -131,6 +138,9 @@ SIGNAL(SIG_OUTPUT_COMPARE1A) {
     } while(pwm_Timer_sleep(sleep));
 
     if(!m_data.readDone && (sleep > pwm_Timer_Cycles_ReadMin)) {
+        /*
+          free space for reading and enough time to read: try to read
+        */
         if(messageQueue_read(m_data.pRead)) {
             m_data.readDone= True;
         }