app_usbd_core.h 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222
  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_CORE_H__
  41. #define APP_USBD_CORE_H__
  42. #include <stdint.h>
  43. #include "sdk_common.h"
  44. #include "nrf_drv_usbd.h"
  45. #include "app_usbd_types.h"
  46. #include "app_usbd_class_base.h"
  47. #ifdef __cplusplus
  48. extern "C" {
  49. #endif
  50. /**
  51. * @defgroup app_usbd_core USB Device high level library core module
  52. * @ingroup app_usbd
  53. *
  54. * @brief @tagAPI52840 Core module that manages current USB state and process device requests.
  55. * @{
  56. */
  57. /**
  58. * @brief Core interface configuration.
  59. *
  60. * Core instance would have 2 endpoints (IN0 and OUT0).
  61. * The interface number does not matter because it is not used.
  62. */
  63. #define APP_USBD_CORE_CLASS_CONFIGURATION ((0, NRF_DRV_USBD_EPOUT0, NRF_DRV_USBD_EPIN0))
  64. /**
  65. * @brief USB Device state.
  66. *
  67. * Possible USB Device states according to specification.
  68. */
  69. typedef enum
  70. {
  71. APP_USBD_STATE_Disabled , /**< The whole USBD library is disabled */
  72. APP_USBD_STATE_Unattached, /**< Device is currently not connected to the host */
  73. APP_USBD_STATE_Powered , /**< Device is connected to the host but has not been enumerated */
  74. APP_USBD_STATE_Default , /**< USB Reset condition detected, waiting for the address */
  75. APP_USBD_STATE_Addressed , /**< Device has been addressed but has not been configured */
  76. APP_USBD_STATE_Configured, /**< Device is addressed and configured */
  77. }app_usbd_state_t;
  78. /**
  79. * @brief EP0 handler function pointer.
  80. *
  81. * Type of the variable that would hold the pointer to the handler for
  82. * endpoint 0 messages processing.
  83. *
  84. * @param p_contex Context variable configured with the transmission request.
  85. */
  86. typedef ret_code_t (*app_usbd_core_setup_data_handler_t)(nrf_drv_usbd_ep_status_t status,
  87. void * p_context);
  88. /**
  89. * @brief Variable type used to register EP0 transfer handler.
  90. *
  91. * EP0 messages are processed by core instance.
  92. * Another class can register itself to receive messages from EP0 when requesting
  93. * for Setup data transfer.
  94. */
  95. typedef struct
  96. {
  97. app_usbd_core_setup_data_handler_t handler; //!< Event handler to be called when transmission is ready
  98. void * p_context; //!< Context pointer to be send to every called event.
  99. } app_usbd_core_setup_data_handler_desc_t;
  100. /*lint -save -e10 -e26 -e93 -e123 -e505 */
  101. /**
  102. * @brief Declare Core instance type.
  103. *
  104. * USBD core instance type definition.
  105. */
  106. APP_USBD_CLASS_TYPEDEF(app_usbd_core,
  107. APP_USBD_CORE_CLASS_CONFIGURATION,
  108. APP_USBD_CLASS_INSTANCE_SPECIFIC_DEC_NONE,
  109. APP_USBD_CLASS_DATA_SPECIFIC_DEC_NONE);
  110. /*lint -restore*/
  111. /**
  112. * @brief Access to core instance.
  113. *
  114. * Function that returns pointer to the USBD core instance.
  115. *
  116. * @return pointer to the core instance.
  117. */
  118. static inline app_usbd_class_inst_t const * app_usbd_core_instance_access(void)
  119. {
  120. extern const APP_USBD_CLASS_INSTANCE_TYPE(app_usbd_core) app_usbd_core_inst;
  121. return (app_usbd_class_inst_t const *)&app_usbd_core_inst;
  122. }
  123. /**
  124. * @brief Enable endpoint 0
  125. *
  126. * Function enables endpoint OUT0 and IN0.
  127. * This makes the USB respond to SETUP transfers.
  128. */
  129. void app_usbd_core_ep0_enable(void);
  130. /**
  131. * @brief Disable endpoint 0
  132. *
  133. * Function disables endpoint OUT0 and IN0.
  134. * This makes the USB ignore SETUP transfers.
  135. */
  136. void app_usbd_core_ep0_disable(void);
  137. /**
  138. * @brief Default simple response to setup command.
  139. *
  140. * This function generates default simple response.
  141. * It sends ZLP when required and on takes care on allowing status stage when
  142. * transfer is finished.
  143. *
  144. * @param p_setup Pointer to original setup message.
  145. * @param p_data Pointer to the response. This has to be globaly aviable data.
  146. * @param size Total size of the answer - The function takes care about
  147. * limiting the size of transfered data to the size required
  148. * by setup command.
  149. */
  150. ret_code_t app_usbd_core_setup_rsp(app_usbd_setup_t const * p_setup,
  151. void const * p_data,
  152. size_t size);
  153. /**
  154. * @brief Configure the handler for the nearest setup data endpoint transfer.
  155. *
  156. * This function would be called on incomming setup data.
  157. * The correct place to set the handler for a data is when SETUP command
  158. * was received.
  159. *
  160. * @param ep Endpoint number (only IN0 and OUT0 are supported).
  161. * @param p_handler_desc Descriptor of the handler to be called.
  162. *
  163. * @retval NRF_SUCCESS Successfully configured.
  164. * @retval NRF_ERROR_INVALID_ADDR Last received setup direction does not match
  165. * configured endpoint.
  166. */
  167. ret_code_t app_usbd_core_setup_data_handler_set(
  168. nrf_drv_usbd_ep_t ep,
  169. app_usbd_core_setup_data_handler_desc_t const * const p_handler_desc);
  170. /**
  171. * @brief Set up a data transfer buffer.
  172. *
  173. * Returns special internal buffer that can be used in setup transfer.
  174. * @return Internal buffer pointer.
  175. */
  176. void * app_usbd_core_setup_transfer_buff_get(size_t * p_size);
  177. /**@brief Return internal USBD core state.
  178. *
  179. * @return Check @ref app_usbd_state_t to find possible USBD core states.
  180. */
  181. app_usbd_state_t app_usbd_core_state_get(void);
  182. /**
  183. * @brief Check current feature state.
  184. *
  185. * Function checks the state of the selected feature that was configured by the host.
  186. *
  187. * @param feature Feature to check. @ref app_usbd_setup_stdfeature_t
  188. * Only features related to the device should be checked by this function.
  189. *
  190. * @retval true Selected feature is set.
  191. * @retval false Selected feature is cleared.
  192. */
  193. bool app_usbd_core_feature_state_get(app_usbd_setup_stdfeature_t feature);
  194. /** @} */
  195. #ifdef __cplusplus
  196. }
  197. #endif
  198. #endif /* APP_USBD_CORE_H__ */