Finished basic documentation of all device mode class drivers.

LUFA/ChangeLog.txt

@@ -5,7 +5,6 @@
  */
    
 ========== TODO: ===========
-	- Document new device class drivers
 	- Make new host class drivers
 	- Document new host class drivers
 	- Convert Host mode demos to class drivers

LUFA/Drivers/USB/Class/Device/Audio.h

@@ -361,9 +361,10 @@
 			uint16_t                  LockDelay; /**< Time required to internally lock endpoint's internal clock recovery circuitry */
 		} USB_AudioStreamEndpoint_Spc_t;	
 
-		/** Type define for an Audio Class interface configuration and state structure. This structure should be used for each Audio
+		/** Class state structure. An instance of this structure should be made for each Audio interface
-		 *  Class unit within the device, and passed (per-interface) to the Audio Class driver functions so that each Audio interface
+		 *  within the user application, and passed to each of the Audio class driver functions as the
-		 *  has seperate state and configuration data and can be controlled seperately.
+		 *  AudioInterfaceInfo parameter. The contents of this structure should be set to their correct
+		 *  values when used, or ommitted to force the library to use default values.
 		 */
 		typedef struct
 		{

LUFA/Drivers/USB/Class/Device/CDC.h

@@ -151,8 +151,10 @@
 		};
 
 	/* Type Defines: */
-		/** Type define for the virtual serial port line encoding settings, for storing the current USART configuration
+		/** Class state structure. An instance of this structure should be made for each CDC interface
-		 *  as set by the host via a class specific request.
+		 *  within the user application, and passed to each of the CDC class driver functions as the
+		 *  CDCInterfaceInfo parameter. The contents of this structure should be set to their correct
+		 *  values when used, or ommitted to force the library to use default values.
 		 */
 		typedef struct
 		{

LUFA/Drivers/USB/Class/Device/MIDI.h

@@ -145,35 +145,72 @@
 			uint8_t                   AssociatedJackID[1]; /**< IDs of each jack inside the endpoint */
 		} USB_MIDI_Jack_Endpoint_t;
 
+		/** Type define for a USB MIDI event packet, used to encapsulate sent and received MIDI messages from a USB MIDI interface. */
 		typedef struct
 		{
-			unsigned char Command     : 4;
+			unsigned char Command     : 4; /**< MIDI command being sent or received in the event packet */
-			unsigned char CableNumber : 4;
+			unsigned char CableNumber : 4; /**< Virtual cable number of the event being sent or received in the given MIDI interface */
 			
-			uint8_t Data1;
+			uint8_t Data1; /**< First byte of data in the MIDI event */
-			uint8_t Data2;
+			uint8_t Data2; /**< Second byte of data in the MIDI event */
-			uint8_t Data3;			
+			uint8_t Data3; /**< Third byte of data in the MIDI event */		
 		} USB_MIDI_EventPacket_t;
 
+		/** Class state structure. An instance of this structure should be made for each MIDI interface
+		 *  within the user application, and passed to each of the MIDI class driver functions as the
+		 *  MIDIInterfaceInfo parameter. The contents of this structure should be set to their correct
+		 *  values when used, or ommitted to force the library to use default values.
+		 */
 		typedef struct
 		{
-			uint8_t  StreamingInterfaceNumber;
+			uint8_t  StreamingInterfaceNumber; /**< Index of the Audio Streaming interface within the device this structure controls */
 
-			uint8_t  DataINEndpointNumber;
+			uint8_t  DataINEndpointNumber; /**< Endpoint number of the incomming MIDI data, if available (zero if unused) */
-			uint16_t DataINEndpointSize;
+			uint16_t DataINEndpointSize; /**< Size in bytes of the incomming MIDI data endpoint, if available (zero if unused) */
 
-			uint8_t  DataOUTEndpointNumber;
+			uint8_t  DataOUTEndpointNumber; /**< Endpoint number of the outgoing MIDI data, if available (zero if unused) */
-			uint16_t DataOUTEndpointSize;
+			uint16_t DataOUTEndpointSize; /**< Size in bytes of the outgoing MIDI data endpoint, if available (zero if unused) */
-
-			bool     InterfaceEnabled;
 		} USB_ClassInfo_MIDI_t;
 		
 	/* Function Prototypes: */
