app_usbd_msc.h 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193
  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_MSC_H__
  41. #define APP_USBD_MSC_H__
  42. #include <stdint.h>
  43. #include <stdbool.h>
  44. #include "nrf_drv_usbd.h"
  45. #include "nrf_block_dev.h"
  46. #include "app_usbd_class_base.h"
  47. #include "app_usbd.h"
  48. #include "app_usbd_core.h"
  49. #include "app_usbd_descriptor.h"
  50. #include "app_usbd_msc_types.h"
  51. #include "app_usbd_msc_desc.h"
  52. #include "app_usbd_msc_scsi.h"
  53. #include "app_usbd_msc_internal.h"
  54. #ifdef __cplusplus
  55. extern "C" {
  56. #endif
  57. /**
  58. * @defgroup app_usbd_msc USB MSC class
  59. * @ingroup app_usbd
  60. *
  61. * @brief @tagAPI52840 Module with types, definitions, and API used by the USB MSC class.
  62. *
  63. * @details References:
  64. * - "Universal Serial Bus Mass Storage Class, Specification Overview,"
  65. * Revision 1.2, USB Implementer's Forum, June 23, 2003.
  66. * - "Universal Serial Bus Mass Storage Class, Bulk-Only Transport,"
  67. * Revision 1.0, USB Implementer's Forum, September 31, 1999.
  68. *
  69. * @{
  70. */
  71. #ifdef DOXYGEN
  72. /**
  73. * @brief Mass storage class instance type.
  74. *
  75. * @ref APP_USBD_CLASS_TYPEDEF
  76. */
  77. typedef struct { } app_usbd_msc_t;
  78. #else
  79. /*lint -save -e10 -e26 -e123 -e505 */
  80. APP_USBD_CLASS_TYPEDEF(app_usbd_msc, \
  81. APP_USBD_MSC_CONFIG(0, (NRF_DRV_USBD_EPIN1, NRF_DRV_USBD_EPOUT1)), \
  82. APP_USBD_MSC_INSTANCE_SPECIFIC_DEC, \
  83. APP_USBD_MSC_DATA_SPECIFIC_DEC \
  84. );
  85. #endif
  86. /*lint -restore*/
  87. /*lint -save -e407 */
  88. /**
  89. * @brief Events passed to user event handler.
  90. *
  91. * @note Example prototype of user event handler:
  92. *
  93. * void msc_user_ev_handler(app_usbd_class_inst_t const * p_inst,
  94. * app_usbd_msc_user_event_t event);
  95. */
  96. typedef enum app_usbd_msc_user_event_e {
  97. APP_USBD_MSC_USER_EVT_NONE, /**< Dummy event to satisfy compilers. */
  98. } app_usbd_msc_user_event_t;
  99. /*lint -restore*/
  100. /**
  101. * @brief Helper macro for defining MSC endpoints.
  102. *
  103. * @param in_number Input endpoint number.
  104. * @param out_number Output endpoint number.
  105. * */
  106. #define APP_USBD_MSC_ENDPOINT_LIST(in_number, out_number) ( \
  107. CONCAT_2(NRF_DRV_USBD_EPIN, in_number), \
  108. CONCAT_2(NRF_DRV_USBD_EPOUT, out_number) \
  109. )
  110. /**
  111. * @brief Global definition of app_usbd_msc_t class.
  112. *
  113. * @param instance_name Name of global instance.
  114. * @param interface_number Unique interface number.
  115. * @param user_ev_handler User event handler (optional).
  116. * @param endpoint_list Input endpoint list (@ref nrf_drv_usbd_ep_t).
  117. * @param blockdev_list Block device list.
  118. * @param workbuffer_size Work buffer size (need to fit into all block devices from
  119. * block device list).
  120. *
  121. * @note This macro is just simplified version of @ref APP_USBD_MSC_GLOBAL_DEF_INTERNAL
  122. *
  123. */
  124. #define APP_USBD_MSC_GLOBAL_DEF(instance_name, \
  125. interface_number, \
  126. user_ev_handler, \
  127. endpoint_list, \
  128. blockdev_list, \
  129. workbuffer_size) \
  130. APP_USBD_MSC_GLOBAL_DEF_INTERNAL(instance_name, \
  131. interface_number, \
  132. user_ev_handler, \
  133. endpoint_list, \
  134. blockdev_list, \
  135. workbuffer_size)
  136. /**
  137. * @@brief Helper function to get class instance from MSC.
  138. *
  139. * @param[in] p_msc MSC instance (declared by @ref APP_USBD_MSC_GLOBAL_DEF).
  140. *
  141. * @return Base class instance.
  142. */
  143. static inline app_usbd_class_inst_t const *
  144. app_usbd_msc_class_inst_get(app_usbd_msc_t const * p_msc)
  145. {
  146. return &p_msc->base;
  147. }
  148. /**
  149. * @brief Helper function to get MSC from base class instance.
  150. *
  151. * @param[in] p_inst Base class instance.
  152. *
  153. * @return MSC class handle.
  154. */
  155. static inline app_usbd_msc_t const * app_usbd_msc_class_get(app_usbd_class_inst_t const * p_inst)
  156. {
  157. return (app_usbd_msc_t const *)p_inst;
  158. }
  159. /**
  160. * @brief Synchronization of all block devices pined to MSC.
  161. *
  162. * @param[in] p_msc MSC instance (declared by @ref APP_USBD_MSC_GLOBAL_DEF).
  163. *
  164. * @retval true All block devices flushed data.
  165. * @retval false At least one block device has not flushed data.
  166. */
  167. bool app_usbd_msc_sync(app_usbd_msc_t const * p_msc);
  168. /** @} */
  169. #ifdef __cplusplus
  170. }
  171. #endif
  172. #endif /* APP_USBD_MSC_H__ */