add a bit of document for cdc device API. also improve cdc write flush when complete.

changelog.md

@@ -14,6 +14,10 @@
 
 - All default IRQ Handler is renamed to `dcd_int_handler()`
 
+### Others
+
+- tud_cdc_n_write_flush() return number of bytes forced to transfer instead of bool 
+
 ## 0.6.0 - 2019.03.30
 
 Added **CONTRIBUTORS.md** to give proper credit for contributors to the stack. Special thanks to [Nathan Conrad](https://github.com/pigrew), [Peter Lawrence](https://github.com/majbthrd) and [William D. Jones](https://github.com/cr1901) and others for spending their precious time to add lots of features and ports for this release.

src/class/cdc/cdc_device.c

@@ -157,10 +157,12 @@ uint32_t tud_cdc_n_write(uint8_t itf, void const* buffer, uint32_t bufsize)
   return ret;
 }
 
-bool tud_cdc_n_write_flush (uint8_t itf)
+uint32_t tud_cdc_n_write_flush (uint8_t itf)
 {
   cdcd_interface_t* p_cdc = &_cdcd_itf[itf];
-  TU_VERIFY( !usbd_edpt_busy(TUD_OPT_RHPORT, p_cdc->ep_in) ); // skip if previous transfer not complete
+
+  // skip if previous transfer not complete yet
+  TU_VERIFY( !usbd_edpt_busy(TUD_OPT_RHPORT, p_cdc->ep_in), 0 );
 
   uint16_t count = tu_fifo_read_n(&_cdcd_itf[itf].tx_ff, p_cdc->epin_buf, TU_ARRAY_SIZE(p_cdc->epin_buf));
   if ( count )
@@ -169,7 +171,7 @@ bool tud_cdc_n_write_flush (uint8_t itf)
     TU_ASSERT( usbd_edpt_xfer(TUD_OPT_RHPORT, p_cdc->ep_in, p_cdc->epin_buf, count) );
   }
 
-  return true;
+  return count;
 }
 
 uint32_t tud_cdc_n_write_available (uint8_t itf)
