usb_audio.h File Reference

USB Audio Device Class public header. More...

#include <zephyr/usb/usb_ch9.h>
#include <zephyr/device.h>
#include <zephyr/net/buf.h>
#include <zephyr/sys/util.h>

Go to the source code of this file.

Data Structures
struct	usb_audio_fu_evt
	Feature Unit event structure. More...
struct	usb_audio_ops
	Audio callbacks used to interact with audio devices by user App. More...

Typedefs
typedef void(*	usb_audio_data_request_cb_t) (const struct device *dev)
	Callback type used to inform the app that data were requested from the device and may be send to the Host.
typedef void(*	usb_audio_data_completion_cb_t) (const struct device *dev, struct net_buf *buffer, size_t size)
	Callback type used to inform the app that data were successfully send/received.
typedef void(*	usb_audio_feature_updated_cb_t) (const struct device *dev, const struct usb_audio_fu_evt *evt)
	Callback type used to inform the app that Host has changed one of the features configured for the device.

Enumerations
enum	usb_audio_int_subclass_codes { USB_AUDIO_SUBCLASS_UNDEFINED = 0x00 , USB_AUDIO_AUDIOCONTROL = 0x01 , USB_AUDIO_AUDIOSTREAMING = 0x02 , USB_AUDIO_MIDISTREAMING = 0x03 }
	Audio Interface Subclass Codes. More...
enum	usb_audio_cs_ac_int_desc_subtypes {   USB_AUDIO_AC_DESCRIPTOR_UNDEFINED = 0x00 , USB_AUDIO_HEADER = 0x01 , USB_AUDIO_INPUT_TERMINAL = 0x02 , USB_AUDIO_OUTPUT_TERMINAL = 0x03 ,   USB_AUDIO_MIXER_UNIT = 0x04 , USB_AUDIO_SELECTOR_UNIT = 0x05 , USB_AUDIO_FEATURE_UNIT = 0x06 , USB_AUDIO_PROCESSING_UNIT = 0x07 ,   USB_AUDIO_EXTENSION_UNIT = 0x08 }
	Audio Class-Specific AC Interface Descriptor Subtypes. More...
enum	usb_audio_cs_as_int_desc_subtypes { USB_AUDIO_AS_DESCRIPTOR_UNDEFINED = 0x00 , USB_AUDIO_AS_GENERAL = 0x01 , USB_AUDIO_FORMAT_TYPE = 0x02 , USB_AUDIO_FORMAT_SPECIFIC = 0x03 }
	Audio Class-Specific AS Interface Descriptor Subtypes Refer to Table A-6 from audio10.pdf. More...
enum	usb_audio_cs_req_codes {   USB_AUDIO_REQUEST_CODE_UNDEFINED = 0x00 , USB_AUDIO_SET_CUR = 0x01 , USB_AUDIO_GET_CUR = 0x81 , USB_AUDIO_SET_MIN = 0x02 ,   USB_AUDIO_GET_MIN = 0x82 , USB_AUDIO_SET_MAX = 0x03 , USB_AUDIO_GET_MAX = 0x83 , USB_AUDIO_SET_RES = 0x04 ,   USB_AUDIO_GET_RES = 0x84 , USB_AUDIO_SET_MEM = 0x05 , USB_AUDIO_GET_MEM = 0x85 , USB_AUDIO_GET_STAT = 0xFF }
	Audio Class-Specific Request Codes Refer to Table A-9 from audio10.pdf. More...
