dt-bindings: usb: initial USB Audio Class 2 support

USB Audio Class 2 (UAC2) includes a method to describe audio device
topology to host using a set of class specific descriptors. The audio
device description includes complete sample clock topology and audio
processing organization.

Zephyr specific bindings are supposed to allow user to create reasonably
simple audio device description using devicetree syntax. The bindings
currently include only the absolute minimum set required for headset
example. Bindings for other entities (Clock Selector, Clock Multiplier,
Mixer Unit, Selector Unit, Feature Unit, Sample Rate Converter,
variuos Effect Units, various Processing Units, Extension Unit) can be
added later together with the actual USB class implementation.

The main idea is that user does create one zephyr,uac2 compatible node
for every USB Audio 2 class instance. Note that in majority of cases
just one USB Audio 2 class is necessary because the number of streaming
interfaces is virtually unlimited (USB Audio 2 class can have up to 255
entities). The zephyr,uac2 node includes child nodes with compatibles
set to desired entity or audiostreaming interface. The parent-child
relationship is necessary to allow grouping entities to correct audio
class instance.

Signed-off-by: Tomasz Moń <tomasz.mon@nordicsemi.no>
This commit is contained in:
Tomasz Moń 2023-11-22 08:45:28 +01:00 committed by Carles Cufí
parent c2dae16a6a
commit d76934daeb
7 changed files with 522 additions and 0 deletions

View File

@ -0,0 +1,80 @@
# Copyright (c) 2023 Nordic Semiconductor ASA
# SPDX-License-Identifier: Apache-2.0
description: USB Audio Class 2 Audio Streaming interface
compatible: "zephyr,uac2-audio-streaming"
properties:
linked-terminal:
type: phandle
required: true
description: |
Input or Output Terminal to which this interface is connected.
active-alternate-setting-control:
type: string
description: Active Alternate Setting Control capabilities
enum:
- "read-only"
valid-alternate-settings-control:
type: string
description: Valid Alternate Settings Control capabilities
enum:
- "read-only"
external-interface:
type: boolean
description: |
Enable if audio stream is not transmitted over USB (Type IV Audio Stream).
implicit-feedback:
type: boolean
description: |
Enable implicit feedback on asynchronous endpoint. For IN endpoints this
sets endpoint behaviour type to implicit feedback data endpoint. For OUT
endpoints setting this property removes explicit feedback endpoint.
pitch-control:
type: string
description: Pitch Control capabilities
enum:
- "read-only"
- "host-programmable"
data-overrun-control:
type: string
description: Data Overrun capabilities
enum:
- "read-only"
data-underrun-control:
type: string
description: Data Underrun capabilities
enum:
- "read-only"
lock-delay:
type: int
description: |
Time it takes this endpoint to reliably lock its internal clock recovery
circuitry. Units depend on the lock-delay-units field. Relevant only if
linked-terminal's clock is sof-synchronized.
lock-delay-units:
type: string
description: Units for lock-delay parameter.
enum:
- "milliseconds"
- "decoded-pcm-samples"
subslot-size:
type: int
description: |
Number of bytes occupied by one audio subslot. Can be 1, 2, 3 or 4.
bit-resolution:
type: int
description: |
Number of effectively used bits in audio subslot.

View File

@ -0,0 +1,117 @@
# Copyright (c) 2023 Nordic Semiconductor ASA
# SPDX-License-Identifier: Apache-2.0
description: USB Audio Class 2 Audio Channel Cluster
properties:
front-left:
type: boolean
description: Front Left channel present in the cluster
front-right:
type: boolean
description: Front Right channel present in the cluster
front-center:
type: boolean
description: Front Center channel present in the cluster
low-frequency-effects:
type: boolean
description: Low Frequency Effects channel present in the cluster
back-left:
type: boolean
description: Back Left channel present in the cluster
back-right:
type: boolean
description: Back Right channel present in the cluster
front-left-of-center:
type: boolean
description: Front Left of Center channel present in the cluster
front-right-of-center:
type: boolean
description: Front Right of Center channel present in the cluster
back-center:
type: boolean
description: Back Center channel present in the cluster
side-left:
type: boolean
description: Side Left channel present in the cluster
side-right:
type: boolean
description: Side Right channel present in the cluster
top-center:
type: boolean
description: Top Center channel present in the cluster
top-front-left:
type: boolean
description: Top Front Left channel present in the cluster
top-front-center:
type: boolean
description: Top Front Center channel present in the cluster
top-front-right:
type: boolean
description: Top Front Right channel present in the cluster
top-back-left:
type: boolean
description: Top Back Left channel present in the cluster
top-back-center:
type: boolean
description: Top Back Center channel present in the cluster
top-back-right:
type: boolean
description: Top Back Right channel present in the cluster
top-front-left-of-center:
type: boolean
description: Top Front Left of Center channel present in the cluster
top-front-right-of-center:
type: boolean
description: Top Front Right of Center channel present in the cluster
left-low-frequency-effects:
type: boolean
description: Left Low Frequency Effects channel present in the cluster
right-low-frequency-effects:
type: boolean
description: Right Low Frequency Effects channel present in the cluster
top-side-left:
type: boolean
description: Top Side Left channel present in the cluster
top-side-right:
type: boolean
description: Top Side Right channel present in the cluster
bottom-center:
type: boolean
description: Bottom Center channel present in the cluster
back-left-of-center:
type: boolean
description: Back Left of Center channel present in the cluster
back-right-of-center:
type: boolean
description: Back Right of Center channel present in the cluster
raw-data:
type: boolean
description: Raw Data, mutually exclusive with all other spatial locations