+		/** Configures the endpoints of a given MIDI interface, ready for use. This should be linked to the library
+		 *  \ref EVENT_USB_ConfigurationChanged() event so that the endpoints are configured when the configuration
+		 *  containing the given MIDI interface is selected.
+		 *
+		 *  \param MIDIInterfaceInfo  Pointer to a structure containing a MIDI Class configuration and state.
+		 *
+		 *  \return Boolean true if the endpoints were sucessfully configured, false otherwise
+		 */
 		bool USB_MIDI_ConfigureEndpoints(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo);
+		
+		/** Processes incomming control requests from the host, that are directed to the given MIDI class interface. This should be
+		 *  linked to the library \ref EVENT_USB_UnhandledControlPacket() event.
+		 *
+		 *  \param MIDIInterfaceInfo  Pointer to a structure containing a MIDI Class configuration and state.
+		 */		
 		void USB_MIDI_ProcessControlPacket(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo);
+
+		/** General management task for a given MIDI class interface, required for the correct operation of the interface. This should
+		 *  be called frequently in the main program loop, before the master USB management task \ref USB_USBTask().
+		 *
+		 *  \param MIDIInterfaceInfo  Pointer to a structure containing a MIDI Class configuration and state.
+		 */
 		void USB_MIDI_USBTask(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo);
 
+		/** Sends a MIDI event packet to the host. If no host is connected, the event packet is discarded.
+		 *
+		 *  \param MIDIInterfaceInfo  Pointer to a structure containing a MIDI Class configuration and state.
+		 *  \param Event  Pointer to a populated USB_MIDI_EventPacket_t structure containing the MIDI event to send
+		 */
 		void USB_MIDI_SendEventPacket(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo, USB_MIDI_EventPacket_t* Event);
+
+		/** Receives a MIDI event packet from the host.
+		 *
+		 *  \param MIDIInterfaceInfo  Pointer to a structure containing a MIDI Class configuration and state.
+		 *  \param Event  Pointer to a USB_MIDI_EventPacket_t structure where the received MIDI event is to be placed
+		 *
+		 *  \return Boolean true if a MIDI event packet was received, false otherwise
+		 */
 		bool USB_MIDI_ReceiveEventPacket(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo, USB_MIDI_EventPacket_t* Event);
 
 	/* Disable C linkage for C++ Compilers: */

LUFA/Drivers/USB/Class/Device/MassStorage.h

@@ -106,8 +106,10 @@
 		};
 		
 	/* Type Defines: */
-		/** Type define for the virtual serial port line encoding settings, for storing the current USART configuration
+		/** Class state structure. An instance of this structure should be made for each Mass Storage interface
-		 *  as set by the host via a class specific request.
+		 *  within the user application, and passed to each of the Mass Storage class driver functions as the
+		 *  MSInterfaceInfo parameter. The contents of this structure should be set to their correct
+		 *  values when used, or ommitted to force the library to use default values.
 		 */
 		typedef struct
 		{
@@ -119,12 +121,18 @@
 			uint8_t  DataOUTEndpointNumber; /**< Endpoint number of the Mass Storage interface's OUT data endpoint */
 			uint16_t DataOUTEndpointSize;  /**< Size in bytes of the Mass Storage interface's OUT data endpoint */
 
-			uint8_t  TotalLUNs;
+			uint8_t  TotalLUNs; /**< Total number of logical drives in the Mass Storage interface */
 
-			CommandBlockWrapper_t  CommandBlock;
+			CommandBlockWrapper_t  CommandBlock; /**< Mass Storage class command block structure, used internally
-			CommandStatusWrapper_t CommandStatus;
+			                                      *   by the class driver
+			                                      */
+			CommandStatusWrapper_t CommandStatus; /**< Mass Storage class command status structure, used internally
+			                                      *   by the class driver
+			                                      */
 
-			bool IsMassStoreReset;
+			bool IsMassStoreReset; /**< Flag indicating that the host has requested that the Mass Storage interface be reset
+			                        *   and that all current Mass Storage operations should immediately abort
+									*/
 		} USB_ClassInfo_MS_t;
 		
 	/* Function Prototypes: */
