Add FatFS library to the Webserver project, extend the HTTP server so that it now...

[pub/USBasp.git] / 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 4982b09..d248868 100644 (file)
--- a/LUFA/Drivers/USB/Class/Device/CDC.h
+++ b/LUFA/Drivers/USB/Class/Device/CDC.h
@@ -1,13 +1,13 @@
 /*\r
              LUFA Library\r
 /*\r
              LUFA Library\r

-     Copyright (C) Dean Camera, 2009.\r
+     Copyright (C) Dean Camera, 2010.\r

               \r
   dean [at] fourwalledcubicle [dot] com\r
       www.fourwalledcubicle.com\r
 */\r
 \r
 /*\r
               \r
   dean [at] fourwalledcubicle [dot] com\r
       www.fourwalledcubicle.com\r
 */\r
 \r
 /*\r

-  Copyright 2009  Dean Camera (dean [at] fourwalledcubicle [dot] com)\r
+  Copyright 2010  Dean Camera (dean [at] fourwalledcubicle [dot] com)\r

 \r
   Permission to use, copy, modify, distribute, and sell this \r
   software and its documentation for any purpose is hereby granted\r
 \r
   Permission to use, copy, modify, distribute, and sell this \r
   software and its documentation for any purpose is hereby granted\r


@@ -38,6 +38,23 @@
  *  \section Module Description\r
  *  Device Mode USB Class driver framework interface, for the CDC USB Class driver.\r
  *\r
  *  \section Module Description\r
  *  Device Mode USB Class driver framework interface, for the CDC USB Class driver.\r
  *\r

+ *  \note There are several major drawbacks to the CDC-ACM standard USB class, however\r
+ *        it is very standardized and thus usually available as a built-in driver on\r
+ *        most platforms, and so is a better choice than a proprietary serial class.\r
+ *        \r
+ *        One major issue with CDC-ACM is that it requires two Interface descriptors,\r
+ *        which will upset most hosts when part of a multi-function "Composite" USB\r
+ *        device, as each interface will be loaded into a separate driver instance. To\r
+ *        conbat this, you should use the "Interface Association Descriptor" addendum to\r
+ *        the USB standard which is available on most OSes when creating Composite devices.\r
+ *\r
+ *        Another major oversight is that there is no mechanism for the host to notify the\r
+ *        device that there is a data sink on the host side ready to accept data. This\r
+ *        means that the device may try to send data while the host isn't listening, causing\r
+ *        lengthy blocking timeouts in the transmission routines. To combat this, it is\r
+ *        recommended that the virtual serial line DTR (Data Terminal Ready) be used where\r
+ *        possible to determine if a host application is ready for data.\r
+ *\r

  *  @{\r
  */\r
  \r
  *  @{\r
  */\r
  \r


@@ -155,7 +172,12 @@
                        void EVENT_CDC_Device_ControLineStateChanged(USB_ClassInfo_CDC_Device_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 \r
                        /** Sends a given string to the attached USB host, if connected. If a host is not connected when the function is called, the\r
                        void EVENT_CDC_Device_ControLineStateChanged(USB_ClassInfo_CDC_Device_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
 \r
                        /** Sends a given string to the attached USB host, if connected. If a host is not connected when the function is called, the\r

-                        *  string is discarded.\r
+                        *  string is discarded. Bytes will be queued for transmission to the host until either the endpoint bank becomes full, or the\r
+                        *  \ref CDC_Device_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be \r
+                        *  packed into a single endpoint packet, increasing data throughput.\r
+                        *\r
+                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or\r
+                        *        the call will fail.\r

                         *\r
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         *  \param[in] Data  Pointer to the string to send to the host\r
                         *\r
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         *  \param[in] Data  Pointer to the string to send to the host\r


@@ -167,7 +189,12 @@
                                                      ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r
                        \r
                        /** Sends a given byte to the attached USB host, if connected. If a host is not connected when the function is called, the\r
                                                      ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r
                        \r
                        /** Sends a given byte to the attached USB host, if connected. If a host is not connected when the function is called, the\r

-                        *  byte is discarded.\r
+                        *  byte is discarded. Bytes will be queued for transmission to the host until either the endpoint bank becomes full, or the\r
+                        *  \ref CDC_Device_Flush() function is called to flush the pending data to the host. This allows for multiple bytes to be \r
+                        *  packed into a single endpoint packet, increasing data throughput.\r
+                        *\r
+                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or\r
+                        *        the call will fail.\r

                         *\r
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         *  \param[in] Data  Byte of data to send to the host\r
                         *\r
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         *  \param[in] Data  Byte of data to send to the host\r


@@ -178,6 +205,9 @@
                        \r
                        /** Determines the number of bytes received by the CDC interface from the host, waiting to be read.\r
                         *\r
                        \r
                        /** Determines the number of bytes received by the CDC interface from the host, waiting to be read.\r
                         *\r

+                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or\r
+                        *        the call will fail.\r
+                        *\r

                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         *\r
                         *  \return Total number of buffered bytes received from the host\r
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         *\r
                         *  \return Total number of buffered bytes received from the host\r


@@ -188,6 +218,9 @@
                         *  returns 0. The \ref CDC_Device_BytesReceived() function should be queried before data is received to ensure that no data\r
                         *  underflow occurs.\r
                         *\r
                         *  returns 0. The \ref CDC_Device_BytesReceived() function should be queried before data is received to ensure that no data\r
                         *  underflow occurs.\r
                         *\r

+                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or\r
+                        *        the call will fail.\r
+                        *\r

                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         *\r
                         *  \return Next received byte from the host, or 0 if no data received\r
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         *\r
                         *  \return Next received byte from the host, or 0 if no data received\r


@@ -196,6 +229,9 @@
                        \r
                        /** Flushes any data waiting to be sent, ensuring that the send buffer is cleared.\r
                         *\r
                        \r
                        /** Flushes any data waiting to be sent, ensuring that the send buffer is cleared.\r
                         *\r

+                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or\r
+                        *        the call will fail.\r
+                        *\r

                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         *\r
                         *  \return A value from the \ref Endpoint_WaitUntilReady_ErrorCodes_t enum\r
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         *\r
                         *  \return A value from the \ref Endpoint_WaitUntilReady_ErrorCodes_t enum\r


@@ -207,6 +243,9 @@
                         *  until they are cleared via a second notification. This should be called each time the CDC class driver's \r
                         *  ControlLineStates.DeviceToHost value is updated to push the new states to the USB host.\r
                         *\r
                         *  until they are cleared via a second notification. This should be called each time the CDC class driver's \r
                         *  ControlLineStates.DeviceToHost value is updated to push the new states to the USB host.\r
                         *\r

+                        *  \note This function must only be called when the Device state machine is in the DEVICE_STATE_Configured state or\r
+                        *        the call will fail.\r
+                        *\r

                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         */\r
                        void CDC_Device_SendControlLineStateChange(USB_ClassInfo_CDC_Device_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r
                         *  \param[in,out] CDCInterfaceInfo  Pointer to a structure containing a CDC Class configuration and state\r
                         */\r
                        void CDC_Device_SendControlLineStateChange(USB_ClassInfo_CDC_Device_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);\r