X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/6122ba93cf957bd495fdd1838bac16fb24896a17..d11ed10c5314c44dc01c06954d1d73d4894cbff8:/LUFA/Drivers/USB/Class/Device/CDC.h

diff --git a/LUFA/Drivers/USB/Class/Device/CDC.h b/LUFA/Drivers/USB/Class/Device/CDC.h
index 30d3526b3..d248868cd 100644
--- a/LUFA/Drivers/USB/Class/Device/CDC.h
+++ b/LUFA/Drivers/USB/Class/Device/CDC.h
@@ -38,6 +38,23 @@
  *  \section Module Description
  *  Device Mode USB Class driver framework interface, for the CDC USB Class driver.
  *
+ *  \note There are several major drawbacks to the CDC-ACM standard USB class, however
+ *        it is very standardized and thus usually available as a built-in driver on
+ *        most platforms, and so is a better choice than a proprietary serial class.
+ *        
+ *        One major issue with CDC-ACM is that it requires two Interface descriptors,
+ *        which will upset most hosts when part of a multi-function "Composite" USB
+ *        device, as each interface will be loaded into a separate driver instance. To
+ *        conbat this, you should use the "Interface Association Descriptor" addendum to
+ *        the USB standard which is available on most OSes when creating Composite devices.
+ *
+ *        Another major oversight is that there is no mechanism for the host to notify the
+ *        device that there is a data sink on the host side ready to accept data. This
+ *        means that the device may try to send data while the host isn't listening, causing
+ *        lengthy blocking timeouts in the transmission routines. To combat this, it is
+ *        recommended that the virtual serial line DTR (Data Terminal Ready) be used where
+ *        possible to determine if a host application is ready for data.
+ *
  *  @{
  */
  
@@ -155,7 +172,9 @@
 			void EVENT_CDC_Device_ControLineStateChanged(USB_ClassInfo_CDC_Device_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 
 			/** Sends a given string to the attached USB host, if connected. If a host is not connected when the function is called, the
-			 *  string is discarded.
+			 *  string is discarded. Bytes will be queued for transmission to the host until either the endpoint bank becomes full, or the
+			 *  \ref CDC_Device_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be 
+			 *  packed into a single endpoint packet, increasing data throughput.
 			 *
 			 *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
 			 *        the call will fail.
@@ -170,7 +189,9 @@
 			                              ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
 			
 			/** Sends a given byte to the attached USB host, if connected. If a host is not connected when the function is called, the
-			 *  byte is discarded.
+			 *  byte is discarded. Bytes will be queued for transmission to the host until either the endpoint bank becomes full, or the
+			 *  \ref CDC_Device_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be 
+			 *  packed into a single endpoint packet, increasing data throughput.
 			 *
 			 *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or
 			 *        the call will fail.