View File

@ -0,0 +1,52 @@
# Copyright (c) 2023 Nordic Semiconductor ASA
# SPDX-License-Identifier: Apache-2.0
description: USB Audio Class 2 Clock Source entity
compatible: "zephyr,uac2-clock-source"
properties:
clock-type:
type: string
required: true
description: |
Clock Type indicating whether the Clock Source represents an external
clock or an internal clock with either fixed frequency, variable
frequency, or programmable frequency.
enum:
- "external"
- "internal-fixed"
- "internal-variable"
- "internal-programmable"
sof-synchronized:
type: boolean
description: |
True if clock is synchronized to USB Start of Frame. False if clock is
free running. External clock must be free running.
frequency-control:
type: string
description: Clock Frequency Control capabilities
enum:
- "read-only"
- "host-programmable"
validity-control:
type: string
description: Clock Validity Control capabilities
enum:
- "read-only"
assoc-terminal:
type: phandle
description: |
Input or Output Terminal associated with this Clock Source. Set if clock
is derived from USB OUT data endpoint (point the handle to respective
Input Terminal) or from input signal on S/PDIF connector.
sampling-frequencies:
type: array
required: true
description: |
Sampling Frequencies, in Hz, this Clock Source Entity can generate.

View File

@ -0,0 +1,62 @@
# Copyright (c) 2023 Nordic Semiconductor ASA
# SPDX-License-Identifier: Apache-2.0
description: USB Audio Class 2 Input Terminal entity
compatible: "zephyr,uac2-input-terminal"
include: zephyr,uac2-channel-cluster.yaml
properties:
terminal-type:
type: int
required: true
description: |
Terminal Type constant specified in USB Audio Terminal Types
assoc-terminal:
type: phandle
description: |
Associated terminal for bi-directional terminal types.
clock-source:
type: phandle
required: true
description: |
Connected clock entity
copy-protect-control:
type: string
description: Copy Protect Control capabilities
enum:
- "read-only"
connector-control:
type: string
description: Connector Control capabilities
enum:
- "read-only"
overload-control:
type: string
description: Overload Control capabilities
enum:
- "read-only"
cluster-control:
type: string
description: Cluster Control capabilities
enum:
- "read-only"
underflow-control:
type: string
description: Underflow Control capabilities
enum:
- "read-only"
overflow-control:
type: string
description: Overflow Control capabilities
enum:
- "read-only"

View File

@ -0,0 +1,60 @@
# Copyright (c) 2023 Nordic Semiconductor ASA
# SPDX-License-Identifier: Apache-2.0
description: USB Audio Class 2 Output Terminal entity
compatible: "zephyr,uac2-output-terminal"
properties:
terminal-type:
type: int
required: true
description: |
Terminal Type constant specified in USB Audio Terminal Types
assoc-terminal:
type: phandle
description: |
Associated terminal, e.g. for bidirectional terminal types.
data-source:
type: phandle
required: true
description: |
Unit or Terminal this terminal receives data from
clock-source:
type: phandle
required: true
description: |
Connected clock entity
copy-protect-control:
type: string
description: Copy Protect Control capabilities
enum:
- "host-programmable"
connector-control:
type: string
description: Connector Control capabilities
enum:
- "read-only"
overload-control:
type: string
description: Overload Control capabilities
enum:
- "read-only"
underflow-control:
type: string
description: Underflow Control capabilities
enum:
- "read-only"
overflow-control:
type: string
description: Overflow Control capabilities
enum:
- "read-only"