@@ -134,10 +142,39 @@
 			static uint8_t StreamCallback_AbortOnMassStoreReset(void);
 		#endif
 	
+		/** Configures the endpoints of a given Mass Storage interface, ready for use. This should be linked to the library
+		 *  \ref EVENT_USB_ConfigurationChanged() event so that the endpoints are configured when the configuration
+		 *  containing the given Mass Storage interface is selected.
+		 *
+		 *  \param MSInterfaceInfo  Pointer to a structure containing a Mass Storage Class configuration and state.
+		 *
+		 *  \return Boolean true if the endpoints were sucessfully configured, false otherwise
+		 */
 		bool USB_MS_ConfigureEndpoints(USB_ClassInfo_MS_t* MSInterfaceInfo);
+		
+		/** Processes incomming control requests from the host, that are directed to the given Mass Storage class interface. This should be
+		 *  linked to the library \ref EVENT_USB_UnhandledControlPacket() event.
+		 *
+		 *  \param MSInterfaceInfo  Pointer to a structure containing a Mass Storage Class configuration and state.
+		 */		
 		void USB_MS_ProcessControlPacket(USB_ClassInfo_MS_t* MSInterfaceInfo);
+
+		/** General management task for a given Mass Storage class interface, required for the correct operation of the interface. This should
+		 *  be called frequently in the main program loop, before the master USB management task \ref USB_USBTask().
+		 *
+		 *  \param MSInterfaceInfo  Pointer to a structure containing a Mass Storage configuration and state.
+		 */
 		void USB_MS_USBTask(USB_ClassInfo_MS_t* MSInterfaceInfo);
 		
+		/** Mass Storage class driver callback for the user processing of a received SCSI command. This callback will fire each time the
+		 *  host sends a SCSI command which requires processing by the user application. Inside this callback the user is responsible
+		 *  for the processing of the received SCSI command from the host. The SCSI command is available in the CommandBlock structure
+		 *  inside the Mass Storage class state structure passed as a parameter to the callback function.
+		 *
+		 *  \param MSInterfaceInfo  Pointer to a structure containing a Mass Storage Class configuration and state.
+		 *
+		 *  \return Boolean true if the SCSI command was successfully processed, false otherwise
+		 */
 		bool CALLBACK_USB_MS_SCSICommandReceived(USB_ClassInfo_MS_t* MSInterfaceInfo);
 		
 	/* Disable C linkage for C++ Compilers: */

LUFA/Drivers/USB/Class/Device/RNDIS.c