@@ -376,16 +378,16 @@ bool cdcd_xfer_cb(uint8_t rhport, uint8_t ep_addr, xfer_result_t result, uint32_
   (void) rhport;
   (void) result;
 
-  uint8_t itf = 0;
-  cdcd_interface_t* p_cdc = _cdcd_itf;
+  uint8_t itf;
+  cdcd_interface_t* p_cdc;
 
   // Identify which interface to use
-  for ( ; ; itf++, p_cdc++)
+  for (itf = 0; itf < CFG_TUD_CDC; itf++)
   {
-    if (itf >= TU_ARRAY_SIZE(_cdcd_itf)) return false;
-
+    p_cdc = &_cdcd_itf[itf];
     if ( ( ep_addr == p_cdc->ep_out ) || ( ep_addr == p_cdc->ep_in ) ) break;
   }
+  TU_ASSERT(itf < CFG_TUD_CDC);
 
   // Received new data
   if ( ep_addr == p_cdc->ep_out )
@@ -408,12 +410,20 @@ bool cdcd_xfer_cb(uint8_t rhport, uint8_t ep_addr, xfer_result_t result, uint32_
     _prep_out_transaction(itf);
   }
 
-  // Data sent to host, we could continue to fetch data tx fifo to send.
-  // But it will cause incorrect baudrate set in line coding.
-  // Though maybe the baudrate is not really important !!!
+  // Data sent to host, we continue to fetch from tx fifo to send.
+  // Note: This will cause incorrect baudrate set in line coding.
+  //       Though maybe the baudrate is not really important !!!
   if ( ep_addr == p_cdc->ep_in )
   {
-    if ( xferred_bytes && (0 == (xferred_bytes % CFG_TUD_CDC_EPSIZE)) && (0 == p_cdc->tx_ff.count) ) usbd_edpt_xfer(TUD_OPT_RHPORT, p_cdc->ep_in, NULL, 0);
+    if ( 0 == tud_cdc_n_write_flush(itf) )
+    {
+      // There is no data left, a ZLP should be sent if
+      // xferred_bytes is multiple of EP size and not zero
+      if ( xferred_bytes && (0 == (xferred_bytes % CFG_TUD_CDC_EPSIZE)) )
+      {
+        usbd_edpt_xfer(TUD_OPT_RHPORT, p_cdc->ep_in, NULL, 0);
+      }
+    }
   }
 
   // nothing to do with notif endpoint for now

src/class/cdc/cdc_device.h

@@ -48,28 +48,58 @@
  *  @{ */
 
 //--------------------------------------------------------------------+
-// Application API (Multiple Interfaces)
+// Application API (Multiple Ports)
 // CFG_TUD_CDC > 1
 //--------------------------------------------------------------------+
+
+
+// Check if terminal is connected to this port
 bool     tud_cdc_n_connected       (uint8_t itf);
+
+// Get current line state. Bit 0:  DTR (Data Terminal Ready), Bit 1: RTS (Request to Send)
 uint8_t  tud_cdc_n_get_line_state  (uint8_t itf);
+
+// Get current line encoding: bit rate, stop bits parity etc ..
 void     tud_cdc_n_get_line_coding (uint8_t itf, cdc_line_coding_t* coding);
+
+// Set special character that will trigger tud_cdc_rx_wanted_cb() callback on receiving
 void     tud_cdc_n_set_wanted_char (uint8_t itf, char wanted);
 
+// Get the number of bytes available for reading
 uint32_t tud_cdc_n_available       (uint8_t itf);
+
+// Read received bytes
 uint32_t tud_cdc_n_read            (uint8_t itf, void* buffer, uint32_t bufsize);
+
+// Read a byte, return -1 if there is none
+static inline
+int32_t  tud_cdc_n_read_char       (uint8_t itf);
+
+// Clear the received FIFO
 void     tud_cdc_n_read_flush      (uint8_t itf);
+
+// Get a byte from FIFO at the specified position without revmoing it
 bool     tud_cdc_n_peek            (uint8_t itf, int pos, uint8_t* u8);
-static inline int32_t tud_cdc_n_read_char (uint8_t itf);
 
+// Write bytes to TX FIFO, data may remain in the FIFO for a while
 uint32_t tud_cdc_n_write           (uint8_t itf, void const* buffer, uint32_t bufsize);
-bool     tud_cdc_n_write_flush     (uint8_t itf);
+
+// Write a byte
+static inline
+uint32_t tud_cdc_n_write_char      (uint8_t itf, char ch);
+
+// Write a nul-terminated string
+static inline
+uint32_t tud_cdc_n_write_str       (uint8_t itf, char const* str);
+
+// Force sending data if possible, return number of forced bytes
+uint32_t tud_cdc_n_write_flush     (uint8_t itf);
+
+// Return number of characters available for writing
 uint32_t tud_cdc_n_write_available (uint8_t itf);
-static inline uint32_t tud_cdc_n_write_char (uint8_t itf, char ch);
-static inline uint32_t tud_cdc_n_write_str  (uint8_t itf, char const* str);
 
 //--------------------------------------------------------------------+
-// Application API (Interface0)
+// Application API (Single Port)
 //--------------------------------------------------------------------+
 static inline bool     tud_cdc_connected       (void);
 static inline uint8_t  tud_cdc_get_line_state  (void);
@@ -85,7 +115,7 @@ static inline bool     tud_cdc_peek            (int pos, uint8_t* u8);
 static inline uint32_t tud_cdc_write_char      (char ch);
 static inline uint32_t tud_cdc_write           (void const* buffer, uint32_t bufsize);
 static inline uint32_t tud_cdc_write_str       (char const* str);
-static inline bool     tud_cdc_write_flush     (void);
+static inline uint32_t tud_cdc_write_flush     (void);
 static inline uint32_t tud_cdc_write_available (void);
 
 //--------------------------------------------------------------------+
@@ -183,7 +213,7 @@ static inline uint32_t tud_cdc_write_str (char const* str)
   return tud_cdc_n_write_str(0, str);
 }
 
-static inline bool tud_cdc_write_flush (void)
+static inline uint32_t tud_cdc_write_flush (void)
 {
   return tud_cdc_n_write_flush(0);
 }