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 /* USB Terminal Types */ 104 USB_AUDIO_USB_UNDEFINED = 0x0100, 105 USB_AUDIO_USB_STREAMING = 0x0101, 106 USB_AUDIO_USB_VENDOR_SPEC = 0x01FF, 107 108 /* Input Terminal Types */ 109 USB_AUDIO_IN_UNDEFINED = 0x0200, 110 USB_AUDIO_IN_MICROPHONE = 0x0201, 111 USB_AUDIO_IN_DESKTOP_MIC = 0x0202, 112 USB_AUDIO_IN_PERSONAL_MIC = 0x0203, 113 USB_AUDIO_IN_OM_DIR_MIC = 0x0204, 114 USB_AUDIO_IN_MIC_ARRAY = 0x0205, 115 USB_AUDIO_IN_PROC_MIC_ARRAY = 0x0205, 116 117 /* Output Terminal Types */ 118 USB_AUDIO_OUT_UNDEFINED = 0x0300, 119 USB_AUDIO_OUT_SPEAKER = 0x0301, 120 USB_AUDIO_OUT_HEADPHONES = 0x0302, 121 USB_AUDIO_OUT_HEAD_AUDIO = 0x0303, 122 USB_AUDIO_OUT_DESKTOP_SPEAKER = 0x0304, 123 USB_AUDIO_OUT_ROOM_SPEAKER = 0x0305, 124 USB_AUDIO_OUT_COMM_SPEAKER = 0x0306, 125 USB_AUDIO_OUT_LOW_FREQ_SPEAKER = 0x0307, 126 127 /* Bi-directional Terminal Types */ 128 USB_AUDIO_IO_UNDEFINED = 0x0400, 129 USB_AUDIO_IO_HANDSET = 0x0401, 130 USB_AUDIO_IO_HEADSET = 0x0402, 131 USB_AUDIO_IO_SPEAKERPHONE_ECHO_NONE = 0x0403, 132 USB_AUDIO_IO_SPEAKERPHONE_ECHO_SUP = 0x0404, 133 USB_AUDIO_IO_SPEAKERPHONE_ECHO_CAN = 0x0405, 134 }; 135 136 enum usb_audio_direction { 137 USB_AUDIO_IN = 0x00, 138 USB_AUDIO_OUT = 0x01 139 }; 140 141 /** 142 * @brief Feature Unit event structure. 143 * 144 * The event structure is used by feature_update_cb in order to inform the App 145 * whenever the Host has modified one of the device features. 146 * 147 * @param dir The device direction that has been changed. Applicable for 148 * Headset device only. 149 * @param cs Control selector, feature that has been changed. 150 * @param channel Device channel that has been changed. If 0xFF, then 151 * all channels have been changed. 152 * @param val_len Length of the val field. 153 * @param val Value of the feature that has been set. 154 */ 155 struct usb_audio_fu_evt { 156 enum usb_audio_direction dir; 157 enum usb_audio_fucs cs; 158 uint8_t channel; 159 uint8_t val_len; 160 const void *val; 161 }; 162 163 /** 164 * @brief Callback type used to inform the app that data were requested 165 * from the device and may be send to the Host. 166 * For sending the data usb_audio_send() API function should be used. 167 * 168 * @note User may not use this callback and may try to send in 1ms task 169 * instead. Sending every 1ms may be unsuccessful and may return -EAGAIN 170 * if Host did not required data. 171 * 172 * @param dev The device for which data were requested by the Host. 173 */ 174 typedef void (*usb_audio_data_request_cb_t)(const struct device *dev); 175 176 /** 177 * @brief Callback type used to inform the app that data were successfully 178 * send/received. 179 * 180 * @param dev The device for which the callback was called. 181 * @param buffer Pointer to the net_buf data chunk that was successfully 182 * send/received. If the application uses data_written_cb and/or 183 * data_received_cb callbacks it is responsible for freeing the 184 * buffer by itself. 185 * @param size Amount of data that were successfully send/received. 186 */ 187 typedef void (*usb_audio_data_completion_cb_t)(const struct device *dev, 188 struct net_buf *buffer, 189 size_t size); 190 191 /** 192 * @brief Callback type used to inform the app that Host has changed 193 * one of the features configured for the device. 194 * Applicable for all devices. 195 * 196 * @warning Host may not use all of configured features. 197 * 198 * @param dev USB Audio device 199 * @param evt Pointer to an event to be parsed by the App. 200 * Pointer struct is temporary and is valid only during the 201 * execution of this callback. 202 */ 203 typedef void (*usb_audio_feature_updated_cb_t)(const struct device *dev, 204 const struct usb_audio_fu_evt *evt); 205 206 /** 207 * @brief Audio callbacks used to interact with audio devices by user App. 208 * 209 * usb_audio_ops structure contains all relevant callbacks to interact with 210 * USB Audio devices. Each of this callbacks is optional and may be left NULL. 211 * This will not break the stack but could make USB Audio device useless. 212 * Depending on the device some of those callbacks are necessary to make USB 213 * device work as expected sending/receiving data. For more information refer 214 * to callback documentation above. 215 */ 216 struct usb_audio_ops { 217 /* Callback called when data could be send */ 218 usb_audio_data_request_cb_t data_request_cb; 219 220 /* Callback called when data were successfully written with sending 221 * capable device. Applicable for headset and microphone. Unused for 222 * headphones. 223 */ 224 usb_audio_data_completion_cb_t data_written_cb; 225 226 /* Callback called when data were successfully received by receive 227 * capable device. Applicable for headset and headphones. Unused for 228 * microphone. 229 */ 230 usb_audio_data_completion_cb_t data_received_cb; 231 232 /* Callback called when features were modified by the Host */ 233 usb_audio_feature_updated_cb_t feature_update_cb; 234 }; 235 236 /** @brief Get the frame size that is accepted by the Host. 237 * 238 * This function returns the frame size for Input Devices that is expected 239 * by the Host. Returned value rely on Input Device configuration: 240 * - number of channels 241 * - sampling frequency 242 * - sample resolution 243 * Device configuration is done via DT overlay. 244 * 245 * @param dev The Input device that is asked for frame size. 246 * 247 * @warning Do not use with OUT only devices (Headphones). 248 * For OUT only devices this function shall return 0. 249 */ 250 size_t usb_audio_get_in_frame_size(const struct device *dev); 251 252 /** 253 * @brief Register the USB Audio device and make it usable. 254 * This must be called in order to make the device work 255 * and respond to all relevant requests. 256 * 257 * @param dev USB Audio device 258 * @param ops USB audio callback structure. Callback are used to 259 * inform the user about what is happening 260 */ 261 void usb_audio_register(const struct device *dev, 262 const struct usb_audio_ops *ops); 263 264 /** 265 * @brief Send data using USB Audio device 266 * 267 * @param dev USB Audio device which will send the data 268 * over its ISO IN endpoint 269 * @param buffer Pointer to the buffer that should be send. User is 270 * responsible for managing the buffer for Input devices. In case 271 * of sending error user must decide if the buffer should be 272 * dropped or retransmitted. 273 * After the buffer was sent successfully it is passed to the 274 * data_written_cb callback if the application uses one or 275 * automatically freed otherwise. 276 * User must provide proper net_buf chunk especially when 277 * it comes to its size. This information can be obtained 278 * using usb_audio_get_in_frame_size() API function. 279 * 280 * @param len Length of the data to be send 281 * 282 * @return 0 on success, negative error on fail 283 */ 284 int usb_audio_send(const struct device *dev, struct net_buf *buffer, 285 size_t len); 286 287 #endif /* ZEPHYR_INCLUDE_USB_CLASS_AUDIO_H_ */ 288