@@ -346,7 +346,7 @@ static bool USB_RNDIS_ProcessNDISQuery(USB_ClassInfo_RNDIS_t* RNDISInterfaceInfo
 		case OID_GEN_HARDWARE_STATUS:
 			*ResponseSize = sizeof(uint32_t);
 			
-			*((uint32_t*)ResponseData) = NdisHardwareStatusReady;
+			*((uint32_t*)ResponseData) = NDIS_HardwareStatus_Ready;
 			
 			return true;
 		case OID_GEN_MEDIA_SUPPORTED:

LUFA/Drivers/USB/Class/Device/RNDIS.h

@@ -33,7 +33,7 @@
  *
  *  \section Sec_Dependencies Module Source Dependencies
  *  The following files must be built with any user project that uses this module:
- *    - LUFA/Drivers/USB/Class/Device/HID.c
+ *    - LUFA/Drivers/USB/Class/Device/RNDIS.c
  *
  *  \section Module Description
  *  Functions, macros, variables, enums and types related to the management of USB RNDIS Ethernet
@@ -69,10 +69,13 @@
 		/** RNDIS request to issue a device-to-host NDIS response */
 		#define REQ_GetEncapsulatedResponse           0x01
 		
+		/** Maximum size in bytes of a RNDIS control message which can be sent or received */
 		#define RNDIS_MESSAGE_BUFFER_SIZE             128
 
+		/** Maximum size in bytes of an Ethernet frame which can be sent or received */
 		#define ETHERNET_FRAME_SIZE_MAX               1500
 		
+		/** Notification request value for a RNDIS Response Available notification */
 		#define NOTIF_ResponseAvailable               1
 		
 	/* Enums: */
@@ -87,11 +90,11 @@
 		/** Enum for the NDIS hardware states */
 		enum NDIS_Hardware_Status_t
 		{
-			NdisHardwareStatusReady, /**< Hardware Ready to accept commands from the host */
+			NDIS_HardwareStatus_Ready, /**< Hardware Ready to accept commands from the host */
-			NdisHardwareStatusInitializing, /**< Hardware busy initializing */
+			NDIS_HardwareStatus_Initializing, /**< Hardware busy initializing */
-			NdisHardwareStatusReset, /**< Hardware reset */
+			NDIS_HardwareStatus_Reset, /**< Hardware reset */
-			NdisHardwareStatusClosing, /**< Hardware currently closing */
+			NDIS_HardwareStatus_Closing, /**< Hardware currently closing */
-			NdisHardwareStatusNotReady /**< Hardware not ready to accept commands from the host */
+			NDIS_HardwareStatus_NotReady /**< Hardware not ready to accept commands from the host */
 		};
 		
 	/* Type Defines: */
@@ -132,30 +135,6 @@
 			uint32_t Reserved;
 		} RNDIS_PACKET_MSG_t;
 
-		typedef struct
-		{
-			uint8_t  ControlInterfaceNumber; /**< Interface number of the CDC control interface within the device */
-
-			uint8_t  DataINEndpointNumber; /**< Endpoint number of the CDC interface's IN data endpoint */
-			uint16_t DataINEndpointSize; /**< Size in bytes of the CDC interface's IN data endpoint */
-
-			uint8_t  DataOUTEndpointNumber; /**< Endpoint number of the CDC interface's OUT data endpoint */
-			uint16_t DataOUTEndpointSize;  /**< Size in bytes of the CDC interface's OUT data endpoint */
-
-			uint8_t  NotificationEndpointNumber; /**< Endpoint number of the CDC interface's IN notification endpoint, if used */
-			uint16_t NotificationEndpointSize;  /**< Size in bytes of the CDC interface's IN notification endpoint, if used */
-			
-			char*         AdapterVendorDescription;
-			MAC_Address_t AdapterMACAddress;
-
-			uint8_t  RNDISMessageBuffer[RNDIS_MESSAGE_BUFFER_SIZE];
-			bool     ResponseReady;
-			uint8_t  CurrRNDISState;
-			uint32_t CurrPacketFilter;
-			Ethernet_Frame_Info_t FrameIN;
-			Ethernet_Frame_Info_t FrameOUT;
-		} USB_ClassInfo_RNDIS_t;
-		
 		/** Type define for a RNDIS Initialize command message */
 		typedef struct
 		{
@@ -261,6 +240,41 @@
 			uint32_t InformationBufferOffset;
 		} RNDIS_QUERY_CMPLT_t;
 