enum	usb_audio_fucs {   USB_AUDIO_FU_CONTROL_UNDEFINED = 0x00 , USB_AUDIO_FU_MUTE_CONTROL = 0x01 , USB_AUDIO_FU_VOLUME_CONTROL = 0x02 , USB_AUDIO_FU_BASS_CONTROL = 0x03 ,   USB_AUDIO_FU_MID_CONTROL = 0x04 , USB_AUDIO_FU_TREBLE_CONTROL = 0x05 , USB_AUDIO_FU_GRAPHIC_EQUALIZER_CONTROL = 0x06 , USB_AUDIO_FU_AUTOMATIC_GAIN_CONTROL = 0x07 ,   USB_AUDIO_FU_DELAY_CONTROL = 0x08 , USB_AUDIO_FU_BASS_BOOST_CONTROL = 0x09 , USB_AUDIO_FU_LOUDNESS_CONTROL = 0x0A }
	Feature Unit Control Selectors Refer to Table A-11 from audio10.pdf. More...
enum	usb_audio_terminal_types {   USB_AUDIO_USB_UNDEFINED = 0x0100 , USB_AUDIO_USB_STREAMING = 0x0101 , USB_AUDIO_USB_VENDOR_SPEC = 0x01FF , USB_AUDIO_IN_UNDEFINED = 0x0200 ,   USB_AUDIO_IN_MICROPHONE = 0x0201 , USB_AUDIO_IN_DESKTOP_MIC = 0x0202 , USB_AUDIO_IN_PERSONAL_MIC = 0x0203 , USB_AUDIO_IN_OM_DIR_MIC = 0x0204 ,   USB_AUDIO_IN_MIC_ARRAY = 0x0205 , USB_AUDIO_IN_PROC_MIC_ARRAY = 0x0205 , USB_AUDIO_OUT_UNDEFINED = 0x0300 , USB_AUDIO_OUT_SPEAKER = 0x0301 ,   USB_AUDIO_OUT_HEADPHONES = 0x0302 , USB_AUDIO_OUT_HEAD_AUDIO = 0x0303 , USB_AUDIO_OUT_DESKTOP_SPEAKER = 0x0304 , USB_AUDIO_OUT_ROOM_SPEAKER = 0x0305 ,   USB_AUDIO_OUT_COMM_SPEAKER = 0x0306 , USB_AUDIO_OUT_LOW_FREQ_SPEAKER = 0x0307 , USB_AUDIO_IO_UNDEFINED = 0x0400 , USB_AUDIO_IO_HANDSET = 0x0401 ,   USB_AUDIO_IO_HEADSET = 0x0402 , USB_AUDIO_IO_SPEAKERPHONE_ECHO_NONE = 0x0403 , USB_AUDIO_IO_SPEAKERPHONE_ECHO_SUP = 0x0404 , USB_AUDIO_IO_SPEAKERPHONE_ECHO_CAN = 0x0405 }
	USB Terminal Types Refer to Table 2-1 - Table 2-4 from termt10.pdf. More...
enum	usb_audio_direction { USB_AUDIO_IN = 0x00 , USB_AUDIO_OUT = 0x01 }
	Audio device direction. More...

Functions
size_t	usb_audio_get_in_frame_size (const struct device *dev)
	Get the frame size that is accepted by the Host.
void	usb_audio_register (const struct device *dev, const struct usb_audio_ops *ops)
	Register the USB Audio device and make it usable.
int	usb_audio_send (const struct device *dev, struct net_buf *buffer, size_t len)
	Send data using USB Audio device.

Detailed Description

USB Audio Device Class public header.

Header follows below documentation:

• USB Device Class Definition for Audio Devices (audio10.pdf)

Additional documentation considered a part of USB Audio v1.0:

• USB Device Class Definition for Audio Data Formats (frmts10.pdf)
• USB Device Class Definition for Terminal Types (termt10.pdf)

Typedef Documentation

usb_audio_data_completion_cb_t

typedef void(* usb_audio_data_completion_cb_t) (const struct device *dev, struct net_buf *buffer, size_t size)

Callback type used to inform the app that data were successfully send/received.

Parameters

dev	The device for which the callback was called.
buffer	Pointer to the net_buf data chunk that was successfully send/received. If the application uses data_written_cb and/or data_received_cb callbacks it is responsible for freeing the buffer by itself.
size	Amount of data that were successfully send/received.

