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 * @{ 27 */ 28 29 /** 30 * @brief Get entity ID 31 * 32 * @param node node identifier 33 */ 34 #define UAC2_ENTITY_ID(node) \ 35 ({ \ 36 BUILD_ASSERT(DT_NODE_HAS_COMPAT(DT_PARENT(node), zephyr_uac2)); \ 37 UTIL_INC(DT_NODE_CHILD_IDX(node)); \ 38 }) 39 40 /** 41 * @brief USB Audio 2 application event handlers 42 */ 43 struct uac2_ops { 44 /** 45 * @brief Start of Frame callback 46 * 47 * Notifies application about SOF event on the bus. 48 * 49 * @param dev USB Audio 2 device 50 * @param user_data Opaque user data pointer 51 */ 52 void (*sof_cb)(const struct device *dev, void *user_data); 53 /** 54 * @brief Terminal update callback 55 * 56 * Notifies application that host has enabled or disabled a terminal. 57 * 58 * @param dev USB Audio 2 device 59 * @param terminal Terminal ID linked to AudioStreaming interface 60 * @param enabled True if host enabled terminal, False otherwise 61 * @param microframes True if USB connection speed uses microframes 62 * @param user_data Opaque user data pointer 63 */ 64 void (*terminal_update_cb)(const struct device *dev, uint8_t terminal, 65 bool enabled, bool microframes, 66 void *user_data); 67 /** 68 * @brief Get receive buffer address 69 * 70 * USB stack calls this function to obtain receive buffer address for 71 * AudioStreaming interface. The buffer is owned by USB stack until 72 * @ref data_recv_cb callback is called. The buffer must be sufficiently 73 * aligned and otherwise suitable for use by UDC driver. 74 * 75 * @param dev USB Audio 2 device 76 * @param terminal Input Terminal ID linked to AudioStreaming interface 77 * @param size Maximum number of bytes USB stack will write to buffer. 78 * @param user_data Opaque user data pointer 79 */ 80 void *(*get_recv_buf)(const struct device *dev, uint8_t terminal, 81 uint16_t size, void *user_data); 82 /** 83 * @brief Data received 84 * 85 * This function releases buffer obtained in @ref get_recv_buf after USB 86 * has written data to the buffer and/or no longer needs it. 87 * 88 * @param dev USB Audio 2 device 89 * @param terminal Input Terminal ID linked to AudioStreaming interface 90 * @param buf Buffer previously obtained via @ref get_recv_buf 91 * @param size Number of bytes written to buffer 92 * @param user_data Opaque user data pointer 93 */ 94 void (*data_recv_cb)(const struct device *dev, uint8_t terminal, 95 void *buf, uint16_t size, void *user_data); 96 /** 97 * @brief Transmit buffer release callback 98 * 99 * This function releases buffer provided in @ref usbd_uac2_send when 100 * the class no longer needs it. 101 * 102 * @param dev USB Audio 2 device 103 * @param terminal Output Terminal ID linked to AudioStreaming interface 104 * @param buf Buffer previously provided via @ref usbd_uac2_send 105 * @param user_data Opaque user data pointer 106 */ 107 void (*buf_release_cb)(const struct device *dev, uint8_t terminal, 108 void *buf, void *user_data); 109 /** 110 * @brief Get Explicit Feedback value 111 * 112 * Explicit feedback value format depends terminal connection speed. 113 * If device is High-Speed capable, it must use Q16.16 format if and 114 * only if the @ref terminal_update_cb was called with microframes 115 * parameter set to true. On Full-Speed only devices, or if High-Speed 116 * capable device is operating at Full-Speed (microframes was false), 117 * the format is Q10.14 stored on 24 least significant bits (i.e. 8 most 118 * significant bits are ignored). 119 * 120 * @param dev USB Audio 2 device 121 * @param terminal Input Terminal ID whose feedback should be returned 122 * @param user_data Opaque user data pointer 123 */ 124 uint32_t (*feedback_cb)(const struct device *dev, uint8_t terminal, 125 void *user_data); 126 }; 127 128 /** 129 * @brief Register USB Audio 2 application callbacks. 130 * 131 * @param dev USB Audio 2 device instance 132 * @param ops USB Audio 2 callback structure 133 * @param user_data Opaque user data to pass to ops callbacks 134 */ 135 void usbd_uac2_set_ops(const struct device *dev, 136 const struct uac2_ops *ops, void *user_data); 137 138 /** 139 * @brief Send audio data to output terminal 140 * 141 * Data buffer must be sufficiently aligned and otherwise suitable for use by 142 * UDC driver. 143 * 144 * @param dev USB Audio 2 device 145 * @param terminal Output Terminal ID linked to AudioStreaming interface 146 * @param data Buffer containing outgoing data 147 * @param size Number of bytes to send 148 * 149 * @return 0 on success, negative value on error 150 */ 151 int usbd_uac2_send(const struct device *dev, uint8_t terminal, 152 void *data, uint16_t size); 153 154 /** 155 * @} 156 */ 157 158 #endif /* ZEPHYR_INCLUDE_USB_CLASS_USBD_UAC2_H_ */ 159
