Commit ccf5bd19 authored by Dean Camera's avatar Dean Camera
Browse files

Finished basic documentation of all device mode class drivers.

parent 1c12341c
...@@ -5,7 +5,6 @@ ...@@ -5,7 +5,6 @@
*/ */
========== TODO: =========== ========== TODO: ===========
- Document new device class drivers
- Make new host class drivers - Make new host class drivers
- Document new host class drivers - Document new host class drivers
- Convert Host mode demos to class drivers - Convert Host mode demos to class drivers
......
...@@ -361,9 +361,10 @@ ...@@ -361,9 +361,10 @@
uint16_t LockDelay; /**< Time required to internally lock endpoint's internal clock recovery circuitry */ uint16_t LockDelay; /**< Time required to internally lock endpoint's internal clock recovery circuitry */
} USB_AudioStreamEndpoint_Spc_t; } 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 typedef struct
{ {
......
...@@ -151,8 +151,10 @@ ...@@ -151,8 +151,10 @@
}; };
/* Type Defines: */ /* 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 typedef struct
{ {
......
...@@ -145,35 +145,72 @@ ...@@ -145,35 +145,72 @@
uint8_t AssociatedJackID[1]; /**< IDs of each jack inside the endpoint */ uint8_t AssociatedJackID[1]; /**< IDs of each jack inside the endpoint */
} USB_MIDI_Jack_Endpoint_t; } 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 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; } 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 typedef struct
{ {
uint8_t StreamingInterfaceNumber; uint8_t StreamingInterfaceNumber; /**< Index of the Audio Streaming interface within the device this structure controls */
uint8_t DataINEndpointNumber;
uint16_t DataINEndpointSize;
uint8_t DataOUTEndpointNumber; uint8_t DataINEndpointNumber; /**< Endpoint number of the incomming MIDI data, if available (zero if unused) */
uint16_t DataOUTEndpointSize; 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; } USB_ClassInfo_MIDI_t;
/* Function Prototypes: */ /* 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); 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); 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); 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); 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); bool USB_MIDI_ReceiveEventPacket(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo, USB_MIDI_EventPacket_t* Event);
/* Disable C linkage for C++ Compilers: */ /* Disable C linkage for C++ Compilers: */
......
...@@ -106,8 +106,10 @@ ...@@ -106,8 +106,10 @@
}; };
/* Type Defines: */ /* 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 typedef struct
{ {
...@@ -119,12 +121,18 @@ ...@@ -119,12 +121,18 @@
uint8_t DataOUTEndpointNumber; /**< Endpoint number of the Mass Storage interface's OUT data endpoint */ 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 */ 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; } USB_ClassInfo_MS_t;
/* Function Prototypes: */ /* Function Prototypes: */
...@@ -134,10 +142,39 @@ ...@@ -134,10 +142,39 @@
static uint8_t StreamCallback_AbortOnMassStoreReset(void); static uint8_t StreamCallback_AbortOnMassStoreReset(void);
#endif #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); 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); 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); 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); bool CALLBACK_USB_MS_SCSICommandReceived(USB_ClassInfo_MS_t* MSInterfaceInfo);
/* Disable C linkage for C++ Compilers: */ /* Disable C linkage for C++ Compilers: */
......
...@@ -346,7 +346,7 @@ static bool USB_RNDIS_ProcessNDISQuery(USB_ClassInfo_RNDIS_t* RNDISInterfaceInfo ...@@ -346,7 +346,7 @@ static bool USB_RNDIS_ProcessNDISQuery(USB_ClassInfo_RNDIS_t* RNDISInterfaceInfo
case OID_GEN_HARDWARE_STATUS: case OID_GEN_HARDWARE_STATUS:
*ResponseSize = sizeof(uint32_t); *ResponseSize = sizeof(uint32_t);
*((uint32_t*)ResponseData) = NdisHardwareStatusReady; *((uint32_t*)ResponseData) = NDIS_HardwareStatus_Ready;
return true; return true;
case OID_GEN_MEDIA_SUPPORTED: case OID_GEN_MEDIA_SUPPORTED:
......
...@@ -33,7 +33,7 @@ ...@@ -33,7 +33,7 @@
* *
* \section Sec_Dependencies Module Source Dependencies * \section Sec_Dependencies Module Source Dependencies
* The following files must be built with any user project that uses this module: * 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 * \section Module Description
* Functions, macros, variables, enums and types related to the management of USB RNDIS Ethernet * Functions, macros, variables, enums and types related to the management of USB RNDIS Ethernet
...@@ -69,10 +69,13 @@ ...@@ -69,10 +69,13 @@
/** RNDIS request to issue a device-to-host NDIS response */ /** RNDIS request to issue a device-to-host NDIS response */
#define REQ_GetEncapsulatedResponse 0x01 #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 #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 #define ETHERNET_FRAME_SIZE_MAX 1500
/** Notification request value for a RNDIS Response Available notification */
#define NOTIF_ResponseAvailable 1 #define NOTIF_ResponseAvailable 1
/* Enums: */ /* Enums: */
...@@ -87,11 +90,11 @@ ...@@ -87,11 +90,11 @@
/** Enum for the NDIS hardware states */ /** Enum for the NDIS hardware states */
enum NDIS_Hardware_Status_t 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: */ /* Type Defines: */
...@@ -132,30 +135,6 @@ ...@@ -132,30 +135,6 @@
uint32_t Reserved; uint32_t Reserved;
} RNDIS_PACKET_MSG_t; } 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 */ /** Type define for a RNDIS Initialize command message */
typedef struct typedef struct
{ {
...@@ -261,6 +240,41 @@ ...@@ -261,6 +240,41 @@
uint32_t InformationBufferOffset; uint32_t InformationBufferOffset;
} RNDIS_QUERY_CMPLT_t; } 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: */ /* Function Prototypes: */
#if defined(INCLUDE_FROM_RNDIS_CLASS_C) #if defined(INCLUDE_FROM_RNDIS_CLASS_C)
static void USB_RNDIS_ProcessRNDISControlMessage(USB_ClassInfo_RNDIS_t* RNDISInterfaceInfo); static void USB_RNDIS_ProcessRNDISControlMessage(USB_ClassInfo_RNDIS_t* RNDISInterfaceInfo);
...@@ -271,8 +285,28 @@ ...@@ -271,8 +285,28 @@
void* SetData, uint16_t SetSize); void* SetData, uint16_t SetSize);
#endif #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); 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); 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); void USB_RNDIS_USBTask(USB_ClassInfo_RNDIS_t* RNDISInterfaceInfo);
/* Disable C linkage for C++ Compilers: */ /* Disable C linkage for C++ Compilers: */
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment