Skip to content

Commit

Permalink
chore: update documentation
Browse files Browse the repository at this point in the history 
improve readability of descriptors
  • Loading branch information
@elagil
elagil committed Dec 25, 2023
1 parent 3388552 commit 6afe94a
Show file tree
Hide file tree
Showing 4 changed files with 69 additions and 43 deletions.
2 changes: 1 addition & 1 deletion .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ repos:
- id: cpplint

- repo: https://github.com/crate-ci/typos
rev: v1.16.23
rev: v1.16.25
hooks:
- id: typos
args:
Expand Down
Binary file added doc/cdc120.pdf
View file
Binary file not shown.
13 changes: 13 additions & 0 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -104,3 +104,16 @@ This feedback mechanism is a control loop, where the sound card (USB device) is

For more detail, see [UAC v1 specification](./doc/audio10.pdf). The audio feedback mechanism is implemented as described in *3.7.2.2 Isochronous Synch Endpoint* (p. 32).
An extended description is found in the [general USB 2.0 specification](./doc/usb_20.pdf) in *5.12.4.2 Feedback* (p.75). Information about [supported audio formats](./doc/frmts10.pdf) and [terminal types](./doc/termt10.pdf) is also available.

# Summary of documentation

## General

- [Universal Serial Bus Specification](./doc/usb_20.pdf)
- [Universal Serial Bus Device Class Definition for Terminal Types](./doc/termt10.pdf)
- [Universal Serial Bus Class Definitions for Communications Devices](./doc/cdc120.pdf)

## Audio specific