usb_audio_data_request_cb_t

typedef void(* usb_audio_data_request_cb_t) (const struct device *dev)

Callback type used to inform the app that data were requested from the device and may be send to the Host.

For sending the data usb_audio_send() API function should be used.

Note

User may not use this callback and may try to send in 1ms task instead. Sending every 1ms may be unsuccessful and may return -EAGAIN if Host did not required data.

Parameters

dev	The device for which data were requested by the Host.

usb_audio_feature_updated_cb_t

typedef void(* usb_audio_feature_updated_cb_t) (const struct device *dev, const struct usb_audio_fu_evt *evt)

Callback type used to inform the app that Host has changed one of the features configured for the device.

Applicable for all devices.

Warning

Host may not use all of configured features.

Parameters

dev	USB Audio device
evt	Pointer to an event to be parsed by the App. Pointer struct is temporary and is valid only during the execution of this callback.

Enumeration Type Documentation

usb_audio_cs_ac_int_desc_subtypes

enum usb_audio_cs_ac_int_desc_subtypes

Audio Class-Specific AC Interface Descriptor Subtypes.

Refer to Table A-5 from audio10.pdf

Enumerator
USB_AUDIO_AC_DESCRIPTOR_UNDEFINED
USB_AUDIO_HEADER
USB_AUDIO_INPUT_TERMINAL
USB_AUDIO_OUTPUT_TERMINAL
USB_AUDIO_MIXER_UNIT
USB_AUDIO_SELECTOR_UNIT
USB_AUDIO_FEATURE_UNIT
USB_AUDIO_PROCESSING_UNIT
USB_AUDIO_EXTENSION_UNIT

usb_audio_cs_as_int_desc_subtypes

enum usb_audio_cs_as_int_desc_subtypes

Audio Class-Specific AS Interface Descriptor Subtypes Refer to Table A-6 from audio10.pdf.

Enumerator
USB_AUDIO_AS_DESCRIPTOR_UNDEFINED
USB_AUDIO_AS_GENERAL
USB_AUDIO_FORMAT_TYPE
USB_AUDIO_FORMAT_SPECIFIC

usb_audio_cs_req_codes

enum usb_audio_cs_req_codes

Audio Class-Specific Request Codes Refer to Table A-9 from audio10.pdf.

Enumerator
USB_AUDIO_REQUEST_CODE_UNDEFINED
USB_AUDIO_SET_CUR
USB_AUDIO_GET_CUR
USB_AUDIO_SET_MIN
USB_AUDIO_GET_MIN
USB_AUDIO_SET_MAX
USB_AUDIO_GET_MAX
USB_AUDIO_SET_RES
USB_AUDIO_GET_RES
USB_AUDIO_SET_MEM
USB_AUDIO_GET_MEM
USB_AUDIO_GET_STAT

usb_audio_direction

enum usb_audio_direction

Audio device direction.

Enumerator
USB_AUDIO_IN
USB_AUDIO_OUT

usb_audio_fucs

enum usb_audio_fucs

Feature Unit Control Selectors Refer to Table A-11 from audio10.pdf.

Enumerator
USB_AUDIO_FU_CONTROL_UNDEFINED
USB_AUDIO_FU_MUTE_CONTROL
USB_AUDIO_FU_VOLUME_CONTROL
USB_AUDIO_FU_BASS_CONTROL
USB_AUDIO_FU_MID_CONTROL
USB_AUDIO_FU_TREBLE_CONTROL
USB_AUDIO_FU_GRAPHIC_EQUALIZER_CONTROL
USB_AUDIO_FU_AUTOMATIC_GAIN_CONTROL
USB_AUDIO_FU_DELAY_CONTROL
USB_AUDIO_FU_BASS_BOOST_CONTROL
USB_AUDIO_FU_LOUDNESS_CONTROL

usb_audio_int_subclass_codes

enum usb_audio_int_subclass_codes

Audio Interface Subclass Codes.

