From d76934daeb43a7f0200847f299e720b68beef084 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20Mo=C5=84?= Date: Wed, 22 Nov 2023 08:45:28 +0100 Subject: [PATCH] dt-bindings: usb: initial USB Audio Class 2 support MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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ń --- .../usb/uac2/zephyr,uac2-audio-streaming.yaml | 80 ++++++++++++ .../usb/uac2/zephyr,uac2-channel-cluster.yaml | 117 ++++++++++++++++++ .../usb/uac2/zephyr,uac2-clock-source.yaml | 52 ++++++++ .../usb/uac2/zephyr,uac2-input-terminal.yaml | 62 ++++++++++ .../usb/uac2/zephyr,uac2-output-terminal.yaml | 60 +++++++++ dts/bindings/usb/uac2/zephyr,uac2.yaml | 39 ++++++ include/zephyr/dt-bindings/usb/audio.h | 112 +++++++++++++++++ 7 files changed, 522 insertions(+) create mode 100644 dts/bindings/usb/uac2/zephyr,uac2-audio-streaming.yaml create mode 100644 dts/bindings/usb/uac2/zephyr,uac2-channel-cluster.yaml create mode 100644 dts/bindings/usb/uac2/zephyr,uac2-clock-source.yaml create mode 100644 dts/bindings/usb/uac2/zephyr,uac2-input-terminal.yaml create mode 100644 dts/bindings/usb/uac2/zephyr,uac2-output-terminal.yaml create mode 100644 dts/bindings/usb/uac2/zephyr,uac2.yaml create mode 100644 include/zephyr/dt-bindings/usb/audio.h diff --git a/dts/bindings/usb/uac2/zephyr,uac2-audio-streaming.yaml b/dts/bindings/usb/uac2/zephyr,uac2-audio-streaming.yaml new file mode 100644 index 00000000000..6e661d1c73d --- /dev/null +++ b/dts/bindings/usb/uac2/zephyr,uac2-audio-streaming.yaml @@ -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. diff --git a/dts/bindings/usb/uac2/zephyr,uac2-channel-cluster.yaml b/dts/bindings/usb/uac2/zephyr,uac2-channel-cluster.yaml new file mode 100644 index 00000000000..e71b2990a29 --- /dev/null +++ b/dts/bindings/usb/uac2/zephyr,uac2-channel-cluster.yaml @@ -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 diff --git a/dts/bindings/usb/uac2/zephyr,uac2-clock-source.yaml b/dts/bindings/usb/uac2/zephyr,uac2-clock-source.yaml new file mode 100644 index 00000000000..3a2412b1427 --- /dev/null +++ b/dts/bindings/usb/uac2/zephyr,uac2-clock-source.yaml @@ -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. diff --git a/dts/bindings/usb/uac2/zephyr,uac2-input-terminal.yaml b/dts/bindings/usb/uac2/zephyr,uac2-input-terminal.yaml new file mode 100644 index 00000000000..0c638566c61 --- /dev/null +++ b/dts/bindings/usb/uac2/zephyr,uac2-input-terminal.yaml @@ -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" diff --git a/dts/bindings/usb/uac2/zephyr,uac2-output-terminal.yaml b/dts/bindings/usb/uac2/zephyr,uac2-output-terminal.yaml new file mode 100644 index 00000000000..c1ce1d842f3 --- /dev/null +++ b/dts/bindings/usb/uac2/zephyr,uac2-output-terminal.yaml @@ -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" diff --git a/dts/bindings/usb/uac2/zephyr,uac2.yaml b/dts/bindings/usb/uac2/zephyr,uac2.yaml new file mode 100644 index 00000000000..0f0aaf5b55f --- /dev/null +++ b/dts/bindings/usb/uac2/zephyr,uac2.yaml @@ -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" diff --git a/include/zephyr/dt-bindings/usb/audio.h b/include/zephyr/dt-bindings/usb/audio.h new file mode 100644 index 00000000000..4bc8c591457 --- /dev/null +++ b/include/zephyr/dt-bindings/usb/audio.h @@ -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 */