1 /* 2 * USB audio class core header 3 * 4 * Copyright (c) 2020 Nordic Semiconductor ASA 5 * 6 * SPDX-License-Identifier: Apache-2.0 7 */ 8 9 /** 10 * @file 11 * @brief USB Audio Device Class public header 12 * 13 * Header follows below documentation: 14 * - USB Device Class Definition for Audio Devices (audio10.pdf) 15 * 16 * Additional documentation considered a part of USB Audio v1.0: 17 * - USB Device Class Definition for Audio Data Formats (frmts10.pdf) 18 * - USB Device Class Definition for Terminal Types (termt10.pdf) 19 */ 20 21 #ifndef ZEPHYR_INCLUDE_USB_CLASS_AUDIO_H_ 22 #define ZEPHYR_INCLUDE_USB_CLASS_AUDIO_H_ 23 24 #include <zephyr/usb/usb_ch9.h> 25 #include <zephyr/device.h> 26 #include <zephyr/net/buf.h> 27 #include <zephyr/sys/util.h> 28 29 /** Audio Interface Subclass Codes. 30 * Refer to Table A-2 from audio10.pdf 31 */ 32 enum usb_audio_int_subclass_codes { 33 USB_AUDIO_SUBCLASS_UNDEFINED = 0x00, 34 USB_AUDIO_AUDIOCONTROL = 0x01, 35 USB_AUDIO_AUDIOSTREAMING = 0x02, 36 USB_AUDIO_MIDISTREAMING = 0x03 37 }; 38 39 /** Audio Class-Specific AC Interface Descriptor Subtypes. 40 * Refer to Table A-5 from audio10.pdf 41 */ 42 enum usb_audio_cs_ac_int_desc_subtypes { 43 USB_AUDIO_AC_DESCRIPTOR_UNDEFINED = 0x00, 44 USB_AUDIO_HEADER = 0x01, 45 USB_AUDIO_INPUT_TERMINAL = 0x02, 46 USB_AUDIO_OUTPUT_TERMINAL = 0x03, 47 USB_AUDIO_MIXER_UNIT = 0x04, 48 USB_AUDIO_SELECTOR_UNIT = 0x05, 49 USB_AUDIO_FEATURE_UNIT = 0x06, 50 USB_AUDIO_PROCESSING_UNIT = 0x07, 51 USB_AUDIO_EXTENSION_UNIT = 0x08 52 }; 53 54 /** Audio Class-Specific AS Interface Descriptor Subtypes 55 * Refer to Table A-6 from audio10.pdf 56 */ 57 enum usb_audio_cs_as_int_desc_subtypes { 58 USB_AUDIO_AS_DESCRIPTOR_UNDEFINED = 0x00, 59 USB_AUDIO_AS_GENERAL = 0x01, 60 USB_AUDIO_FORMAT_TYPE = 0x02, 61 USB_AUDIO_FORMAT_SPECIFIC = 0x03 62 }; 63 64 /** Audio Class-Specific Request Codes 65 * Refer to Table A-9 from audio10.pdf 66 */ 67 enum usb_audio_cs_req_codes { 68 USB_AUDIO_REQUEST_CODE_UNDEFINED = 0x00, 69 USB_AUDIO_SET_CUR = 0x01, 70 USB_AUDIO_GET_CUR = 0x81, 71 USB_AUDIO_SET_MIN = 0x02, 72 USB_AUDIO_GET_MIN = 0x82, 73 USB_AUDIO_SET_MAX = 0x03, 74 USB_AUDIO_GET_MAX = 0x83, 75 USB_AUDIO_SET_RES = 0x04, 76 USB_AUDIO_GET_RES = 0x84, 77 USB_AUDIO_SET_MEM = 0x05, 78 USB_AUDIO_GET_MEM = 0x85, 79 USB_AUDIO_GET_STAT = 0xFF 80 }; 81 82 /** Feature Unit Control Selectors 83 * Refer to Table A-11 from audio10.pdf 84 */ 85 enum usb_audio_fucs { 86 USB_AUDIO_FU_CONTROL_UNDEFINED = 0x00, 87 USB_AUDIO_FU_MUTE_CONTROL = 0x01, 88 USB_AUDIO_FU_VOLUME_CONTROL = 0x02, 89 USB_AUDIO_FU_BASS_CONTROL = 0x03, 90 USB_AUDIO_FU_MID_CONTROL = 0x04, 91 USB_AUDIO_FU_TREBLE_CONTROL = 0x05, 92 USB_AUDIO_FU_GRAPHIC_EQUALIZER_CONTROL = 0x06, 93 USB_AUDIO_FU_AUTOMATIC_GAIN_CONTROL = 0x07, 94 USB_AUDIO_FU_DELAY_CONTROL = 0x08, 95 USB_AUDIO_FU_BASS_BOOST_CONTROL = 0x09, 96 USB_AUDIO_FU_LOUDNESS_CONTROL = 0x0A 97 }; 98 99 /** USB Terminal Types 100 * Refer to Table 2-1 - Table 2-4 from termt10.pdf 101 */ 102 enum usb_audio_terminal_types { 103 /** 104 * @name USB Terminal Types 105 * @{ 106 */ 107 /** USB undefined */ 108 USB_AUDIO_USB_UNDEFINED = 0x0100, 109 /** USB streaming */ 110 USB_AUDIO_USB_STREAMING = 0x0101, 111 /** USB vendor specific */ 112 USB_AUDIO_USB_VENDOR_SPEC = 0x01FF, 113 /** @} */ 114 115 /** 116 * @name Input Terminal Types 117 * @{ 118 */ 119 /** Input undefined */ 120 USB_AUDIO_IN_UNDEFINED = 0x0200, 121 /** Microphone */ 122 USB_AUDIO_IN_MICROPHONE = 0x0201, 123 /** Desktop microphone */ 124 USB_AUDIO_IN_DESKTOP_MIC = 0x0202, 125 /** Personal microphone */ 126 USB_AUDIO_IN_PERSONAL_MIC = 0x0203, 127 /** Omni directional microphone */ 128 USB_AUDIO_IN_OM_DIR_MIC = 0x0204, 129 /** Microphone array */ 130 USB_AUDIO_IN_MIC_ARRAY = 0x0205, 131 /** Processing microphone array */ 132 USB_AUDIO_IN_PROC_MIC_ARRAY = 0x0205, 133 /** @} */ 134 135 /** 136 * @name Output Terminal Types 137 * @{ 138 */ 139 /** Output undefined */ 140 USB_AUDIO_OUT_UNDEFINED = 0x0300, 141 /** Speaker */ 142 USB_AUDIO_OUT_SPEAKER = 0x0301, 143 /** Headphones */ 144 USB_AUDIO_OUT_HEADPHONES = 0x0302, 145 /** Head mounted display audio */ 146 USB_AUDIO_OUT_HEAD_AUDIO = 0x0303, 147 /** Desktop speaker */ 148 USB_AUDIO_OUT_DESKTOP_SPEAKER = 0x0304, 149 /** Room speaker */ 150 USB_AUDIO_OUT_ROOM_SPEAKER = 0x0305, 151 /** Communication speaker */ 152 USB_AUDIO_OUT_COMM_SPEAKER = 0x0306, 153 /** Low frequency effects speaker */ 154 USB_AUDIO_OUT_LOW_FREQ_SPEAKER = 0x0307, 155 /** @} */ 156 157 /** 158 * @name Bi-directional Terminal Types 159 * @{ 160 */ 161 /** Bidirectional undefined */ 162 USB_AUDIO_IO_UNDEFINED = 0x0400, 163 /** Handset */ 164 USB_AUDIO_IO_HANDSET = 0x0401, 165 /** Headset */ 166 USB_AUDIO_IO_HEADSET = 0x0402, 167 /** Speakerphone, no echo reduction */ 168 USB_AUDIO_IO_SPEAKERPHONE_ECHO_NONE = 0x0403, 169 /** Speakerphone, echo reduction */ 170 USB_AUDIO_IO_SPEAKERPHONE_ECHO_SUP = 0x0404, 171 /** Speakerphone, echo cancellation */ 172 USB_AUDIO_IO_SPEAKERPHONE_ECHO_CAN = 0x0405, 173 }; 174 175 /** 176 * @brief Audio device direction. 177 */ 178 enum usb_audio_direction { 179 USB_AUDIO_IN = 0x00, 180 USB_AUDIO_OUT = 0x01 181 }; 182 183 /** 184 * @brief Feature Unit event structure. 185 * 186 * The event structure is used by feature_update_cb in order to inform the App 187 * whenever the Host has modified one of the device features. 188 */ 189 struct usb_audio_fu_evt { 190 /** 191 * The device direction that has been changed. 192 * Applicable for Headset device only. 193 */ 194 enum usb_audio_direction dir; 195 /** Control selector feature that has been changed. */ 196 enum usb_audio_fucs cs; 197 /** 198 * Device channel that has been changed. 199 * If 0xFF, then all channels have been changed. 200 */ 201 uint8_t channel; 202 /** Length of the val field. */ 203 uint8_t val_len; 204 /** Value of the feature that has been set. */ 205 const void *val; 206 }; 207 208 /** 209 * @brief Callback type used to inform the app that data were requested 210 * from the device and may be send to the Host. 211 * For sending the data usb_audio_send() API function should be used. 212 * 213 * @note User may not use this callback and may try to send in 1ms task 214 * instead. Sending every 1ms may be unsuccessful and may return -EAGAIN 215 * if Host did not required data. 216 * 217 * @param dev The device for which data were requested by the Host. 218 */ 219 typedef void (*usb_audio_data_request_cb_t)(const struct device *dev); 220 221 /** 222 * @brief Callback type used to inform the app that data were successfully 223 * send/received. 224 * 225 * @param dev The device for which the callback was called. 226 * @param buffer Pointer to the net_buf data chunk that was successfully 227 * send/received. If the application uses data_written_cb and/or 228 * data_received_cb callbacks it is responsible for freeing the 229 * buffer by itself. 230 * @param size Amount of data that were successfully send/received. 231 */ 232 typedef void (*usb_audio_data_completion_cb_t)(const struct device *dev, 233 struct net_buf *buffer, 234 size_t size); 235 236 /** 237 * @brief Callback type used to inform the app that Host has changed 238 * one of the features configured for the device. 239 * Applicable for all devices. 240 * 241 * @warning Host may not use all of configured features. 242 * 243 * @param dev USB Audio device 244 * @param evt Pointer to an event to be parsed by the App. 245 * Pointer struct is temporary and is valid only during the 246 * execution of this callback. 247 */ 248 typedef void (*usb_audio_feature_updated_cb_t)(const struct device *dev, 249 const struct usb_audio_fu_evt *evt); 250 251 /** 252 * @brief Audio callbacks used to interact with audio devices by user App. 253 * 254 * usb_audio_ops structure contains all relevant callbacks to interact with 255 * USB Audio devices. Each of this callbacks is optional and may be left NULL. 256 * This will not break the stack but could make USB Audio device useless. 257 * Depending on the device some of those callbacks are necessary to make USB 258 * device work as expected sending/receiving data. For more information refer 259 * to callback documentation above. 260 */ 261 struct usb_audio_ops { 262 /** Callback called when data could be send */ 263 usb_audio_data_request_cb_t data_request_cb; 264 265 /** Callback called when data were successfully written with sending 266 * capable device. Applicable for headset and microphone. Unused for 267 * headphones. 268 */ 269 usb_audio_data_completion_cb_t data_written_cb; 270 271 /** Callback called when data were successfully received by receive 272 * capable device. Applicable for headset and headphones. Unused for 273 * microphone. 274 */ 275 usb_audio_data_completion_cb_t data_received_cb; 276 277 /** Callback called when features were modified by the Host */ 278 usb_audio_feature_updated_cb_t feature_update_cb; 279 }; 280 281 /** @brief Get the frame size that is accepted by the Host. 282 * 283 * This function returns the frame size for Input Devices that is expected 284 * by the Host. Returned value rely on Input Device configuration: 285 * - number of channels 286 * - sampling frequency 287 * - sample resolution 288 * Device configuration is done via DT overlay. 289 * 290 * @param dev The Input device that is asked for frame size. 291 * 292 * @warning Do not use with OUT only devices (Headphones). 293 * For OUT only devices this function shall return 0. 294 */ 295 size_t usb_audio_get_in_frame_size(const struct device *dev); 296 297 /** 298 * @brief Register the USB Audio device and make it usable. 299 * This must be called in order to make the device work 300 * and respond to all relevant requests. 301 * 302 * @param dev USB Audio device 303 * @param ops USB audio callback structure. Callback are used to 304 * inform the user about what is happening 305 */ 306 void usb_audio_register(const struct device *dev, 307 const struct usb_audio_ops *ops); 308 309 /** 310 * @brief Send data using USB Audio device 311 * 312 * @param dev USB Audio device which will send the data 313 * over its ISO IN endpoint 314 * @param buffer Pointer to the buffer that should be send. User is 315 * responsible for managing the buffer for Input devices. In case 316 * of sending error user must decide if the buffer should be 317 * dropped or retransmitted. 318 * After the buffer was sent successfully it is passed to the 319 * data_written_cb callback if the application uses one or 320 * automatically freed otherwise. 321 * User must provide proper net_buf chunk especially when 322 * it comes to its size. This information can be obtained 323 * using usb_audio_get_in_frame_size() API function. 324 * 325 * @param len Length of the data to be send 326 * 327 * @return 0 on success, negative error on fail 328 */ 329 int usb_audio_send(const struct device *dev, struct net_buf *buffer, 330 size_t len); 331 332 #endif /* ZEPHYR_INCLUDE_USB_CLASS_AUDIO_H_ */ 333
