app_usbd_cdc_acm.h 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362
  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_CDC_ACM_H__
  41. #define APP_USBD_CDC_ACM_H__
  42. #ifdef __cplusplus
  43. extern "C" {
  44. #endif
  45. #include <stdint.h>
  46. #include <stdbool.h>
  47. #include "nrf_drv_usbd.h"
  48. #include "app_usbd_class_base.h"
  49. #include "app_usbd.h"
  50. #include "app_usbd_core.h"
  51. #include "app_usbd_descriptor.h"
  52. #include "app_usbd_cdc_desc.h"
  53. #include "app_usbd_cdc_types.h"
  54. #include "app_usbd_cdc_acm_internal.h"
  55. /**
  56. * @defgroup app_usbd_cdc_acm USB CDC ACM class
  57. * @ingroup app_usbd
  58. *
  59. * @brief @tagAPI52840 Module with types, definitions and API used by CDC ACM class.
  60. *
  61. * @details References:
  62. * - "Universal Serial Bus Class Definitions for Communications Devices"
  63. * Revision 1.2, November 3, 2010
  64. * - "Universal Serial Bus Communications Class Subclass Specification for PSTN Devices"
  65. * Revision 1.2, February 9, 2007
  66. *
  67. * @{
  68. */
  69. #ifdef DOXYGEN
  70. /**
  71. * @brief CDC ACM class instance type.
  72. *
  73. * @ref APP_USBD_CLASS_TYPEDEF
  74. */
  75. typedef struct { } app_usbd_cdc_acm_t;
  76. #else
  77. /*lint -save -e10 -e26 -e123 -e505 */
  78. APP_USBD_CLASS_TYPEDEF(app_usbd_cdc_acm, \
  79. APP_USBD_CDC_ACM_CONFIG(0, 0, 0, 0, 0), \
  80. APP_USBD_CDC_ACM_INSTANCE_SPECIFIC_DEC, \
  81. APP_USBD_CDC_ACM_DATA_SPECIFIC_DEC \
  82. );
  83. /*lint -restore*/
  84. #endif
  85. /*lint -save -e407 */
  86. /**
  87. * @brief Events passed to user event handler.
  88. *
  89. * @note Example prototype of user event handler:
  90. *
  91. * @code
  92. void cdc_acm_user_ev_handler(app_usbd_class_inst_t const * p_inst,
  93. app_usbd_cdc_acm_user_event_t event);
  94. * @endcode
  95. */
  96. typedef enum app_usbd_cdc_acm_user_event_e {
  97. APP_USBD_CDC_ACM_USER_EVT_RX_DONE, /**< User event RX_DONE. */
  98. APP_USBD_CDC_ACM_USER_EVT_TX_DONE, /**< User event TX_DONE. */
  99. APP_USBD_CDC_ACM_USER_EVT_PORT_OPEN, /**< User event PORT_OPEN. */
  100. APP_USBD_CDC_ACM_USER_EVT_PORT_CLOSE, /**< User event PORT_CLOSE. */
  101. } app_usbd_cdc_acm_user_event_t;
  102. /*lint -restore*/
  103. /**
  104. * @brief Default CDC ACM descriptors.
  105. *
  106. * @param comm_interface COMM interface number.
  107. * @param comm_epin COMM interface IN endpoint.
  108. * @param data_interface DATA interface number.
  109. * @param data_epin DATA interface IN endpoint.
  110. * @param data_epout DATA interface OUT endpoint.
  111. */
  112. #define APP_USBD_CDC_ACM_DEFAULT_DESC(comm_interface, \
  113. comm_epin, \
  114. data_interface, \
  115. data_epin, \
  116. data_epout) \
  117. APP_USBD_CDC_IAD_DSC(comm_interface, \
  118. APP_USBD_CDC_SUBCLASS_ACM, \
  119. APP_USBD_CDC_COMM_PROTOCOL_AT_V250) \
  120. APP_USBD_CDC_COMM_INTERFACE_DSC(comm_interface, \
  121. APP_USBD_CDC_SUBCLASS_ACM, \
  122. APP_USBD_CDC_COMM_PROTOCOL_AT_V250) \
  123. APP_USBD_CDC_HEADER_DSC(0x0110) \
  124. APP_USBD_CDC_CALL_MGMT_DSC(0x03, data_interface) \
  125. APP_USBD_CDC_ACM_DSC(0x02) \
  126. APP_USBD_CDC_UNION_DSC(comm_interface, data_interface) \
  127. APP_USBD_CDC_COM_EP_DSC(comm_epin, NRF_DRV_USBD_EPSIZE) \
  128. APP_USBD_CDC_DATA_INTERFACE_DSC(data_interface, 0, 0) \
  129. APP_USBD_CDC_DATA_EP_DSC(data_epin, data_epout, NRF_DRV_USBD_EPSIZE)
  130. /**
  131. * @brief Global definition of app_usbd_cdc_acm_t class instance.
  132. *
  133. * @param instance_name Name of global instance.
  134. * @param user_ev_handler User event handler (optional).
  135. * @param comm_ifc Interface number of cdc_acm control.
  136. * @param data_ifc Interface number of cdc_acm DATA.
  137. * @param comm_ein COMM subclass IN endpoint.
  138. * @param data_ein DATA subclass IN endpoint.
  139. * @param data_eout DATA subclass OUT endpoint.
  140. * @param cdc_protocol CDC protocol @ref app_usbd_cdc_comm_protocol_t
  141. *
  142. * @note This macro is just simplified version of @ref APP_USBD_CDC_ACM_GLOBAL_DEF_INTERNAL.
  143. *
  144. */
  145. #define APP_USBD_CDC_ACM_GLOBAL_DEF(instance_name, \
  146. user_ev_handler, \
  147. comm_ifc, \
  148. data_ifc, \
  149. comm_ein, \
  150. data_ein, \
  151. data_eout, \
  152. cdc_protocol) \
  153. APP_USBD_CDC_ACM_GLOBAL_DEF_INTERNAL(instance_name, \
  154. user_ev_handler, \
  155. comm_ifc, \
  156. data_ifc, \
  157. comm_ein, \
  158. data_ein, \
  159. data_eout, \
  160. cdc_protocol) \
  161. /**
  162. * @brief Helper function to get class instance from CDC ACM class.
  163. *
  164. * @param[in] p_cdc_acm CDC ACM class instance (defined by @ref APP_USBD_CDC_ACM_GLOBAL_DEF).
  165. *
  166. * @return Base class instance.
  167. */
  168. static inline app_usbd_class_inst_t const *
  169. app_usbd_cdc_acm_class_inst_get(app_usbd_cdc_acm_t const * p_cdc_acm)
  170. {
  171. return &p_cdc_acm->base;
  172. }
  173. /**
  174. * @brief Helper function to get cdc_acm specific request from cdc_acm class.
  175. *
  176. * @param[in] p_cdc_acm CDC ACM class instance (defined by @ref APP_USBD_CDC_ACM_GLOBAL_DEF).
  177. *
  178. * @return CDC ACM class specific request.
  179. */
  180. static inline app_usbd_cdc_acm_req_t *
  181. app_usbd_cdc_acm_class_request_get(app_usbd_cdc_acm_t const * p_cdc_acm)
  182. {
  183. return &p_cdc_acm->specific.p_data->ctx.request;
  184. }
  185. /**
  186. * @brief Helper function to get cdc_acm from base class instance.
  187. *
  188. * @param[in] p_inst Base class instance.
  189. *
  190. * @return CDC ACM class handle.
  191. */
  192. static inline app_usbd_cdc_acm_t const *
  193. app_usbd_cdc_acm_class_get(app_usbd_class_inst_t const * p_inst)
  194. {
  195. return (app_usbd_cdc_acm_t const *)p_inst;
  196. }
  197. /**
  198. * @brief Writes data to CDC ACM serial port.
  199. *
  200. * This is asynchronous call. User should wait for @ref APP_USBD_CDC_ACM_USER_EVT_TX_DONE event
  201. * to be sure that all data has been sent and input buffer could be accessed again.
  202. *
  203. * @param[in] p_cdc_acm CDC ACM class instance (defined by @ref APP_USBD_CDC_ACM_GLOBAL_DEF).
  204. * @param[in] p_buf Input buffer.
  205. * @param[in] length Input buffer length.
  206. *
  207. * @return Standard error code.
  208. */
  209. ret_code_t app_usbd_cdc_acm_write(app_usbd_cdc_acm_t const * p_cdc_acm,
  210. const void * p_buf,
  211. size_t length);
  212. /**
  213. * @brief Returns the amount of data that was read.
  214. *
  215. * This function should be used on @ref APP_USBD_CDC_ACM_USER_EVT_RX_DONE event to get
  216. * information how many bytes have been transfered into user buffer.
  217. *
  218. * @param[in] p_cdc_acm CDC ACM class instance (defined by @ref APP_USBD_CDC_ACM_GLOBAL_DEF).
  219. *
  220. * @return Amount of data transfered.
  221. */
  222. size_t app_usbd_cdc_acm_rx_size(app_usbd_cdc_acm_t const * p_cdc_acm);
  223. /**
  224. * @brief Returns the amount of data that was stored into internal buffer
  225. *
  226. * This function should be used on @ref APP_USBD_CDC_ACM_USER_EVT_RX_DONE event to get
  227. * information how many bytes are waiting in internal buffer.
  228. *
  229. * @param[in] p_cdc_acm CDC ACM class instance (defined by @ref APP_USBD_CDC_ACM_GLOBAL_DEF).
  230. *
  231. * @return Amount of data waiting.
  232. */
  233. size_t app_usbd_cdc_acm_bytes_stored(app_usbd_cdc_acm_t const * p_cdc_acm);
  234. /**
  235. * @brief Reads data from CDC ACM serial port.
  236. *
  237. * This function uses internal buffer and double buffering for continuous transmission.
  238. *
  239. * If there is enough data in internal buffer to fill user buffer, NRF_SUCCESS is
  240. * returned and data is immediately available in the user buffer.
  241. *
  242. * If not, up to two user buffers can be scheduled, function returns NRF_ERROR_IO_PENDING
  243. * when first buffer is filled and @ref APP_USBD_CDC_ACM_USER_EVT_RX_DONE event is generated.
  244. *
  245. * @sa app_usbd_cdc_acm_read_any
  246. * @sa app_usbd_cdc_acm_rx_size
  247. *
  248. * @param[in] p_cdc_acm CDC ACM class instance (defined by @ref APP_USBD_CDC_ACM_GLOBAL_DEF).
  249. * @param[out] p_buf Output buffer.
  250. * @param[in] length Number of bytes to read.
  251. *
  252. * @retval NRF_SUCCESS Data is stored into user buffer.
  253. * @retval NRF_ERROR_IO_PENDING Awaiting transmission, when data is stored into user buffer,
  254. * @ref APP_USBD_CDC_ACM_USER_EVT_RX_DONE event will be raised.
  255. * @retval NRF_ERROR_BUSY There are already 2 buffers queued for transfers.
  256. * @retval other Standard error code.
  257. */
  258. ret_code_t app_usbd_cdc_acm_read(app_usbd_cdc_acm_t const * p_cdc_acm,
  259. void * p_buf,
  260. size_t length);
  261. /**
  262. * @brief Read any data from CDC ACM port up to given buffer size
  263. *
  264. * This function is very similar to the @ref app_usbd_cdc_acm_read but it returns
  265. * data as quick as any data is available, even if the given buffer was not totally full.
  266. *
  267. * @note This function cannot use double buffering.
  268. * @note To check the number of bytes really read use @ref app_usbd_cdc_acm_rx_size
  269. * function.
  270. *
  271. * @sa app_usbd_cdc_acm_read
  272. * @sa app_usbd_cdc_acm_rx_size
  273. *
  274. * @param p_cdc_acm CDC ACM class instance (defined by @ref APP_USBD_CDC_ACM_GLOBAL_DEF).
  275. * @param[out] p_buf Output buffer.
  276. * @param[in] length Maximum number of bytes to read.
  277. *
  278. * @retval NRF_SUCCESS Data is stored into user buffer.
  279. * @retval NRF_ERROR_IO_PENDING Awaiting transmission, when data is stored into user buffer,
  280. * @ref APP_USBD_CDC_ACM_USER_EVT_RX_DONE event will be raised.
  281. * @retval NRF_ERROR_BUSY There is already buffer set for a transfer.
  282. * @retval other Standard error code.
  283. */
  284. ret_code_t app_usbd_cdc_acm_read_any(app_usbd_cdc_acm_t const * p_cdc_acm,
  285. void * p_buf,
  286. size_t length);
  287. /**
  288. * @brief Serial state notifications.
  289. * */
  290. typedef enum {
  291. APP_USBD_CDC_ACM_SERIAL_STATE_DCD = (1u << 0), /**< Notification bit DCD. */
  292. APP_USBD_CDC_ACM_SERIAL_STATE_DSR = (1u << 1), /**< Notification bit DSR. */
  293. APP_USBD_CDC_ACM_SERIAL_STATE_BREAK = (1u << 2), /**< Notification bit BREAK. */
  294. APP_USBD_CDC_ACM_SERIAL_STATE_RING = (1u << 3), /**< Notification bit RING. */
  295. APP_USBD_CDC_ACM_SERIAL_STATE_FRAMING = (1u << 4), /**< Notification bit FRAMING.*/
  296. APP_USBD_CDC_ACM_SERIAL_STATE_PARITY = (1u << 5), /**< Notification bit PARITY. */
  297. APP_USBD_CDC_ACM_SERIAL_STATE_OVERRUN = (1u << 6), /**< Notification bit OVERRUN.*/
  298. } app_usbd_cdc_acm_serial_state_t;
  299. /**
  300. * @brief Serial line state.
  301. */
  302. typedef enum {
  303. APP_USBD_CDC_ACM_LINE_STATE_DTR = (1u << 0), /**< Line state bit DTR.*/
  304. APP_USBD_CDC_ACM_LINE_STATE_RTS = (1u << 1), /**< Line state bit RTS.*/
  305. } app_usbd_cdc_acm_line_state_t;
  306. /**
  307. * @brief Serial state notification via IN interrupt endpoint.
  308. *
  309. * @param[in] p_cdc_acm CDC ACM class instance (defined by @ref APP_USBD_CDC_ACM_GLOBAL_DEF).
  310. * @param[in] serial_state Serial state notification type.
  311. * @param[in] value Serial state value.
  312. *
  313. * @return Standard error code.
  314. */
  315. ret_code_t app_usbd_cdc_acm_serial_state_notify(app_usbd_cdc_acm_t const * p_cdc_acm,
  316. app_usbd_cdc_acm_serial_state_t serial_state,
  317. bool value);
  318. /**
  319. * @brief Control line value get.
  320. *
  321. * @param[in] p_cdc_acm CDC ACM class instance (defined by @ref APP_USBD_CDC_ACM_GLOBAL_DEF).
  322. * @param[in] line_state Line control value type.
  323. * @param[out] value Line control value.
  324. *
  325. * @return Standard error code.
  326. */
  327. ret_code_t app_usbd_cdc_acm_line_state_get(app_usbd_cdc_acm_t const * p_cdc_acm,
  328. app_usbd_cdc_acm_line_state_t line_state,
  329. uint32_t * value);
  330. /** @} */
  331. #ifdef __cplusplus
  332. }
  333. #endif
  334. #endif /* APP_USBD_CDC_ACM_H__ */