app_usbd_hid_generic.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284
  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_HID_GENERIC_H__
  41. #define APP_USBD_HID_GENERIC_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_hid_types.h"
  50. #include "app_usbd_hid.h"
  51. #include "app_usbd.h"
  52. #include "app_usbd_core.h"
  53. #include "app_usbd_descriptor.h"
  54. #include "app_usbd_hid_generic_desc.h"
  55. #include "app_usbd_hid_generic_internal.h"
  56. /**
  57. * @defgroup app_usbd_hid_generic USB HID generic
  58. * @ingroup app_usbd_hid
  59. *
  60. * @brief @tagAPI52840 Module with types, definitions, and API used by the HID generic class.
  61. * @{
  62. */
  63. #ifdef DOXYGEN
  64. /**
  65. * @brief HID generic class instance type.
  66. *
  67. * @ref APP_USBD_CLASS_TYPEDEF
  68. */
  69. typedef struct { } app_usbd_hid_generic_t;
  70. #else
  71. /*lint -save -e10 -e26 -e123 -e505 */
  72. APP_USBD_CLASS_TYPEDEF(app_usbd_hid_generic, \
  73. APP_USBD_HID_GENERIC_CONFIG(0, (NRF_DRV_USBD_EPIN1, NRF_DRV_USBD_EPOUT1)), \
  74. APP_USBD_HID_GENERIC_INSTANCE_SPECIFIC_DEC, \
  75. APP_USBD_HID_GENERIC_DATA_SPECIFIC_DEC \
  76. );
  77. /*lint -restore*/
  78. #endif
  79. /**
  80. * @brief Global definition of app_usbd_hid_generic_t class.
  81. *
  82. * @param instance_name Name of global instance.
  83. * @param interface_number Unique interface index.
  84. * @param user_ev_handler User event handler (optional).
  85. * @param endpoint_list Input endpoint list (@ref nrf_drv_usbd_ep_t).
  86. * @param subclass_descriptors HID subclass descriptors.
  87. * @param report_in_queue_size IN report queue size.
  88. * @param report_out_maxsize Maximum output report size.
  89. * @param report_feature_maxsize Maximum feature report size.
  90. * @param subclass_boot Subclass boot (@ref app_usbd_hid_subclass_t).
  91. * @param protocol HID protocol (@ref app_usbd_hid_protocol_t).
  92. *
  93. * @note This macro is just simplified version of @ref APP_USBD_HID_GENERIC_GLOBAL_DEF_INTERNAL.
  94. *
  95. * Example class definition:
  96. * @code
  97. APP_USBD_HID_GENERIC_SUBCLASS_REPORT_DESC(mouse_desc,APP_USBD_HID_MOUSE_REPORT_DSC_BUTTON(2));
  98. static const app_usbd_hid_subclass_desc_t * reps[] = {&mouse_desc};
  99. #define ENDPOINT_LIST \
  100. ( \
  101. NRF_DRV_USBD_EPIN1 \
  102. )
  103. #define REPORT_COUNT 1
  104. #define REPORT_OUT_MAXSIZE 0
  105. APP_USBD_HID_GENERIC_GLOBAL_DEF(m_app_hid_generic,
  106. 0,
  107. hid_user_ev_handler,
  108. ENDPOINT_LIST(),
  109. reps,
  110. REPORT_IN_QUEUE_SIZE,
  111. REPORT_OUT_MAXSIZE,
  112. REPORT_FEATURE_MAXSIZE,
  113. APP_USBD_HID_SUBCLASS_BOOT,
  114. APP_USBD_HID_PROTO_MOUSE);
  115. @endcode
  116. *
  117. */
  118. /*lint -emacro( (40), APP_USBD_HID_GENERIC_GLOBAL_DEF) */
  119. #define APP_USBD_HID_GENERIC_GLOBAL_DEF(instance_name, \
  120. interface_number, \
  121. user_ev_handler, \
  122. endpoint_list, \
  123. subclass_descriptors, \
  124. report_in_queue_size, \
  125. report_out_maxsize, \
  126. report_feature_maxsize, \
  127. subclass_boot, \
  128. protocol) \
  129. APP_USBD_HID_GENERIC_GLOBAL_DEF_INTERNAL(instance_name, \
  130. interface_number, \
  131. user_ev_handler, \
  132. endpoint_list, \
  133. subclass_descriptors, \
  134. report_in_queue_size, \
  135. report_out_maxsize, \
  136. report_feature_maxsize, \
  137. subclass_boot, \
  138. protocol)
  139. /**
  140. * @brief Helper function to get class instance from HID generic class.
  141. *
  142. * @param[in] p_generic HID generic class instance.
  143. *
  144. * @return Base class instance.
  145. */
  146. static inline app_usbd_class_inst_t const *
  147. app_usbd_hid_generic_class_inst_get(app_usbd_hid_generic_t const * p_generic)
  148. {
  149. return &p_generic->base;
  150. }
  151. /**
  152. * @brief Helper function to get HID generic from base class instance.
  153. *
  154. * @param[in] p_inst Base class instance.
  155. *
  156. * @return HID generic class handle.
  157. */
  158. static inline app_usbd_hid_generic_t const *
  159. app_usbd_hid_generic_class_get(app_usbd_class_inst_t const * p_inst)
  160. {
  161. return (app_usbd_hid_generic_t const *)p_inst;
  162. }
  163. /**
  164. * @brief Changes default HID idle report.
  165. *
  166. *
  167. * @param[in] p_generic HID generic class instance.
  168. * @param[in] p_buff Report buffer.
  169. * @param[in] size Report size.
  170. *
  171. * @return Standard error code.
  172. */
  173. ret_code_t hid_generic_idle_set(app_usbd_hid_generic_t const * p_generic,
  174. const void * p_buff,
  175. size_t size);
  176. /**
  177. * @brief New IN report trigger.
  178. *
  179. *
  180. * @param[in] p_generic HID generic class instance.
  181. * @param[in] p_buff Report buffer.
  182. * @param[in] size Report size.
  183. *
  184. * @return Standard error code.
  185. */
  186. ret_code_t app_usbd_hid_generic_in_report_set(app_usbd_hid_generic_t const * p_generic,
  187. const void * p_buff,
  188. size_t size);
  189. /**
  190. * @brief Returns last successful transfered IN report.
  191. *
  192. * @note Use this call only on @ref APP_USBD_HID_USER_EVT_IN_REPORT_DONE event.
  193. *
  194. * @param[in] p_generic HID generic class instance.
  195. * @param[out] p_size Last transfered IN report size.
  196. *
  197. * @return Last transfered report ID.
  198. */
  199. const void * app_usbd_hid_generic_in_report_get(app_usbd_hid_generic_t const * p_generic,
  200. size_t * p_size);
  201. /**
  202. * @brief Returns last successful transfered OUT report.
  203. *
  204. * @warning Use this call only on @ref APP_USBD_HID_USER_EVT_OUT_REPORT_READY event.
  205. *
  206. * @param[in] p_generic HID generic class instance.
  207. * @param[out] p_size Last transfered OUT report size.
  208. *
  209. * @return Last transfered OUT report.
  210. */
  211. const void * app_usbd_hid_generic_out_report_get(app_usbd_hid_generic_t const * p_generic,
  212. size_t * p_size);
  213. /**
  214. * @brief Function handling SET_PROTOCOL command.
  215. *
  216. *
  217. * @param[in] p_generic HID generic class instance.
  218. * @param[in] ev User event.
  219. *
  220. * @return Standard error code.
  221. */
  222. ret_code_t hid_generic_on_set_protocol(app_usbd_hid_generic_t const * p_generic,
  223. app_usbd_hid_user_event_t ev);
  224. /**
  225. * @brief Function that clears HID generic buffers and sends an empty report.
  226. *
  227. * @param[in] p_inst Base class instance.
  228. *
  229. * @return Standard error code.
  230. */
  231. ret_code_t hid_generic_clear_buffer(app_usbd_class_inst_t const * p_inst);
  232. /**
  233. * @brief Sets handler for idle reports.
  234. *
  235. * @param[in] p_inst Base class instance.
  236. * @param[in] handler Handler.
  237. *
  238. * @return Standard error code.
  239. */
  240. ret_code_t hid_generic_idle_handler_set(app_usbd_class_inst_t const * p_inst,
  241. app_usbd_hid_idle_handler_t handler);
  242. /**
  243. * @brief Sends idle reoprt.
  244. *
  245. * @param[in] p_generic HID generic class instance.
  246. * @param[in] p_buff Report buffer.
  247. * @param[in] size Size of report.
  248. *
  249. * @return Standard error code.
  250. */
  251. ret_code_t app_usbd_hid_generic_idle_report_set(app_usbd_hid_generic_t const * p_generic,
  252. const void * p_buff,
  253. size_t size);
  254. /** @} */
  255. #ifdef __cplusplus
  256. }
  257. #endif
  258. #endif /* APP_USBD_HID_GENERIC_H__ */