X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/a67bd74e3e8aad87dcee8cf0c0eaaccbe7d00552..c75f8bf2236bc69511d0ff0bc79bfaf1f62e3bfd:/LUFA/Drivers/USB/Class/Device/MIDI.h diff --git a/LUFA/Drivers/USB/Class/Device/MIDI.h b/LUFA/Drivers/USB/Class/Device/MIDI.h index 890d3bb55..87aabe1c5 100644 --- a/LUFA/Drivers/USB/Class/Device/MIDI.h +++ b/LUFA/Drivers/USB/Class/Device/MIDI.h @@ -28,11 +28,21 @@ this software. */ -#ifndef _MIDI_CLASS_H_ -#define _MIDI_CLASS_H_ +/** \ingroup Group_USBClassMIDI + * @defgroup Group_USBClassMIDIDevice MIDI Class Device Mode Driver + * + * \section Module Description + * Device Mode USB Class driver framework interface, for the MIDI USB Class driver. + * + * @{ + */ + +#ifndef _MIDI_CLASS_DEVICE_H_ +#define _MIDI_CLASS_DEVICE_H_ /* Includes: */ #include "../../USB.h" + #include "../Common/MIDI.h" #include "Audio.h" #include @@ -42,123 +52,47 @@ extern "C" { #endif - /* Macros: */ - /** Audio class descriptor subtype value for a Audio class specific MIDI input jack descriptor. */ - #define DSUBTYPE_InputJack 0x02 - - /** Audio class descriptor subtype value for a Audio class specific MIDI output jack descriptor. */ - #define DSUBTYPE_OutputJack 0x03 - - /** Audio class descriptor jack type value for an embedded (logical) MIDI input or output jack. */ - #define MIDI_JACKTYPE_EMBEDDED 0x01 - - /** Audio class descriptor jack type value for an external (physical) MIDI input or output jack. */ - #define MIDI_JACKTYPE_EXTERNAL 0x02 - - /** MIDI command for a note on (activation) event */ - #define MIDI_COMMAND_NOTE_ON 0x09 - - /** MIDI command for a note off (deactivation) event */ - #define MIDI_COMMAND_NOTE_OFF 0x08 - - /** Standard key press velocity value used for all note events, as no pressure sensor is mounted */ - #define MIDI_STANDARD_VELOCITY 64 - - /** Convenience macro. MIDI channels are numbered from 1-10 (natural numbers) however the logical channel - * addresses are zero-indexed. This converts a natural MIDI channel number into the logical channel address. - * - * \param channel MIDI channel number to address - */ - #define MIDI_CHANNEL(channel) (channel - 1) - - /* Type Defines: */ - /** Type define for an Audio class specific MIDI streaming interface descriptor. This indicates to the host - * how MIDI the specification compliance of the device and the total length of the Audio class specific descriptors. - * See the USB Audio specification for more details. - */ - typedef struct - { - USB_Descriptor_Header_t Header; /**< Regular descriptor header containing the descriptor's type and length */ - uint8_t Subtype; /**< Sub type value used to distinguish between audio class specific descriptors */ - - uint16_t AudioSpecification; /**< Binary coded decimal value, indicating the supported Audio Class specification version */ - uint16_t TotalLength; /**< Total length of the Audio class specific descriptors, including this descriptor */ - } USB_AudioInterface_MIDI_AS_t; - - /** Type define for an Audio class specific MIDI IN jack. This gives information to the host on a MIDI input, either - * a physical input jack, or a logical jack (receiving input data internally, or from the host via an endpoint). - */ - typedef struct - { - USB_Descriptor_Header_t Header; /**< Regular descriptor header containing the descriptor's type and length */ - uint8_t Subtype; /**< Sub type value used to distinguish between audio class specific descriptors */ - - uint8_t JackType; /**< Type of jack, one of the JACKTYPE_* mask values */ - uint8_t JackID; /**< ID value of this jack - must be a unique value within the device */ - - uint8_t JackStrIndex; /**< Index of a string descriptor describing this descriptor within the device */ - } USB_MIDI_In_Jack_t; - - /** Type define for an Audio class specific MIDI OUT jack. This gives information to the host on a MIDI output, either - * a physical output jack, or a logical jack (sending output data internally, or to the host via an endpoint). - */ - typedef struct - { - USB_Descriptor_Header_t Header; /**< Regular descriptor header containing the descriptor's type and length */ - uint8_t Subtype; /**< Sub type value used to distinguish between audio class specific descriptors */ - - uint8_t JackType; /**< Type of jack, one of the JACKTYPE_* mask values */ - uint8_t JackID; /**< ID value of this jack - must be a unique value within the device */ - - uint8_t NumberOfPins; /**< Number of output channels within the jack, either physical or logical */ - uint8_t SourceJackID[1]; /**< ID of each output pin's source data jack */ - uint8_t SourcePinID[1]; /**< Pin number in the input jack of each output pin's source data */ + /* Public Interface - May be used in end-application: */ + /* 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 MIDI_Device_ConfigureEndpoints(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo); - uint8_t JackStrIndex; /**< Index of a string descriptor describing this descriptor within the device */ - } USB_MIDI_Out_Jack_t; - - /** Type define for an Audio class specific extended MIDI jack endpoint descriptor. This contains extra information - * on the usage of MIDI endpoints used to stream MIDI events in and out of the USB Audio device, and follows an Audio - * class specific extended MIDI endpoint descriptor. See the USB Audio specification for more details. - */ - typedef struct - { - USB_Descriptor_Header_t Header; /**< Regular descriptor header containing the descriptor's type and length */ - uint8_t Subtype; /**< Sub type value used to distinguish between audio class specific descriptors */ - - uint8_t TotalEmbeddedJacks; /**< Total number of jacks inside this endpoint */ - uint8_t AssociatedJackID[1]; /**< IDs of each jack inside the endpoint */ - } USB_MIDI_Jack_Endpoint_t; - - typedef struct - { - unsigned char Command : 4; - unsigned char CableNumber : 4; - - uint8_t Data1; - uint8_t Data2; - uint8_t Data3; - } USB_MIDI_EventPacket_t; - - typedef struct - { - uint8_t StreamingInterfaceNumber; - - uint8_t DataINEndpointNumber; - uint16_t DataINEndpointSize; - - uint8_t DataOUTEndpointNumber; - uint16_t DataOUTEndpointSize; - - bool InterfaceEnabled; - } USB_ClassInfo_MIDI_t; - - /* Function Prototypes: */ - bool USB_MIDI_ConfigureEndpoints(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo); - void USB_MIDI_USBTask(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo); - - void USB_MIDI_SendEventPacket(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo, USB_MIDI_EventPacket_t* Event); - bool USB_MIDI_ReceiveEventPacket(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo, USB_MIDI_EventPacket_t* Event); + /** 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 MIDI_Device_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 MIDI_Device_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 MIDI_Device_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 MIDI_Device_ReceiveEventPacket(USB_ClassInfo_MIDI_t* MIDIInterfaceInfo, USB_MIDI_EventPacket_t* Event); /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus) @@ -166,3 +100,5 @@ #endif #endif + +/** @} */