app_usbd_audio.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346
  1. /**
  2. * Copyright (c) 2017 - 2020, Nordic Semiconductor ASA
  3. *
  4. * All rights reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. * 1. Redistributions of source code must retain the above copyright notice, this
  10. * list of conditions and the following disclaimer.
  11. *
  12. * 2. Redistributions in binary form, except as embedded into a Nordic
  13. * Semiconductor ASA integrated circuit in a product or a software update for
  14. * such product, must reproduce the above copyright notice, this list of
  15. * conditions and the following disclaimer in the documentation and/or other
  16. * materials provided with the distribution.
  17. *
  18. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  19. * contributors may be used to endorse or promote products derived from this
  20. * software without specific prior written permission.
  21. *
  22. * 4. This software, with or without modification, must only be used with a
  23. * Nordic Semiconductor ASA integrated circuit.
  24. *
  25. * 5. Any software provided in binary form under this license must not be reverse
  26. * engineered, decompiled, modified and/or disassembled.
  27. *
  28. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  29. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  31. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  32. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  33. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  36. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  37. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38. *
  39. */
  40. #ifndef APP_USBD_AUDIO_H__
  41. #define APP_USBD_AUDIO_H__
  42. #include <stdint.h>
  43. #include <stdbool.h>
  44. #include "nrf_drv_usbd.h"
  45. #include "app_usbd.h"
  46. #include "app_usbd_core.h"
  47. #include "app_usbd_class_base.h"
  48. #include "app_usbd_descriptor.h"
  49. #include "app_usbd_audio_types.h"
  50. #include "app_usbd_audio_desc.h"
  51. #include "app_usbd_audio_internal.h"
  52. #ifdef __cplusplus
  53. extern "C" {
  54. #endif
  55. /**
  56. * @defgroup app_usbd_audio USB AUDIO class
  57. * @ingroup app_usbd
  58. *
  59. * @brief @tagAPI52840 Module with types, definitions, and API used by USB Audio class.
  60. *
  61. * @details Reference specifications:
  62. * - "Universal Serial Bus Device Class Definition for Audio Devices"
  63. * Release 1.0, March 18, 1998.
  64. * - "Universal Serial Bus Device Class Definition for Audio Data Formats"
  65. * Release 1.0, March 18, 1998.
  66. * - "Universal Serial Bus Device Class Definition for Terminal Types"
  67. * Release 1.0, March 18, 1998.
  68. *
  69. * @{
  70. */
  71. #ifdef DOXYGEN
  72. /**
  73. * @brief Audio class instance type
  74. *
  75. * @ref APP_USBD_CLASS_TYPEDEF
  76. */
  77. typedef struct { } app_usbd_audio_t;
  78. #else
  79. /*lint -save -e10 -e26 -e123 -e505 */
  80. APP_USBD_CLASS_TYPEDEF(app_usbd_audio, \
  81. APP_USBD_AUDIO_CONFIG(0, 1), \
  82. APP_USBD_AUDIO_INSTANCE_SPECIFIC_DEC, \
  83. APP_USBD_AUDIO_DATA_SPECIFIC_DEC \
  84. );
  85. /*lint -restore*/
  86. #endif
  87. /*lint -save -e407 */
  88. /**
  89. * @brief Events passed to user event handler
  90. *
  91. * @note Example prototype of user event handler:
  92. *
  93. * @code
  94. void audio_user_ev_handler(app_usbd_class_inst_t const * p_inst,
  95. app_usbd_audio_user_event_t event);
  96. * @endcode
  97. */
  98. typedef enum app_usbd_audio_user_event_e {
  99. APP_USBD_AUDIO_USER_EVT_CLASS_REQ, /**< User event CLASS_REQ */
  100. APP_USBD_AUDIO_USER_EVT_RX_DONE, /**< User event RX_DONE */
  101. APP_USBD_AUDIO_USER_EVT_TX_DONE, /**< User event TX_DONE */
  102. } app_usbd_audio_user_event_t;
  103. /*lint -restore*/
  104. /**
  105. * @brief Global definition of app_usbd_audio_t class instance.
  106. *
  107. * @param instance_name Name of global instance.
  108. * @param interfaces_configs Interfaces configurations.
  109. * @param user_ev_handler User event handler.
  110. * @param format_descriptor Audio class Format descriptor.
  111. * @param input_descriptor Audio class Input Terminal descriptor.
  112. * @param output_descriptor Audio class Output Terminal descriptor.
  113. * @param feature_descriptor Audio class Feature Unit descriptor.
  114. * @param delay Streaming delay.
  115. * @param format FormatTag (@ref app_usbd_audio_as_iface_format_tag_t).
  116. * @param ep_size Endpoint size.
  117. * @param type_str Streaming type MIDISTREAMING/AUDIOSTREAMING.
  118. * @param terminal_link Terminal link in AS Interface Descriptor.
  119. *
  120. * @note This macro is just simplified version of @ref APP_USBD_AUDIO_GLOBAL_DEF_INTERNAL
  121. *
  122. */
  123. #define APP_USBD_AUDIO_GLOBAL_DEF(instance_name, \
  124. interfaces_configs, \
  125. user_ev_handler, \
  126. format_descriptor, \
  127. input_descriptor, \
  128. output_descriptor, \
  129. feature_descriptor, \
  130. delay, \
  131. format, \
  132. ep_size, \
  133. type_str, \
  134. terminal_link) \
  135. APP_USBD_AUDIO_GLOBAL_DEF_INTERNAL(instance_name, \
  136. interfaces_configs, \
  137. user_ev_handler, \
  138. format_descriptor, \
  139. input_descriptor, \
  140. output_descriptor, \
  141. feature_descriptor, \
  142. delay, \
  143. format, \
  144. ep_size, \
  145. type_str, \
  146. terminal_link)
  147. /**
  148. * @brief Initializer of Audio Format descriptor.
  149. *
  150. * @param name Format descriptor name.
  151. * @param ... Format descriptor data.
  152. */
  153. #define APP_USBD_AUDIO_FORMAT_DESCRIPTOR(name, ...) \
  154. static uint8_t const CONCAT_2(name, _data)[] = \
  155. { \
  156. __VA_ARGS__ \
  157. }; \
  158. static const app_usbd_audio_subclass_desc_t name = \
  159. { \
  160. sizeof(CONCAT_2(name, _data)), \
  161. APP_USBD_AUDIO_AS_IFACE_SUBTYPE_FORMAT_TYPE, \
  162. CONCAT_2(name,_data) \
  163. }
  164. /**
  165. * @brief Initializer of Audio Input descriptor.
  166. *
  167. * @param name Input descriptor name.
  168. * @param ... Input descriptor data.
  169. */
  170. #define APP_USBD_AUDIO_INPUT_DESCRIPTOR(name, ...) \
  171. static uint8_t const CONCAT_2(name, _data)[] = \
  172. { \
  173. __VA_ARGS__ \
  174. }; \
  175. static const app_usbd_audio_subclass_desc_t name = \
  176. { \
  177. sizeof(CONCAT_2(name, _data)), \
  178. APP_USBD_AUDIO_AC_IFACE_SUBTYPE_INPUT_TERMINAL, \
  179. CONCAT_2(name,_data) \
  180. }
  181. /**
  182. * @brief Initializer of Audio Output descriptor.
  183. *
  184. * @param name Output descriptor name.
  185. * @param ... Output descriptor data.
  186. */
  187. #define APP_USBD_AUDIO_OUTPUT_DESCRIPTOR(name, ...) \
  188. static uint8_t const CONCAT_2(name, _data)[] = \
  189. { \
  190. __VA_ARGS__ \
  191. }; \
  192. static const app_usbd_audio_subclass_desc_t name = \
  193. { \
  194. sizeof(CONCAT_2(name, _data)), \
  195. APP_USBD_AUDIO_AC_IFACE_SUBTYPE_OUTPUT_TERMINAL, \
  196. CONCAT_2(name,_data) \
  197. }
  198. /**
  199. * @brief Initializer of Feture Output descriptor.
  200. *
  201. * @param name Feture descriptor name.
  202. * @param ... Feture descriptor data.
  203. */
  204. #define APP_USBD_AUDIO_FEATURE_DESCRIPTOR(name, ...) \
  205. static uint8_t const CONCAT_2(name, _data)[] = \
  206. { \
  207. __VA_ARGS__ \
  208. }; \
  209. static const app_usbd_audio_subclass_desc_t name = \
  210. { \
  211. sizeof(CONCAT_2(name, _data)), \
  212. APP_USBD_AUDIO_AC_IFACE_SUBTYPE_FEATURE_UNIT, \
  213. CONCAT_2(name,_data) \
  214. }
  215. /**
  216. * @@brief Helper function to get class instance from Audio class.
  217. *
  218. * @param[in] p_audio Audio class instance (declared by @ref APP_USBD_AUDIO_GLOBAL_DEF).
  219. * @return Base class instance.
  220. */
  221. static inline app_usbd_class_inst_t const *
  222. app_usbd_audio_class_inst_get(app_usbd_audio_t const * p_audio)
  223. {
  224. return &p_audio->base;
  225. }
  226. /**
  227. * @brief Helper function to get audio specific request from audio class.
  228. *
  229. * @param[in] p_audio Audio class instance (declared by @ref APP_USBD_AUDIO_GLOBAL_DEF).
  230. * @return Audio class specific request.
  231. */
  232. static inline app_usbd_audio_req_t *
  233. app_usbd_audio_class_request_get(app_usbd_audio_t const * p_audio)
  234. {
  235. return &p_audio->specific.p_data->ctx.request;
  236. }
  237. /**
  238. * @brief Helper function to get audio from base class instance.
  239. *
  240. * @param[in] p_inst Base class instance.
  241. * @return Audio class handle.
  242. */
  243. static inline app_usbd_audio_t const *
  244. app_usbd_audio_class_get(app_usbd_class_inst_t const * p_inst)
  245. {
  246. return (app_usbd_audio_t const *)p_inst;
  247. }
  248. /**
  249. * @brief Get the size of last received transfer.
  250. *
  251. * @note Call this function in reaction to a SOF event to check if there is any data to process.
  252. *
  253. * @param p_inst Base class instance.
  254. *
  255. * @return Number of bytes received in the last transmission.
  256. */
  257. size_t app_usbd_audio_class_rx_size_get(app_usbd_class_inst_t const * p_inst);
  258. /**
  259. * @brief Start audio data copying from the endpoint buffer.
  260. *
  261. * Function to be used to copy data from an audio OUT endpoint to a given buffer.
  262. * When it finishes, an @ref APP_USBD_AUDIO_USER_EVT_RX_DONE event is generated.
  263. *
  264. * @param p_inst Base class instance.
  265. * @param p_buff Target buffer.
  266. * @param size Size of the requested data.
  267. *
  268. * @return Result of the endpoint transmission start.
  269. *
  270. * @sa app_usbd_audio_class_rx_size_get
  271. *
  272. * @note This function should be called in reaction to a SOF event.
  273. * Isochronous endpoints are double buffered and they are automatically switched at every SOF.
  274. */
  275. ret_code_t app_usbd_audio_class_rx_start(
  276. app_usbd_class_inst_t const * p_inst,
  277. void * p_buff,
  278. size_t size);
  279. /**
  280. * @brief Start copying audio data to the endpoint buffer.
  281. *
  282. * Function to be used to copy data to an audio IN endpoint from a given buffer.
  283. * When it finishes, an @ref APP_USBD_AUDIO_USER_EVT_TX_DONE event is generated.
  284. *
  285. * @param p_inst Base class instance.
  286. * @param p_buff Source buffer.
  287. * @param size Size of the data to be sent.
  288. *
  289. * @return Result of the endpoint transsmision start.
  290. *
  291. * @note This function should be called in reaction to a SOF event.
  292. * Isochronous endpoints are double buffered and they are automatically switched at every SOF.
  293. */
  294. ret_code_t app_usbd_audio_class_tx_start(
  295. app_usbd_class_inst_t const * p_inst,
  296. const void * p_buff,
  297. size_t size);
  298. /**
  299. * @brief Register audio instance as the one that requires SOF events in interrupt.
  300. *
  301. * This function should be called before appending the instance.
  302. *
  303. * @param p_inst Audio instance that requires SOF event.
  304. * @param handler Handler to SOF event
  305. *
  306. * @retval NRF_SUCCESS Instance linked into SOF processing list.
  307. *
  308. * @sa app_usbd_class_sof_interrupt_register
  309. */
  310. ret_code_t app_usbd_audio_sof_interrupt_register(app_usbd_class_inst_t const * p_inst,
  311. app_usbd_sof_interrupt_handler_t handler);
  312. /** @} */
  313. #ifdef __cplusplus
  314. }
  315. #endif
  316. #endif /* APP_USBD_AUDIO_H__ */