+		/** Class state structure. An instance of this structure should be made for each RNDIS interface
+		 *  within the user application, and passed to each of the RNDIS class driver functions as the
+		 *  RNDISInterfaceInfo parameter. The contents of this structure should be set to their correct
+		 *  values when used, or ommitted to force the library to use default values.
+		 */
+		typedef struct
+		{
+			uint8_t  ControlInterfaceNumber; /**< Interface number of the CDC control interface within the device */
+
+			uint8_t  DataINEndpointNumber; /**< Endpoint number of the CDC interface's IN data endpoint */
+			uint16_t DataINEndpointSize; /**< Size in bytes of the CDC interface's IN data endpoint */
+
+			uint8_t  DataOUTEndpointNumber; /**< Endpoint number of the CDC interface's OUT data endpoint */
+			uint16_t DataOUTEndpointSize;  /**< Size in bytes of the CDC interface's OUT data endpoint */
+
+			uint8_t  NotificationEndpointNumber; /**< Endpoint number of the CDC interface's IN notification endpoint, if used */
+			uint16_t NotificationEndpointSize;  /**< Size in bytes of the CDC interface's IN notification endpoint, if used */
+			
+			char*         AdapterVendorDescription; /**< String description of the adapter vendor */
+			MAC_Address_t AdapterMACAddress; /**< MAC address of the adapter */
+
+			uint8_t  RNDISMessageBuffer[RNDIS_MESSAGE_BUFFER_SIZE]; /**< Buffer to hold RNDIS messages to and from the host,
+			                                                         *   managed by the class driver
+			                                                         */
+			bool     ResponseReady; /**< Internal flag indicating if a RNDIS message is waiting to be returned to the host */
+			uint8_t  CurrRNDISState; /**< Current RNDIS state of the adapter, a value from the RNDIS_States_t enum */
+			uint32_t CurrPacketFilter; /**< Current packet filter mode, used internally by the class driver */
+			Ethernet_Frame_Info_t FrameIN; /**< Structure holding the last received Ethernet frame from the host, for user
+			                                *   processing
+			                                */
+			Ethernet_Frame_Info_t FrameOUT; /**< Structure holding the next Ethernet frame to send to the host, populated by the
+			                                 *   user application
+			                                 */
+		} USB_ClassInfo_RNDIS_t;
+				
 	/* Function Prototypes: */
 		#if defined(INCLUDE_FROM_RNDIS_CLASS_C)
 			static void USB_RNDIS_ProcessRNDISControlMessage(USB_ClassInfo_RNDIS_t* RNDISInterfaceInfo);
@@ -271,8 +285,28 @@
 			                                     void* SetData, uint16_t SetSize);	
 		#endif
 
+		/** Configures the endpoints of a given RNDIS interface, ready for use. This should be linked to the library
+		 *  \ref EVENT_USB_ConfigurationChanged() event so that the endpoints are configured when the configuration
+		 *  containing the given HID interface is selected.
+		 *
+		 *  \param RNDISInterfaceInfo  Pointer to a structure containing a RNDIS Class configuration and state.
+		 *
+		 *  \return Boolean true if the endpoints were sucessfully configured, false otherwise
+		 */
 		bool USB_RNDIS_ConfigureEndpoints(USB_ClassInfo_RNDIS_t* RNDISInterfaceInfo);
+
+		/** Processes incomming control requests from the host, that are directed to the given RNDIS class interface. This should be
+		 *  linked to the library \ref EVENT_USB_UnhandledControlPacket() event.
+		 *
+		 *  \param RNDISInterfaceInfo  Pointer to a structure containing a RNDIS Class configuration and state.
+		 */		
 		void USB_RNDIS_ProcessControlPacket(USB_ClassInfo_RNDIS_t* RNDISInterfaceInfo);
+		
+		/** General management task for a given HID class interface, required for the correct operation of the interface. This should
+		 *  be called frequently in the main program loop, before the master USB management task \ref USB_USBTask().
+		 *
+		 *  \param RNDISInterfaceInfo  Pointer to a structure containing a RNDIS Class configuration and state.
+		 */
 		void USB_RNDIS_USBTask(USB_ClassInfo_RNDIS_t* RNDISInterfaceInfo);
 		
 	/* Disable C linkage for C++ Compilers: */