View File

@ -0,0 +1,39 @@
# Copyright (c) 2023 Nordic Semiconductor ASA
# SPDX-License-Identifier: Apache-2.0
description: USB Audio Class 2 instance
compatible: "zephyr,uac2"
# Child nodes of "zephyr,uac2" compatibles are supposed to be Audio Control
# entities, i.e. clock sources, input terminals, output terminals, etc.
# After all Audio Control entities, the Audio Streaming interface compatibles
# should follow (as child nodes of "zephyr,uac2").
#
# The only reason for putting Audio Streaming interfaces at the end is because
# Audio Control entities derive their unique ID from child index (+ 1). For most
# cases the order shouldn't really matter, but if there happen to be maximum
# possible number of entities (255) then the Audio Streaming would inadvertedly
# "consume" one of the available IDs.
properties:
audio-function:
type: int
required: true
description: |
Constant, indicating the primary use of this audio function, as intended
by the manufacturer. Use Audio Function category codes define from
dt-bindings/usb/audio.h.
interrupt-endpoint:
type: boolean
description: |
Enable to support an optional interrupt endpoint to inform the Host about
dynamic changes that occur on the different addressable entities.
latency-control:
type: string
description: Latency Control capabilities
enum:
- "read-only"
- "host-programmable"

View File

