From ccf5bd19f2d750440043b242cf26fcda09b69cce Mon Sep 17 00:00:00 2001 From: Dean Camera Date: Mon, 8 Jun 2009 11:31:41 +0000 Subject: [PATCH] Finished basic documentation of all device mode class drivers. --- LUFA/ChangeLog.txt | 1 - LUFA/Drivers/USB/Class/Device/Audio.h | 7 +- LUFA/Drivers/USB/Class/Device/CDC.h | 6 +- LUFA/Drivers/USB/Class/Device/MIDI.h | 61 ++++++++++--- LUFA/Drivers/USB/Class/Device/MassStorage.h | 49 +++++++++-- LUFA/Drivers/USB/Class/Device/RNDIS.c | 2 +- LUFA/Drivers/USB/Class/Device/RNDIS.h | 96 ++++++++++++++------- 7 files changed, 166 insertions(+), 56 deletions(-) diff --git a/LUFA/ChangeLog.txt b/LUFA/ChangeLog.txt index 0eea9c43c7..0410be4ba4 100644 --- a/LUFA/ChangeLog.txt +++ b/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 diff --git a/LUFA/Drivers/USB/Class/Device/Audio.h b/LUFA/Drivers/USB/Class/Device/Audio.h index 230da4d9ef..0749d9536a 100644 --- a/LUFA/Drivers/USB/Class/Device/Audio.h +++ b/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 unit within the device, and passed (per-interface) to the Audio Class driver functions so that each Audio interface - * has seperate state and configuration data and can be controlled seperately. + /** Class state structure. An instance of this structure should be made for each Audio interface + * within the user application, and passed to each of the Audio class driver functions as the + * 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 { diff --git a/LUFA/Drivers/USB/Class/Device/CDC.h b/LUFA/Drivers/USB/Class/Device/CDC.h index feb7ff24b5..390ebbcb65 100644 --- a/LUFA/Drivers/USB/Class/Device/CDC.h +++ b/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 - * as set by the host via a class specific request. + /** Class state structure. An instance of this structure should be made for each CDC interface + * 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 { diff --git a/LUFA/Drivers/USB/Class/Device/MIDI.h b/LUFA/Drivers/USB/Class/Device/MIDI.h index 08a530af2e..4be472c0e6 100644 --- a/LUFA/Drivers/USB/Class/Device/MIDI.h +++ b/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 CableNumber : 4; + unsigned char Command : 4; /**< MIDI command being sent or received in the event packet */ + unsigned char CableNumber : 4; /**< Virtual cable number of the event being sent or received in the given MIDI interface */ - uint8_t Data1; - uint8_t Data2; - uint8_t Data3; + uint8_t Data1; /**< First byte of data in the MIDI event */ + uint8_t Data2; /**< Second byte of data in the MIDI event */ + 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 DataINEndpointNumber; - uint16_t DataINEndpointSize; + uint8_t StreamingInterfaceNumber; /**< Index of the Audio Streaming interface within the device this structure controls */ - uint8_t DataOUTEndpointNumber; - uint16_t DataOUTEndpointSize; + uint8_t DataINEndpointNumber; /**< Endpoint number of the incomming MIDI data, if available (zero if unused) */ + uint16_t DataINEndpointSize; /**< Size in bytes of the incomming MIDI data endpoint, if available (zero if unused) */ - bool InterfaceEnabled; + uint8_t DataOUTEndpointNumber; /**< Endpoint number of the outgoing MIDI data, if available (zero if unused) */ + uint16_t DataOUTEndpointSize; /**< Size in bytes of the outgoing MIDI data endpoint, if available (zero if unused) */ } 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: */ diff --git a/LUFA/Drivers/USB/Class/Device/MassStorage.h b/LUFA/Drivers/USB/Class/Device/MassStorage.h index d8da15c2b0..0ecc4aa1d6 100644 --- a/LUFA/Drivers/USB/Class/Device/MassStorage.h +++ b/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 - * as set by the host via a class specific request. + /** Class state structure. An instance of this structure should be made for each Mass Storage interface + * 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; - CommandStatusWrapper_t CommandStatus; + CommandBlockWrapper_t CommandBlock; /**< Mass Storage class command block structure, used internally + * 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: */ diff --git a/LUFA/Drivers/USB/Class/Device/RNDIS.c b/LUFA/Drivers/USB/Class/Device/RNDIS.c index 49c7df01da..7b51b2a3ad 100644 --- a/LUFA/Drivers/USB/Class/Device/RNDIS.c +++ b/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: diff --git a/LUFA/Drivers/USB/Class/Device/RNDIS.h b/LUFA/Drivers/USB/Class/Device/RNDIS.h index a8c8db9b71..a21a3de93c 100644 --- a/LUFA/Drivers/USB/Class/Device/RNDIS.h +++ b/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 */ - NdisHardwareStatusInitializing, /**< Hardware busy initializing */ - NdisHardwareStatusReset, /**< Hardware reset */ - NdisHardwareStatusClosing, /**< Hardware currently closing */ - NdisHardwareStatusNotReady /**< Hardware not ready to accept commands from the host */ + NDIS_HardwareStatus_Ready, /**< Hardware Ready to accept commands from the host */ + NDIS_HardwareStatus_Initializing, /**< Hardware busy initializing */ + NDIS_HardwareStatus_Reset, /**< Hardware reset */ + NDIS_HardwareStatus_Closing, /**< Hardware currently closing */ + 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 { @@ -260,7 +239,42 @@ uint32_t InformationBufferLength; 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: */