- [Universal Serial Bus Device Class Definition for Audio Devices](./doc/audio10.pdf)
- [Universal Serial Bus Device Class Definition for Audio Data Formats](./doc/frmts10.pdf)
97 changes: 55 additions & 42 deletions source/usb/usb_descriptors.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,19 +144,32 @@ enum usb_desc_channel_config {
* @brief Feature unit control bit masks.
*/
enum usb_desc_fu_controls {
USB_DESC_FU_CONTROLS_NONE = 0X0000U,
USB_DESC_FU_CONTROLS_MUTE = 0X0001U,
USB_DESC_FU_CONTROLS_VOLUME = 0X0002u,
USB_DESC_FU_CONTROLS_BASS = 0X0004U,
USB_DESC_FU_CONTROLS_MID = 0X0008U,
USB_DESC_FU_CONTROLS_TREBLE = 0X0010u,
USB_DESC_FU_CONTROLS_NONE = 0x0000U,
USB_DESC_FU_CONTROLS_MUTE = 0x0001U,
USB_DESC_FU_CONTROLS_VOLUME = 0x0002u,
USB_DESC_FU_CONTROLS_BASS = 0x0004U,
USB_DESC_FU_CONTROLS_MID = 0x0008U,
USB_DESC_FU_CONTROLS_TREBLE = 0x0010u,
USB_DESC_FU_CONTROLS_GRAPHIC_EQUALIZER = 0x0020u,
USB_DESC_FU_CONTROLS_AUTOMATIC_GAIN = 0x0040u,
USB_DESC_FU_CONTROLS_DELAY = 0x0080u,
USB_DESC_FU_CONTROLS_BASS_BOOST = 0x0100u,
USB_DESC_FU_CONTROLS_LOUDNESS = 0x0200u,
};

/**
* @brief Type Values for the bDescriptorType Field.
* @note The bDescriptorType values are the same ones defined in the USB Device Class Definition for Audio Devices
* Specification. They were derived by using the DEVICE, CONFIGURATION, STRING, INTERFACE, and ENDPOINT constants
* defined in chapter 9 of the USB Specification and by setting the class-specific bit defined within the Common Class
* Specification to generate corresponding class-specific constants. See "Universal Serial Bus Class Definitions for
* Communications Devices".
*/
enum usb_desc_class_specific_type {
USB_DESC_CLASS_SPECIFIC_TYPE_INTERFACE = 0x24u,
USB_DESC_CLASS_SPECIFIC_TYPE_ENDPOINT = 0x25u,
};

// USB interface definitions.
#define USB_DESC_INTERFACE_CLASS_AUDIO 0x01u
#define USB_DESC_INTERFACE_CLASS_AUDIO_SUBCLASS_CONTROL 0x01u
Expand Down Expand Up @@ -209,30 +222,30 @@ static const uint8_t audio_configuration_descriptor_data[USB_DESCRIPTORS_TOTAL_L
0u), // iInterface.

// Class-specific AC Interface Descriptor (UAC 4.3.2)
USB_DESC_BYTE(9u), // bLength.
USB_DESC_BYTE(0x24u), // bDescriptorType (CS_INTERFACE).
USB_DESC_BYTE(0x01u), // bDescriptorSubtype (Header).
USB_DESC_BCD(USB_DESC_ADC_VERSION), // bcdADC.
USB_DESC_WORD(43u), // wTotalLength.
USB_DESC_BYTE(0x01u), // bInCollection (1 streaming interface).
USB_DESC_BYTE(USB_DESC_INTERFACE_STREAMING), // baInterfaceNr.
USB_DESC_BYTE(9u), // bLength.
USB_DESC_BYTE(USB_DESC_CLASS_SPECIFIC_TYPE_INTERFACE), // bDescriptorType.
USB_DESC_BYTE(0x01u), // bDescriptorSubtype (Header).
USB_DESC_BCD(USB_DESC_ADC_VERSION), // bcdADC.
USB_DESC_WORD(43u), // wTotalLength.
USB_DESC_BYTE(0x01u), // bInCollection (1 streaming interface).
USB_DESC_BYTE(USB_DESC_INTERFACE_STREAMING), // baInterfaceNr.

// Input Terminal Descriptor (UAC 4.3.2.1)
USB_DESC_BYTE(12u), // bLength.
USB_DESC_BYTE(0x24u), // bDescriptorType.
USB_DESC_BYTE(USB_DESC_TERMINAL_TYPE_INPUT), // bDescriptorSubtype.
USB_DESC_BYTE(USB_DESC_UNIT_INPUT), // bTerminalID.
USB_DESC_WORD(USB_DESC_TERMINAL_TYPE_STREAMING), // wTerminalType.
USB_DESC_BYTE(0x00u), // bAssocTerminal (none).
USB_DESC_BYTE(AUDIO_CHANNEL_COUNT), // bNrChannels.
USB_DESC_BYTE(12u), // bLength.
USB_DESC_BYTE(USB_DESC_CLASS_SPECIFIC_TYPE_INTERFACE), // bDescriptorType.
USB_DESC_BYTE(USB_DESC_TERMINAL_TYPE_INPUT), // bDescriptorSubtype.
USB_DESC_BYTE(USB_DESC_UNIT_INPUT), // bTerminalID.
USB_DESC_WORD(USB_DESC_TERMINAL_TYPE_STREAMING), // wTerminalType.
USB_DESC_BYTE(0x00u), // bAssocTerminal (none).
USB_DESC_BYTE(AUDIO_CHANNEL_COUNT), // bNrChannels.
USB_DESC_WORD(USB_DESC_CHANNEL_CONFIG_RIGHT_FRONT |
USB_DESC_CHANNEL_CONFIG_LEFT_FRONT), // wChannelConfig (left, right).
USB_DESC_BYTE(0x00u), // iChannelNames (none).
USB_DESC_BYTE(0x00u), // iTerminal (none).

// Feature Unit Descriptor (UAC 4.3.2.5)
USB_DESC_BYTE(13u), // bLength.
USB_DESC_BYTE(0x24u), // bDescriptorType.
USB_DESC_BYTE(USB_DESC_CLASS_SPECIFIC_TYPE_INTERFACE), // bDescriptorType.
USB_DESC_BYTE(0x06u), // bDescriptorSubtype (Feature Unit).
USB_DESC_BYTE(USB_DESC_UNIT_FUNCTION), // bUnitID.
USB_DESC_BYTE(USB_DESC_UNIT_INPUT), // bSourceID.
Expand All @@ -243,14 +256,14 @@ static const uint8_t audio_configuration_descriptor_data[USB_DESCRIPTORS_TOTAL_L
USB_DESC_BYTE(0x00u), // iFeature (none)

// Output Terminal Descriptor (UAC 4.3.2.2)
USB_DESC_BYTE(9u), // bLength.
USB_DESC_BYTE(0x24u), // bDescriptorType.
USB_DESC_BYTE(USB_DESC_TERMINAL_TYPE_OUTPUT), // bDescriptorSubtype.
USB_DESC_BYTE(USB_DESC_UNIT_OUTPUT), // bTerminalID.
USB_DESC_WORD(USB_DESC_OUTPUT_TERMINAL_TYPE_SPEAKER), // wTerminalType.
USB_DESC_BYTE(0x00u), // bAssocTerminal (none).
USB_DESC_BYTE(USB_DESC_UNIT_FUNCTION), // bSourceID.
USB_DESC_BYTE(0x00u), // iTerminal (none).
USB_DESC_BYTE(9u), // bLength.
USB_DESC_BYTE(USB_DESC_CLASS_SPECIFIC_TYPE_INTERFACE), // bDescriptorType.
USB_DESC_BYTE(USB_DESC_TERMINAL_TYPE_OUTPUT), // bDescriptorSubtype.
USB_DESC_BYTE(USB_DESC_UNIT_OUTPUT), // bTerminalID.
USB_DESC_WORD(USB_DESC_OUTPUT_TERMINAL_TYPE_SPEAKER), // wTerminalType.
USB_DESC_BYTE(0x00u), // bAssocTerminal (none).
USB_DESC_BYTE(USB_DESC_UNIT_FUNCTION), // bSourceID.
USB_DESC_BYTE(0x00u), // iTerminal (none).

// Standard AS Interface Descriptor (zero-bandwidth) (UAC 4.5.1)
USB_DESC_INTERFACE(USB_DESC_INTERFACE_STREAMING, // bInterfaceNumber.
Expand All @@ -271,16 +284,16 @@ static const uint8_t audio_configuration_descriptor_data[USB_DESCRIPTORS_TOTAL_L
USB_DESC_INTERFACE_NONE), // iInterface.

// Class-specific AS Interface Descriptor (UAC 4.5.2)
USB_DESC_BYTE(7u), // bLength.
USB_DESC_BYTE(0x24u), // bDescriptorType (CS_INTERFACE).
USB_DESC_BYTE(0x01u), // bDescriptorSubtype (general).
USB_DESC_BYTE(USB_DESC_UNIT_INPUT), // bTerminalLink.
USB_DESC_BYTE(0x00u), // bDelay (none).
USB_DESC_WORD(0x0001u), // wFormatTag (PCM format).
USB_DESC_BYTE(7u), // bLength.
USB_DESC_BYTE(USB_DESC_CLASS_SPECIFIC_TYPE_INTERFACE), // bDescriptorType (CS_INTERFACE).
USB_DESC_BYTE(0x01u), // bDescriptorSubtype (general).
USB_DESC_BYTE(USB_DESC_UNIT_INPUT), // bTerminalLink.
USB_DESC_BYTE(0x00u), // bDelay (none).
USB_DESC_WORD(0x0001u), // wFormatTag (PCM format).

// Class-Specific AS Format Type Descriptor (UAC 4.5.3)
USB_DESC_BYTE(14u), // bLength.
USB_DESC_BYTE(0x24u), // bDescriptorType (CS_INTERFACE).
USB_DESC_BYTE(USB_DESC_CLASS_SPECIFIC_TYPE_INTERFACE), // bDescriptorType (CS_INTERFACE).
USB_DESC_BYTE(0x02u), // bDescriptorSubtype (Format).
USB_DESC_BYTE(USB_DESC_AUDIO_FORMAT_TYPE_I), // bFormatType (Type I).
USB_DESC_BYTE(AUDIO_CHANNEL_COUNT), // bNrChannels.
Expand All @@ -305,12 +318,12 @@ static const uint8_t audio_configuration_descriptor_data[USB_DESCRIPTORS_TOTAL_L
USB_DESC_BYTE(USB_DESC_ENDPOINT_FEEDBACK | 0x80u), // bSynchAddress.

// C-S AS Isochronous Audio Data Endpoint Descriptor (UAC 4.6.1.2)
USB_DESC_BYTE(7u), // bLength.
USB_DESC_BYTE(0x25u), // bDescriptorType (CS_ENDPOINT).
USB_DESC_BYTE(0x01u), // bDescriptorSubtype (General).
USB_DESC_BYTE(0x01u), // bmAttributes - support sampling frequency adjustment.
USB_DESC_BYTE(0x02u), // bLockDelayUnits (PCM Samples).
USB_DESC_WORD(0x0000u), // bLockDelay (0).
USB_DESC_BYTE(7u), // bLength.
USB_DESC_BYTE(USB_DESC_CLASS_SPECIFIC_TYPE_ENDPOINT), // bDescriptorType.
USB_DESC_BYTE(0x01u), // bDescriptorSubtype (General).
USB_DESC_BYTE(0x01u), // bmAttributes - support sampling frequency adjustment.
USB_DESC_BYTE(0x02u), // bLockDelayUnits (PCM sample count).
USB_DESC_WORD(0x0000u), // bLockDelay (0).

// Standard Isochronous Audio Feedback Endpoint Descriptor
USB_DESC_BYTE(9u), // bLength (9).
Expand Down

0 comments on commit 6afe94a

Please sign in to comment.