Refer to Table A-2 from audio10.pdf

Enumerator
USB_AUDIO_SUBCLASS_UNDEFINED
USB_AUDIO_AUDIOCONTROL
USB_AUDIO_AUDIOSTREAMING
USB_AUDIO_MIDISTREAMING

usb_audio_terminal_types

enum usb_audio_terminal_types

USB Terminal Types Refer to Table 2-1 - Table 2-4 from termt10.pdf.

Enumerator
USB_AUDIO_USB_UNDEFINED	USB undefined.
USB_AUDIO_USB_STREAMING	USB streaming.
USB_AUDIO_USB_VENDOR_SPEC	USB vendor specific.
USB_AUDIO_IN_UNDEFINED	Input undefined.
USB_AUDIO_IN_MICROPHONE	Microphone.
USB_AUDIO_IN_DESKTOP_MIC	Desktop microphone.
USB_AUDIO_IN_PERSONAL_MIC	Personal microphone.
USB_AUDIO_IN_OM_DIR_MIC	Omni directional microphone.
USB_AUDIO_IN_MIC_ARRAY	Microphone array.
USB_AUDIO_IN_PROC_MIC_ARRAY	Processing microphone array.
USB_AUDIO_OUT_UNDEFINED	Output undefined.
USB_AUDIO_OUT_SPEAKER	Speaker.
USB_AUDIO_OUT_HEADPHONES	Headphones.
USB_AUDIO_OUT_HEAD_AUDIO	Head mounted display audio.
USB_AUDIO_OUT_DESKTOP_SPEAKER	Desktop speaker.
USB_AUDIO_OUT_ROOM_SPEAKER	Room speaker.
USB_AUDIO_OUT_COMM_SPEAKER	Communication speaker.
USB_AUDIO_OUT_LOW_FREQ_SPEAKER	Low frequency effects speaker.
USB_AUDIO_IO_UNDEFINED	Bidirectional undefined.
USB_AUDIO_IO_HANDSET	Handset.
USB_AUDIO_IO_HEADSET	Headset.
USB_AUDIO_IO_SPEAKERPHONE_ECHO_NONE	Speakerphone, no echo reduction.
USB_AUDIO_IO_SPEAKERPHONE_ECHO_SUP	Speakerphone, echo reduction.
USB_AUDIO_IO_SPEAKERPHONE_ECHO_CAN	Speakerphone, echo cancellation.

Function Documentation

usb_audio_get_in_frame_size()

size_t usb_audio_get_in_frame_size

(

const struct device *

dev

)

Get the frame size that is accepted by the Host.

This function returns the frame size for Input Devices that is expected by the Host. Returned value rely on Input Device configuration:

• number of channels
• sampling frequency
• sample resolution Device configuration is done via DT overlay.

Parameters

dev	The Input device that is asked for frame size.

Warning

Do not use with OUT only devices (Headphones). For OUT only devices this function shall return 0.

usb_audio_register()

void usb_audio_register	(	const struct device *	dev,
		const struct usb_audio_ops *	ops
	)

Register the USB Audio device and make it usable.

This must be called in order to make the device work and respond to all relevant requests.

Parameters

dev	USB Audio device
ops	USB audio callback structure. Callback are used to inform the user about what is happening

usb_audio_send()

int usb_audio_send	(	const struct device *	dev,
		struct net_buf *	buffer,
		size_t	len
	)

Send data using USB Audio device.

Parameters

dev	USB Audio device which will send the data over its ISO IN endpoint
buffer	Pointer to the buffer that should be send. User is responsible for managing the buffer for Input devices. In case of sending error user must decide if the buffer should be dropped or retransmitted. After the buffer was sent successfully it is passed to the data_written_cb callback if the application uses one or automatically freed otherwise. User must provide proper net_buf chunk especially when it comes to its size. This information can be obtained using usb_audio_get_in_frame_size() API function.
len	Length of the data to be send

Returns

0 on success, negative error on fail