app_usbd_audio_desc.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318
  1. /**
  2. * Copyright (c) 2016 - 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_DESC_H__
  41. #define APP_USBD_AUDIO_DESC_H__
  42. #include "app_usbd_descriptor.h"
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46. /**
  47. * @defgroup app_usbd_audio_dsc USB Audio descriptors
  48. * @brief @tagAPI52840 Descriptors used in the USB Audio class.
  49. * @ingroup app_usbd_audio
  50. * @{
  51. */
  52. /**
  53. * @brief Initializer of interface descriptor for AUDIO class.
  54. *
  55. * @param interface_number Interface number.
  56. * @param alt_setting Interface alternate setting.
  57. * @param ep_num Number of endpoints.
  58. * @param subclass Audio subclass @ref app_usbd_audio_subclass_t
  59. * */
  60. #define APP_USBD_AUDIO_INTERFACE_DSC(interface_number, alt_setting, ep_num, subclass) \
  61. /*.bLength = */ sizeof(app_usbd_descriptor_iface_t), \
  62. /*.bDescriptorType = */ APP_USBD_DESCRIPTOR_INTERFACE, \
  63. /*.bInterfaceNumber = */ (interface_number), \
  64. /*.bAlternateSetting = */ (alt_setting), \
  65. /*.bNumEndpoints = */ (ep_num), \
  66. /*.bInterfaceClass = */ APP_USBD_AUDIO_CLASS, \
  67. /*.bInterfaceSubClass = */ (subclass), \
  68. /*.bInterfaceProtocol = */ APP_USBD_AUDIO_CLASS_PROTOCOL_UNDEFINED, \
  69. /*.iInterface = 0, */ 0x00, \
  70. /**
  71. * @brief Initializer of isochronous endpoint descriptors for audio class.
  72. *
  73. * @param ep ISO endpoint id: @ref NRF_DRV_USBD_EPIN8, @ref NRF_DRV_USBD_EPOUT8
  74. * @param ep_size Endpoint size (bytes).
  75. * @param interval Endpoint interval (milliseconds).
  76. * @param refresh Refresh value (usually 0).
  77. * @param synch_addr Synch address (usually 0).
  78. * */
  79. #define APP_USBD_AUDIO_ISO_EP_DSC(ep, ep_size, interval, refresh, synch_addr) \
  80. /*.bLength = */ sizeof(app_usbd_descriptor_ep_t) + 2, \
  81. /*.bDescriptorType = */ APP_USBD_DESCRIPTOR_ENDPOINT, \
  82. /*.bEndpointAddress = */ ep, \
  83. /*.bmAttributes = */ APP_USBD_DESCRIPTOR_EP_ATTR_TYPE_ISOCHRONOUS, \
  84. /*.wMaxPacketSize = */ APP_USBD_U16_TO_RAW_DSC(ep_size), \
  85. /*.bInterval = */ (interval), \
  86. /*.bRefresh = */ (refresh), \
  87. /*.bInterval = */ (synch_addr), \
  88. /**
  89. * @brief Simplified version of @ref APP_USBD_AUDIO_ISO_EP_DSC for ISO IN endpoint
  90. */
  91. #define APP_USBD_AUDIO_ISO_EP_IN_DSC(ep_size) \
  92. APP_USBD_AUDIO_ISO_EP_DSC(NRF_DRV_USBD_EPIN8, ep_size, 1, 0, 0)
  93. /**
  94. * @brief Simplified version of @ref APP_USBD_AUDIO_ISO_EP_DSC for ISO OUT endpoint
  95. */
  96. #define APP_USBD_AUDIO_ISO_EP_OUT_DSC(ep_size) \
  97. APP_USBD_AUDIO_ISO_EP_DSC(NRF_DRV_USBD_EPOUT8, ep_size, 1, 0, 0)
  98. /**
  99. * @brief Initializer of @ref app_usbd_audio_ac_iface_header_desc_t
  100. *
  101. * @param descriptor_list Descriptor list following audio interface header descriptor.
  102. * @param ... List of interfaces following audio control interface.
  103. * */
  104. #define APP_USBD_AUDIO_AC_IFACE_HEADER_DSC(descriptor_list, ...) \
  105. /*.bLength = */ sizeof(app_usbd_audio_ac_iface_header_desc_t) + \
  106. (NUM_VA_ARGS(__VA_ARGS__)), \
  107. /*.bDescriptorType = */ APP_USBD_AUDIO_DESCRIPTOR_INTERFACE, \
  108. /*.bDescriptorSubtype = */ APP_USBD_AUDIO_AC_IFACE_SUBTYPE_HEADER, \
  109. /*.bcdADC = */ APP_USBD_U16_TO_RAW_DSC(0x0100), \
  110. /*.wTotalLength = */ APP_USBD_U16_TO_RAW_DSC( \
  111. sizeof((uint8_t[]){BRACKET_EXTRACT(descriptor_list)}) + \
  112. sizeof(app_usbd_audio_ac_iface_header_desc_t) + \
  113. (NUM_VA_ARGS(__VA_ARGS__))), \
  114. /*.bInCollection = */ (NUM_VA_ARGS(__VA_ARGS__)), \
  115. /*.baInterfaceNr[] = */ __VA_ARGS__, \
  116. /**
  117. * @brief Initializer of @ref app_usbd_audio_input_terminal_desc_t
  118. *
  119. * @param terminal_id Terminal ID.
  120. * @param terminal_type Terminal type @ref app_usbd_audio_terminal_type_t
  121. * @param nr_channels Number of channels.
  122. * @param ch_config Channel config bitmask.
  123. * */
  124. #define APP_USBD_AUDIO_INPUT_TERMINAL_DSC(terminal_id, terminal_type, nr_channels, ch_config) \
  125. /*.bLength = */ sizeof(app_usbd_audio_input_terminal_desc_t), \
  126. /*.bDescriptorType = */ APP_USBD_AUDIO_DESCRIPTOR_INTERFACE, \
  127. /*.bDescriptorSubtype = */ APP_USBD_AUDIO_AC_IFACE_SUBTYPE_INPUT_TERMINAL, \
  128. /*.bTerminalID = */ (terminal_id), \
  129. /*.wTerminalType = */ APP_USBD_U16_TO_RAW_DSC(terminal_type), \
  130. /*.bAssocTerminal = */ 0, \
  131. /*.bNrChannels = */ (nr_channels), \
  132. /*.wChannelConfig = */ APP_USBD_U16_TO_RAW_DSC(ch_config), \
  133. /*.iChannelNames = */ 0, \
  134. /*.iTerminal = */ 0, \
  135. /**
  136. * @brief Initializer of @ref app_usbd_audio_output_terminal_desc_t
  137. *
  138. * @param terminal_id Terminal ID.
  139. * @param terminal_type Terminal type @ref app_usbd_audio_terminal_type_t
  140. * @param source_id Source ID.
  141. * */
  142. #define APP_USBD_AUDIO_OUTPUT_TERMINAL_DSC(terminal_id, terminal_type, source_id) \
  143. /*.bLength = */ sizeof(app_usbd_audio_output_terminal_desc_t), \
  144. /*.bDescriptorType = */ APP_USBD_AUDIO_DESCRIPTOR_INTERFACE, \
  145. /*.bDescriptorSubtype = */ APP_USBD_AUDIO_AC_IFACE_SUBTYPE_OUTPUT_TERMINAL, \
  146. /*.bTerminalID = */ (terminal_id), \
  147. /*.wTerminalType = */ APP_USBD_U16_TO_RAW_DSC(terminal_type), \
  148. /*.bAssocTerminal = */ 0, \
  149. /*.bSourceID = */ (source_id), \
  150. /*.iTerminal = */ 0, \
  151. /**
  152. * @brief Initializer of @ref app_usbd_audio_feature_unit_desc_t
  153. *
  154. * @param unit_id Unit ID.
  155. * @param source_id Source ID.
  156. * @param ... List of controls.
  157. * */
  158. #define APP_USBD_AUDIO_FEATURE_UNIT_DSC(unit_id, source_id, ...) \
  159. /*.bLength = */ sizeof(app_usbd_audio_feature_unit_desc_t) + \
  160. 1 + (NUM_VA_ARGS(__VA_ARGS__)), \
  161. /*.bDescriptorType = */ APP_USBD_AUDIO_DESCRIPTOR_INTERFACE, \
  162. /*.bDescriptorSubtype = */ APP_USBD_AUDIO_AC_IFACE_SUBTYPE_FEATURE_UNIT, \
  163. /*.bUnitID = */ (unit_id), \
  164. /*.bSourceID = */ (source_id), \
  165. /*.bControlSize = */ sizeof(uint16_t), \
  166. /*.bmaControls[] = */ __VA_ARGS__, \
  167. /*.iFeature = */ 0, \
  168. /**
  169. * @brief Initializer of @ref app_usbd_audio_as_iface_desc_t
  170. *
  171. * @param terminal_link Terminal link.
  172. * @param delay Delay.
  173. * @param format_tag Format TAG.
  174. * */
  175. #define APP_USBD_AUDIO_AS_IFACE_DSC(terminal_link, delay, format_tag) \
  176. /*.bLength = */ sizeof(app_usbd_audio_as_iface_desc_t), \
  177. /*.bDescriptorType = */ APP_USBD_AUDIO_DESCRIPTOR_INTERFACE, \
  178. /*.bDescriptorSubtype = */ APP_USBD_AUDIO_AS_IFACE_SUBTYPE_GENERAL, \
  179. /*.bTerminalLink = */ (terminal_link), \
  180. /*.bDelay = */ (delay), \
  181. /*.wFormatTag = */ APP_USBD_U16_TO_RAW_DSC(format_tag), \
  182. /**
  183. * @brief Initializer of @ref app_usbd_audio_as_format_type_one_desc_t
  184. *
  185. * @param nr_channels Number of channels.
  186. * @param subframe_size Subframe size.
  187. * @param resolution Bit resolution.
  188. * @param freq_type Frequency type.
  189. * @param ... List of frequencies.
  190. * */
  191. #define APP_USBD_AUDIO_AS_FORMAT_I_DSC(nr_channels, subframe_size, resolution, freq_type, ...) \
  192. /*.bLength = */ sizeof(app_usbd_audio_as_format_type_one_desc_t) + \
  193. (NUM_VA_ARGS(__VA_ARGS__)), \
  194. /*.bDescriptorType = */ APP_USBD_AUDIO_DESCRIPTOR_INTERFACE, \
  195. /*.bDescriptorSubtype = */ APP_USBD_AUDIO_AS_IFACE_SUBTYPE_FORMAT_TYPE, \
  196. /*.bFormatType = */ (1), \
  197. /*.bNrChannels = */ (nr_channels), \
  198. /*.bSubFrameSize = */ (subframe_size), \
  199. /*.bBitResolution = */ (resolution), \
  200. /*.bSamFreqType = */ (freq_type), \
  201. /*.tSamFreq = */ __VA_ARGS__, \
  202. /**
  203. * @brief Initializer of @ref app_usbd_audio_as_format_type_two_desc_t
  204. *
  205. * @param max_bitrate Maximum bitrate.
  206. * @param samples_per_frame Samples per frame.
  207. * @param freq_type Frequency type.
  208. * @param ... List of frequencies.
  209. * */
  210. #define APP_USBD_AUDIO_AS_FORMAT_II_DSC(max_bitrate, samples_per_frame, freq_type, ...) \
  211. /*.bLength = */ sizeof(app_usbd_audio_as_format_type_two_desc_t) + \
  212. (NUM_VA_ARGS(__VA_ARGS__)), \
  213. /*.bDescriptorType = */ APP_USBD_AUDIO_DESCRIPTOR_INTERFACE, \
  214. /*.bDescriptorSubtype = */ APP_USBD_AUDIO_AS_IFACE_SUBTYPE_FORMAT_TYPE, \
  215. /*.bFormatType = */ (2), \
  216. /*.wMaxBitRate = */ APP_USBD_U16_TO_RAW_DSC(max_bitrate), \
  217. /*.wSamplesPerFrame = */ APP_USBD_U16_TO_RAW_DSC(samples_per_frame), \
  218. /*.bSamFreqType = */ (freq_type), \
  219. /*.tSamFreq = */ __VA_ARGS__, \
  220. /**
  221. * @brief Initializer of @ref app_usbd_audio_as_format_type_three_desc_t
  222. *
  223. * @param nr_channels Number of channels.
  224. * @param subframe_size Subframe size.
  225. * @param resolution Bit resolution.
  226. * @param freq_type Frequency type.
  227. * @param ... List of frequencies.
  228. * */
  229. #define APP_USBD_AUDIO_AS_FORMAT_III_DSC(nr_channels, subframe_size, resolution, freq_type, ...) \
  230. /*.bLength = */ sizeof(app_usbd_audio_as_format_type_three_desc_t) + \
  231. (NUM_VA_ARGS(__VA_ARGS__)), \
  232. /*.bDescriptorType = */ APP_USBD_AUDIO_DESCRIPTOR_INTERFACE, \
  233. /*.bDescriptorSubtype = */ APP_USBD_AUDIO_AS_IFACE_SUBTYPE_FORMAT_TYPE, \
  234. /*.bFormatType = */ (3), \
  235. /*.bNrChannels = */ (nr_channels), \
  236. /*.bSubFrameSize = */ (subframe_size), \
  237. /*.bBitResolution = */ (resolution), \
  238. /*.bSamFreqType = */ (freq_type), \
  239. /*.tSamFreq = */ __VA_ARGS__, \
  240. /**
  241. * @brief Initializer of @ref app_usbd_audio_as_endpoint_desc_t
  242. *
  243. * @param attributes Endpoint attributes.
  244. * @param lock_delay_units Lock delay units.
  245. * @param lock_delay Lock delay.
  246. * */
  247. #define APP_USBD_AUDIO_EP_GENERAL_DSC(attributes, lock_delay_units, lock_delay) \
  248. /*.bLength = */ sizeof(app_usbd_audio_as_endpoint_desc_t), \
  249. /*.bDescriptorType = */ APP_USBD_AUDIO_DESCRIPTOR_ENDPOINT, \
  250. /*.bDescriptorSubtype = */ APP_USBD_AUDIO_EP_SUBTYPE_GENERAL, \
  251. /*.bmAttributes = */ (attributes), \
  252. /*.bLockDelayUnits = */ (lock_delay_units), \
  253. /*.wLockDelay = */ APP_USBD_U16_TO_RAW_DSC(lock_delay), \
  254. /**
  255. * @brief Macro to configure Audio Class control descriptor.
  256. *
  257. * @param interface_number Interface number.
  258. * @param descriptor_list List of descriptors after Audio interface header descriptor.
  259. * @param interface_list List of interfaces passed to @ref APP_USBD_AUDIO_AC_IFACE_HEADER_DSC
  260. * */
  261. #define APP_USBD_AUDIO_CONTROL_DSC(interface_number, descriptor_list, interface_list) \
  262. APP_USBD_AUDIO_INTERFACE_DSC(interface_number, 0, 0, APP_USBD_AUDIO_SUBCLASS_AUDIOCONTROL) \
  263. APP_USBD_AUDIO_AC_IFACE_HEADER_DSC(descriptor_list, BRACKET_EXTRACT(interface_list)) \
  264. BRACKET_EXTRACT(descriptor_list)
  265. /**
  266. * @brief Macro to configure Audio Class streaming descriptor.
  267. *
  268. * @param interface_number Interface number.
  269. * @param alt_setting Alternate interface setting.
  270. * @param ep_num Number of endpoints.
  271. */
  272. #define APP_USBD_AUDIO_STREAMING_DSC(interface_number, alt_setting, ep_num) \
  273. APP_USBD_AUDIO_INTERFACE_DSC(interface_number, alt_setting, ep_num, \
  274. APP_USBD_AUDIO_SUBCLASS_AUDIOSTREAMING)
  275. /**
  276. * @brief Macro to configure Audio Class MIDI streaming descriptor.
  277. *
  278. * @param interface_number Interface number.
  279. * @param alt_setting Alternate interface setting.
  280. * @param ep_num Number of endpoints.
  281. */
  282. #define APP_USBD_AUDIO_MIDI_STREAMING_DSC(interface_number, alt_setting, ep_num) \
  283. APP_USBD_AUDIO_INTERFACE_DSC(interface_number, alt_setting, ep_num, \
  284. APP_USBD_AUDIO_SUBCLASS_MIDISTREAMING)
  285. /** @} */
  286. #ifdef __cplusplus
  287. }
  288. #endif
  289. #endif /* APP_USBD_AUDIO_DESC_H__ */