1 /* 2 * Copyright (c) 2023-2024 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /** 8 * @file 9 * @brief USB Audio Class 2 device public header 10 * 11 * This header describes only class API interaction with application. 12 * The audio device itself is modelled with devicetree zephyr,uac2 compatible. 13 * 14 * This API is currently considered experimental. 15 */ 16 17 #ifndef ZEPHYR_INCLUDE_USB_CLASS_USBD_UAC2_H_ 18 #define ZEPHYR_INCLUDE_USB_CLASS_USBD_UAC2_H_ 19 20 #include <zephyr/device.h> 21 22 /** 23 * @brief USB Audio Class 2 device API 24 * @defgroup uac2_device USB Audio Class 2 device API 25 * @ingroup usb 26 * @since 3.6 27 * @version 0.1.0 28 * @{ 29 */ 30 31 /** 32 * @brief Get entity ID 33 * 34 * @param node node identifier 35 */ 36 #define UAC2_ENTITY_ID(node) \ 37 ({ \ 38 BUILD_ASSERT(DT_NODE_HAS_COMPAT(DT_PARENT(node), zephyr_uac2)); \ 39 UTIL_INC(DT_NODE_CHILD_IDX(node)); \ 40 }) 41 42 /** 43 * @brief USB Audio 2 application event handlers 44 */ 45 struct uac2_ops { 46 /** 47 * @brief Start of Frame callback 48 * 49 * Notifies application about SOF event on the bus. 50 * This callback is mandatory to register. 51 * 52 * @param dev USB Audio 2 device 53 * @param user_data Opaque user data pointer 54 */ 55 void (*sof_cb)(const struct device *dev, void *user_data); 56 /** 57 * @brief Terminal update callback 58 * 59 * Notifies application that host has enabled or disabled a terminal. 60 * This callback is mandatory to register. 61 * 62 * @param dev USB Audio 2 device 63 * @param terminal Terminal ID linked to AudioStreaming interface 64 * @param enabled True if host enabled terminal, False otherwise 65 * @param microframes True if USB connection speed uses microframes 66 * @param user_data Opaque user data pointer 67 */ 68 void (*terminal_update_cb)(const struct device *dev, uint8_t terminal, 69 bool enabled, bool microframes, 70 void *user_data); 71 /** 72 * @brief Get receive buffer address 73 * 74 * USB stack calls this function to obtain receive buffer address for 75 * AudioStreaming interface. The buffer is owned by USB stack until 76 * @ref data_recv_cb callback is called. The buffer must be sufficiently 77 * aligned and otherwise suitable for use by UDC driver. 78 * This callback is mandatory to register for devices receiving USB audio from the USB host. 79 * 80 * @param dev USB Audio 2 device 81 * @param terminal Input Terminal ID linked to AudioStreaming interface 82 * @param size Maximum number of bytes USB stack will write to buffer. 83 * @param user_data Opaque user data pointer 84 */ 85 void *(*get_recv_buf)(const struct device *dev, uint8_t terminal, 86 uint16_t size, void *user_data); 87 /** 88 * @brief Data received 89 * 90 * This function releases buffer obtained in @ref get_recv_buf after USB 91 * has written data to the buffer and/or no longer needs it. 92 * This callback is mandatory to register for devices receiving USB audio from the USB host. 93 * 94 * @param dev USB Audio 2 device 95 * @param terminal Input Terminal ID linked to AudioStreaming interface 96 * @param buf Buffer previously obtained via @ref get_recv_buf 97 * @param size Number of bytes written to buffer 98 * @param user_data Opaque user data pointer 99 */ 100 void (*data_recv_cb)(const struct device *dev, uint8_t terminal, 101 void *buf, uint16_t size, void *user_data); 102 /** 103 * @brief Transmit buffer release callback 104 * 105 * This function releases buffer provided in @ref usbd_uac2_send when 106 * the class no longer needs it. 107 * This callback is mandatory to register if calling @ref usbd_uac2_send. 108 * 109 * @param dev USB Audio 2 device 110 * @param terminal Output Terminal ID linked to AudioStreaming interface 111 * @param buf Buffer previously provided via @ref usbd_uac2_send 112 * @param user_data Opaque user data pointer 113 */ 114 void (*buf_release_cb)(const struct device *dev, uint8_t terminal, 115 void *buf, void *user_data); 116 /** 117 * @brief Get Explicit Feedback value 118 * 119 * Explicit feedback value format depends terminal connection speed. 120 * If device is High-Speed capable, it must use Q16.16 format if and 121 * only if the @ref terminal_update_cb was called with microframes 122 * parameter set to true. On Full-Speed only devices, or if High-Speed 123 * capable device is operating at Full-Speed (microframes was false), 124 * the format is Q10.14 stored on 24 least significant bits (i.e. 8 most 125 * significant bits are ignored). 126 * This callback is mandatory to register if there is USB Audio Streaming interface linked 127 * to Input Terminal clocked from asynchronous clock (i.e. clock source without 128 * sof-synchronized;) and there is no implicit-feedback; on the interface. 129 * 130 * @param dev USB Audio 2 device 131 * @param terminal Input Terminal ID whose feedback should be returned 132 * @param user_data Opaque user data pointer 133 */ 134 uint32_t (*feedback_cb)(const struct device *dev, uint8_t terminal, 135 void *user_data); 136 /** 137 * @brief Get active sample rate 138 * 139 * USB stack calls this function when the host asks for active sample 140 * rate if the Clock Source entity supports more than one sample rate. 141 * This function won't ever be called (should be NULL) if all Clock 142 * Source entities support only one sample rate. 143 * 144 * @param dev USB Audio 2 device 145 * @param clock_id Clock Source ID whose sample rate should be returned 146 * @param user_data Opaque user data pointer 147 * 148 * @return Active sample rate in Hz 149 */ 150 uint32_t (*get_sample_rate)(const struct device *dev, uint8_t clock_id, 151 void *user_data); 152 /** 153 * @brief Set active sample rate 154 * 155 * USB stack calls this function when the host sets active sample rate. 156 * This callback may be NULL if all Clock Source entities have only one 157 * sample rate. USB stack sanitizes the sample rate to closest valid 158 * rate for given Clock Source entity. 159 * 160 * @param dev USB Audio 2 device 161 * @param clock_id Clock Source ID whose sample rate should be set 162 * @param rate Sample rate in Hz 163 * @param user_data Opaque user data pointer 164 * 165 * @return 0 on success, negative value on error 166 */ 167 int (*set_sample_rate)(const struct device *dev, uint8_t clock_id, 168 uint32_t rate, void *user_data); 169 }; 170 171 /** 172 * @brief Register USB Audio 2 application callbacks. 173 * 174 * @param dev USB Audio 2 device instance 175 * @param ops USB Audio 2 callback structure 176 * @param user_data Opaque user data to pass to ops callbacks 177 */ 178 void usbd_uac2_set_ops(const struct device *dev, 179 const struct uac2_ops *ops, void *user_data); 180 181 /** 182 * @brief Send audio data to output terminal 183 * 184 * Data buffer must be sufficiently aligned and otherwise suitable for use by 185 * UDC driver. 186 * 187 * @note Buffer ownership is transferred to the stack in case of success, in 188 * case of an error the caller retains the ownership of the buffer. 189 * 190 * @param dev USB Audio 2 device 191 * @param terminal Output Terminal ID linked to AudioStreaming interface 192 * @param data Buffer containing outgoing data 193 * @param size Number of bytes to send 194 * 195 * @return 0 on success, negative value on error 196 */ 197 int usbd_uac2_send(const struct device *dev, uint8_t terminal, 198 void *data, uint16_t size); 199 200 /** 201 * @} 202 */ 203 204 #endif /* ZEPHYR_INCLUDE_USB_CLASS_USBD_UAC2_H_ */ 205
