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.2.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 : * This callback is mandatory to register.
51 : *
52 : * @param dev USB Audio 2 device
53 : * @param user_data Opaque user data pointer
54 : */
55 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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_ */
|
