Line data Source code
1 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 1 : #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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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_ */
