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 * 51 * @param dev USB Audio 2 device 52 * @param user_data Opaque user data pointer 53 */ 54 void (*sof_cb)(const struct device *dev, void *user_data); 55 /** 56 * @brief Terminal update callback 57 * 58 * Notifies application that host has enabled or disabled a terminal. 59 * 60 * @param dev USB Audio 2 device 61 * @param terminal Terminal ID linked to AudioStreaming interface 62 * @param enabled True if host enabled terminal, False otherwise 63 * @param microframes True if USB connection speed uses microframes 64 * @param user_data Opaque user data pointer 65 */ 66 void (*terminal_update_cb)(const struct device *dev, uint8_t terminal, 67 bool enabled, bool microframes, 68 void *user_data); 69 /** 70 * @brief Get receive buffer address 71 * 72 * USB stack calls this function to obtain receive buffer address for 73 * AudioStreaming interface. The buffer is owned by USB stack until 74 * @ref data_recv_cb callback is called. The buffer must be sufficiently 75 * aligned and otherwise suitable for use by UDC driver. 76 * 77 * @param dev USB Audio 2 device 78 * @param terminal Input Terminal ID linked to AudioStreaming interface 79 * @param size Maximum number of bytes USB stack will write to buffer. 80 * @param user_data Opaque user data pointer 81 */ 82 void *(*get_recv_buf)(const struct device *dev, uint8_t terminal, 83 uint16_t size, void *user_data); 84 /** 85 * @brief Data received 86 * 87 * This function releases buffer obtained in @ref get_recv_buf after USB 88 * has written data to the buffer and/or no longer needs it. 89 * 90 * @param dev USB Audio 2 device 91 * @param terminal Input Terminal ID linked to AudioStreaming interface 92 * @param buf Buffer previously obtained via @ref get_recv_buf 93 * @param size Number of bytes written to buffer 94 * @param user_data Opaque user data pointer 95 */ 96 void (*data_recv_cb)(const struct device *dev, uint8_t terminal, 97 void *buf, uint16_t size, void *user_data); 98 /** 99 * @brief Transmit buffer release callback 100 * 101 * This function releases buffer provided in @ref usbd_uac2_send when 102 * the class no longer needs it. 103 * 104 * @param dev USB Audio 2 device 105 * @param terminal Output Terminal ID linked to AudioStreaming interface 106 * @param buf Buffer previously provided via @ref usbd_uac2_send 107 * @param user_data Opaque user data pointer 108 */ 109 void (*buf_release_cb)(const struct device *dev, uint8_t terminal, 110 void *buf, void *user_data); 111 /** 112 * @brief Get Explicit Feedback value 113 * 114 * Explicit feedback value format depends terminal connection speed. 115 * If device is High-Speed capable, it must use Q16.16 format if and 116 * only if the @ref terminal_update_cb was called with microframes 117 * parameter set to true. On Full-Speed only devices, or if High-Speed 118 * capable device is operating at Full-Speed (microframes was false), 119 * the format is Q10.14 stored on 24 least significant bits (i.e. 8 most 120 * significant bits are ignored). 121 * 122 * @param dev USB Audio 2 device 123 * @param terminal Input Terminal ID whose feedback should be returned 124 * @param user_data Opaque user data pointer 125 */ 126 uint32_t (*feedback_cb)(const struct device *dev, uint8_t terminal, 127 void *user_data); 128 /** 129 * @brief Get active sample rate 130 * 131 * USB stack calls this function when the host asks for active sample 132 * rate if the Clock Source entity supports more than one sample rate. 133 * This function won't ever be called (should be NULL) if all Clock 134 * Source entities support only one sample rate. 135 * 136 * @param dev USB Audio 2 device 137 * @param clock_id Clock Source ID whose sample rate should be returned 138 * @param user_data Opaque user data pointer 139 * 140 * @return Active sample rate in Hz 141 */ 142 uint32_t (*get_sample_rate)(const struct device *dev, uint8_t clock_id, 143 void *user_data); 144 /** 145 * @brief Set active sample rate 146 * 147 * USB stack calls this function when the host sets active sample rate. 148 * This callback may be NULL if all Clock Source entities have only one 149 * sample rate. USB stack sanitizes the sample rate to closest valid 150 * rate for given Clock Source entity. 151 * 152 * @param dev USB Audio 2 device 153 * @param clock_id Clock Source ID whose sample rate should be set 154 * @param rate Sample rate in Hz 155 * @param user_data Opaque user data pointer 156 * 157 * @return 0 on success, negative value on error 158 */ 159 int (*set_sample_rate)(const struct device *dev, uint8_t clock_id, 160 uint32_t rate, void *user_data); 161 }; 162 163 /** 164 * @brief Register USB Audio 2 application callbacks. 165 * 166 * @param dev USB Audio 2 device instance 167 * @param ops USB Audio 2 callback structure 168 * @param user_data Opaque user data to pass to ops callbacks 169 */ 170 void usbd_uac2_set_ops(const struct device *dev, 171 const struct uac2_ops *ops, void *user_data); 172 173 /** 174 * @brief Send audio data to output terminal 175 * 176 * Data buffer must be sufficiently aligned and otherwise suitable for use by 177 * UDC driver. 178 * 179 * @param dev USB Audio 2 device 180 * @param terminal Output Terminal ID linked to AudioStreaming interface 181 * @param data Buffer containing outgoing data 182 * @param size Number of bytes to send 183 * 184 * @return 0 on success, negative value on error 185 */ 186 int usbd_uac2_send(const struct device *dev, uint8_t terminal, 187 void *data, uint16_t size); 188 189 /** 190 * @} 191 */ 192 193 #endif /* ZEPHYR_INCLUDE_USB_CLASS_USBD_UAC2_H_ */ 194