@ -0,0 +1,112 @@
/*
* Copyright (c) 2023 Nordic Semiconductor ASA
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ZEPHYR_INCLUDE_DT_BINDINGS_USB_AUDIO_H
#define ZEPHYR_INCLUDE_DT_BINDINGS_USB_AUDIO_H
/* USB Device Class Definition for Audio Devices Release 2.0 May 31, 2006
* A.7 Audio Function Category Codes
*/
#define AUDIO_FUNCTION_SUBCLASS_UNDEFINED 0x00
#define AUDIO_FUNCTION_DESKTOP_SPEAKER 0x01
#define AUDIO_FUNCTION_HOME_THEATER 0x02
#define AUDIO_FUNCTION_MICROPHONE 0x03
#define AUDIO_FUNCTION_HEADSET 0x04
#define AUDIO_FUNCTION_TELEPHONE 0x05
#define AUDIO_FUNCTION_CONVERTER 0x06
#define AUDIO_FUNCTION_VOICE_SOUND_RECORDER 0x07
#define AUDIO_FUNCTION_IO_BOX 0x08
#define AUDIO_FUNCTION_MUSICAL_INSTRUMENT 0x09
#define AUDIO_FUNCTION_PRO_AUDIO 0x0A
#define AUDIO_FUNCTION_AUDIO_VIDEO 0x0B
#define AUDIO_FUNCTION_CONTROL_PANEL 0x0C
#define AUDIO_FUNCTION_OTHER 0xFF
/* USB Device Class Definition for Terminal Types
* Both "Universal Serial Bus Device Class Definition for Terminal Types"
* Release 2.0 May 31, 2006 and Release 3.0 September 22, 2016 contain exactly
* the same terminal types and values.
*/
/* 2.1 USB Terminal Types */
#define USB_TERMINAL_UNDEFINED 0x0100
#define USB_TERMINAL_STREAMING 0x0101
#define USB_TERMINAL_VENDOR_SPECIFIC 0x01FF
/* 2.2 Input Terminal Types */
#define INPUT_TERMINAL_UNDEFINED 0x0200
#define INPUT_TERMINAL_MICROPHONE 0x0201
#define INPUT_TERMINAL_DESKTOP_MICROPHONE 0x0202
#define INPUT_TERMINAL_PERSONAL_MICROPHONE 0x0203
#define INPUT_TERMINAL_OMNI_DIRECTIONAL_MICROPHONE 0x0204
#define INPUT_TERMINAL_MICROPHONE_ARRAY 0x0205
#define INPUT_TERMINAL_PROCESSING_MICROPHONE_ARRAY 0x0206
/* 2.3 Output Terminal Types */
#define OUTPUT_TERMINAL_UNDEFINED 0x0300
#define OUTPUT_TERMINAL_SPEAKER 0x0301
#define OUTPUT_TERMINAL_HEADPHONES 0x0302
#define OUTPUT_TERMINAL_HEAD_MOUNTED_DISPLAY_AUDIO 0x0303
#define OUTPUT_TERMINAL_DESKTOP_SPEAKER 0x0304
#define OUTPUT_TERMINAL_ROOM_SPEAKER 0x0305
#define OUTPUT_TERMINAL_COMMUNICATION_SPEAKER 0x0306
#define OUTPUT_TERMINAL_LOW_FREQUENCY_EFFECTS_SPEAKER 0x0307
/* 2.4 Bi-directional Terminal Types */
#define BIDIRECTIONAL_TERMINAL_UNDEFINED 0x0400
#define BIDIRECTIONAL_TERMINAL_HANDSET 0x0401
#define BIDIRECTIONAL_TERMINAL_HEADSET 0x0402
#define BIDIRECTIONAL_TERMINAL_SPEAKERPHONE_NO_ECHO_REDUCTION 0x0403
#define BIDIRECTIONAL_TERMINAL_ECHO_SUPPRESSING_SPEAKERPHONE 0x0404
#define BIDIRECTIONAL_TERMINAL_ECHO_CANCELLING_SPEAKERPHONE 0x0405
/* 2.5 Telephony Terminal Types */
#define TELEPHONY_TERMINAL_UNDEFINED 0x0500
#define TELEPHONY_TERMINAL_PHONE_LINE 0x0501
#define TELEPHONY_TERMINAL_TELEPHONE 0x0502
#define TELEPHONY_TERMINAL_DOWN_LINE_PHONE 0x0503
/* 2.6 External Terminal Types */
#define EXTERNAL_TERMINAL_UNDEFINED 0x0600
#define EXTERNAL_TERMINAL_ANALOG_CONNECTOR 0x0601
#define EXTERNAL_TERMINAL_DIGITAL_AUDIO_INTERFACE 0x0602
#define EXTERNAL_TERMINAL_LINE_CONNECTOR 0x0603
#define EXTERNAL_TERMINAL_LEGACY_AUDIO_CONNECTOR 0x0604
#define EXTERNAL_TERMINAL_SPDIF_INTERFACE 0x0605
#define EXTERNAL_TERMINAL_1394_DA_STREAM 0x0606
#define EXTERNAL_TERMINAL_1394_DV_STREAM_SOUNDTRACK 0x0607
#define EXTERNAL_TERMINAL_ADAT_LIGHTPIPE 0x0608
#define EXTERNAL_TERMINAL_TDIF 0x0609
#define EXTERNAL_TERMINAL_MADI 0x060A
/* 2.7 Embedded Function Terminal Types */
#define EMBEDDED_TERMINAL_UNDEFINED 0x0700
#define EMBEDDED_TERMINAL_LEVEL_CALIBRATION_NOISE_SOURCE 0x0701
#define EMBEDDED_TERMINAL_EQUALIZATION_NOISE 0x0702
#define EMBEDDED_TERMINAL_CD_PLAYER 0x0703
#define EMBEDDED_TERMINAL_DAT 0x0704
#define EMBEDDED_TERMINAL_DCC 0x0705
#define EMBEDDED_TERMINAL_COMPRESSED_AUDIO_PLAYER 0x0706
#define EMBEDDED_TERMINAL_ANALOG_TAPE 0x0707
#define EMBEDDED_TERMINAL_PHONOGRAPH 0x0708
#define EMBEDDED_TERMINAL_VCR_AUDIO 0x0709
#define EMBEDDED_TERMINAL_VIDEO_DISC_AUDIO 0x070A
#define EMBEDDED_TERMINAL_DVD_AUDIO 0x070B
#define EMBEDDED_TERMINAL_TV_TUNER_AUDIO 0x070C
#define EMBEDDED_TERMINAL_SATELLITE_RECEIVER_AUDIO 0x070D
#define EMBEDDED_TERMINAL_CABLE_TUNER_AUDIO 0x070E
#define EMBEDDED_TERMINAL_DSS_AUDIO 0x070F
#define EMBEDDED_TERMINAL_RADIO_RECEIVER 0x0710
#define EMBEDDED_TERMINAL_RADIO_TRANSMITTER 0x0711
#define EMBEDDED_TERMINAL_MULTI_TRACK_RECORDER 0x0712
#define EMBEDDED_TERMINAL_SYNTHESIZER 0x0713
#define EMBEDDED_TERMINAL_PIANO 0x0714
#define EMBEDDED_TERMINAL_GUITAR 0x0715
#define EMBEDDED_TERMINAL_DRUMS_RHYTHM 0x0716
#define EMBEDDED_TERMINAL_OTHER_MUSICAL_INSTRUMENT 0x0717
#endif /* ZEPHYR_INCLUDE_DT_BINDINGS_USB_AUDIO_H */