descriptors.h

LUFA (Lightweight USB Framework for AVRs) is my first foray into the world of USB. Originally based

			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                  ACSpecification; /**< 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 */
			
			uint8_t                   InCollection; /**< Total number of audio class interfaces within this device */
			uint8_t                   InterfaceNumbers[1]; /**< Interface numbers of each audio interface */
		} USB_AudioInterface_AC_t;
		
		/** Type define for an Audio class specific Feature Unit descriptor. This indicates to the host what features
		 *  are present in the device's audio stream for basic control, such as per-channel volume. 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                   UnitID; /**< ID value of this feature unit - must be a unique value within the device */
			uint8_t                   SourceID; /**< Source ID value of the audio source input into this feature unit */
			
			uint8_t                   ControlSize; /**< Size of each element in the ChanelControlls array */
			uint8_t                   ChannelControls[3]; /**< Feature masks for the control channel, and each separate audio channel */
			
			uint8_t                   FeatureUnitStrIndex; /**< Index of a string descriptor describing this descriptor within the device */
		} USB_AudioFeatureUnit_t;

		/** Type define for an Audio class specific input terminal descriptor. This indicates to the host that the device
		 *  contains an input audio source, either from a physical terminal on the device, or a logical terminal (for example,
		 *  a USB endpoint). 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                   TerminalID; /**< ID value of this terminal unit - must be a unique value within the device */
			uint16_t                  TerminalType; /**< Type of terminal, a TERMINAL_* mask */
			uint8_t                   AssociatedOutputTerminal; /**< ID of associated output terminal, for physically grouped terminals
			                                                     *   such as the speaker and microphone of a phone handset
			                                                     */
			uint8_t                   TotalChannels; /**< Total number of separate audio channels within this interface (right, left, etc.) */
			uint16_t                  ChannelConfig; /**< CHANNEL_* masks indicating what channel layout is supported by this terminal */
			
			uint8_t                   ChannelStrIndex; /**< Index of a string descriptor describing this channel within the device */
			uint8_t                   TerminalStrIndex; /**< Index of a string descriptor describing this descriptor within the device */
		} USB_AudioInputTerminal_t;

		/** Type define for an Audio class specific output terminal descriptor. This indicates to the host that the device
		 *  contains an output audio sink, either to a physical terminal on the device, or a logical terminal (for example,
		 *  a USB endpoint). 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                   TerminalID; /**< ID value of this terminal unit - must be a unique value within the device */
			uint16_t                  TerminalType; /**< Type of terminal, a TERMINAL_* mask */
			uint8_t                   AssociatedInputTerminal; /**< ID of associated input terminal, for physically grouped terminals
			                                                    *   such as the speaker and microphone of a phone handset
			                                                    */
			uint8_t                   SourceID; /**< ID value of the unit this terminal's audio is sourced from */
			
			uint8_t                   TerminalStrIndex; /**< Index of a string descriptor describing this descriptor within the device */
		} USB_AudioOutputTerminal_t;
		
		/** Type define for an Audio class specific streaming interface descriptor. This indicates to the host
		 *  how audio streams within the device are formatted. 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                   TerminalLink; /**< ID value of the output terminal this descriptor is describing */
			
			uint8_t                   FrameDelay; /**< Delay in frames resulting from the complete sample processing from input to output */
			uint16_t                  AudioFormat; /**< Format of the audio stream, see Audio Device Formats specification */
		} USB_AudioInterface_AS_t;
		
		/** Type define for a 24bit audio sample frequency structure. GCC does not contain a built in 24bit datatype,
		 *  this this structure is used to build up the value instead. Fill this structure with the SAMPLE_FREQ() macro.
		 */
		typedef struct
		{
			uint16_t                  LowWord; /**< Low 16 bits of the 24-bit value */
			uint8_t                   HighByte; /**< Upper 8 bits of the 24-bit value */
		} AudioSampleFreq_t;

		/** Type define for an Audio class specific audio format descriptor. This is used to give the host full details
		 *  about the number of channels, the sample resolution, acceptable sample frequencies and encoding method used
		 *  in the device's audio streams. 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                   FormatType; /**< Format of the audio stream, see Audio Device Formats specification */
			uint8_t                   Channels; /**< Total number of discrete channels in the stream */
			
			uint8_t                   SubFrameSize; /**< Size in bytes of each channel's sample data in the stream */
			uint8_t                   BitResolution; /**< Bits of resolution of each channel's samples in the stream */

			uint8_t                   SampleFrequencyType; /**< Total number of sample frequencies supported by the device */			
			AudioSampleFreq_t         SampleFrequencies[1]; /**< Sample frequencies supported by the device */
		} USB_AudioFormat_t;
		
		/** Type define for an Audio class specific endpoint descriptor. This contains a regular endpoint 
		 *  descriptor with a few Audio-class specific extensions. See the USB Audio specification for more details.
		 */
		typedef struct
		{
			USB_Descriptor_Endpoint_t Endpoint; /**< Standard endpoint descriptor describing the audio endpoint */

			uint8_t                   Refresh; /**< Always set to zero */
			uint8_t                   SyncEndpointNumber; /**< Endpoint address to send synchronisation information to, if needed (zero otherwise) */
		} USB_AudioStreamEndpoint_Std_t;
					
		/** Type define for an Audio class specific extended endpoint descriptor. This contains extra information
		 *  on the usage of endpoints used to stream audio in and out of the USB Audio device, and follows an Audio
		 *  class specific extended 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                   Attributes; /**< Audio class specific endpoint attributes, such as ACCEPTS_SMALL_PACKETS */

			uint8_t                   LockDelayUnits; /**< Units used for the LockDelay field, see Audio class specification */
			uint16_t                  LockDelay; /**< Time required to internally lock endpoint's internal clock recovery circuitry */
		} USB_AudioStreamEndpoint_Spc_t;
		
		/** Type define for the device configuration descriptor structure. This must be defined in the
		 *  application code, as the configuration descriptor contains several sub-descriptors which
		 *  vary between devices, and which describe the device's usage to the host.
		 */
		typedef struct
		{
			USB_Descriptor_Configuration_Header_t Config;
			USB_Descriptor_Interface_t            AudioControlInterface;
			USB_AudioInterface_AC_t               AudioControlInterface_SPC;
			USB_AudioInputTerminal_t              InputTerminal;
			USB_AudioOutputTerminal_t             OutputTerminal;
			USB_Descriptor_Interface_t            AudioStreamInterface_Alt0;
			USB_Descriptor_Interface_t            AudioStreamInterface_Alt1;
			USB_AudioInterface_AS_t               AudioStreamInterface_SPC;
			USB_AudioFormat_t                     AudioFormat;
			USB_AudioStreamEndpoint_Std_t         AudioEndpoint;
			USB_AudioStreamEndpoint_Spc_t         AudioEndpoint_SPC;
		} USB_Descriptor_Configuration_t;
		
	/* Function Prototypes: */
		uint16_t USB_GetDescriptor(const uint16_t wValue, const uint8_t wIndex, void** const DescriptorAddress)
		                           ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(3);

#endif