update fifo per PanRe review

Author: hathach

src/common/tusb_fifo.c

@@ -352,9 +352,10 @@ static uint16_t backward_pointer(tu_fifo_t* f, uint16_t p, uint16_t offset)
   return new_p;
 }
 
-// index to pointer, simply an modulo with minus
+// index to pointer, simply an modulo with minus.
 static inline uint16_t idx2ptr(uint16_t idx, uint16_t depth)
 {
+  // Only run at most 3 times since index is limit in the range of [0..2*depth)
   while ( idx >= depth ) idx -= depth;
   return idx;
 }
@@ -509,6 +510,7 @@ static uint16_t _tu_fifo_write_n(tu_fifo_t* f, const void * data, uint16_t n, tu
     else if (overflowable_count + n >= 2*f->depth)
     {
       // Double overflowed
+      // Index is bigger than the allowed range [0,2*depth)
       // re-position write index to have a full fifo after pushed
       wr_idx = advance_pointer(f, rd_idx, f->depth - n);
 
@@ -518,7 +520,9 @@ static uint16_t _tu_fifo_write_n(tu_fifo_t* f, const void * data, uint16_t n, tu
       // currently deliberately not implemented --> result in incorrect data read back
     }else
     {
-      // normal + single overflowed: just increase write index
+      // normal + single overflowed:
+      // Index is in the range of [0,2*depth) and thus detect and recoverable. Recovering is handled in read()
+      // Therefore we just increase write index
       // we will correct (re-position) read index later on in fifo_read() function
     }
   }

src/common/tusb_fifo.h

@@ -54,7 +54,7 @@ extern "C" {
 
 /* Write/Read index is always in the range of:
  *      0 .. 2*depth-1
- * The extra window allow us to determine the fifo state of empty or full with only 2 indexes
+ * The extra window allow us to determine the fifo state of empty or full with only 2 indices
  * Following are examples with depth = 3
  *
  * - empty: W = R
@@ -86,15 +86,16 @@ extern "C" {
  *      -------------------------
  *      | R | 1 | 2 | 3 | W | 5 |
  *
- *  - Double Overflowed: write(3), write(1), write(2)
+ *  - Double Overflowed i.e index is out of allowed range [0,2*depth) e.g:
+ *      write(3), write(1), write(2)
  *    Continue to write after overflowed to 2nd overflowed.
  *    We must prevent 2nd overflowed since it will cause incorrect computed of count, in above example
  *    if not handled the fifo will be empty instead of continue-to-be full. Since we must not modify
  *    read index in write() function, which cause race condition. We will re-position write index so that
  *    after data is written it is a full fifo i.e W = depth - R
  *
  *      re-position W = 1 before write(2)
- *      Note: we should also move data from mem[4] to read index as well, but deliberately skipped here
+ *      Note: we should also move data from mem[3] to read index as well, but deliberately skipped here
  *      since it is an expensive operation !!!
  *                  |
  *      -------------------------