diff options
Diffstat (limited to 'LUFA/Drivers/USB/Class/Common')
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/AndroidAccessoryClassCommon.h | 129 | ||||
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/AudioClassCommon.h | 780 | ||||
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/CDCClassCommon.h | 391 | ||||
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/HIDClassCommon.h | 681 | ||||
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/HIDParser.c | 389 | ||||
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/HIDParser.h | 364 | ||||
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/HIDReportData.h | 126 | ||||
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/MIDIClassCommon.h | 363 | ||||
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/MassStorageClassCommon.h | 368 | ||||
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/PrinterClassCommon.h | 119 | ||||
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/RNDISClassCommon.h | 411 | ||||
| -rw-r--r-- | LUFA/Drivers/USB/Class/Common/StillImageClassCommon.h | 161 |
12 files changed, 4282 insertions, 0 deletions
diff --git a/LUFA/Drivers/USB/Class/Common/AndroidAccessoryClassCommon.h b/LUFA/Drivers/USB/Class/Common/AndroidAccessoryClassCommon.h new file mode 100644 index 0000000000..fdf8671fc9 --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/AndroidAccessoryClassCommon.h @@ -0,0 +1,129 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Common definitions and declarations for the library USB Android Open Accessory Class driver. + * + * Common definitions and declarations for the library USB Android Open Accessory Class driver. + * + * \note This file should not be included directly. It is automatically included as needed by the USB module driver + * dispatch header located in LUFA/Drivers/USB.h. + */ + +/** \ingroup Group_USBClassAOA + * \defgroup Group_USBClassAOACommon Common Class Definitions + * + * \section Sec_USBClassAOACommon_ModDescription Module Description + * Constants, Types and Enum definitions that are common to both Device and Host modes for the USB + * Android Open Accessory Class. + * + * @{ + */ + +#ifndef _AOA_CLASS_COMMON_H_ +#define _AOA_CLASS_COMMON_H_ + + /* Includes: */ + #include "../../Core/StdDescriptors.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_AOA_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. + #endif + + /* Macros: */ + /** Product ID value in a Device Descriptor to indicate an Android device in Open Accessory mode. */ + #define ANDROID_ACCESSORY_PRODUCT_ID 0x2D00 + + /** Product ID value in a Device Descriptor to indicate an Android device in Open Accessory and Android Debug mode. */ + #define ANDROID_ACCESSORY_ADB_PRODUCT_ID 0x2D01 + + /* Enums: */ + /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the + * Android Open Accessory class. + */ + enum AOA_Descriptor_ClassSubclassProtocol_t + { + AOA_CSCP_AOADataClass = 0xFF, /**< Descriptor Class value indicating that the device or interface + * belongs to the AOA data class. + */ + AOA_CSCP_AOADataSubclass = 0xFF, /**< Descriptor Subclass value indicating that the device or interface + * belongs to AOA data subclass. + */ + AOA_CSCP_AOADataProtocol = 0x00, /**< Descriptor Protocol value indicating that the device or interface + * belongs to the AOA data class protocol. + */ + }; + + /** Enum for the Android Open Accessory class specific control requests that can be issued by the USB bus host. */ + enum AOA_ClassRequests_t + { + AOA_REQ_GetAccessoryProtocol = 0x33, /**< Android Open Accessory control request to retrieve the device's supported Accessory Protocol version. */ + AOA_REQ_SendString = 0x34, /**< Android Open Accessory control request to set an accessory property string in the device. */ + AOA_REQ_StartAccessoryMode = 0x35, /**< Android Open Accessory control request to switch the device into Accessory mode. */ + }; + + /** Enum for the possible Android Open Accessory property string indexes. */ + enum AOA_Strings_t + { + AOA_STRING_Manufacturer = 0, /**< Index of the Manufacturer property string. */ + AOA_STRING_Model = 1, /**< Index of the Model Name property string. */ + AOA_STRING_Description = 2, /**< Index of the Description property string. */ + AOA_STRING_Version = 3, /**< Index of the Version Number property string. */ + AOA_STRING_URI = 4, /**< Index of the URI Information property string. */ + AOA_STRING_Serial = 5, /**< Index of the Serial Number property string. */ + + #if !defined(__DOXYGEN__) + AOA_STRING_TOTAL_STRINGS + #endif + }; + + /** Enum for the possible Android Open Accessory protocol versions. */ + enum AOA_Protocols_t + { + AOA_PROTOCOL_AccessoryV1 = 0x0001, /**< Android Open Accessory version 1. */ + AOA_PROTOCOL_AccessoryV2 = 0x0002, /**< Android Open Accessory version 2. */ + }; + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ + + diff --git a/LUFA/Drivers/USB/Class/Common/AudioClassCommon.h b/LUFA/Drivers/USB/Class/Common/AudioClassCommon.h new file mode 100644 index 0000000000..46ecd08587 --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/AudioClassCommon.h @@ -0,0 +1,780 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Common definitions and declarations for the library USB Audio 1.0 Class driver. + * + * Common definitions and declarations for the library USB Audio 1.0 Class driver. + * + * \note This file should not be included directly. It is automatically included as needed by the USB module driver + * dispatch header located in LUFA/Drivers/USB.h. + */ + +/** \ingroup Group_USBClassAudio + * \defgroup Group_USBClassAudioCommon Common Class Definitions + * + * \section Sec_USBClassAudioCommon_ModDescription Module Description + * Constants, Types and Enum definitions that are common to both Device and Host modes for the USB + * Audio 1.0 Class. + * + * @{ + */ + +#ifndef _AUDIO_CLASS_COMMON_H_ +#define _AUDIO_CLASS_COMMON_H_ + + /* Includes: */ + #include "../../Core/StdDescriptors.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_AUDIO_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. + #endif + + /* Macros: */ + /** \name Audio Channel Masks */ + //@{ + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_LEFT_FRONT (1 << 0) + + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_RIGHT_FRONT (1 << 1) + + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_CENTER_FRONT (1 << 2) + + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_LOW_FREQ_ENHANCE (1 << 3) + + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_LEFT_SURROUND (1 << 4) + + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_RIGHT_SURROUND (1 << 5) + + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_LEFT_OF_CENTER (1 << 6) + + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_RIGHT_OF_CENTER (1 << 7) + + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_SURROUND (1 << 8) + + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_SIDE_LEFT (1 << 9) + + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_SIDE_RIGHT (1 << 10) + + /** Supported channel mask for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_CHANNEL_TOP (1 << 11) + //@} + + /** \name Audio Feature Masks */ + //@{ + /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */ + #define AUDIO_FEATURE_MUTE (1 << 0) + + /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */ + #define AUDIO_FEATURE_VOLUME (1 << 1) + + /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */ + #define AUDIO_FEATURE_BASS (1 << 2) + + /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */ + #define AUDIO_FEATURE_MID (1 << 3) + + /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */ + #define AUDIO_FEATURE_TREBLE (1 << 4) + + /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */ + #define AUDIO_FEATURE_GRAPHIC_EQUALIZER (1 << 5) + + /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */ + #define AUDIO_FEATURE_AUTOMATIC_GAIN (1 << 6) + + /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */ + #define AUDIO_FEATURE_DELAY (1 << 7) + + /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */ + #define AUDIO_FEATURE_BASS_BOOST (1 << 8) + + /** Supported feature mask for an Audio class feature unit descriptor. See the Audio class specification for more details. */ + #define AUDIO_FEATURE_BASS_LOUDNESS (1 << 9) + //@} + + /** \name Audio Terminal Types */ + //@{ + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_UNDEFINED 0x0100 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_STREAMING 0x0101 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_VENDOR 0x01FF + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_IN_UNDEFINED 0x0200 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_IN_MIC 0x0201 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_IN_DESKTOP_MIC 0x0202 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_IN_PERSONAL_MIC 0x0203 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_IN_OMNIDIR_MIC 0x0204 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_IN_MIC_ARRAY 0x0205 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_IN_PROCESSING_MIC 0x0206 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_IN_OUT_UNDEFINED 0x0300 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_OUT_SPEAKER 0x0301 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_OUT_HEADPHONES 0x0302 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_OUT_HEAD_MOUNTED 0x0303 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_OUT_DESKTOP 0x0304 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_OUT_ROOM 0x0305 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_OUT_COMMUNICATION 0x0306 + + /** Terminal type constant for an Audio class terminal descriptor. See the Audio class specification for more details. */ + #define AUDIO_TERMINAL_OUT_LOWFREQ 0x0307 + //@} + + /** Convenience macro to fill a 24-bit \ref USB_Audio_SampleFreq_t structure with the given sample rate as a 24-bit number. + * + * \param[in] freq Required audio sampling frequency in HZ + */ + #define AUDIO_SAMPLE_FREQ(freq) {.Byte1 = ((uint32_t)freq & 0xFF), .Byte2 = (((uint32_t)freq >> 8) & 0xFF), .Byte3 = (((uint32_t)freq >> 16) & 0xFF)} + + /** Mask for the attributes parameter of an Audio class-specific Endpoint descriptor, indicating that the endpoint + * accepts only filled endpoint packets of audio samples. + */ + #define AUDIO_EP_FULL_PACKETS_ONLY (1 << 7) + + /** Mask for the attributes parameter of an Audio class-specific Endpoint descriptor, indicating that the endpoint + * will accept partially filled endpoint packets of audio samples. + */ + #define AUDIO_EP_ACCEPTS_SMALL_PACKETS (0 << 7) + + /** Mask for the attributes parameter of an Audio class-specific Endpoint descriptor, indicating that the endpoint + * allows for sampling frequency adjustments to be made via control requests directed at the endpoint. + */ + #define AUDIO_EP_SAMPLE_FREQ_CONTROL (1 << 0) + + /** Mask for the attributes parameter of an Audio class-specific Endpoint descriptor, indicating that the endpoint + * allows for pitch adjustments to be made via control requests directed at the endpoint. + */ + #define AUDIO_EP_PITCH_CONTROL (1 << 1) + + /* Enums: */ + /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the Audio + * device class. + */ + enum Audio_Descriptor_ClassSubclassProtocol_t + { + AUDIO_CSCP_AudioClass = 0x01, /**< Descriptor Class value indicating that the device or + * interface belongs to the USB Audio 1.0 class. + */ + AUDIO_CSCP_ControlSubclass = 0x01, /**< Descriptor Subclass value indicating that the device or + * interface belongs to the Audio Control subclass. + */ + AUDIO_CSCP_ControlProtocol = 0x00, /**< Descriptor Protocol value indicating that the device or + * interface belongs to the Audio Control protocol. + */ + AUDIO_CSCP_AudioStreamingSubclass = 0x02, /**< Descriptor Subclass value indicating that the device or + * interface belongs to the MIDI Streaming subclass. + */ + AUDIO_CSCP_MIDIStreamingSubclass = 0x03, /**< Descriptor Subclass value indicating that the device or + * interface belongs to the Audio streaming subclass. + */ + AUDIO_CSCP_StreamingProtocol = 0x00, /**< Descriptor Protocol value indicating that the device or + * interface belongs to the Streaming Audio protocol. + */ + }; + + /** Audio class specific interface description subtypes, for the Audio Control interface. */ + enum Audio_CSInterface_AC_SubTypes_t + { + AUDIO_DSUBTYPE_CSInterface_Header = 0x01, /**< Audio class specific control interface header. */ + AUDIO_DSUBTYPE_CSInterface_InputTerminal = 0x02, /**< Audio class specific control interface Input Terminal. */ + AUDIO_DSUBTYPE_CSInterface_OutputTerminal = 0x03, /**< Audio class specific control interface Output Terminal. */ + AUDIO_DSUBTYPE_CSInterface_Mixer = 0x04, /**< Audio class specific control interface Mixer Unit. */ + AUDIO_DSUBTYPE_CSInterface_Selector = 0x05, /**< Audio class specific control interface Selector Unit. */ + AUDIO_DSUBTYPE_CSInterface_Feature = 0x06, /**< Audio class specific control interface Feature Unit. */ + AUDIO_DSUBTYPE_CSInterface_Processing = 0x07, /**< Audio class specific control interface Processing Unit. */ + AUDIO_DSUBTYPE_CSInterface_Extension = 0x08, /**< Audio class specific control interface Extension Unit. */ + }; + + /** Audio class specific interface description subtypes, for the Audio Streaming interface. */ + enum Audio_CSInterface_AS_SubTypes_t + { + AUDIO_DSUBTYPE_CSInterface_General = 0x01, /**< Audio class specific streaming interface general descriptor. */ + AUDIO_DSUBTYPE_CSInterface_FormatType = 0x02, /**< Audio class specific streaming interface format type descriptor. */ + AUDIO_DSUBTYPE_CSInterface_FormatSpecific = 0x03, /**< Audio class specific streaming interface format information descriptor. */ + }; + + /** Audio class specific endpoint description subtypes, for the Audio Streaming interface. */ + enum Audio_CSEndpoint_SubTypes_t + { + AUDIO_DSUBTYPE_CSEndpoint_General = 0x01, /**< Audio class specific endpoint general descriptor. */ + }; + + /** Enum for the Audio class specific control requests that can be issued by the USB bus host. */ + enum Audio_ClassRequests_t + { + AUDIO_REQ_SetCurrent = 0x01, /**< Audio class-specific request to set the current value of a parameter within the device. */ + AUDIO_REQ_SetMinimum = 0x02, /**< Audio class-specific request to set the minimum value of a parameter within the device. */ + AUDIO_REQ_SetMaximum = 0x03, /**< Audio class-specific request to set the maximum value of a parameter within the device. */ + AUDIO_REQ_SetResolution = 0x04, /**< Audio class-specific request to set the resolution value of a parameter within the device. */ + AUDIO_REQ_SetMemory = 0x05, /**< Audio class-specific request to set the memory value of a parameter within the device. */ + AUDIO_REQ_GetCurrent = 0x81, /**< Audio class-specific request to get the current value of a parameter within the device. */ + AUDIO_REQ_GetMinimum = 0x82, /**< Audio class-specific request to get the minimum value of a parameter within the device. */ + AUDIO_REQ_GetMaximum = 0x83, /**< Audio class-specific request to get the maximum value of a parameter within the device. */ + AUDIO_REQ_GetResolution = 0x84, /**< Audio class-specific request to get the resolution value of a parameter within the device. */ + AUDIO_REQ_GetMemory = 0x85, /**< Audio class-specific request to get the memory value of a parameter within the device. */ + AUDIO_REQ_GetStatus = 0xFF, /**< Audio class-specific request to get the device status. */ + }; + + /** Enum for Audio class specific Endpoint control modifiers which can be set and retrieved by a USB host, if the corresponding + * endpoint control is indicated to be supported in the Endpoint's Audio-class specific endpoint descriptor. + */ + enum Audio_EndpointControls_t + { + AUDIO_EPCONTROL_SamplingFreq = 0x01, /**< Sampling frequency adjustment of the endpoint. */ + AUDIO_EPCONTROL_Pitch = 0x02, /**< Pitch adjustment of the endpoint. */ + }; + + /* Type Defines: */ + /** \brief Audio class-specific Input Terminal Descriptor (LUFA naming conventions). + * + * 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. + * + * \see \ref USB_Audio_StdDescriptor_InputTerminal_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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, + * must be \ref AUDIO_DSUBTYPE_CSInterface_InputTerminal. + */ + + uint8_t TerminalID; /**< ID value of this terminal unit - must be a unique value within the device. */ + uint16_t TerminalType; /**< Type of terminal, a \c 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; /**< \c 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. */ + } ATTR_PACKED USB_Audio_Descriptor_InputTerminal_t; + + /** \brief Audio class-specific Input Terminal Descriptor (USB-IF naming conventions). + * + * 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. + * + * \see \ref USB_Audio_Descriptor_InputTerminal_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + + uint8_t bDescriptorSubtype; /**< Sub type value used to distinguish between audio class-specific descriptors, + * must be \ref AUDIO_DSUBTYPE_CSInterface_InputTerminal. + */ + uint8_t bTerminalID; /**< ID value of this terminal unit - must be a unique value within the device. */ + uint16_t wTerminalType; /**< Type of terminal, a \c TERMINAL_* mask. */ + uint8_t bAssocTerminal; /**< ID of associated output terminal, for physically grouped terminals + * such as the speaker and microphone of a phone handset. + */ + uint8_t bNrChannels; /**< Total number of separate audio channels within this interface (right, left, etc.) */ + uint16_t wChannelConfig; /**< \c CHANNEL_* masks indicating what channel layout is supported by this terminal. */ + + uint8_t iChannelNames; /**< Index of a string descriptor describing this channel within the device. */ + uint8_t iTerminal; /**< Index of a string descriptor describing this descriptor within the device. */ + } ATTR_PACKED USB_Audio_StdDescriptor_InputTerminal_t; + + /** \brief Audio class-specific Output Terminal Descriptor (LUFA naming conventions). + * + * 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. + * + * \see \ref USB_Audio_StdDescriptor_OutputTerminal_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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, + * must be \ref AUDIO_DSUBTYPE_CSInterface_OutputTerminal. + */ + + uint8_t TerminalID; /**< ID value of this terminal unit - must be a unique value within the device. */ + uint16_t TerminalType; /**< Type of terminal, a \c 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. */ + } ATTR_PACKED USB_Audio_Descriptor_OutputTerminal_t; + + /** \brief Audio class-specific Output Terminal Descriptor (USB-IF naming conventions). + * + * 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. + * + * \see \ref USB_Audio_Descriptor_OutputTerminal_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Sub type value used to distinguish between audio class-specific descriptors, + * must be \ref AUDIO_DSUBTYPE_CSInterface_OutputTerminal. + */ + + uint8_t bDescriptorSubtype; /**< Sub type value used to distinguish between audio class-specific descriptors, + * a value from the \ref Audio_CSInterface_AC_SubTypes_t enum. + */ + uint8_t bTerminalID; /**< ID value of this terminal unit - must be a unique value within the device. */ + uint16_t wTerminalType; /**< Type of terminal, a \c TERMINAL_* mask. */ + uint8_t bAssocTerminal; /**< ID of associated input terminal, for physically grouped terminals + * such as the speaker and microphone of a phone handset. + */ + uint8_t bSourceID; /**< ID value of the unit this terminal's audio is sourced from. */ + + uint8_t iTerminal; /**< Index of a string descriptor describing this descriptor within the device. */ + } ATTR_PACKED USB_Audio_StdDescriptor_OutputTerminal_t; + + /** \brief Audio class-specific Interface Descriptor (LUFA naming conventions). + * + * Type define for an Audio class-specific interface descriptor. This follows a regular interface descriptor to + * supply extra information about the audio device's layout to the host. See the USB Audio specification for more + * details. + * + * \see \ref USB_Audio_StdDescriptor_Interface_AC_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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, + * a value from the \ref Audio_CSInterface_AS_SubTypes_t enum. + */ + + uint16_t ACSpecification; /**< Binary Coded Decimal value, indicating the supported Audio Class specification version. + * + * \see \ref VERSION_BCD() utility macro. + */ + uint16_t TotalLength; /**< Total length of the Audio class-specific descriptors, including this descriptor. */ + + uint8_t InCollection; /**< Total number of Audio Streaming interfaces linked to this Audio Control interface (must be 1). */ + uint8_t InterfaceNumber; /**< Interface number of the associated Audio Streaming interface. */ + } ATTR_PACKED USB_Audio_Descriptor_Interface_AC_t; + + /** \brief Audio class-specific Interface Descriptor (USB-IF naming conventions). + * + * Type define for an Audio class-specific interface descriptor. This follows a regular interface descriptor to + * supply extra information about the audio device's layout to the host. See the USB Audio specification for more + * details. + * + * \see \ref USB_Audio_Descriptor_Interface_AC_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + + uint8_t bDescriptorSubtype;/**< Sub type value used to distinguish between audio class-specific descriptors, + * a value from the \ref Audio_CSInterface_AS_SubTypes_t enum. + */ + + uint16_t bcdADC; /**< Binary coded decimal value, indicating the supported Audio Class specification version. + * + * \see \ref VERSION_BCD() utility macro. + */ + uint16_t wTotalLength; /**< Total length of the Audio class-specific descriptors, including this descriptor. */ + + uint8_t bInCollection; /**< Total number of Audio Streaming interfaces linked to this Audio Control interface (must be 1). */ + uint8_t bInterfaceNumbers; /**< Interface number of the associated Audio Streaming interface. */ + } ATTR_PACKED USB_Audio_StdDescriptor_Interface_AC_t; + + /** \brief Audio class-specific Feature Unit Descriptor (LUFA naming conventions). + * + * 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. + * + * \see \ref USB_Audio_StdDescriptor_FeatureUnit_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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, + * must be \ref AUDIO_DSUBTYPE_CSInterface_Feature. + */ + + 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 \c ChannelControls 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. */ + } ATTR_PACKED USB_Audio_Descriptor_FeatureUnit_t; + + /** \brief Audio class-specific Feature Unit Descriptor (USB-IF naming conventions). + * + * 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. + * + * \see \ref USB_Audio_Descriptor_FeatureUnit_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + + uint8_t bDescriptorSubtype; /**< Sub type value used to distinguish between audio class-specific descriptors, + * must be \ref AUDIO_DSUBTYPE_CSInterface_Feature. + */ + + uint8_t bUnitID; /**< ID value of this feature unit - must be a unique value within the device. */ + uint8_t bSourceID; /**< Source ID value of the audio source input into this feature unit. */ + + uint8_t bControlSize; /**< Size of each element in the \c ChannelControls array. */ + uint8_t bmaControls[3]; /**< Feature masks for the control channel, and each separate audio channel. */ + + uint8_t iFeature; /**< Index of a string descriptor describing this descriptor within the device. */ + } ATTR_PACKED USB_Audio_StdDescriptor_FeatureUnit_t; + + /** \brief Audio class-specific Streaming Audio Interface Descriptor (LUFA naming conventions). + * + * 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. + * + * \see \ref USB_Audio_StdDescriptor_Interface_AS_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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, + * a value from the \ref Audio_CSInterface_AS_SubTypes_t enum. + */ + + 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. */ + } ATTR_PACKED USB_Audio_Descriptor_Interface_AS_t; + + /** \brief Audio class-specific Streaming Audio Interface Descriptor (USB-IF naming conventions). + * + * 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. + * + * \see \ref USB_Audio_Descriptor_Interface_AS_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + + uint8_t bDescriptorSubtype; /**< Sub type value used to distinguish between audio class-specific descriptors, + * a value from the \ref Audio_CSInterface_AS_SubTypes_t enum. + */ + + uint8_t bTerminalLink; /**< ID value of the output terminal this descriptor is describing. */ + + uint8_t bDelay; /**< Delay in frames resulting from the complete sample processing from input to output. */ + uint16_t wFormatTag; /**< Format of the audio stream, see Audio Device Formats specification. */ + } ATTR_PACKED USB_Audio_StdDescriptor_Interface_AS_t; + + /** \brief Audio class-specific Format Descriptor (LUFA naming conventions). + * + * 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. + * + * \attention This descriptor <b>must</b> be followed by one or more \ref USB_Audio_SampleFreq_t elements containing + * the continuous or discrete sample frequencies. + * + * \see \ref USB_Audio_StdDescriptor_Format_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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, + * must be \ref AUDIO_DSUBTYPE_CSInterface_FormatType. + */ + + 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 TotalDiscreteSampleRates; /**< Total number of discrete sample frequencies supported by the device. When + * zero, this must be followed by the lower and upper continuous sampling + * frequencies supported by the device; otherwise, this must be followed + * by the given number of discrete sampling frequencies supported. + */ + } ATTR_PACKED USB_Audio_Descriptor_Format_t; + + /** \brief 24-Bit Audio Frequency Structure. + * + * Type define for a 24-bit audio sample frequency structure. As GCC does not contain a built in 24-bit datatype, + * this this structure is used to build up the value instead. Fill this structure with the \ref AUDIO_SAMPLE_FREQ() macro. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t Byte1; /**< Lowest 8 bits of the 24-bit value. */ + uint8_t Byte2; /**< Middle 8 bits of the 24-bit value. */ + uint8_t Byte3; /**< Upper 8 bits of the 24-bit value. */ + } ATTR_PACKED USB_Audio_SampleFreq_t; + + /** \brief Audio class-specific Format Descriptor (USB-IF naming conventions). + * + * 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. + * + * \attention This descriptor <b>must</b> be followed by one or more 24-bit integer elements containing the continuous + * or discrete sample frequencies. + * + * \see \ref USB_Audio_Descriptor_Format_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Sub type value used to distinguish between audio class-specific descriptors, + * must be \ref AUDIO_DSUBTYPE_CSInterface_FormatType. + */ + + uint8_t bDescriptorSubtype;/**< Sub type value used to distinguish between audio class-specific descriptors, + * a value from the \ref Audio_CSInterface_AS_SubTypes_t enum. + */ + + uint8_t bFormatType; /**< Format of the audio stream, see Audio Device Formats specification. */ + uint8_t bNrChannels; /**< Total number of discrete channels in the stream. */ + + uint8_t bSubFrameSize; /**< Size in bytes of each channel's sample data in the stream. */ + uint8_t bBitResolution; /**< Bits of resolution of each channel's samples in the stream. */ + + uint8_t bSampleFrequencyType; /**< Total number of sample frequencies supported by the device. When + * zero, this must be followed by the lower and upper continuous sampling + * frequencies supported by the device; otherwise, this must be followed + * by the given number of discrete sampling frequencies supported. + */ + } ATTR_PACKED USB_Audio_StdDescriptor_Format_t; + + /** \brief Audio class-specific Streaming Endpoint Descriptor (LUFA naming conventions). + * + * 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. + * + * \see \ref USB_Audio_StdDescriptor_StreamEndpoint_Std_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + USB_Descriptor_Endpoint_t Endpoint; /**< Standard endpoint descriptor describing the audio endpoint. */ + + uint8_t Refresh; /**< Always set to zero for Audio class devices. */ + uint8_t SyncEndpointNumber; /**< Endpoint address to send synchronization information to, if needed (zero otherwise). */ + } ATTR_PACKED USB_Audio_Descriptor_StreamEndpoint_Std_t; + + /** \brief Audio class-specific Streaming Endpoint Descriptor (USB-IF naming conventions). + * + * 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. + * + * \see \ref USB_Audio_Descriptor_StreamEndpoint_Std_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a + * value given by the specific class. + */ + uint8_t bEndpointAddress; /**< Logical address of the endpoint within the device for the current + * configuration, including direction mask. + */ + uint8_t bmAttributes; /**< Endpoint attributes, comprised of a mask of the endpoint type (\c EP_TYPE_*) + * and attributes (\c ENDPOINT_ATTR_*) masks. + */ + uint16_t wMaxPacketSize; /**< Size of the endpoint bank, in bytes. This indicates the maximum packet size + * that the endpoint can receive at a time. + */ + uint8_t bInterval; /**< Polling interval in milliseconds for the endpoint if it is an INTERRUPT or + * ISOCHRONOUS type. + */ + + uint8_t bRefresh; /**< Always set to zero for Audio class devices. */ + uint8_t bSynchAddress; /**< Endpoint address to send synchronization information to, if needed (zero otherwise). */ + } ATTR_PACKED USB_Audio_StdDescriptor_StreamEndpoint_Std_t; + + /** \brief Audio class-specific Extended Endpoint Descriptor (LUFA naming conventions). + * + * 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. + * + * \see \ref USB_Audio_StdDescriptor_StreamEndpoint_Spc_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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, + * a value from the \ref Audio_CSEndpoint_SubTypes_t enum. + */ + + uint8_t Attributes; /**< Audio class-specific endpoint attributes, such as \ref AUDIO_EP_FULL_PACKETS_ONLY. */ + + 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. */ + } ATTR_PACKED USB_Audio_Descriptor_StreamEndpoint_Spc_t; + + /** \brief Audio class-specific Extended Endpoint Descriptor (USB-IF naming conventions). + * + * 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. + * + * \see \ref USB_Audio_Descriptor_StreamEndpoint_Spc_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + + uint8_t bDescriptorSubtype; /**< Sub type value used to distinguish between audio class-specific descriptors, + * a value from the \ref Audio_CSEndpoint_SubTypes_t enum. + */ + + uint8_t bmAttributes; /**< Audio class-specific endpoint attributes, such as \ref AUDIO_EP_FULL_PACKETS_ONLY. */ + + uint8_t bLockDelayUnits; /**< Units used for the LockDelay field, see Audio class specification. */ + uint16_t wLockDelay; /**< Time required to internally lock endpoint's internal clock recovery circuitry. */ + } ATTR_PACKED USB_Audio_StdDescriptor_StreamEndpoint_Spc_t; + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ + diff --git a/LUFA/Drivers/USB/Class/Common/CDCClassCommon.h b/LUFA/Drivers/USB/Class/Common/CDCClassCommon.h new file mode 100644 index 0000000000..1ad49eca14 --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/CDCClassCommon.h @@ -0,0 +1,391 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Common definitions and declarations for the library USB CDC Class driver. + * + * Common definitions and declarations for the library USB CDC Class driver. + * + * \note This file should not be included directly. It is automatically included as needed by the USB module driver + * dispatch header located in LUFA/Drivers/USB.h. + */ + +/** \ingroup Group_USBClassCDC + * \defgroup Group_USBClassCDCCommon Common Class Definitions + * + * \section Sec_USBClassCDCCommon_ModDescription Module Description + * Constants, Types and Enum definitions that are common to both Device and Host modes for the USB + * CDC Class. + * + * @{ + */ + +#ifndef _CDC_CLASS_COMMON_H_ +#define _CDC_CLASS_COMMON_H_ + + /* Includes: */ + #include "../../Core/StdDescriptors.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_CDC_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. + #endif + + /* Macros: */ + /** \name Virtual Control Line Masks */ + //@{ + /** Mask for the DTR handshake line for use with the \ref CDC_REQ_SetControlLineState class-specific request + * from the host, to indicate that the DTR line state should be high. + */ + #define CDC_CONTROL_LINE_OUT_DTR (1 << 0) + + /** Mask for the RTS handshake line for use with the \ref CDC_REQ_SetControlLineState class-specific request + * from the host, to indicate that the RTS line state should be high. + */ + #define CDC_CONTROL_LINE_OUT_RTS (1 << 1) + + /** Mask for the DCD handshake line for use with the \ref CDC_NOTIF_SerialState class-specific notification + * from the device to the host, to indicate that the DCD line state is currently high. + */ + #define CDC_CONTROL_LINE_IN_DCD (1 << 0) + + /** Mask for the DSR handshake line for use with the \ref CDC_NOTIF_SerialState class-specific notification + * from the device to the host, to indicate that the DSR line state is currently high. + */ + #define CDC_CONTROL_LINE_IN_DSR (1 << 1) + + /** Mask for the BREAK handshake line for use with the \ref CDC_NOTIF_SerialState class-specific notification + * from the device to the host, to indicate that the BREAK line state is currently high. + */ + #define CDC_CONTROL_LINE_IN_BREAK (1 << 2) + + /** Mask for the RING handshake line for use with the \ref CDC_NOTIF_SerialState class-specific notification + * from the device to the host, to indicate that the RING line state is currently high. + */ + #define CDC_CONTROL_LINE_IN_RING (1 << 3) + + /** Mask for use with the \ref CDC_NOTIF_SerialState class-specific notification from the device to the host, + * to indicate that a framing error has occurred on the virtual serial port. + */ + #define CDC_CONTROL_LINE_IN_FRAMEERROR (1 << 4) + + /** Mask for use with the \ref CDC_NOTIF_SerialState class-specific notification from the device to the host, + * to indicate that a parity error has occurred on the virtual serial port. + */ + #define CDC_CONTROL_LINE_IN_PARITYERROR (1 << 5) + + /** Mask for use with the \ref CDC_NOTIF_SerialState class-specific notification from the device to the host, + * to indicate that a data overrun error has occurred on the virtual serial port. + */ + #define CDC_CONTROL_LINE_IN_OVERRUNERROR (1 << 6) + //@} + + /** Macro to define a CDC class-specific functional descriptor. CDC functional descriptors have a + * uniform structure but variable sized data payloads, thus cannot be represented accurately by + * a single \c typedef \c struct. A macro is used instead so that functional descriptors can be created + * easily by specifying the size of the payload. This allows \c sizeof() to work correctly. + * + * \param[in] DataSize Size in bytes of the CDC functional descriptor's data payload. + */ + #define CDC_FUNCTIONAL_DESCRIPTOR(DataSize) \ + struct \ + { \ + USB_Descriptor_Header_t Header; \ + uint8_t SubType; \ + uint8_t Data[DataSize]; \ + } + + /* Enums: */ + /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the CDC + * device class. + */ + enum CDC_Descriptor_ClassSubclassProtocol_t + { + CDC_CSCP_CDCClass = 0x02, /**< Descriptor Class value indicating that the device or interface + * belongs to the CDC class. + */ + CDC_CSCP_NoSpecificSubclass = 0x00, /**< Descriptor Subclass value indicating that the device or interface + * belongs to no specific subclass of the CDC class. + */ + CDC_CSCP_ACMSubclass = 0x02, /**< Descriptor Subclass value indicating that the device or interface + * belongs to the Abstract Control Model CDC subclass. + */ + CDC_CSCP_ATCommandProtocol = 0x01, /**< Descriptor Protocol value indicating that the device or interface + * belongs to the AT Command protocol of the CDC class. + */ + CDC_CSCP_NoSpecificProtocol = 0x00, /**< Descriptor Protocol value indicating that the device or interface + * belongs to no specific protocol of the CDC class. + */ + CDC_CSCP_VendorSpecificProtocol = 0xFF, /**< Descriptor Protocol value indicating that the device or interface + * belongs to a vendor-specific protocol of the CDC class. + */ + CDC_CSCP_CDCDataClass = 0x0A, /**< Descriptor Class value indicating that the device or interface + * belongs to the CDC Data class. + */ + CDC_CSCP_NoDataSubclass = 0x00, /**< Descriptor Subclass value indicating that the device or interface + * belongs to no specific subclass of the CDC data class. + */ + CDC_CSCP_NoDataProtocol = 0x00, /**< Descriptor Protocol value indicating that the device or interface + * belongs to no specific protocol of the CDC data class. + */ + }; + + /** Enum for the CDC class specific control requests that can be issued by the USB bus host. */ + enum CDC_ClassRequests_t + { + CDC_REQ_SendEncapsulatedCommand = 0x00, /**< CDC class-specific request to send an encapsulated command to the device. */ + CDC_REQ_GetEncapsulatedResponse = 0x01, /**< CDC class-specific request to retrieve an encapsulated command response from the device. */ + CDC_REQ_SetLineEncoding = 0x20, /**< CDC class-specific request to set the current virtual serial port configuration settings. */ + CDC_REQ_GetLineEncoding = 0x21, /**< CDC class-specific request to get the current virtual serial port configuration settings. */ + CDC_REQ_SetControlLineState = 0x22, /**< CDC class-specific request to set the current virtual serial port handshake line states. */ + CDC_REQ_SendBreak = 0x23, /**< CDC class-specific request to send a break to the receiver via the carrier channel. */ + }; + + /** Enum for the CDC class specific notification requests that can be issued by a CDC device to a host. */ + enum CDC_ClassNotifications_t + { + CDC_NOTIF_SerialState = 0x20, /**< Notification type constant for a change in the virtual serial port + * handshake line states, for use with a \ref USB_Request_Header_t + * notification structure when sent to the host via the CDC notification + * endpoint. + */ + }; + + /** Enum for the CDC class specific interface descriptor subtypes. */ + enum CDC_DescriptorSubtypes_t + { + CDC_DSUBTYPE_CSInterface_Header = 0x00, /**< CDC class-specific Header functional descriptor. */ + CDC_DSUBTYPE_CSInterface_CallManagement = 0x01, /**< CDC class-specific Call Management functional descriptor. */ + CDC_DSUBTYPE_CSInterface_ACM = 0x02, /**< CDC class-specific Abstract Control Model functional descriptor. */ + CDC_DSUBTYPE_CSInterface_DirectLine = 0x03, /**< CDC class-specific Direct Line functional descriptor. */ + CDC_DSUBTYPE_CSInterface_TelephoneRinger = 0x04, /**< CDC class-specific Telephone Ringer functional descriptor. */ + CDC_DSUBTYPE_CSInterface_TelephoneCall = 0x05, /**< CDC class-specific Telephone Call functional descriptor. */ + CDC_DSUBTYPE_CSInterface_Union = 0x06, /**< CDC class-specific Union functional descriptor. */ + CDC_DSUBTYPE_CSInterface_CountrySelection = 0x07, /**< CDC class-specific Country Selection functional descriptor. */ + CDC_DSUBTYPE_CSInterface_TelephoneOpModes = 0x08, /**< CDC class-specific Telephone Operation Modes functional descriptor. */ + CDC_DSUBTYPE_CSInterface_USBTerminal = 0x09, /**< CDC class-specific USB Terminal functional descriptor. */ + CDC_DSUBTYPE_CSInterface_NetworkChannel = 0x0A, /**< CDC class-specific Network Channel functional descriptor. */ + CDC_DSUBTYPE_CSInterface_ProtocolUnit = 0x0B, /**< CDC class-specific Protocol Unit functional descriptor. */ + CDC_DSUBTYPE_CSInterface_ExtensionUnit = 0x0C, /**< CDC class-specific Extension Unit functional descriptor. */ + CDC_DSUBTYPE_CSInterface_MultiChannel = 0x0D, /**< CDC class-specific Multi-Channel Management functional descriptor. */ + CDC_DSUBTYPE_CSInterface_CAPI = 0x0E, /**< CDC class-specific Common ISDN API functional descriptor. */ + CDC_DSUBTYPE_CSInterface_Ethernet = 0x0F, /**< CDC class-specific Ethernet functional descriptor. */ + CDC_DSUBTYPE_CSInterface_ATM = 0x10, /**< CDC class-specific Asynchronous Transfer Mode functional descriptor. */ + }; + + /** Enum for the possible line encoding formats of a virtual serial port. */ + enum CDC_LineEncodingFormats_t + { + CDC_LINEENCODING_OneStopBit = 0, /**< Each frame contains one stop bit. */ + CDC_LINEENCODING_OneAndAHalfStopBits = 1, /**< Each frame contains one and a half stop bits. */ + CDC_LINEENCODING_TwoStopBits = 2, /**< Each frame contains two stop bits. */ + }; + + /** Enum for the possible line encoding parity settings of a virtual serial port. */ + enum CDC_LineEncodingParity_t + { + CDC_PARITY_None = 0, /**< No parity bit mode on each frame. */ + CDC_PARITY_Odd = 1, /**< Odd parity bit mode on each frame. */ + CDC_PARITY_Even = 2, /**< Even parity bit mode on each frame. */ + CDC_PARITY_Mark = 3, /**< Mark parity bit mode on each frame. */ + CDC_PARITY_Space = 4, /**< Space parity bit mode on each frame. */ + }; + + /* Type Defines: */ + /** \brief CDC class-specific Functional Header Descriptor (LUFA naming conventions). + * + * Type define for a CDC class-specific functional header descriptor. This indicates to the host that the device + * contains one or more CDC functional data descriptors, which give the CDC interface's capabilities and configuration. + * See the CDC class specification for more details. + * + * \see \ref USB_CDC_StdDescriptor_FunctionalHeader_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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 CDC class-specific descriptors, + * must be \ref CDC_DSUBTYPE_CSInterface_Header. + */ + uint16_t CDCSpecification; /**< Version number of the CDC specification implemented by the device, + * encoded in BCD format. + * + * \see \ref VERSION_BCD() utility macro. + */ + } ATTR_PACKED USB_CDC_Descriptor_FunctionalHeader_t; + + /** \brief CDC class-specific Functional Header Descriptor (USB-IF naming conventions). + * + * Type define for a CDC class-specific functional header descriptor. This indicates to the host that the device + * contains one or more CDC functional data descriptors, which give the CDC interface's capabilities and configuration. + * See the CDC class specification for more details. + * + * \see \ref USB_CDC_Descriptor_FunctionalHeader_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bFunctionLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + uint8_t bDescriptorSubType; /**< Sub type value used to distinguish between CDC class-specific descriptors, + * must be \ref CDC_DSUBTYPE_CSInterface_Header. + */ + uint16_t bcdCDC; /**< Version number of the CDC specification implemented by the device, encoded in BCD format. + * + * \see \ref VERSION_BCD() utility macro. + */ + } ATTR_PACKED USB_CDC_StdDescriptor_FunctionalHeader_t; + + /** \brief CDC class-specific Functional ACM Descriptor (LUFA naming conventions). + * + * Type define for a CDC class-specific functional ACM descriptor. This indicates to the host that the CDC interface + * supports the CDC ACM subclass of the CDC specification. See the CDC class specification for more details. + * + * \see \ref USB_CDC_StdDescriptor_FunctionalACM_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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 CDC class-specific descriptors, + * must be \ref CDC_DSUBTYPE_CSInterface_ACM. + */ + uint8_t Capabilities; /**< Capabilities of the ACM interface, given as a bit mask. For most devices, + * this should be set to a fixed value of \c 0x06 - for other capabilities, refer + * to the CDC ACM specification. + */ + } ATTR_PACKED USB_CDC_Descriptor_FunctionalACM_t; + + /** \brief CDC class-specific Functional ACM Descriptor (USB-IF naming conventions). + * + * Type define for a CDC class-specific functional ACM descriptor. This indicates to the host that the CDC interface + * supports the CDC ACM subclass of the CDC specification. See the CDC class specification for more details. + * + * \see \ref USB_CDC_Descriptor_FunctionalACM_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bFunctionLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + uint8_t bDescriptorSubType; /**< Sub type value used to distinguish between CDC class-specific descriptors, + * must be \ref CDC_DSUBTYPE_CSInterface_ACM. + */ + uint8_t bmCapabilities; /**< Capabilities of the ACM interface, given as a bit mask. For most devices, + * this should be set to a fixed value of 0x06 - for other capabilities, refer + * to the CDC ACM specification. + */ + } ATTR_PACKED USB_CDC_StdDescriptor_FunctionalACM_t; + + /** \brief CDC class-specific Functional Union Descriptor (LUFA naming conventions). + * + * Type define for a CDC class-specific functional Union descriptor. This indicates to the host that specific + * CDC control and data interfaces are related. See the CDC class specification for more details. + * + * \see \ref USB_CDC_StdDescriptor_FunctionalUnion_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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 CDC class-specific descriptors, + * must be \ref CDC_DSUBTYPE_CSInterface_Union. + */ + uint8_t MasterInterfaceNumber; /**< Interface number of the CDC Control interface. */ + uint8_t SlaveInterfaceNumber; /**< Interface number of the CDC Data interface. */ + } ATTR_PACKED USB_CDC_Descriptor_FunctionalUnion_t; + + /** \brief CDC class-specific Functional Union Descriptor (USB-IF naming conventions). + * + * Type define for a CDC class-specific functional Union descriptor. This indicates to the host that specific + * CDC control and data interfaces are related. See the CDC class specification for more details. + * + * \see \ref USB_CDC_Descriptor_FunctionalUnion_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bFunctionLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + uint8_t bDescriptorSubType; /**< Sub type value used to distinguish between CDC class-specific descriptors, + * must be \ref CDC_DSUBTYPE_CSInterface_Union. + */ + uint8_t bMasterInterface; /**< Interface number of the CDC Control interface. */ + uint8_t bSlaveInterface0; /**< Interface number of the CDC Data interface. */ + } ATTR_PACKED USB_CDC_StdDescriptor_FunctionalUnion_t; + + /** \brief CDC Virtual Serial Port Line Encoding Settings Structure. + * + * Type define for a CDC Line Encoding structure, used to hold the various encoding parameters for a virtual + * serial port. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t BaudRateBPS; /**< Baud rate of the virtual serial port, in bits per second. */ + uint8_t CharFormat; /**< Character format of the virtual serial port, a value from the + * \ref CDC_LineEncodingFormats_t enum. + */ + uint8_t ParityType; /**< Parity setting of the virtual serial port, a value from the + * \ref CDC_LineEncodingParity_t enum. + */ + uint8_t DataBits; /**< Bits of data per character of the virtual serial port. */ + } ATTR_PACKED CDC_LineEncoding_t; + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ + diff --git a/LUFA/Drivers/USB/Class/Common/HIDClassCommon.h b/LUFA/Drivers/USB/Class/Common/HIDClassCommon.h new file mode 100644 index 0000000000..6e700a9b1e --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/HIDClassCommon.h @@ -0,0 +1,681 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Common definitions and declarations for the library USB HID Class driver. + * + * Common definitions and declarations for the library USB HID Class driver. + * + * \note This file should not be included directly. It is automatically included as needed by the USB module driver + * dispatch header located in LUFA/Drivers/USB.h. + */ + +/** \ingroup Group_USBClassHID + * \defgroup Group_USBClassHIDCommon Common Class Definitions + * + * \section Sec_USBClassHIDCommon_ModDescription Module Description + * Constants, Types and Enum definitions that are common to both Device and Host modes for the USB + * HID Class. + * + * @{ + */ + +#ifndef _HID_CLASS_COMMON_H_ +#define _HID_CLASS_COMMON_H_ + + /* Includes: */ + #include "../../Core/StdDescriptors.h" + #include "HIDParser.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_HID_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. + #endif + + /* Macros: */ + /** \name Keyboard Standard Report Modifier Masks */ + //@{ + /** Constant for a keyboard report modifier byte, indicating that the keyboard's left control key is currently pressed. */ + #define HID_KEYBOARD_MODIFIER_LEFTCTRL (1 << 0) + + /** Constant for a keyboard report modifier byte, indicating that the keyboard's left shift key is currently pressed. */ + #define HID_KEYBOARD_MODIFIER_LEFTSHIFT (1 << 1) + + /** Constant for a keyboard report modifier byte, indicating that the keyboard's left alt key is currently pressed. */ + #define HID_KEYBOARD_MODIFIER_LEFTALT (1 << 2) + + /** Constant for a keyboard report modifier byte, indicating that the keyboard's left GUI key is currently pressed. */ + #define HID_KEYBOARD_MODIFIER_LEFTGUI (1 << 3) + + /** Constant for a keyboard report modifier byte, indicating that the keyboard's right control key is currently pressed. */ + #define HID_KEYBOARD_MODIFIER_RIGHTCTRL (1 << 4) + + /** Constant for a keyboard report modifier byte, indicating that the keyboard's right shift key is currently pressed. */ + #define HID_KEYBOARD_MODIFIER_RIGHTSHIFT (1 << 5) + + /** Constant for a keyboard report modifier byte, indicating that the keyboard's right alt key is currently pressed. */ + #define HID_KEYBOARD_MODIFIER_RIGHTALT (1 << 6) + + /** Constant for a keyboard report modifier byte, indicating that the keyboard's right GUI key is currently pressed. */ + #define HID_KEYBOARD_MODIFIER_RIGHTGUI (1 << 7) + //@} + + /** \name Keyboard Standard Report LED Masks */ + //@{ + /** Constant for a keyboard output report LED byte, indicating that the host's NUM LOCK mode is currently set. */ + #define HID_KEYBOARD_LED_NUMLOCK (1 << 0) + + /** Constant for a keyboard output report LED byte, indicating that the host's CAPS LOCK mode is currently set. */ + #define HID_KEYBOARD_LED_CAPSLOCK (1 << 1) + + /** Constant for a keyboard output report LED byte, indicating that the host's SCROLL LOCK mode is currently set. */ + #define HID_KEYBOARD_LED_SCROLLLOCK (1 << 2) + + /** Constant for a keyboard output report LED byte, indicating that the host's COMPOSE mode is currently set. */ + #define HID_KEYBOARD_LED_COMPOSE (1 << 3) + + /** Constant for a keyboard output report LED byte, indicating that the host's KANA mode is currently set. */ + #define HID_KEYBOARD_LED_KANA (1 << 4) + //@} + + /** \name Keyboard Standard Report Key Scan-codes */ + //@{ + #define HID_KEYBOARD_SC_ERROR_ROLLOVER 0x01 + #define HID_KEYBOARD_SC_POST_FAIL 0x02 + #define HID_KEYBOARD_SC_ERROR_UNDEFINED 0x03 + #define HID_KEYBOARD_SC_A 0x04 + #define HID_KEYBOARD_SC_B 0x05 + #define HID_KEYBOARD_SC_C 0x06 + #define HID_KEYBOARD_SC_D 0x07 + #define HID_KEYBOARD_SC_E 0x08 + #define HID_KEYBOARD_SC_F 0x09 + #define HID_KEYBOARD_SC_G 0x0A + #define HID_KEYBOARD_SC_H 0x0B + #define HID_KEYBOARD_SC_I 0x0C + #define HID_KEYBOARD_SC_J 0x0D + #define HID_KEYBOARD_SC_K 0x0E + #define HID_KEYBOARD_SC_L 0x0F + #define HID_KEYBOARD_SC_M 0x10 + #define HID_KEYBOARD_SC_N 0x11 + #define HID_KEYBOARD_SC_O 0x12 + #define HID_KEYBOARD_SC_P 0x13 + #define HID_KEYBOARD_SC_Q 0x14 + #define HID_KEYBOARD_SC_R 0x15 + #define HID_KEYBOARD_SC_S 0x16 + #define HID_KEYBOARD_SC_T 0x17 + #define HID_KEYBOARD_SC_U 0x18 + #define HID_KEYBOARD_SC_V 0x19 + #define HID_KEYBOARD_SC_W 0x1A + #define HID_KEYBOARD_SC_X 0x1B + #define HID_KEYBOARD_SC_Y 0x1C + #define HID_KEYBOARD_SC_Z 0x1D + #define HID_KEYBOARD_SC_1_AND_EXCLAMATION 0x1E + #define HID_KEYBOARD_SC_2_AND_AT 0x1F + #define HID_KEYBOARD_SC_3_AND_HASHMARK 0x20 + #define HID_KEYBOARD_SC_4_AND_DOLLAR 0x21 + #define HID_KEYBOARD_SC_5_AND_PERCENTAGE 0x22 + #define HID_KEYBOARD_SC_6_AND_CARET 0x23 + #define HID_KEYBOARD_SC_7_AND_AMPERSAND 0x24 + #define HID_KEYBOARD_SC_8_AND_ASTERISK 0x25 + #define HID_KEYBOARD_SC_9_AND_OPENING_PARENTHESIS 0x26 + #define HID_KEYBOARD_SC_0_AND_CLOSING_PARENTHESIS 0x27 + #define HID_KEYBOARD_SC_ENTER 0x28 + #define HID_KEYBOARD_SC_ESCAPE 0x29 + #define HID_KEYBOARD_SC_BACKSPACE 0x2A + #define HID_KEYBOARD_SC_TAB 0x2B + #define HID_KEYBOARD_SC_SPACE 0x2C + #define HID_KEYBOARD_SC_MINUS_AND_UNDERSCORE 0x2D + #define HID_KEYBOARD_SC_EQUAL_AND_PLUS 0x2E + #define HID_KEYBOARD_SC_OPENING_BRACKET_AND_OPENING_BRACE 0x2F + #define HID_KEYBOARD_SC_CLOSING_BRACKET_AND_CLOSING_BRACE 0x30 + #define HID_KEYBOARD_SC_BACKSLASH_AND_PIPE 0x31 + #define HID_KEYBOARD_SC_NON_US_HASHMARK_AND_TILDE 0x32 + #define HID_KEYBOARD_SC_SEMICOLON_AND_COLON 0x33 + #define HID_KEYBOARD_SC_APOSTROPHE_AND_QUOTE 0x34 + #define HID_KEYBOARD_SC_GRAVE_ACCENT_AND_TILDE 0x35 + #define HID_KEYBOARD_SC_COMMA_AND_LESS_THAN_SIGN 0x36 + #define HID_KEYBOARD_SC_DOT_AND_GREATER_THAN_SIGN 0x37 + #define HID_KEYBOARD_SC_SLASH_AND_QUESTION_MARK 0x38 + #define HID_KEYBOARD_SC_CAPS_LOCK 0x39 + #define HID_KEYBOARD_SC_F1 0x3A + #define HID_KEYBOARD_SC_F2 0x3B + #define HID_KEYBOARD_SC_F3 0x3C + #define HID_KEYBOARD_SC_F4 0x3D + #define HID_KEYBOARD_SC_F5 0x3E + #define HID_KEYBOARD_SC_F6 0x3F + #define HID_KEYBOARD_SC_F7 0x40 + #define HID_KEYBOARD_SC_F8 0x41 + #define HID_KEYBOARD_SC_F9 0x42 + #define HID_KEYBOARD_SC_F10 0x43 + #define HID_KEYBOARD_SC_F11 0x44 + #define HID_KEYBOARD_SC_F12 0x45 + #define HID_KEYBOARD_SC_PRINT_SCREEN 0x46 + #define HID_KEYBOARD_SC_SCROLL_LOCK 0x47 + #define HID_KEYBOARD_SC_PAUSE 0x48 + #define HID_KEYBOARD_SC_INSERT 0x49 + #define HID_KEYBOARD_SC_HOME 0x4A + #define HID_KEYBOARD_SC_PAGE_UP 0x4B + #define HID_KEYBOARD_SC_DELETE 0x4C + #define HID_KEYBOARD_SC_END 0x4D + #define HID_KEYBOARD_SC_PAGE_DOWN 0x4E + #define HID_KEYBOARD_SC_RIGHT_ARROW 0x4F + #define HID_KEYBOARD_SC_LEFT_ARROW 0x50 + #define HID_KEYBOARD_SC_DOWN_ARROW 0x51 + #define HID_KEYBOARD_SC_UP_ARROW 0x52 + #define HID_KEYBOARD_SC_NUM_LOCK 0x53 + #define HID_KEYBOARD_SC_KEYPAD_SLASH 0x54 + #define HID_KEYBOARD_SC_KEYPAD_ASTERISK 0x55 + #define HID_KEYBOARD_SC_KEYPAD_MINUS 0x56 + #define HID_KEYBOARD_SC_KEYPAD_PLUS 0x57 + #define HID_KEYBOARD_SC_KEYPAD_ENTER 0x58 + #define HID_KEYBOARD_SC_KEYPAD_1_AND_END 0x59 + #define HID_KEYBOARD_SC_KEYPAD_2_AND_DOWN_ARROW 0x5A + #define HID_KEYBOARD_SC_KEYPAD_3_AND_PAGE_DOWN 0x5B + #define HID_KEYBOARD_SC_KEYPAD_4_AND_LEFT_ARROW 0x5C + #define HID_KEYBOARD_SC_KEYPAD_5 0x5D + #define HID_KEYBOARD_SC_KEYPAD_6_AND_RIGHT_ARROW 0x5E + #define HID_KEYBOARD_SC_KEYPAD_7_AND_HOME 0x5F + #define HID_KEYBOARD_SC_KEYPAD_8_AND_UP_ARROW 0x60 + #define HID_KEYBOARD_SC_KEYPAD_9_AND_PAGE_UP 0x61 + #define HID_KEYBOARD_SC_KEYPAD_0_AND_INSERT 0x62 + #define HID_KEYBOARD_SC_KEYPAD_DOT_AND_DELETE 0x63 + #define HID_KEYBOARD_SC_NON_US_BACKSLASH_AND_PIPE 0x64 + #define HID_KEYBOARD_SC_APPLICATION 0x65 + #define HID_KEYBOARD_SC_POWER 0x66 + #define HID_KEYBOARD_SC_KEYPAD_EQUAL_SIGN 0x67 + #define HID_KEYBOARD_SC_F13 0x68 + #define HID_KEYBOARD_SC_F14 0x69 + #define HID_KEYBOARD_SC_F15 0x6A + #define HID_KEYBOARD_SC_F16 0x6B + #define HID_KEYBOARD_SC_F17 0x6C + #define HID_KEYBOARD_SC_F18 0x6D + #define HID_KEYBOARD_SC_F19 0x6E + #define HID_KEYBOARD_SC_F20 0x6F + #define HID_KEYBOARD_SC_F21 0x70 + #define HID_KEYBOARD_SC_F22 0x71 + #define HID_KEYBOARD_SC_F23 0x72 + #define HID_KEYBOARD_SC_F24 0x73 + #define HID_KEYBOARD_SC_EXECUTE 0x74 + #define HID_KEYBOARD_SC_HELP 0x75 + #define HID_KEYBOARD_SC_MENU 0x76 + #define HID_KEYBOARD_SC_SELECT 0x77 + #define HID_KEYBOARD_SC_STOP 0x78 + #define HID_KEYBOARD_SC_AGAIN 0x79 + #define HID_KEYBOARD_SC_UNDO 0x7A + #define HID_KEYBOARD_SC_CUT 0x7B + #define HID_KEYBOARD_SC_COPY 0x7C + #define HID_KEYBOARD_SC_PASTE 0x7D + #define HID_KEYBOARD_SC_FIND 0x7E + #define HID_KEYBOARD_SC_MUTE 0x7F + #define HID_KEYBOARD_SC_VOLUME_UP 0x80 + #define HID_KEYBOARD_SC_VOLUME_DOWN 0x81 + #define HID_KEYBOARD_SC_LOCKING_CAPS_LOCK 0x82 + #define HID_KEYBOARD_SC_LOCKING_NUM_LOCK 0x83 + #define HID_KEYBOARD_SC_LOCKING_SCROLL_LOCK 0x84 + #define HID_KEYBOARD_SC_KEYPAD_COMMA 0x85 + #define HID_KEYBOARD_SC_KEYPAD_EQUAL_SIGN_AS400 0x86 + #define HID_KEYBOARD_SC_INTERNATIONAL1 0x87 + #define HID_KEYBOARD_SC_INTERNATIONAL2 0x88 + #define HID_KEYBOARD_SC_INTERNATIONAL3 0x89 + #define HID_KEYBOARD_SC_INTERNATIONAL4 0x8A + #define HID_KEYBOARD_SC_INTERNATIONAL5 0x8B + #define HID_KEYBOARD_SC_INTERNATIONAL6 0x8C + #define HID_KEYBOARD_SC_INTERNATIONAL7 0x8D + #define HID_KEYBOARD_SC_INTERNATIONAL8 0x8E + #define HID_KEYBOARD_SC_INTERNATIONAL9 0x8F + #define HID_KEYBOARD_SC_LANG1 0x90 + #define HID_KEYBOARD_SC_LANG2 0x91 + #define HID_KEYBOARD_SC_LANG3 0x92 + #define HID_KEYBOARD_SC_LANG4 0x93 + #define HID_KEYBOARD_SC_LANG5 0x94 + #define HID_KEYBOARD_SC_LANG6 0x95 + #define HID_KEYBOARD_SC_LANG7 0x96 + #define HID_KEYBOARD_SC_LANG8 0x97 + #define HID_KEYBOARD_SC_LANG9 0x98 + #define HID_KEYBOARD_SC_ALTERNATE_ERASE 0x99 + #define HID_KEYBOARD_SC_SYSREQ 0x9A + #define HID_KEYBOARD_SC_CANCEL 0x9B + #define HID_KEYBOARD_SC_CLEAR 0x9C + #define HID_KEYBOARD_SC_PRIOR 0x9D + #define HID_KEYBOARD_SC_RETURN 0x9E + #define HID_KEYBOARD_SC_SEPARATOR 0x9F + #define HID_KEYBOARD_SC_OUT 0xA0 + #define HID_KEYBOARD_SC_OPER 0xA1 + #define HID_KEYBOARD_SC_CLEAR_AND_AGAIN 0xA2 + #define HID_KEYBOARD_SC_CRSEL_AND_PROPS 0xA3 + #define HID_KEYBOARD_SC_EXSEL 0xA4 + #define HID_KEYBOARD_SC_KEYPAD_00 0xB0 + #define HID_KEYBOARD_SC_KEYPAD_000 0xB1 + #define HID_KEYBOARD_SC_THOUSANDS_SEPARATOR 0xB2 + #define HID_KEYBOARD_SC_DECIMAL_SEPARATOR 0xB3 + #define HID_KEYBOARD_SC_CURRENCY_UNIT 0xB4 + #define HID_KEYBOARD_SC_CURRENCY_SUB_UNIT 0xB5 + #define HID_KEYBOARD_SC_KEYPAD_OPENING_PARENTHESIS 0xB6 + #define HID_KEYBOARD_SC_KEYPAD_CLOSING_PARENTHESIS 0xB7 + #define HID_KEYBOARD_SC_KEYPAD_OPENING_BRACE 0xB8 + #define HID_KEYBOARD_SC_KEYPAD_CLOSING_BRACE 0xB9 + #define HID_KEYBOARD_SC_KEYPAD_TAB 0xBA + #define HID_KEYBOARD_SC_KEYPAD_BACKSPACE 0xBB + #define HID_KEYBOARD_SC_KEYPAD_A 0xBC + #define HID_KEYBOARD_SC_KEYPAD_B 0xBD + #define HID_KEYBOARD_SC_KEYPAD_C 0xBE + #define HID_KEYBOARD_SC_KEYPAD_D 0xBF + #define HID_KEYBOARD_SC_KEYPAD_E 0xC0 + #define HID_KEYBOARD_SC_KEYPAD_F 0xC1 + #define HID_KEYBOARD_SC_KEYPAD_XOR 0xC2 + #define HID_KEYBOARD_SC_KEYPAD_CARET 0xC3 + #define HID_KEYBOARD_SC_KEYPAD_PERCENTAGE 0xC4 + #define HID_KEYBOARD_SC_KEYPAD_LESS_THAN_SIGN 0xC5 + #define HID_KEYBOARD_SC_KEYPAD_GREATER_THAN_SIGN 0xC6 + #define HID_KEYBOARD_SC_KEYPAD_AMP 0xC7 + #define HID_KEYBOARD_SC_KEYPAD_AMP_AMP 0xC8 + #define HID_KEYBOARD_SC_KEYPAD_PIPE 0xC9 + #define HID_KEYBOARD_SC_KEYPAD_PIPE_PIPE 0xCA + #define HID_KEYBOARD_SC_KEYPAD_COLON 0xCB + #define HID_KEYBOARD_SC_KEYPAD_HASHMARK 0xCC + #define HID_KEYBOARD_SC_KEYPAD_SPACE 0xCD + #define HID_KEYBOARD_SC_KEYPAD_AT 0xCE + #define HID_KEYBOARD_SC_KEYPAD_EXCLAMATION_SIGN 0xCF + #define HID_KEYBOARD_SC_KEYPAD_MEMORY_STORE 0xD0 + #define HID_KEYBOARD_SC_KEYPAD_MEMORY_RECALL 0xD1 + #define HID_KEYBOARD_SC_KEYPAD_MEMORY_CLEAR 0xD2 + #define HID_KEYBOARD_SC_KEYPAD_MEMORY_ADD 0xD3 + #define HID_KEYBOARD_SC_KEYPAD_MEMORY_SUBTRACT 0xD4 + #define HID_KEYBOARD_SC_KEYPAD_MEMORY_MULTIPLY 0xD5 + #define HID_KEYBOARD_SC_KEYPAD_MEMORY_DIVIDE 0xD6 + #define HID_KEYBOARD_SC_KEYPAD_PLUS_AND_MINUS 0xD7 + #define HID_KEYBOARD_SC_KEYPAD_CLEAR 0xD8 + #define HID_KEYBOARD_SC_KEYPAD_CLEAR_ENTRY 0xD9 + #define HID_KEYBOARD_SC_KEYPAD_BINARY 0xDA + #define HID_KEYBOARD_SC_KEYPAD_OCTAL 0xDB + #define HID_KEYBOARD_SC_KEYPAD_DECIMAL 0xDC + #define HID_KEYBOARD_SC_KEYPAD_HEXADECIMAL 0xDD + #define HID_KEYBOARD_SC_LEFT_CONTROL 0xE0 + #define HID_KEYBOARD_SC_LEFT_SHIFT 0xE1 + #define HID_KEYBOARD_SC_LEFT_ALT 0xE2 + #define HID_KEYBOARD_SC_LEFT_GUI 0xE3 + #define HID_KEYBOARD_SC_RIGHT_CONTROL 0xE4 + #define HID_KEYBOARD_SC_RIGHT_SHIFT 0xE5 + #define HID_KEYBOARD_SC_RIGHT_ALT 0xE6 + #define HID_KEYBOARD_SC_RIGHT_GUI 0xE7 + #define HID_KEYBOARD_SC_MEDIA_PLAY 0xE8 + #define HID_KEYBOARD_SC_MEDIA_STOP 0xE9 + #define HID_KEYBOARD_SC_MEDIA_PREVIOUS_TRACK 0xEA + #define HID_KEYBOARD_SC_MEDIA_NEXT_TRACK 0xEB + #define HID_KEYBOARD_SC_MEDIA_EJECT 0xEC + #define HID_KEYBOARD_SC_MEDIA_VOLUME_UP 0xED + #define HID_KEYBOARD_SC_MEDIA_VOLUME_DOWN 0xEE + #define HID_KEYBOARD_SC_MEDIA_MUTE 0xEF + #define HID_KEYBOARD_SC_MEDIA_WWW 0xF0 + #define HID_KEYBOARD_SC_MEDIA_BACKWARD 0xF1 + #define HID_KEYBOARD_SC_MEDIA_FORWARD 0xF2 + #define HID_KEYBOARD_SC_MEDIA_CANCEL 0xF3 + #define HID_KEYBOARD_SC_MEDIA_SEARCH 0xF4 + #define HID_KEYBOARD_SC_MEDIA_SLEEP 0xF8 + #define HID_KEYBOARD_SC_MEDIA_LOCK 0xF9 + #define HID_KEYBOARD_SC_MEDIA_RELOAD 0xFA + #define HID_KEYBOARD_SC_MEDIA_CALCULATOR 0xFB + //@} + + /** \name Common HID Device Report Descriptors */ + //@{ + /** \hideinitializer + * A list of HID report item array elements that describe a typical HID USB Joystick. The resulting report + * descriptor is structured according to the following layout: + * + * \code + * struct + * { + * intA_t X; // Signed X axis value + * intA_t Y; // Signed Y axis value + * intA_t Z; // Signed Z axis value + * uintB_t Buttons; // Pressed buttons bitmask + * } Joystick_Report; + * \endcode + * + * Where \c uintA_t is a type large enough to hold the ranges of the signed \c MinAxisVal and \c MaxAxisVal values, + * and \c intB_t is a type large enough to hold one bit per button. + * + * \param[in] MinAxisVal Minimum logical axis value (16-bit). + * \param[in] MaxAxisVal Maximum logical axis value (16-bit). + * \param[in] MinPhysicalVal Minimum physical axis value, for movement resolution calculations (16-bit). + * \param[in] MaxPhysicalVal Maximum physical axis value, for movement resolution calculations (16-bit). + * \param[in] Buttons Total number of buttons in the device (8-bit). + */ + #define HID_DESCRIPTOR_JOYSTICK(MinAxisVal, MaxAxisVal, MinPhysicalVal, MaxPhysicalVal, Buttons) \ + HID_RI_USAGE_PAGE(8, 0x01), \ + HID_RI_USAGE(8, 0x04), \ + HID_RI_COLLECTION(8, 0x01), \ + HID_RI_USAGE(8, 0x01), \ + HID_RI_COLLECTION(8, 0x00), \ + HID_RI_USAGE(8, 0x30), \ + HID_RI_USAGE(8, 0x31), \ + HID_RI_USAGE(8, 0x32), \ + HID_RI_LOGICAL_MINIMUM(16, MinAxisVal), \ + HID_RI_LOGICAL_MAXIMUM(16, MaxAxisVal), \ + HID_RI_PHYSICAL_MINIMUM(16, MinPhysicalVal), \ + HID_RI_PHYSICAL_MAXIMUM(16, MaxPhysicalVal), \ + HID_RI_REPORT_COUNT(8, 3), \ + HID_RI_REPORT_SIZE(8, (((MinAxisVal >= -128) && (MaxAxisVal <= 127)) ? 8 : 16)), \ + HID_RI_INPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | HID_IOF_ABSOLUTE), \ + HID_RI_END_COLLECTION(0), \ + HID_RI_USAGE_PAGE(8, 0x09), \ + HID_RI_USAGE_MINIMUM(8, 0x01), \ + HID_RI_USAGE_MAXIMUM(8, Buttons), \ + HID_RI_LOGICAL_MINIMUM(8, 0x00), \ + HID_RI_LOGICAL_MAXIMUM(8, 0x01), \ + HID_RI_REPORT_SIZE(8, 0x01), \ + HID_RI_REPORT_COUNT(8, Buttons), \ + HID_RI_INPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | HID_IOF_ABSOLUTE), \ + HID_RI_REPORT_SIZE(8, (Buttons % 8) ? (8 - (Buttons % 8)) : 0), \ + HID_RI_REPORT_COUNT(8, 0x01), \ + HID_RI_INPUT(8, HID_IOF_CONSTANT), \ + HID_RI_END_COLLECTION(0) + + /** \hideinitializer + * A list of HID report item array elements that describe a typical HID USB keyboard. The resulting report descriptor + * is compatible with \ref USB_KeyboardReport_Data_t when \c MaxKeys is equal to 6. For other values, the report will + * be structured according to the following layout: + * + * \code + * struct + * { + * uint8_t Modifier; // Keyboard modifier byte indicating pressed modifier keys (\c HID_KEYBOARD_MODIFER_* masks) + * uint8_t Reserved; // Reserved for OEM use, always set to 0. + * uint8_t KeyCode[MaxKeys]; // Length determined by the number of keys that can be reported + * } Keyboard_Report; + * \endcode + * + * \param[in] MaxKeys Number of simultaneous keys that can be reported at the one time (8-bit). + */ + #define HID_DESCRIPTOR_KEYBOARD(MaxKeys) \ + HID_RI_USAGE_PAGE(8, 0x01), \ + HID_RI_USAGE(8, 0x06), \ + HID_RI_COLLECTION(8, 0x01), \ + HID_RI_USAGE_PAGE(8, 0x07), \ + HID_RI_USAGE_MINIMUM(8, 0xE0), \ + HID_RI_USAGE_MAXIMUM(8, 0xE7), \ + HID_RI_LOGICAL_MINIMUM(8, 0x00), \ + HID_RI_LOGICAL_MAXIMUM(8, 0x01), \ + HID_RI_REPORT_SIZE(8, 0x01), \ + HID_RI_REPORT_COUNT(8, 0x08), \ + HID_RI_INPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | HID_IOF_ABSOLUTE), \ + HID_RI_REPORT_COUNT(8, 0x01), \ + HID_RI_REPORT_SIZE(8, 0x08), \ + HID_RI_INPUT(8, HID_IOF_CONSTANT), \ + HID_RI_USAGE_PAGE(8, 0x08), \ + HID_RI_USAGE_MINIMUM(8, 0x01), \ + HID_RI_USAGE_MAXIMUM(8, 0x05), \ + HID_RI_REPORT_COUNT(8, 0x05), \ + HID_RI_REPORT_SIZE(8, 0x01), \ + HID_RI_OUTPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | HID_IOF_ABSOLUTE | HID_IOF_NON_VOLATILE), \ + HID_RI_REPORT_COUNT(8, 0x01), \ + HID_RI_REPORT_SIZE(8, 0x03), \ + HID_RI_OUTPUT(8, HID_IOF_CONSTANT), \ + HID_RI_LOGICAL_MINIMUM(8, 0x00), \ + HID_RI_LOGICAL_MAXIMUM(16, 0xFF), \ + HID_RI_USAGE_PAGE(8, 0x07), \ + HID_RI_USAGE_MINIMUM(8, 0x00), \ + HID_RI_USAGE_MAXIMUM(8, 0xFF), \ + HID_RI_REPORT_COUNT(8, MaxKeys), \ + HID_RI_REPORT_SIZE(8, 0x08), \ + HID_RI_INPUT(8, HID_IOF_DATA | HID_IOF_ARRAY | HID_IOF_ABSOLUTE), \ + HID_RI_END_COLLECTION(0) + + /** \hideinitializer + * A list of HID report item array elements that describe a typical HID USB mouse. The resulting report descriptor + * is compatible with \ref USB_MouseReport_Data_t if the \c MinAxisVal and \c MaxAxisVal values fit within a \c int8_t range + * and the number of Buttons is less than 8. For other values, the report is structured according to the following layout: + * + * \code + * struct + * { + * uintA_t Buttons; // Pressed buttons bitmask + * intB_t X; // X axis value + * intB_t Y; // Y axis value + * } Mouse_Report; + * \endcode + * + * Where \c intA_t is a type large enough to hold one bit per button, and \c intB_t is a type large enough to hold the + * ranges of the signed \c MinAxisVal and \c MaxAxisVal values. + * + * \param[in] MinAxisVal Minimum X/Y logical axis value (16-bit). + * \param[in] MaxAxisVal Maximum X/Y logical axis value (16-bit). + * \param[in] MinPhysicalVal Minimum X/Y physical axis value, for movement resolution calculations (16-bit). + * \param[in] MaxPhysicalVal Maximum X/Y physical axis value, for movement resolution calculations (16-bit). + * \param[in] Buttons Total number of buttons in the device (8-bit). + * \param[in] AbsoluteCoords Boolean \c true to use absolute X/Y coordinates (e.g. touchscreen). + */ + #define HID_DESCRIPTOR_MOUSE(MinAxisVal, MaxAxisVal, MinPhysicalVal, MaxPhysicalVal, Buttons, AbsoluteCoords) \ + HID_RI_USAGE_PAGE(8, 0x01), \ + HID_RI_USAGE(8, 0x02), \ + HID_RI_COLLECTION(8, 0x01), \ + HID_RI_USAGE(8, 0x01), \ + HID_RI_COLLECTION(8, 0x00), \ + HID_RI_USAGE_PAGE(8, 0x09), \ + HID_RI_USAGE_MINIMUM(8, 0x01), \ + HID_RI_USAGE_MAXIMUM(8, Buttons), \ + HID_RI_LOGICAL_MINIMUM(8, 0x00), \ + HID_RI_LOGICAL_MAXIMUM(8, 0x01), \ + HID_RI_REPORT_COUNT(8, Buttons), \ + HID_RI_REPORT_SIZE(8, 0x01), \ + HID_RI_INPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | HID_IOF_ABSOLUTE), \ + HID_RI_REPORT_COUNT(8, 0x01), \ + HID_RI_REPORT_SIZE(8, (Buttons % 8) ? (8 - (Buttons % 8)) : 0), \ + HID_RI_INPUT(8, HID_IOF_CONSTANT), \ + HID_RI_USAGE_PAGE(8, 0x01), \ + HID_RI_USAGE(8, 0x30), \ + HID_RI_USAGE(8, 0x31), \ + HID_RI_LOGICAL_MINIMUM(16, MinAxisVal), \ + HID_RI_LOGICAL_MAXIMUM(16, MaxAxisVal), \ + HID_RI_PHYSICAL_MINIMUM(16, MinPhysicalVal), \ + HID_RI_PHYSICAL_MAXIMUM(16, MaxPhysicalVal), \ + HID_RI_REPORT_COUNT(8, 0x02), \ + HID_RI_REPORT_SIZE(8, (((MinAxisVal >= -128) && (MaxAxisVal <= 127)) ? 8 : 16)), \ + HID_RI_INPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | (AbsoluteCoords ? HID_IOF_ABSOLUTE : HID_IOF_RELATIVE)), \ + HID_RI_END_COLLECTION(0), \ + HID_RI_END_COLLECTION(0) + + /** \hideinitializer + * A list of HID report item array elements that describe a typical Vendor Defined byte array HID report descriptor, + * used for transporting arbitrary data between the USB host and device via HID reports. The resulting report should be + * a \c uint8_t byte array of the specified length in both Device to Host (IN) and Host to Device (OUT) directions. + * + * \param[in] VendorPageNum Vendor Defined HID Usage Page index, ranging from 0x00 to 0xFF. + * \param[in] CollectionUsage Vendor Usage for the encompassing report IN and OUT collection, ranging from 0x00 to 0xFF. + * \param[in] DataINUsage Vendor Usage for the IN report data, ranging from 0x00 to 0xFF. + * \param[in] DataOUTUsage Vendor Usage for the OUT report data, ranging from 0x00 to 0xFF. + * \param[in] NumBytes Length of the data IN and OUT reports. + */ + #define HID_DESCRIPTOR_VENDOR(VendorPageNum, CollectionUsage, DataINUsage, DataOUTUsage, NumBytes) \ + HID_RI_USAGE_PAGE(16, (0xFF00 | VendorPageNum)), \ + HID_RI_USAGE(8, CollectionUsage), \ + HID_RI_COLLECTION(8, 0x01), \ + HID_RI_USAGE(8, DataINUsage), \ + HID_RI_LOGICAL_MINIMUM(8, 0x00), \ + HID_RI_LOGICAL_MAXIMUM(8, 0xFF), \ + HID_RI_REPORT_SIZE(8, 0x08), \ + HID_RI_REPORT_COUNT(8, NumBytes), \ + HID_RI_INPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | HID_IOF_ABSOLUTE), \ + HID_RI_USAGE(8, DataOUTUsage), \ + HID_RI_LOGICAL_MINIMUM(8, 0x00), \ + HID_RI_LOGICAL_MAXIMUM(8, 0xFF), \ + HID_RI_REPORT_SIZE(8, 0x08), \ + HID_RI_REPORT_COUNT(8, NumBytes), \ + HID_RI_OUTPUT(8, HID_IOF_DATA | HID_IOF_VARIABLE | HID_IOF_ABSOLUTE | HID_IOF_NON_VOLATILE), \ + HID_RI_END_COLLECTION(0) + //@} + + /* Type Defines: */ + /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the HID + * device class. + */ + enum HID_Descriptor_ClassSubclassProtocol_t + { + HID_CSCP_HIDClass = 0x03, /**< Descriptor Class value indicating that the device or interface + * belongs to the HID class. + */ + HID_CSCP_NonBootSubclass = 0x00, /**< Descriptor Subclass value indicating that the device or interface + * does not implement a HID boot protocol. + */ + HID_CSCP_BootSubclass = 0x01, /**< Descriptor Subclass value indicating that the device or interface + * implements a HID boot protocol. + */ + HID_CSCP_NonBootProtocol = 0x00, /**< Descriptor Protocol value indicating that the device or interface + * does not belong to a HID boot protocol. + */ + HID_CSCP_KeyboardBootProtocol = 0x01, /**< Descriptor Protocol value indicating that the device or interface + * belongs to the Keyboard HID boot protocol. + */ + HID_CSCP_MouseBootProtocol = 0x02, /**< Descriptor Protocol value indicating that the device or interface + * belongs to the Mouse HID boot protocol. + */ + }; + + /** Enum for the HID class specific control requests that can be issued by the USB bus host. */ + enum HID_ClassRequests_t + { + HID_REQ_GetReport = 0x01, /**< HID class-specific Request to get the current HID report from the device. */ + HID_REQ_GetIdle = 0x02, /**< HID class-specific Request to get the current device idle count. */ + HID_REQ_GetProtocol = 0x03, /**< HID class-specific Request to get the current HID report protocol mode. */ + HID_REQ_SetReport = 0x09, /**< HID class-specific Request to set the current HID report to the device. */ + HID_REQ_SetIdle = 0x0A, /**< HID class-specific Request to set the device's idle count. */ + HID_REQ_SetProtocol = 0x0B, /**< HID class-specific Request to set the current HID report protocol mode. */ + }; + + /** Enum for the HID class specific descriptor types. */ + enum HID_DescriptorTypes_t + { + HID_DTYPE_HID = 0x21, /**< Descriptor header type value, to indicate a HID class HID descriptor. */ + HID_DTYPE_Report = 0x22, /**< Descriptor header type value, to indicate a HID class HID report descriptor. */ + }; + + /** Enum for the different types of HID reports. */ + enum HID_ReportItemTypes_t + { + HID_REPORT_ITEM_In = 0, /**< Indicates that the item is an IN report type. */ + HID_REPORT_ITEM_Out = 1, /**< Indicates that the item is an OUT report type. */ + HID_REPORT_ITEM_Feature = 2, /**< Indicates that the item is a FEATURE report type. */ + }; + + /** \brief HID class-specific HID Descriptor (LUFA naming conventions). + * + * Type define for the HID class-specific HID descriptor, to describe the HID device's specifications. Refer to the HID + * specification for details on the structure elements. + * + * \see \ref USB_HID_StdDescriptor_HID_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + USB_Descriptor_Header_t Header; /**< Regular descriptor header containing the descriptor's type and length. */ + + uint16_t HIDSpec; /**< BCD encoded version that the HID descriptor and device complies to. + * + * \see \ref VERSION_BCD() utility macro. + */ + uint8_t CountryCode; /**< Country code of the localized device, or zero if universal. */ + + uint8_t TotalReportDescriptors; /**< Total number of HID report descriptors for the interface. */ + + uint8_t HIDReportType; /**< Type of HID report, set to \ref HID_DTYPE_Report. */ + uint16_t HIDReportLength; /**< Length of the associated HID report descriptor, in bytes. */ + } ATTR_PACKED USB_HID_Descriptor_HID_t; + + /** \brief HID class-specific HID Descriptor (USB-IF naming conventions). + * + * Type define for the HID class-specific HID descriptor, to describe the HID device's specifications. Refer to the HID + * specification for details on the structure elements. + * + * \see \ref USB_HID_Descriptor_HID_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + + uint16_t bcdHID; /**< BCD encoded version that the HID descriptor and device complies to. + * + * \see \ref VERSION_BCD() utility macro. + */ + uint8_t bCountryCode; /**< Country code of the localized device, or zero if universal. */ + + uint8_t bNumDescriptors; /**< Total number of HID report descriptors for the interface. */ + + uint8_t bDescriptorType2; /**< Type of HID report, set to \ref HID_DTYPE_Report. */ + uint16_t wDescriptorLength; /**< Length of the associated HID report descriptor, in bytes. */ + } ATTR_PACKED USB_HID_StdDescriptor_HID_t; + + /** \brief Standard HID Boot Protocol Mouse Report. + * + * Type define for a standard Boot Protocol Mouse report + */ + typedef struct + { + uint8_t Button; /**< Button mask for currently pressed buttons in the mouse. */ + int8_t X; /**< Current delta X movement of the mouse. */ + int8_t Y; /**< Current delta Y movement on the mouse. */ + } ATTR_PACKED USB_MouseReport_Data_t; + + /** \brief Standard HID Boot Protocol Keyboard Report. + * + * Type define for a standard Boot Protocol Keyboard report + */ + typedef struct + { + uint8_t Modifier; /**< Keyboard modifier byte, indicating pressed modifier keys (a combination of + * \c HID_KEYBOARD_MODIFER_* masks). + */ + uint8_t Reserved; /**< Reserved for OEM use, always set to 0. */ + uint8_t KeyCode[6]; /**< Key codes of the currently pressed keys. */ + } ATTR_PACKED USB_KeyboardReport_Data_t; + + /** Type define for the data type used to store HID report descriptor elements. */ + typedef uint8_t USB_Descriptor_HIDReport_Datatype_t; + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ diff --git a/LUFA/Drivers/USB/Class/Common/HIDParser.c b/LUFA/Drivers/USB/Class/Common/HIDParser.c new file mode 100644 index 0000000000..62f10c4e22 --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/HIDParser.c @@ -0,0 +1,389 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +#define __INCLUDE_FROM_USB_DRIVER +#define __INCLUDE_FROM_HID_DRIVER +#include "HIDParser.h" + +uint8_t USB_ProcessHIDReport(const uint8_t* ReportData, + uint16_t ReportSize, + HID_ReportInfo_t* const ParserData) +{ + HID_StateTable_t StateTable[HID_STATETABLE_STACK_DEPTH]; + HID_StateTable_t* CurrStateTable = &StateTable[0]; + HID_CollectionPath_t* CurrCollectionPath = NULL; + HID_ReportSizeInfo_t* CurrReportIDInfo = &ParserData->ReportIDSizes[0]; + uint16_t UsageList[HID_USAGE_STACK_DEPTH]; + uint8_t UsageListSize = 0; + HID_MinMax_t UsageMinMax = {0, 0}; + + memset(ParserData, 0x00, sizeof(HID_ReportInfo_t)); + memset(CurrStateTable, 0x00, sizeof(HID_StateTable_t)); + memset(CurrReportIDInfo, 0x00, sizeof(HID_ReportSizeInfo_t)); + + ParserData->TotalDeviceReports = 1; + + while (ReportSize) + { + uint8_t HIDReportItem = *ReportData; + uint32_t ReportItemData; + + ReportData++; + ReportSize--; + + switch (HIDReportItem & HID_RI_DATA_SIZE_MASK) + { + case HID_RI_DATA_BITS_32: + ReportItemData = (((uint32_t)ReportData[3] << 24) | ((uint32_t)ReportData[2] << 16) | + ((uint16_t)ReportData[1] << 8) | ReportData[0]); + ReportSize -= 4; + ReportData += 4; + break; + + case HID_RI_DATA_BITS_16: + ReportItemData = (((uint16_t)ReportData[1] << 8) | (ReportData[0])); + ReportSize -= 2; + ReportData += 2; + break; + + case HID_RI_DATA_BITS_8: + ReportItemData = ReportData[0]; + ReportSize -= 1; + ReportData += 1; + break; + + default: + ReportItemData = 0; + break; + } + + switch (HIDReportItem & (HID_RI_TYPE_MASK | HID_RI_TAG_MASK)) + { + case HID_RI_PUSH(0): + if (CurrStateTable == &StateTable[HID_STATETABLE_STACK_DEPTH - 1]) + return HID_PARSE_HIDStackOverflow; + + memcpy((CurrStateTable + 1), + CurrStateTable, + sizeof(HID_ReportItem_t)); + + CurrStateTable++; + break; + + case HID_RI_POP(0): + if (CurrStateTable == &StateTable[0]) + return HID_PARSE_HIDStackUnderflow; + + CurrStateTable--; + break; + + case HID_RI_USAGE_PAGE(0): + if ((HIDReportItem & HID_RI_DATA_SIZE_MASK) == HID_RI_DATA_BITS_32) + CurrStateTable->Attributes.Usage.Page = (ReportItemData >> 16); + + CurrStateTable->Attributes.Usage.Page = ReportItemData; + break; + + case HID_RI_LOGICAL_MINIMUM(0): + CurrStateTable->Attributes.Logical.Minimum = ReportItemData; + break; + + case HID_RI_LOGICAL_MAXIMUM(0): + CurrStateTable->Attributes.Logical.Maximum = ReportItemData; + break; + + case HID_RI_PHYSICAL_MINIMUM(0): + CurrStateTable->Attributes.Physical.Minimum = ReportItemData; + break; + + case HID_RI_PHYSICAL_MAXIMUM(0): + CurrStateTable->Attributes.Physical.Maximum = ReportItemData; + break; + + case HID_RI_UNIT_EXPONENT(0): + CurrStateTable->Attributes.Unit.Exponent = ReportItemData; + break; + + case HID_RI_UNIT(0): + CurrStateTable->Attributes.Unit.Type = ReportItemData; + break; + + case HID_RI_REPORT_SIZE(0): + CurrStateTable->Attributes.BitSize = ReportItemData; + break; + + case HID_RI_REPORT_COUNT(0): + CurrStateTable->ReportCount = ReportItemData; + break; + + case HID_RI_REPORT_ID(0): + CurrStateTable->ReportID = ReportItemData; + + if (ParserData->UsingReportIDs) + { + CurrReportIDInfo = NULL; + + for (uint8_t i = 0; i < ParserData->TotalDeviceReports; i++) + { + if (ParserData->ReportIDSizes[i].ReportID == CurrStateTable->ReportID) + { + CurrReportIDInfo = &ParserData->ReportIDSizes[i]; + break; + } + } + + if (CurrReportIDInfo == NULL) + { + if (ParserData->TotalDeviceReports == HID_MAX_REPORT_IDS) + return HID_PARSE_InsufficientReportIDItems; + + CurrReportIDInfo = &ParserData->ReportIDSizes[ParserData->TotalDeviceReports++]; + memset(CurrReportIDInfo, 0x00, sizeof(HID_ReportSizeInfo_t)); + } + } + + ParserData->UsingReportIDs = true; + + CurrReportIDInfo->ReportID = CurrStateTable->ReportID; + break; + + case HID_RI_USAGE(0): + if (UsageListSize == HID_USAGE_STACK_DEPTH) + return HID_PARSE_UsageListOverflow; + + UsageList[UsageListSize++] = ReportItemData; + break; + + case HID_RI_USAGE_MINIMUM(0): + UsageMinMax.Minimum = ReportItemData; + break; + + case HID_RI_USAGE_MAXIMUM(0): + UsageMinMax.Maximum = ReportItemData; + break; + + case HID_RI_COLLECTION(0): + if (CurrCollectionPath == NULL) + { + CurrCollectionPath = &ParserData->CollectionPaths[0]; + } + else + { + HID_CollectionPath_t* ParentCollectionPath = CurrCollectionPath; + + CurrCollectionPath = &ParserData->CollectionPaths[1]; + + while (CurrCollectionPath->Parent != NULL) + { + if (CurrCollectionPath == &ParserData->CollectionPaths[HID_MAX_COLLECTIONS - 1]) + return HID_PARSE_InsufficientCollectionPaths; + + CurrCollectionPath++; + } + + CurrCollectionPath->Parent = ParentCollectionPath; + } + + CurrCollectionPath->Type = ReportItemData; + CurrCollectionPath->Usage.Page = CurrStateTable->Attributes.Usage.Page; + + if (UsageListSize) + { + CurrCollectionPath->Usage.Usage = UsageList[0]; + + for (uint8_t i = 1; i < UsageListSize; i++) + UsageList[i - 1] = UsageList[i]; + + UsageListSize--; + } + else if (UsageMinMax.Minimum <= UsageMinMax.Maximum) + { + CurrCollectionPath->Usage.Usage = UsageMinMax.Minimum++; + } + + break; + + case HID_RI_END_COLLECTION(0): + if (CurrCollectionPath == NULL) + return HID_PARSE_UnexpectedEndCollection; + + CurrCollectionPath = CurrCollectionPath->Parent; + break; + + case HID_RI_INPUT(0): + case HID_RI_OUTPUT(0): + case HID_RI_FEATURE(0): + for (uint8_t ReportItemNum = 0; ReportItemNum < CurrStateTable->ReportCount; ReportItemNum++) + { + HID_ReportItem_t NewReportItem; + + memcpy(&NewReportItem.Attributes, + &CurrStateTable->Attributes, + sizeof(HID_ReportItem_Attributes_t)); + + NewReportItem.ItemFlags = ReportItemData; + NewReportItem.CollectionPath = CurrCollectionPath; + NewReportItem.ReportID = CurrStateTable->ReportID; + + if (UsageListSize) + { + NewReportItem.Attributes.Usage.Usage = UsageList[0]; + + for (uint8_t i = 1; i < UsageListSize; i++) + UsageList[i - 1] = UsageList[i]; + + UsageListSize--; + } + else if (UsageMinMax.Minimum <= UsageMinMax.Maximum) + { + NewReportItem.Attributes.Usage.Usage = UsageMinMax.Minimum++; + } + + uint8_t ItemTypeTag = (HIDReportItem & (HID_RI_TYPE_MASK | HID_RI_TAG_MASK)); + + if (ItemTypeTag == HID_RI_INPUT(0)) + NewReportItem.ItemType = HID_REPORT_ITEM_In; + else if (ItemTypeTag == HID_RI_OUTPUT(0)) + NewReportItem.ItemType = HID_REPORT_ITEM_Out; + else + NewReportItem.ItemType = HID_REPORT_ITEM_Feature; + + NewReportItem.BitOffset = CurrReportIDInfo->ReportSizeBits[NewReportItem.ItemType]; + + CurrReportIDInfo->ReportSizeBits[NewReportItem.ItemType] += CurrStateTable->Attributes.BitSize; + + ParserData->LargestReportSizeBits = MAX(ParserData->LargestReportSizeBits, CurrReportIDInfo->ReportSizeBits[NewReportItem.ItemType]); + + if (ParserData->TotalReportItems == HID_MAX_REPORTITEMS) + return HID_PARSE_InsufficientReportItems; + + memcpy(&ParserData->ReportItems[ParserData->TotalReportItems], + &NewReportItem, sizeof(HID_ReportItem_t)); + + if (!(ReportItemData & HID_IOF_CONSTANT) && CALLBACK_HIDParser_FilterHIDReportItem(&NewReportItem)) + ParserData->TotalReportItems++; + } + + break; + + default: + break; + } + + if ((HIDReportItem & HID_RI_TYPE_MASK) == HID_RI_TYPE_MAIN) + { + UsageMinMax.Minimum = 0; + UsageMinMax.Maximum = 0; + UsageListSize = 0; + } + } + + if (!(ParserData->TotalReportItems)) + return HID_PARSE_NoUnfilteredReportItems; + + return HID_PARSE_Successful; +} + +bool USB_GetHIDReportItemInfo(const uint8_t* ReportData, + HID_ReportItem_t* const ReportItem) +{ + if (ReportItem == NULL) + return false; + + uint16_t DataBitsRem = ReportItem->Attributes.BitSize; + uint16_t CurrentBit = ReportItem->BitOffset; + uint32_t BitMask = (1 << 0); + + if (ReportItem->ReportID) + { + if (ReportItem->ReportID != ReportData[0]) + return false; + + ReportData++; + } + + ReportItem->PreviousValue = ReportItem->Value; + ReportItem->Value = 0; + + while (DataBitsRem--) + { + if (ReportData[CurrentBit / 8] & (1 << (CurrentBit % 8))) + ReportItem->Value |= BitMask; + + CurrentBit++; + BitMask <<= 1; + } + + return true; +} + +void USB_SetHIDReportItemInfo(uint8_t* ReportData, + HID_ReportItem_t* const ReportItem) +{ + if (ReportItem == NULL) + return; + + uint16_t DataBitsRem = ReportItem->Attributes.BitSize; + uint16_t CurrentBit = ReportItem->BitOffset; + uint32_t BitMask = (1 << 0); + + if (ReportItem->ReportID) + { + ReportData[0] = ReportItem->ReportID; + ReportData++; + } + + ReportItem->PreviousValue = ReportItem->Value; + + while (DataBitsRem--) + { + if (ReportItem->Value & BitMask) + ReportData[CurrentBit / 8] |= (1 << (CurrentBit % 8)); + + CurrentBit++; + BitMask <<= 1; + } +} + +uint16_t USB_GetHIDReportSize(HID_ReportInfo_t* const ParserData, + const uint8_t ReportID, + const uint8_t ReportType) +{ + for (uint8_t i = 0; i < HID_MAX_REPORT_IDS; i++) + { + uint16_t ReportSizeBits = ParserData->ReportIDSizes[i].ReportSizeBits[ReportType]; + + if (ParserData->ReportIDSizes[i].ReportID == ReportID) + return (ReportSizeBits / 8) + ((ReportSizeBits % 8) ? 1 : 0); + } + + return 0; +} + diff --git a/LUFA/Drivers/USB/Class/Common/HIDParser.h b/LUFA/Drivers/USB/Class/Common/HIDParser.h new file mode 100644 index 0000000000..023316d7ea --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/HIDParser.h @@ -0,0 +1,364 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief USB Human Interface Device (HID) Class report descriptor parser. + * + * This file allows for the easy parsing of complex HID report descriptors, which describes the data that + * a HID device transmits to the host. It also provides an easy API for extracting and processing the data + * elements inside a HID report sent from an attached HID device. + */ + +/** \ingroup Group_USB + * \defgroup Group_HIDParser HID Report Parser + * \brief USB Human Interface Device (HID) Class report descriptor parser. + * + * \section Sec_HIDParser_Dependencies Module Source Dependencies + * The following files must be built with any user project that uses this module: + * - LUFA/Drivers/USB/Class/Host/HIDParser.c <i>(Makefile source module name: LUFA_SRC_USB)</i> + * + * \section Sec_HIDParser_ModDescription Module Description + * Human Interface Device (HID) class report descriptor parser. This module implements a parser than is + * capable of processing a complete HID report descriptor, and outputting a flat structure containing the + * contents of the report in an a more friendly format. The parsed data may then be further processed and used + * within an application to process sent and received HID reports to and from an attached HID device. + * + * A HID report descriptor consists of a set of HID report items, which describe the function and layout + * of data exchanged between a HID device and a host, including both the physical encoding of each item + * (such as a button, key press or joystick axis) in the sent and received data packets - known as "reports" - + * as well as other information about each item such as the usages, data range, physical location and other + * characteristics. In this way a HID device can retain a high degree of flexibility in its capabilities, as it + * is not forced to comply with a given report layout or feature-set. + * + * This module also contains routines for the processing of data in an actual HID report, using the parsed report + * descriptor data as a guide for the encoding. + * + * @{ + */ + +#ifndef __HIDPARSER_H__ +#define __HIDPARSER_H__ + + /* Includes: */ + #include "../../../../Common/Common.h" + + #include "HIDReportData.h" + #include "HIDClassCommon.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Macros: */ + #if !defined(HID_STATETABLE_STACK_DEPTH) || defined(__DOXYGEN__) + /** Constant indicating the maximum stack depth of the state table. A larger state table + * allows for more PUSH/POP report items to be nested, but consumes more memory. By default + * this is set to 2 levels (allowing non-nested PUSH items) but this can be overridden by + * defining \c HID_STATETABLE_STACK_DEPTH to another value in the user project makefile, passing the + * define to the compiler using the -D compiler switch. + */ + #define HID_STATETABLE_STACK_DEPTH 2 + #endif + + #if !defined(HID_USAGE_STACK_DEPTH) || defined(__DOXYGEN__) + /** Constant indicating the maximum stack depth of the usage table. A larger usage table + * allows for more USAGE items to be indicated sequentially for REPORT COUNT entries of more than + * one, but requires more stack space. By default this is set to 8 levels (allowing for a report + * item with a count of 8) but this can be overridden by defining \c HID_USAGE_STACK_DEPTH to another + * value in the user project makefile, passing the define to the compiler using the -D compiler + * switch. + */ + #define HID_USAGE_STACK_DEPTH 8 + #endif + + #if !defined(HID_MAX_COLLECTIONS) || defined(__DOXYGEN__) + /** Constant indicating the maximum number of COLLECTION items (nested or unnested) that can be + * processed in the report item descriptor. A large value allows for more COLLECTION items to be + * processed, but consumes more memory. By default this is set to 10 collections, but this can be + * overridden by defining \c HID_MAX_COLLECTIONS to another value in the user project makefile, passing + * the define to the compiler using the -D compiler switch. + */ + #define HID_MAX_COLLECTIONS 10 + #endif + + #if !defined(HID_MAX_REPORTITEMS) || defined(__DOXYGEN__) + /** Constant indicating the maximum number of report items (IN, OUT or FEATURE) that can be processed + * in the report item descriptor and stored in the user HID Report Info structure. A large value allows + * for more report items to be stored, but consumes more memory. By default this is set to 20 items, + * but this can be overridden by defining \c HID_MAX_REPORTITEMS to another value in the user project + * makefile, and passing the define to the compiler using the -D compiler switch. + */ + #define HID_MAX_REPORTITEMS 20 + #endif + + #if !defined(HID_MAX_REPORT_IDS) || defined(__DOXYGEN__) + /** Constant indicating the maximum number of unique report IDs that can be processed in the report item + * descriptor for the report size information array in the user HID Report Info structure. A large value + * allows for more report ID report sizes to be stored, but consumes more memory. By default this is set + * to 10 items, but this can be overridden by defining \c HID_MAX_REPORT_IDS to another value in the user project + * makefile, and passing the define to the compiler using the -D compiler switch. Note that IN, OUT and FEATURE + * items sharing the same report ID consume only one size item in the array. + */ + #define HID_MAX_REPORT_IDS 10 + #endif + + /** Returns the value a given HID report item (once its value has been fetched via \ref USB_GetHIDReportItemInfo()) + * left-aligned to the given data type. This allows for signed data to be interpreted correctly, by shifting the data + * leftwards until the data's sign bit is in the correct position. + * + * \param[in] ReportItem HID Report Item whose retrieved value is to be aligned. + * \param[in] Type Data type to align the HID report item's value to. + * + * \return Left-aligned data of the given report item's pre-retrieved value for the given datatype. + */ + #define HID_ALIGN_DATA(ReportItem, Type) ((Type)(ReportItem->Value << ((8 * sizeof(Type)) - ReportItem->Attributes.BitSize))) + + /* Public Interface - May be used in end-application: */ + /* Enums: */ + /** Enum for the possible error codes in the return value of the \ref USB_ProcessHIDReport() function. */ + enum HID_Parse_ErrorCodes_t + { + HID_PARSE_Successful = 0, /**< Successful parse of the HID report descriptor, no error. */ + HID_PARSE_HIDStackOverflow = 1, /**< More than \ref HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */ + HID_PARSE_HIDStackUnderflow = 2, /**< A POP was found when the state table stack was empty. */ + HID_PARSE_InsufficientReportItems = 3, /**< More than \ref HID_MAX_REPORTITEMS report items in the report. */ + HID_PARSE_UnexpectedEndCollection = 4, /**< An END COLLECTION item found without matching COLLECTION item. */ + HID_PARSE_InsufficientCollectionPaths = 5, /**< More than \ref HID_MAX_COLLECTIONS collections in the report. */ + HID_PARSE_UsageListOverflow = 6, /**< More than \ref HID_USAGE_STACK_DEPTH usages listed in a row. */ + HID_PARSE_InsufficientReportIDItems = 7, /**< More than \ref HID_MAX_REPORT_IDS report IDs in the device. */ + HID_PARSE_NoUnfilteredReportItems = 8, /**< All report items from the device were filtered by the filtering callback routine. */ + }; + + /* Type Defines: */ + /** \brief HID Parser Report Item Min/Max Structure. + * + * Type define for an attribute with both minimum and maximum values (e.g. Logical Min/Max). + */ + typedef struct + { + uint32_t Minimum; /**< Minimum value for the attribute. */ + uint32_t Maximum; /**< Maximum value for the attribute. */ + } HID_MinMax_t; + + /** \brief HID Parser Report Item Unit Structure. + * + * Type define for the Unit attributes of a report item. + */ + typedef struct + { + uint32_t Type; /**< Unit type (refer to HID specifications for details). */ + uint8_t Exponent; /**< Unit exponent (refer to HID specifications for details). */ + } HID_Unit_t; + + /** \brief HID Parser Report Item Usage Structure. + * + * Type define for the Usage attributes of a report item. + */ + typedef struct + { + uint16_t Page; /**< Usage page of the report item. */ + uint16_t Usage; /**< Usage of the report item. */ + } HID_Usage_t; + + /** \brief HID Parser Report Item Collection Path Structure. + * + * Type define for a COLLECTION object. Contains the collection attributes and a reference to the + * parent collection if any. + */ + typedef struct HID_CollectionPath + { + uint8_t Type; /**< Collection type (e.g. "Generic Desktop"). */ + HID_Usage_t Usage; /**< Collection usage. */ + struct HID_CollectionPath* Parent; /**< Reference to parent collection, or \c NULL if root collection. */ + } HID_CollectionPath_t; + + /** \brief HID Parser Report Item Attributes Structure. + * + * Type define for all the data attributes of a report item, except flags. + */ + typedef struct + { + uint8_t BitSize; /**< Size in bits of the report item's data. */ + + HID_Usage_t Usage; /**< Usage of the report item. */ + HID_Unit_t Unit; /**< Unit type and exponent of the report item. */ + HID_MinMax_t Logical; /**< Logical minimum and maximum of the report item. */ + HID_MinMax_t Physical; /**< Physical minimum and maximum of the report item. */ + } HID_ReportItem_Attributes_t; + + /** \brief HID Parser Report Item Details Structure. + * + * Type define for a report item (IN, OUT or FEATURE) layout attributes and other details. + */ + typedef struct + { + uint16_t BitOffset; /**< Bit offset in the IN, OUT or FEATURE report of the item. */ + uint8_t ItemType; /**< Report item type, a value in \ref HID_ReportItemTypes_t. */ + uint16_t ItemFlags; /**< Item data flags, a mask of \c HID_IOF_* constants. */ + uint8_t ReportID; /**< Report ID this item belongs to, or 0x00 if device has only one report */ + HID_CollectionPath_t* CollectionPath; /**< Collection path of the item. */ + + HID_ReportItem_Attributes_t Attributes; /**< Report item attributes. */ + + uint32_t Value; /**< Current value of the report item - use \ref HID_ALIGN_DATA() when processing + * a retrieved value so that it is aligned to a specific type. + */ + uint32_t PreviousValue; /**< Previous value of the report item. */ + } HID_ReportItem_t; + + /** \brief HID Parser Report Size Structure. + * + * Type define for a report item size information structure, to retain the size of a device's reports by ID. + */ + typedef struct + { + uint8_t ReportID; /**< Report ID of the report within the HID interface. */ + uint16_t ReportSizeBits[3]; /**< Total number of bits in each report type for the given Report ID, + * indexed by the \ref HID_ReportItemTypes_t enum. + */ + } HID_ReportSizeInfo_t; + + /** \brief HID Parser State Structure. + * + * Type define for a complete processed HID report, including all report item data and collections. + */ + typedef struct + { + uint8_t TotalReportItems; /**< Total number of report items stored in the \c ReportItems array. */ + HID_ReportItem_t ReportItems[HID_MAX_REPORTITEMS]; /**< Report items array, including all IN, OUT + * and FEATURE items. + */ + HID_CollectionPath_t CollectionPaths[HID_MAX_COLLECTIONS]; /**< All collection items, referenced + * by the report items. + */ + uint8_t TotalDeviceReports; /**< Number of reports within the HID interface */ + HID_ReportSizeInfo_t ReportIDSizes[HID_MAX_REPORT_IDS]; /**< Report sizes for each report in the interface */ + uint16_t LargestReportSizeBits; /**< Largest report that the attached device will generate, in bits */ + bool UsingReportIDs; /**< Indicates if the device has at least one REPORT ID + * element in its HID report descriptor. + */ + } HID_ReportInfo_t; + + /* Function Prototypes: */ + /** Function to process a given HID report returned from an attached device, and store it into a given + * \ref HID_ReportInfo_t structure. + * + * \param[in] ReportData Buffer containing the device's HID report table. + * \param[in] ReportSize Size in bytes of the HID report table. + * \param[out] ParserData Pointer to a \ref HID_ReportInfo_t instance for the parser output. + * + * \return A value in the \ref HID_Parse_ErrorCodes_t enum. + */ + uint8_t USB_ProcessHIDReport(const uint8_t* ReportData, + uint16_t ReportSize, + HID_ReportInfo_t* const ParserData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3); + + /** Extracts the given report item's value out of the given HID report and places it into the Value + * member of the report item's \ref HID_ReportItem_t structure. + * + * When called on a report with an item that exists in that report, this copies the report item's \c Value + * to its \c PreviousValue element for easy checking to see if an item's value has changed before processing + * a report. If the given item does not exist in the report, the function does not modify the report item's + * data. + * + * \param[in] ReportData Buffer containing an IN or FEATURE report from an attached device. + * \param[in,out] ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array. + * + * \returns Boolean \c true if the item to retrieve was located in the given report, \c false otherwise. + */ + bool USB_GetHIDReportItemInfo(const uint8_t* ReportData, + HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1); + + /** Retrieves the given report item's value out of the \c Value member of the report item's + * \ref HID_ReportItem_t structure and places it into the correct position in the HID report + * buffer. The report buffer is assumed to have the appropriate bits cleared before calling + * this function (i.e., the buffer should be explicitly cleared before report values are added). + * + * When called, this copies the report item's \c Value element to its \c PreviousValue element for easy + * checking to see if an item's value has changed before sending a report. + * + * If the device has multiple HID reports, the first byte in the report is set to the report ID of the given item. + * + * \param[out] ReportData Buffer holding the current OUT or FEATURE report data. + * \param[in] ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array. + */ + void USB_SetHIDReportItemInfo(uint8_t* ReportData, + HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1); + + /** Retrieves the size of a given HID report in bytes from its Report ID. + * + * \param[in] ParserData Pointer to a \ref HID_ReportInfo_t instance containing the parser output. + * \param[in] ReportID Report ID of the report whose size is to be determined. + * \param[in] ReportType Type of the report whose size is to be determined, a value from the + * \ref HID_ReportItemTypes_t enum. + * + * \return Size of the report in bytes, or \c 0 if the report does not exist. + */ + uint16_t USB_GetHIDReportSize(HID_ReportInfo_t* const ParserData, + const uint8_t ReportID, + const uint8_t ReportType) ATTR_CONST ATTR_NON_NULL_PTR_ARG(1); + + /** Callback routine for the HID Report Parser. This callback <b>must</b> be implemented by the user code when + * the parser is used, to determine what report IN, OUT and FEATURE item's information is stored into the user + * \ref HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that + * no RAM is wasted storing the attributes for report items which will never be referenced by the application. + * + * Report item pointers passed to this callback function may be cached by the user application for later use + * when processing report items. This provides faster report processing in the user application than would + * a search of the entire parsed report item table for each received or sent report. + * + * \param[in] CurrentItem Pointer to the current report item for user checking. + * + * \return Boolean \c true if the item should be stored into the \ref HID_ReportInfo_t structure, \c false if + * it should be ignored. + */ + bool CALLBACK_HIDParser_FilterHIDReportItem(HID_ReportItem_t* const CurrentItem); + + /* Private Interface - For use in library only: */ + #if !defined(__DOXYGEN__) + /* Type Defines: */ + typedef struct + { + HID_ReportItem_Attributes_t Attributes; + uint8_t ReportCount; + uint8_t ReportID; + } HID_StateTable_t; + #endif + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ + diff --git a/LUFA/Drivers/USB/Class/Common/HIDReportData.h b/LUFA/Drivers/USB/Class/Common/HIDReportData.h new file mode 100644 index 0000000000..fe1c4df943 --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/HIDReportData.h @@ -0,0 +1,126 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Constants for HID report item attributes. + * + * HID report item constants for report item attributes. Refer to the HID specification for + * details on each flag's meaning when applied to an IN, OUT or FEATURE item. + */ + +/** \ingroup Group_HIDParser + * \defgroup Group_HIDReportItemConst HID Report Descriptor Item Constants + * + * General HID constant definitions for HID Report Descriptor elements. + * + * @{ + */ + +#ifndef __HIDREPORTDATA_H__ +#define __HIDREPORTDATA_H__ + + /* Private Interface - For use in library only: */ + #if !defined(__DOXYGEN__) + /* Macros: */ + #define HID_RI_DATA_SIZE_MASK 0x03 + #define HID_RI_TYPE_MASK 0x0C + #define HID_RI_TAG_MASK 0xF0 + + #define HID_RI_TYPE_MAIN 0x00 + #define HID_RI_TYPE_GLOBAL 0x04 + #define HID_RI_TYPE_LOCAL 0x08 + + #define HID_RI_DATA_BITS_0 0x00 + #define HID_RI_DATA_BITS_8 0x01 + #define HID_RI_DATA_BITS_16 0x02 + #define HID_RI_DATA_BITS_32 0x03 + #define HID_RI_DATA_BITS(DataBits) CONCAT_EXPANDED(HID_RI_DATA_BITS_, DataBits) + + #define _HID_RI_ENCODE_0(Data) + #define _HID_RI_ENCODE_8(Data) , (Data & 0xFF) + #define _HID_RI_ENCODE_16(Data) _HID_RI_ENCODE_8(Data) _HID_RI_ENCODE_8(Data >> 8) + #define _HID_RI_ENCODE_32(Data) _HID_RI_ENCODE_16(Data) _HID_RI_ENCODE_16(Data >> 16) + #define _HID_RI_ENCODE(DataBits, ...) CONCAT_EXPANDED(_HID_RI_ENCODE_, DataBits(__VA_ARGS__)) + + #define _HID_RI_ENTRY(Type, Tag, DataBits, ...) (Type | Tag | HID_RI_DATA_BITS(DataBits)) _HID_RI_ENCODE(DataBits, (__VA_ARGS__)) + #endif + + /* Public Interface - May be used in end-application: */ + /* Macros: */ + /** \name HID Input, Output and Feature Report Descriptor Item Flags */ + //@{ + #define HID_IOF_CONSTANT (1 << 0) + #define HID_IOF_DATA (0 << 0) + #define HID_IOF_VARIABLE (1 << 1) + #define HID_IOF_ARRAY (0 << 1) + #define HID_IOF_RELATIVE (1 << 2) + #define HID_IOF_ABSOLUTE (0 << 2) + #define HID_IOF_WRAP (1 << 3) + #define HID_IOF_NO_WRAP (0 << 3) + #define HID_IOF_NON_LINEAR (1 << 4) + #define HID_IOF_LINEAR (0 << 4) + #define HID_IOF_NO_PREFERRED_STATE (1 << 5) + #define HID_IOF_PREFERRED_STATE (0 << 5) + #define HID_IOF_NULLSTATE (1 << 6) + #define HID_IOF_NO_NULL_POSITION (0 << 6) + #define HID_IOF_VOLATILE (1 << 7) + #define HID_IOF_NON_VOLATILE (0 << 7) + #define HID_IOF_BUFFERED_BYTES (1 << 8) + #define HID_IOF_BITFIELD (0 << 8) + //@} + + /** \name HID Report Descriptor Item Macros */ + //@{ + #define HID_RI_INPUT(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_MAIN , 0x80, DataBits, __VA_ARGS__) + #define HID_RI_OUTPUT(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_MAIN , 0x90, DataBits, __VA_ARGS__) + #define HID_RI_COLLECTION(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_MAIN , 0xA0, DataBits, __VA_ARGS__) + #define HID_RI_FEATURE(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_MAIN , 0xB0, DataBits, __VA_ARGS__) + #define HID_RI_END_COLLECTION(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_MAIN , 0xC0, DataBits, __VA_ARGS__) + #define HID_RI_USAGE_PAGE(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0x00, DataBits, __VA_ARGS__) + #define HID_RI_LOGICAL_MINIMUM(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0x10, DataBits, __VA_ARGS__) + #define HID_RI_LOGICAL_MAXIMUM(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0x20, DataBits, __VA_ARGS__) + #define HID_RI_PHYSICAL_MINIMUM(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0x30, DataBits, __VA_ARGS__) + #define HID_RI_PHYSICAL_MAXIMUM(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0x40, DataBits, __VA_ARGS__) + #define HID_RI_UNIT_EXPONENT(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0x50, DataBits, __VA_ARGS__) + #define HID_RI_UNIT(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0x60, DataBits, __VA_ARGS__) + #define HID_RI_REPORT_SIZE(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0x70, DataBits, __VA_ARGS__) + #define HID_RI_REPORT_ID(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0x80, DataBits, __VA_ARGS__) + #define HID_RI_REPORT_COUNT(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0x90, DataBits, __VA_ARGS__) + #define HID_RI_PUSH(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0xA0, DataBits, __VA_ARGS__) + #define HID_RI_POP(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_GLOBAL, 0xB0, DataBits, __VA_ARGS__) + #define HID_RI_USAGE(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_LOCAL , 0x00, DataBits, __VA_ARGS__) + #define HID_RI_USAGE_MINIMUM(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_LOCAL , 0x10, DataBits, __VA_ARGS__) + #define HID_RI_USAGE_MAXIMUM(DataBits, ...) _HID_RI_ENTRY(HID_RI_TYPE_LOCAL , 0x20, DataBits, __VA_ARGS__) + //@} + +/** @} */ + +#endif + diff --git a/LUFA/Drivers/USB/Class/Common/MIDIClassCommon.h b/LUFA/Drivers/USB/Class/Common/MIDIClassCommon.h new file mode 100644 index 0000000000..b6414bc06b --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/MIDIClassCommon.h @@ -0,0 +1,363 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Common definitions and declarations for the library USB MIDI Class driver. + * + * Common definitions and declarations for the library USB MIDI Class driver. + * + * \note This file should not be included directly. It is automatically included as needed by the USB module driver + * dispatch header located in LUFA/Drivers/USB.h. + */ + +/** \ingroup Group_USBClassMIDI + * \defgroup Group_USBClassMIDICommon Common Class Definitions + * + * \section Sec_USBClassMIDICommon_ModDescription Module Description + * Constants, Types and Enum definitions that are common to both Device and Host modes for the USB + * MIDI Class. + * + * @{ + */ + +#ifndef _MIDI_CLASS_COMMON_H_ +#define _MIDI_CLASS_COMMON_H_ + + /* Macros: */ + #define __INCLUDE_FROM_AUDIO_DRIVER + + /* Includes: */ + #include "../../Core/StdDescriptors.h" + #include "AudioClassCommon.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_MIDI_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. + #endif + + /* Macros: */ + /** \name MIDI Command Values + * See http://www.midi.org/techspecs/midimessages.php for more information. + */ + //@{ + /** MIDI command for System Exclusive (SysEx) single event that has one byte of data total. */ + #define MIDI_COMMAND_SYSEX_1BYTE MIDI_COMMAND_SYSEX_END_1BYTE + + /** MIDI command for System Exclusive (SysEx) single event that has two bytes of data total. */ + #define MIDI_COMMAND_SYSEX_2BYTE 0x20 + + /** MIDI command for System Exclusive (SysEx) single event that has three bytes of data total. */ + #define MIDI_COMMAND_SYSEX_3BYTE 0x30 + + /** MIDI command for System Exclusive (SysEx) stream event that has at least four bytes of data total. */ + #define MIDI_COMMAND_SYSEX_START_3BYTE 0x40 + + /** MIDI command for System Exclusive (SysEx) stream event terminator with one remaining data byte. */ + #define MIDI_COMMAND_SYSEX_END_1BYTE 0x50 + + /** MIDI command for System Exclusive (SysEx) stream event terminator with two remaining data bytes. */ + #define MIDI_COMMAND_SYSEX_END_2BYTE 0x60 + + /** MIDI command for System Exclusive (SysEx) stream event terminator with three remaining data bytes. */ + #define MIDI_COMMAND_SYSEX_END_3BYTE 0x70 + + /** MIDI command for a note off (deactivation) event. */ + #define MIDI_COMMAND_NOTE_OFF 0x80 + + /** MIDI command for a note on (activation) event. */ + #define MIDI_COMMAND_NOTE_ON 0x90 + + /** MIDI command for a note pressure change event. */ + #define MIDI_COMMAND_NOTE_PRESSURE 0xA0 + + /** MIDI command for a control change event. */ + #define MIDI_COMMAND_CONTROL_CHANGE 0xB0 + + /** MIDI command for a control change event. */ + #define MIDI_COMMAND_PROGRAM_CHANGE 0xC0 + + /** MIDI command for a channel pressure change event. */ + #define MIDI_COMMAND_CHANNEL_PRESSURE 0xD0 + + /** MIDI command for a pitch change event. */ + #define MIDI_COMMAND_PITCH_WHEEL_CHANGE 0xE0 + //@} + + /** Standard key press velocity value used for all note events. */ + #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[in] channel MIDI channel number to address. + * + * \return Constructed MIDI channel ID. + */ + #define MIDI_CHANNEL(channel) ((channel) - 1) + + /** Constructs a MIDI event ID from a given MIDI command and a virtual MIDI cable index. This can then be + * used to create and decode \ref MIDI_EventPacket_t MIDI event packets. + * + * \param[in] virtualcable Index of the virtual MIDI cable the event relates to + * \param[in] command MIDI command to send through the virtual MIDI cable + * + * \return Constructed MIDI event ID. + */ + #define MIDI_EVENT(virtualcable, command) (((virtualcable) << 4) | ((command) >> 4)) + + /* Enums: */ + /** Enum for the possible MIDI jack types in a MIDI device jack descriptor. */ + enum MIDI_JackTypes_t + { + MIDI_JACKTYPE_Embedded = 0x01, /**< MIDI class descriptor jack type value for an embedded (logical) MIDI input or output jack. */ + MIDI_JACKTYPE_External = 0x02, /**< MIDI class descriptor jack type value for an external (physical) MIDI input or output jack. */ + }; + + /* Type Defines: */ + /** \brief MIDI class-specific Streaming Interface Descriptor (LUFA naming conventions). + * + * 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. + * + * \see \ref USB_MIDI_StdDescriptor_AudioInterface_AS_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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. + * + * \see \ref VERSION_BCD() utility macro. + */ + uint16_t TotalLength; /**< Total length of the Audio class-specific descriptors, including this descriptor. */ + } ATTR_PACKED USB_MIDI_Descriptor_AudioInterface_AS_t; + + /** \brief MIDI class-specific Streaming Interface Descriptor (USB-IF naming conventions). + * + * 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. + * + * \see \ref USB_MIDI_Descriptor_AudioInterface_AS_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + + uint8_t bDescriptorSubtype; /**< Sub type value used to distinguish between audio class-specific descriptors. */ + + uint16_t bcdMSC; /**< Binary coded decimal value, indicating the supported MIDI Class specification version. + * + * \see \ref VERSION_BCD() utility macro. + */ + uint16_t wTotalLength; /**< Total length of the Audio class-specific descriptors, including this descriptor. */ + } ATTR_PACKED USB_MIDI_StdDescriptor_AudioInterface_AS_t; + + /** \brief MIDI class-specific Input Jack Descriptor (LUFA naming conventions). + * + * 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). + * + * \see \ref USB_MIDI_StdDescriptor_InputJack_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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 \c 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. */ + } ATTR_PACKED USB_MIDI_Descriptor_InputJack_t; + + /** \brief MIDI class-specific Input Jack Descriptor (USB-IF naming conventions). + * + * 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). + * + * \see \ref USB_MIDI_Descriptor_InputJack_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + + uint8_t bDescriptorSubtype; /**< Sub type value used to distinguish between audio class-specific descriptors. */ + + uint8_t bJackType; /**< Type of jack, one of the \c JACKTYPE_* mask values. */ + uint8_t bJackID; /**< ID value of this jack - must be a unique value within the device. */ + + uint8_t iJack; /**< Index of a string descriptor describing this descriptor within the device. */ + } ATTR_PACKED USB_MIDI_StdDescriptor_InputJack_t; + + /** \brief MIDI class-specific Output Jack Descriptor (LUFA naming conventions). + * + * 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). + * + * \see \ref USB_MIDI_StdDescriptor_OutputJack_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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 \c 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. */ + + uint8_t JackStrIndex; /**< Index of a string descriptor describing this descriptor within the device. */ + } ATTR_PACKED USB_MIDI_Descriptor_OutputJack_t; + + /** \brief MIDI class-specific Output Jack Descriptor (USB-IF naming conventions). + * + * 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). + * + * \see \ref USB_MIDI_Descriptor_OutputJack_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + + uint8_t bDescriptorSubtype; /**< Sub type value used to distinguish between audio class-specific descriptors. */ + + uint8_t bJackType; /**< Type of jack, one of the \c JACKTYPE_* mask values. */ + uint8_t bJackID; /**< ID value of this jack - must be a unique value within the device. */ + + uint8_t bNrInputPins; /**< Number of output channels within the jack, either physical or logical. */ + uint8_t baSourceID[1]; /**< ID of each output pin's source data jack. */ + uint8_t baSourcePin[1]; /**< Pin number in the input jack of each output pin's source data. */ + + uint8_t iJack; /**< Index of a string descriptor describing this descriptor within the device. */ + } ATTR_PACKED USB_MIDI_StdDescriptor_OutputJack_t; + + /** \brief Audio class-specific Jack Endpoint Descriptor (LUFA naming conventions). + * + * 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. + * + * \see \ref USB_MIDI_StdDescriptor_Jack_Endpoint_t for the version of this type with standard element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + 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. */ + } ATTR_PACKED USB_MIDI_Descriptor_Jack_Endpoint_t; + + /** \brief Audio class-specific Jack Endpoint Descriptor (USB-IF naming conventions). + * + * 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. + * + * \see \ref USB_MIDI_Descriptor_Jack_Endpoint_t for the version of this type with non-standard LUFA specific + * element names. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t bLength; /**< Size of the descriptor, in bytes. */ + uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value + * given by the specific class. + */ + + uint8_t bDescriptorSubtype; /**< Sub type value used to distinguish between audio class-specific descriptors. */ + + uint8_t bNumEmbMIDIJack; /**< Total number of jacks inside this endpoint. */ + uint8_t bAssocJackID[1]; /**< IDs of each jack inside the endpoint. */ + } ATTR_PACKED USB_MIDI_StdDescriptor_Jack_Endpoint_t; + + /** \brief MIDI Class Driver Event Packet. + * + * Type define for a USB MIDI event packet, used to encapsulate sent and received MIDI messages from a USB MIDI interface. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint8_t Event; /**< MIDI event type, constructed with the \ref MIDI_EVENT() macro. */ + + 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. */ + } ATTR_PACKED MIDI_EventPacket_t; + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ + diff --git a/LUFA/Drivers/USB/Class/Common/MassStorageClassCommon.h b/LUFA/Drivers/USB/Class/Common/MassStorageClassCommon.h new file mode 100644 index 0000000000..d2ea37a82a --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/MassStorageClassCommon.h @@ -0,0 +1,368 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Common definitions and declarations for the library USB Mass Storage Class driver. + * + * Common definitions and declarations for the library USB Mass Storage Class driver. + * + * \note This file should not be included directly. It is automatically included as needed by the USB module driver + * dispatch header located in LUFA/Drivers/USB.h. + */ + +/** \ingroup Group_USBClassMS + * \defgroup Group_USBClassMSCommon Common Class Definitions + * + * \section Sec_USBClassMSCommon_ModDescription Module Description + * Constants, Types and Enum definitions that are common to both Device and Host modes for the USB + * Mass Storage Class. + * + * @{ + */ + +#ifndef _MS_CLASS_COMMON_H_ +#define _MS_CLASS_COMMON_H_ + + /* Includes: */ + #include "../../Core/StdDescriptors.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_MS_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. + #endif + + /* Macros: */ + /** Magic signature for a Command Block Wrapper used in the Mass Storage Bulk-Only transport protocol. */ + #define MS_CBW_SIGNATURE 0x43425355UL + + /** Magic signature for a Command Status Wrapper used in the Mass Storage Bulk-Only transport protocol. */ + #define MS_CSW_SIGNATURE 0x53425355UL + + /** Mask for a Command Block Wrapper's flags attribute to specify a command with data sent from host-to-device. */ + #define MS_COMMAND_DIR_DATA_OUT (0 << 7) + + /** Mask for a Command Block Wrapper's flags attribute to specify a command with data sent from device-to-host. */ + #define MS_COMMAND_DIR_DATA_IN (1 << 7) + + /** \name SCSI Commands*/ + //@{ + /** SCSI Command Code for an INQUIRY command. */ + #define SCSI_CMD_INQUIRY 0x12 + + /** SCSI Command Code for a REQUEST SENSE command. */ + #define SCSI_CMD_REQUEST_SENSE 0x03 + + /** SCSI Command Code for a TEST UNIT READY command. */ + #define SCSI_CMD_TEST_UNIT_READY 0x00 + + /** SCSI Command Code for a READ CAPACITY (10) command. */ + #define SCSI_CMD_READ_CAPACITY_10 0x25 + + /** SCSI Command Code for a START STOP UNIT command. */ + #define SCSI_CMD_START_STOP_UNIT 0x1B + + /** SCSI Command Code for a SEND DIAGNOSTIC command. */ + #define SCSI_CMD_SEND_DIAGNOSTIC 0x1D + + /** SCSI Command Code for a PREVENT ALLOW MEDIUM REMOVAL command. */ + #define SCSI_CMD_PREVENT_ALLOW_MEDIUM_REMOVAL 0x1E + + /** SCSI Command Code for a WRITE (10) command. */ + #define SCSI_CMD_WRITE_10 0x2A + + /** SCSI Command Code for a READ (10) command. */ + #define SCSI_CMD_READ_10 0x28 + + /** SCSI Command Code for a WRITE (6) command. */ + #define SCSI_CMD_WRITE_6 0x0A + + /** SCSI Command Code for a READ (6) command. */ + #define SCSI_CMD_READ_6 0x08 + + /** SCSI Command Code for a VERIFY (10) command. */ + #define SCSI_CMD_VERIFY_10 0x2F + + /** SCSI Command Code for a MODE SENSE (6) command. */ + #define SCSI_CMD_MODE_SENSE_6 0x1A + + /** SCSI Command Code for a MODE SENSE (10) command. */ + #define SCSI_CMD_MODE_SENSE_10 0x5A + //@} + + /** \name SCSI Sense Key Values */ + //@{ + /** SCSI Sense Code to indicate no error has occurred. */ + #define SCSI_SENSE_KEY_GOOD 0x00 + + /** SCSI Sense Code to indicate that the device has recovered from an error. */ + #define SCSI_SENSE_KEY_RECOVERED_ERROR 0x01 + + /** SCSI Sense Code to indicate that the device is not ready for a new command. */ + #define SCSI_SENSE_KEY_NOT_READY 0x02 + + /** SCSI Sense Code to indicate an error whilst accessing the medium. */ + #define SCSI_SENSE_KEY_MEDIUM_ERROR 0x03 + + /** SCSI Sense Code to indicate a hardware error has occurred. */ + #define SCSI_SENSE_KEY_HARDWARE_ERROR 0x04 + + /** SCSI Sense Code to indicate that an illegal request has been issued. */ + #define SCSI_SENSE_KEY_ILLEGAL_REQUEST 0x05 + + /** SCSI Sense Code to indicate that the unit requires attention from the host to indicate + * a reset event, medium removal or other condition. + */ + #define SCSI_SENSE_KEY_UNIT_ATTENTION 0x06 + + /** SCSI Sense Code to indicate that a write attempt on a protected block has been made. */ + #define SCSI_SENSE_KEY_DATA_PROTECT 0x07 + + /** SCSI Sense Code to indicate an error while trying to write to a write-once medium. */ + #define SCSI_SENSE_KEY_BLANK_CHECK 0x08 + + /** SCSI Sense Code to indicate a vendor specific error has occurred. */ + #define SCSI_SENSE_KEY_VENDOR_SPECIFIC 0x09 + + /** SCSI Sense Code to indicate that an EXTENDED COPY command has aborted due to an error. */ + #define SCSI_SENSE_KEY_COPY_ABORTED 0x0A + + /** SCSI Sense Code to indicate that the device has aborted the issued command. */ + #define SCSI_SENSE_KEY_ABORTED_COMMAND 0x0B + + /** SCSI Sense Code to indicate an attempt to write past the end of a partition has been made. */ + #define SCSI_SENSE_KEY_VOLUME_OVERFLOW 0x0D + + /** SCSI Sense Code to indicate that the source data did not match the data read from the medium. */ + #define SCSI_SENSE_KEY_MISCOMPARE 0x0E + //@} + + /** \name SCSI Additional Sense Codes */ + //@{ + /** SCSI Additional Sense Code to indicate no additional sense information is available. */ + #define SCSI_ASENSE_NO_ADDITIONAL_INFORMATION 0x00 + + /** SCSI Additional Sense Code to indicate that the logical unit (LUN) addressed is not ready. */ + #define SCSI_ASENSE_LOGICAL_UNIT_NOT_READY 0x04 + + /** SCSI Additional Sense Code to indicate an invalid field was encountered while processing the issued command. */ + #define SCSI_ASENSE_INVALID_FIELD_IN_CDB 0x24 + + /** SCSI Additional Sense Code to indicate that a medium that was previously indicated as not ready has now + * become ready for use. + */ + #define SCSI_ASENSE_NOT_READY_TO_READY_CHANGE 0x28 + + /** SCSI Additional Sense Code to indicate that an attempt to write to a protected area was made. */ + #define SCSI_ASENSE_WRITE_PROTECTED 0x27 + + /** SCSI Additional Sense Code to indicate an error whilst formatting the device medium. */ + #define SCSI_ASENSE_FORMAT_ERROR 0x31 + + /** SCSI Additional Sense Code to indicate an invalid command was issued. */ + #define SCSI_ASENSE_INVALID_COMMAND 0x20 + + /** SCSI Additional Sense Code to indicate a write to a block out outside of the medium's range was issued. */ + #define SCSI_ASENSE_LOGICAL_BLOCK_ADDRESS_OUT_OF_RANGE 0x21 + + /** SCSI Additional Sense Code to indicate that no removable medium is inserted into the device. */ + #define SCSI_ASENSE_MEDIUM_NOT_PRESENT 0x3A + //@} + + /** \name SCSI Additional Sense Key Code Qualifiers */ + //@{ + /** SCSI Additional Sense Qualifier Code to indicate no additional sense qualifier information is available. */ + #define SCSI_ASENSEQ_NO_QUALIFIER 0x00 + + /** SCSI Additional Sense Qualifier Code to indicate that a medium format command failed to complete. */ + #define SCSI_ASENSEQ_FORMAT_COMMAND_FAILED 0x01 + + /** SCSI Additional Sense Qualifier Code to indicate that an initializing command must be issued before the issued + * command can be executed. + */ + #define SCSI_ASENSEQ_INITIALIZING_COMMAND_REQUIRED 0x02 + + /** SCSI Additional Sense Qualifier Code to indicate that an operation is currently in progress. */ + #define SCSI_ASENSEQ_OPERATION_IN_PROGRESS 0x07 + //@} + + /* Enums: */ + /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the Mass + * Storage device class. + */ + enum MS_Descriptor_ClassSubclassProtocol_t + { + MS_CSCP_MassStorageClass = 0x08, /**< Descriptor Class value indicating that the device or interface + * belongs to the Mass Storage class. + */ + MS_CSCP_SCSITransparentSubclass = 0x06, /**< Descriptor Subclass value indicating that the device or interface + * belongs to the SCSI Transparent Command Set subclass of the Mass + * storage class. + */ + MS_CSCP_BulkOnlyTransportProtocol = 0x50, /**< Descriptor Protocol value indicating that the device or interface + * belongs to the Bulk Only Transport protocol of the Mass Storage class. + */ + }; + + /** Enum for the Mass Storage class specific control requests that can be issued by the USB bus host. */ + enum MS_ClassRequests_t + { + MS_REQ_GetMaxLUN = 0xFE, /**< Mass Storage class-specific request to retrieve the total number of Logical + * Units (drives) in the SCSI device. + */ + MS_REQ_MassStorageReset = 0xFF, /**< Mass Storage class-specific request to reset the Mass Storage interface, + * ready for the next command. + */ + }; + + /** Enum for the possible command status wrapper return status codes. */ + enum MS_CommandStatusCodes_t + { + MS_SCSI_COMMAND_Pass = 0, /**< Command completed with no error */ + MS_SCSI_COMMAND_Fail = 1, /**< Command failed to complete - host may check the exact error via a + * SCSI REQUEST SENSE command. + */ + MS_SCSI_COMMAND_PhaseError = 2, /**< Command failed due to being invalid in the current phase. */ + }; + + /* Type Defines: */ + /** \brief Mass Storage Class Command Block Wrapper. + * + * Type define for a Command Block Wrapper, used in the Mass Storage Bulk-Only Transport protocol. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t Signature; /**< Command block signature, must be \ref MS_CBW_SIGNATURE to indicate a valid Command Block. */ + uint32_t Tag; /**< Unique command ID value, to associate a command block wrapper with its command status wrapper. */ + uint32_t DataTransferLength; /**< Length of the optional data portion of the issued command, in bytes. */ + uint8_t Flags; /**< Command block flags, indicating command data direction. */ + uint8_t LUN; /**< Logical Unit number this command is issued to. */ + uint8_t SCSICommandLength; /**< Length of the issued SCSI command within the SCSI command data array. */ + uint8_t SCSICommandData[16]; /**< Issued SCSI command in the Command Block. */ + } ATTR_PACKED MS_CommandBlockWrapper_t; + + /** \brief Mass Storage Class Command Status Wrapper. + * + * Type define for a Command Status Wrapper, used in the Mass Storage Bulk-Only Transport protocol. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t Signature; /**< Status block signature, must be \ref MS_CSW_SIGNATURE to indicate a valid Command Status. */ + uint32_t Tag; /**< Unique command ID value, to associate a command block wrapper with its command status wrapper. */ + uint32_t DataTransferResidue; /**< Number of bytes of data not processed in the SCSI command. */ + uint8_t Status; /**< Status code of the issued command - a value from the \ref MS_CommandStatusCodes_t enum. */ + } ATTR_PACKED MS_CommandStatusWrapper_t; + + /** \brief Mass Storage Class SCSI Sense Structure + * + * Type define for a SCSI Sense structure. Structures of this type are filled out by the + * device via the \ref MS_Host_RequestSense() function, indicating the current sense data of the + * device (giving explicit error codes for the last issued command). For details of the + * structure contents, refer to the SCSI specifications. + */ + typedef struct + { + uint8_t ResponseCode; + + uint8_t SegmentNumber; + + unsigned SenseKey : 4; + unsigned Reserved : 1; + unsigned ILI : 1; + unsigned EOM : 1; + unsigned FileMark : 1; + + uint8_t Information[4]; + uint8_t AdditionalLength; + uint8_t CmdSpecificInformation[4]; + uint8_t AdditionalSenseCode; + uint8_t AdditionalSenseQualifier; + uint8_t FieldReplaceableUnitCode; + uint8_t SenseKeySpecific[3]; + } ATTR_PACKED SCSI_Request_Sense_Response_t; + + /** \brief Mass Storage Class SCSI Inquiry Structure. + * + * Type define for a SCSI Inquiry structure. Structures of this type are filled out by the + * device via the \ref MS_Host_GetInquiryData() function, retrieving the attached device's + * information. + * + * For details of the structure contents, refer to the SCSI specifications. + */ + typedef struct + { + unsigned DeviceType : 5; + unsigned PeripheralQualifier : 3; + + unsigned Reserved : 7; + unsigned Removable : 1; + + uint8_t Version; + + unsigned ResponseDataFormat : 4; + unsigned Reserved2 : 1; + unsigned NormACA : 1; + unsigned TrmTsk : 1; + unsigned AERC : 1; + + uint8_t AdditionalLength; + uint8_t Reserved3[2]; + + unsigned SoftReset : 1; + unsigned CmdQue : 1; + unsigned Reserved4 : 1; + unsigned Linked : 1; + unsigned Sync : 1; + unsigned WideBus16Bit : 1; + unsigned WideBus32Bit : 1; + unsigned RelAddr : 1; + + uint8_t VendorID[8]; + uint8_t ProductID[16]; + uint8_t RevisionID[4]; + } ATTR_PACKED SCSI_Inquiry_Response_t; + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ + diff --git a/LUFA/Drivers/USB/Class/Common/PrinterClassCommon.h b/LUFA/Drivers/USB/Class/Common/PrinterClassCommon.h new file mode 100644 index 0000000000..2db830e048 --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/PrinterClassCommon.h @@ -0,0 +1,119 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Common definitions and declarations for the library USB Printer Class driver. + * + * Common definitions and declarations for the library USB Printer Class driver. + * + * \note This file should not be included directly. It is automatically included as needed by the USB module driver + * dispatch header located in LUFA/Drivers/USB.h. + */ + +/** \ingroup Group_USBClassPrinter + * \defgroup Group_USBClassPrinterCommon Common Class Definitions + * + * \section Sec_USBClassPrinterCommon_ModDescription Module Description + * Constants, Types and Enum definitions that are common to both Device and Host modes for the USB + * Printer Class. + * + * @{ + */ + +#ifndef _PRINTER_CLASS_COMMON_H_ +#define _PRINTER_CLASS_COMMON_H_ + + /* Includes: */ + #include "../../Core/StdDescriptors.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_PRINTER_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. + #endif + + /* Macros: */ + /** \name Virtual Printer Status Line Masks */ + //@{ + /** Port status mask for a printer device, indicating that an error has *not* occurred. */ + #define PRNT_PORTSTATUS_NOTERROR (1 << 3) + + /** Port status mask for a printer device, indicating that the device is currently selected. */ + #define PRNT_PORTSTATUS_SELECT (1 << 4) + + /** Port status mask for a printer device, indicating that the device is currently out of paper. */ + #define PRNT_PORTSTATUS_PAPEREMPTY (1 << 5) + //@} + + /* Enums: */ + /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the Printer + * device class. + */ + enum PRNT_Descriptor_ClassSubclassProtocol_t + { + PRNT_CSCP_PrinterClass = 0x07, /**< Descriptor Class value indicating that the device or interface + * belongs to the Printer class. + */ + PRNT_CSCP_PrinterSubclass = 0x01, /**< Descriptor Subclass value indicating that the device or interface + * belongs to the Printer subclass. + */ + PRNT_CSCP_BidirectionalProtocol = 0x02, /**< Descriptor Protocol value indicating that the device or interface + * belongs to the Bidirectional protocol of the Printer class. + */ + }; + + /** Enum for the Printer class specific control requests that can be issued by the USB bus host. */ + enum PRNT_ClassRequests_t + { + PRNT_REQ_GetDeviceID = 0x00, /**< Printer class-specific request to retrieve the Unicode ID + * string of the device, containing the device's name, manufacturer + * and supported printer languages. + */ + PRNT_REQ_GetPortStatus = 0x01, /**< Printer class-specific request to get the current status of the + * virtual printer port, for device selection and ready states. + */ + PRNT_REQ_SoftReset = 0x02, /**< Printer class-specific request to reset the device, ready for new + * printer commands. + */ + }; + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ + diff --git a/LUFA/Drivers/USB/Class/Common/RNDISClassCommon.h b/LUFA/Drivers/USB/Class/Common/RNDISClassCommon.h new file mode 100644 index 0000000000..ade1af0673 --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/RNDISClassCommon.h @@ -0,0 +1,411 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Common definitions and declarations for the library USB RNDIS Class driver. + * + * Common definitions and declarations for the library USB RNDIS Class driver. + * + * \note This file should not be included directly. It is automatically included as needed by the USB module driver + * dispatch header located in LUFA/Drivers/USB.h. + */ + +/** \ingroup Group_USBClassRNDIS + * \defgroup Group_USBClassRNDISCommon Common Class Definitions + * + * \section Sec_USBClassRNDISCommon_ModDescription Module Description + * Constants, Types and Enum definitions that are common to both Device and Host modes for the USB + * RNDIS Class. + * + * @{ + */ + +#ifndef _RNDIS_CLASS_COMMON_H_ +#define _RNDIS_CLASS_COMMON_H_ + + /* Macros: */ + #define __INCLUDE_FROM_CDC_DRIVER + + /* Includes: */ + #include "../../Core/StdDescriptors.h" + #include "CDCClassCommon.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_RNDIS_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. + #endif + + /* Macros: */ + /** Additional error code for RNDIS functions when a device returns a logical command failure. */ + #define RNDIS_ERROR_LOGICAL_CMD_FAILED 0x80 + + /** Implemented RNDIS Version Major. */ + #define REMOTE_NDIS_VERSION_MAJOR 0x01 + + /** Implemented RNDIS Version Minor. */ + #define REMOTE_NDIS_VERSION_MINOR 0x00 + + /** \name RNDIS Message Values */ + //@{ + #define REMOTE_NDIS_PACKET_MSG 0x00000001UL + #define REMOTE_NDIS_INITIALIZE_MSG 0x00000002UL + #define REMOTE_NDIS_HALT_MSG 0x00000003UL + #define REMOTE_NDIS_QUERY_MSG 0x00000004UL + #define REMOTE_NDIS_SET_MSG 0x00000005UL + #define REMOTE_NDIS_RESET_MSG 0x00000006UL + #define REMOTE_NDIS_INDICATE_STATUS_MSG 0x00000007UL + #define REMOTE_NDIS_KEEPALIVE_MSG 0x00000008UL + //@} + + /** \name RNDIS Response Values */ + //@{ + #define REMOTE_NDIS_INITIALIZE_CMPLT 0x80000002UL + #define REMOTE_NDIS_QUERY_CMPLT 0x80000004UL + #define REMOTE_NDIS_SET_CMPLT 0x80000005UL + #define REMOTE_NDIS_RESET_CMPLT 0x80000006UL + #define REMOTE_NDIS_KEEPALIVE_CMPLT 0x80000008UL + //@} + + /** \name RNDIS Status Values */ + //@{ + #define REMOTE_NDIS_STATUS_SUCCESS 0x00000000UL + #define REMOTE_NDIS_STATUS_FAILURE 0xC0000001UL + #define REMOTE_NDIS_STATUS_INVALID_DATA 0xC0010015UL + #define REMOTE_NDIS_STATUS_NOT_SUPPORTED 0xC00000BBUL + #define REMOTE_NDIS_STATUS_MEDIA_CONNECT 0x4001000BUL + #define REMOTE_NDIS_STATUS_MEDIA_DISCONNECT 0x4001000CUL + //@} + + /** \name RNDIS Media States */ + //@{ + #define REMOTE_NDIS_MEDIA_STATE_CONNECTED 0x00000000UL + #define REMOTE_NDIS_MEDIA_STATE_DISCONNECTED 0x00000001UL + //@} + + /** \name RNDIS Media Types */ + //@{ + #define REMOTE_NDIS_MEDIUM_802_3 0x00000000UL + //@} + + /** \name RNDIS Connection Types */ + //@{ + #define REMOTE_NDIS_DF_CONNECTIONLESS 0x00000001UL + #define REMOTE_NDIS_DF_CONNECTION_ORIENTED 0x00000002UL + //@} + + /** \name RNDIS Packet Types */ + //@{ + #define REMOTE_NDIS_PACKET_DIRECTED 0x00000001UL + #define REMOTE_NDIS_PACKET_MULTICAST 0x00000002UL + #define REMOTE_NDIS_PACKET_ALL_MULTICAST 0x00000004UL + #define REMOTE_NDIS_PACKET_BROADCAST 0x00000008UL + #define REMOTE_NDIS_PACKET_SOURCE_ROUTING 0x00000010UL + #define REMOTE_NDIS_PACKET_PROMISCUOUS 0x00000020UL + #define REMOTE_NDIS_PACKET_SMT 0x00000040UL + #define REMOTE_NDIS_PACKET_ALL_LOCAL 0x00000080UL + #define REMOTE_NDIS_PACKET_GROUP 0x00001000UL + #define REMOTE_NDIS_PACKET_ALL_FUNCTIONAL 0x00002000UL + #define REMOTE_NDIS_PACKET_FUNCTIONAL 0x00004000UL + #define REMOTE_NDIS_PACKET_MAC_FRAME 0x00008000UL + //@} + + /** \name RNDIS OID Values */ + //@{ + #define OID_GEN_SUPPORTED_LIST 0x00010101UL + #define OID_GEN_HARDWARE_STATUS 0x00010102UL + #define OID_GEN_MEDIA_SUPPORTED 0x00010103UL + #define OID_GEN_MEDIA_IN_USE 0x00010104UL + #define OID_GEN_MAXIMUM_FRAME_SIZE 0x00010106UL + #define OID_GEN_MAXIMUM_TOTAL_SIZE 0x00010111UL + #define OID_GEN_LINK_SPEED 0x00010107UL + #define OID_GEN_TRANSMIT_BLOCK_SIZE 0x0001010AUL + #define OID_GEN_RECEIVE_BLOCK_SIZE 0x0001010BUL + #define OID_GEN_VENDOR_ID 0x0001010CUL + #define OID_GEN_VENDOR_DESCRIPTION 0x0001010DUL + #define OID_GEN_CURRENT_PACKET_FILTER 0x0001010EUL + #define OID_GEN_MAXIMUM_TOTAL_SIZE 0x00010111UL + #define OID_GEN_MEDIA_CONNECT_STATUS 0x00010114UL + #define OID_GEN_PHYSICAL_MEDIUM 0x00010202UL + #define OID_GEN_XMIT_OK 0x00020101UL + #define OID_GEN_RCV_OK 0x00020102UL + #define OID_GEN_XMIT_ERROR 0x00020103UL + #define OID_GEN_RCV_ERROR 0x00020104UL + #define OID_GEN_RCV_NO_BUFFER 0x00020105UL + #define OID_802_3_PERMANENT_ADDRESS 0x01010101UL + #define OID_802_3_CURRENT_ADDRESS 0x01010102UL + #define OID_802_3_MULTICAST_LIST 0x01010103UL + #define OID_802_3_MAXIMUM_LIST_SIZE 0x01010104UL + #define OID_802_3_RCV_ERROR_ALIGNMENT 0x01020101UL + #define OID_802_3_XMIT_ONE_COLLISION 0x01020102UL + #define OID_802_3_XMIT_MORE_COLLISIONS 0x01020103UL + //@} + + /** Maximum size in bytes of an Ethernet frame according to the Ethernet standard. */ + #define ETHERNET_FRAME_SIZE_MAX 1500 + + /* Enums: */ + /** Enum for the RNDIS class specific control requests that can be issued by the USB bus host. */ + enum RNDIS_ClassRequests_t + { + RNDIS_REQ_SendEncapsulatedCommand = 0x00, /**< RNDIS request to issue a host-to-device NDIS command. */ + RNDIS_REQ_GetEncapsulatedResponse = 0x01, /**< RNDIS request to issue a device-to-host NDIS response. */ + }; + + /** Enum for the possible NDIS adapter states. */ + enum RNDIS_States_t + { + RNDIS_Uninitialized = 0, /**< Adapter currently uninitialized. */ + RNDIS_Initialized = 1, /**< Adapter currently initialized but not ready for data transfers. */ + RNDIS_Data_Initialized = 2, /**< Adapter currently initialized and ready for data transfers. */ + }; + + /** Enum for the RNDIS class specific notification requests that can be issued by a RNDIS device to a host. */ + enum RNDIS_ClassNotifications_t + { + RNDIS_NOTIF_ResponseAvailable = 0x01, /**< Notification request value for a RNDIS Response Available notification. */ + }; + + /** Enum for the NDIS hardware states. */ + enum NDIS_Hardware_Status_t + { + 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: */ + /** \brief MAC Address Structure. + * + * Type define for a physical MAC address of a device on a network. + */ + typedef struct + { + uint8_t Octets[6]; /**< Individual bytes of a MAC address */ + } ATTR_PACKED MAC_Address_t; + + /** \brief RNDIS Common Message Header Structure. + * + * Type define for a RNDIS message header, sent before RNDIS messages. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t MessageType; /**< RNDIS message type, a \c REMOTE_NDIS_*_MSG constant */ + uint32_t MessageLength; /**< Total length of the RNDIS message, in bytes */ + } ATTR_PACKED RNDIS_Message_Header_t; + + /** \brief RNDIS Message Structure. + * + * Type define for a RNDIS packet message, used to encapsulate Ethernet packets sent to and from the adapter. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t MessageType; + uint32_t MessageLength; + uint32_t DataOffset; + uint32_t DataLength; + uint32_t OOBDataOffset; + uint32_t OOBDataLength; + uint32_t NumOOBDataElements; + uint32_t PerPacketInfoOffset; + uint32_t PerPacketInfoLength; + uint32_t VcHandle; + uint32_t Reserved; + } ATTR_PACKED RNDIS_Packet_Message_t; + + /** \brief RNDIS Initialization Message Structure. + * + * Type define for a RNDIS Initialize command message. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t MessageType; + uint32_t MessageLength; + uint32_t RequestId; + + uint32_t MajorVersion; + uint32_t MinorVersion; + uint32_t MaxTransferSize; + } ATTR_PACKED RNDIS_Initialize_Message_t; + + /** \brief RNDIS Initialize Complete Message Structure. + * + * Type define for a RNDIS Initialize Complete response message. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t MessageType; + uint32_t MessageLength; + uint32_t RequestId; + uint32_t Status; + + uint32_t MajorVersion; + uint32_t MinorVersion; + uint32_t DeviceFlags; + uint32_t Medium; + uint32_t MaxPacketsPerTransfer; + uint32_t MaxTransferSize; + uint32_t PacketAlignmentFactor; + uint32_t AFListOffset; + uint32_t AFListSize; + } ATTR_PACKED RNDIS_Initialize_Complete_t; + + /** \brief RNDIS Keep Alive Message Structure. + * + * Type define for a RNDIS Keep Alive command message. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t MessageType; + uint32_t MessageLength; + uint32_t RequestId; + } ATTR_PACKED RNDIS_KeepAlive_Message_t; + + /** \brief RNDIS Keep Alive Complete Message Structure. + * + * Type define for a RNDIS Keep Alive Complete response message. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t MessageType; + uint32_t MessageLength; + uint32_t RequestId; + uint32_t Status; + } ATTR_PACKED RNDIS_KeepAlive_Complete_t; + + /** \brief RNDIS Reset Complete Message Structure. + * + * Type define for a RNDIS Reset Complete response message. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t MessageType; + uint32_t MessageLength; + uint32_t Status; + + uint32_t AddressingReset; + } ATTR_PACKED RNDIS_Reset_Complete_t; + + /** \brief RNDIS OID Property Set Message Structure. + * + * Type define for a RNDIS OID Property Set command message. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t MessageType; + uint32_t MessageLength; + uint32_t RequestId; + + uint32_t Oid; + uint32_t InformationBufferLength; + uint32_t InformationBufferOffset; + uint32_t DeviceVcHandle; + } ATTR_PACKED RNDIS_Set_Message_t; + + /** \brief RNDIS OID Property Set Complete Message Structure. + * + * Type define for a RNDIS OID Property Set Complete response message. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t MessageType; + uint32_t MessageLength; + uint32_t RequestId; + uint32_t Status; + } ATTR_PACKED RNDIS_Set_Complete_t; + + /** \brief RNDIS OID Property Query Message Structure. + * + * Type define for a RNDIS OID Property Query command message. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t MessageType; + uint32_t MessageLength; + uint32_t RequestId; + + uint32_t Oid; + uint32_t InformationBufferLength; + uint32_t InformationBufferOffset; + uint32_t DeviceVcHandle; + } ATTR_PACKED RNDIS_Query_Message_t; + + /** \brief RNDIS OID Property Query Complete Message Structure. + * + * Type define for a RNDIS OID Property Query Complete response message. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t MessageType; + uint32_t MessageLength; + uint32_t RequestId; + uint32_t Status; + + uint32_t InformationBufferLength; + uint32_t InformationBufferOffset; + } ATTR_PACKED RNDIS_Query_Complete_t; + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ + diff --git a/LUFA/Drivers/USB/Class/Common/StillImageClassCommon.h b/LUFA/Drivers/USB/Class/Common/StillImageClassCommon.h new file mode 100644 index 0000000000..7608b18cc4 --- /dev/null +++ b/LUFA/Drivers/USB/Class/Common/StillImageClassCommon.h @@ -0,0 +1,161 @@ +/* + LUFA Library + Copyright (C) Dean Camera, 2017. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2017 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the + software without specific, written prior permission. + + The author disclaims all warranties with regard to this + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Common definitions and declarations for the library USB Still Image Class driver. + * + * Common definitions and declarations for the library USB Still Image Class driver. + * + * \note This file should not be included directly. It is automatically included as needed by the USB module driver + * dispatch header located in LUFA/Drivers/USB.h. + */ + +/** \ingroup Group_USBClassSI + * \defgroup Group_USBClassSICommon Common Class Definitions + * + * \section Sec_USBClassSICommon_ModDescription Module Description + * Constants, Types and Enum definitions that are common to both Device and Host modes for the USB + * Still Image Class. + * + * @{ + */ + +#ifndef _SI_CLASS_COMMON_H_ +#define _SI_CLASS_COMMON_H_ + + /* Includes: */ + #include "../../Core/StdDescriptors.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_SI_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. + #endif + + /* Macros: */ + /** Length in bytes of a given Unicode string's character length. + * + * \param[in] Chars Total number of Unicode characters in the string. + * + * \return Number of bytes of the given unicode string. + */ + #define UNICODE_STRING_LENGTH(Chars) ((Chars) << 1) + + /** Used in the DataLength field of a PIMA container, to give the total container size in bytes for + * a command container. + * + * \param[in] Params Number of parameters which are to be sent in the \c Param field of the container. + */ + #define PIMA_COMMAND_SIZE(Params) ((sizeof(PIMA_Container_t) - 12) + ((Params) * sizeof(uint32_t))) + + /** Used in the DataLength field of a PIMA container, to give the total container size in bytes for + * a data container. + * + * \param[in] DataLen Length in bytes of the data in the container. + */ + #define PIMA_DATA_SIZE(DataLen) ((sizeof(PIMA_Container_t) - 12) + (DataLen)) + + /* Enums: */ + /** Enum for the possible PIMA contains types. */ + enum PIMA_Container_Types_t + { + PIMA_CONTAINER_Undefined = 0, /**< Undefined container type. */ + PIMA_CONTAINER_CommandBlock = 1, /**< Command Block container type. */ + PIMA_CONTAINER_DataBlock = 2, /**< Data Block container type. */ + PIMA_CONTAINER_ResponseBlock = 3, /**< Response container type. */ + PIMA_CONTAINER_EventBlock = 4, /**< Event Block container type. */ + }; + + /* Enums: */ + /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors relating to the + * Still Image device class. + */ + enum SI_Descriptor_ClassSubclassProtocol_t + { + SI_CSCP_StillImageClass = 0x06, /**< Descriptor Class value indicating that the device or interface + * belongs to the Still Image class. + */ + SI_CSCP_StillImageSubclass = 0x01, /**< Descriptor Subclass value indicating that the device or interface + * belongs to the Still Image subclass. + */ + SI_CSCP_BulkOnlyProtocol = 0x01, /**< Descriptor Protocol value indicating that the device or interface + * belongs to the Bulk Only Transport protocol of the Still Image class. + */ + }; + + /** Enums for the possible status codes of a returned Response Block from an attached PIMA compliant Still Image device. */ + enum PIMA_ResponseCodes_t + { + PIMA_RESPONSE_OK = 1, /**< Response code indicating no error in the issued command. */ + PIMA_RESPONSE_GeneralError = 2, /**< Response code indicating a general error while processing the + * issued command. + */ + PIMA_RESPONSE_SessionNotOpen = 3, /**< Response code indicating that the sent command requires an open + * session before being issued. + */ + PIMA_RESPONSE_InvalidTransaction = 4, /**< Response code indicating an invalid transaction occurred. */ + PIMA_RESPONSE_OperationNotSupported = 5, /**< Response code indicating that the issued command is not supported + * by the attached device. + */ + PIMA_RESPONSE_ParameterNotSupported = 6, /**< Response code indicating that one or more of the issued command's + * parameters are not supported by the device. + */ + }; + + /* Type Defines: */ + /** \brief PIMA Still Image Device Command/Response Container. + * + * Type define for a PIMA container, use to send commands and receive responses to and from an + * attached Still Image device. + * + * \note Regardless of CPU architecture, these values should be stored as little endian. + */ + typedef struct + { + uint32_t DataLength; /**< Length of the container and data, in bytes. */ + uint16_t Type; /**< Container type, a value from the \ref PIMA_Container_Types_t enum. */ + uint16_t Code; /**< Command, event or response code of the container. */ + uint32_t TransactionID; /**< Unique container ID to link blocks together. */ + uint32_t Params[3]; /**< Block parameters to be issued along with the block code (command blocks only). */ + } ATTR_PACKED PIMA_Container_t; + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ + |