ser_hal_transport.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268
  1. /**
  2. * Copyright (c) 2014 - 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. /** @file
  41. *
  42. * @defgroup ser_hal_transport Serialization HAL Transport
  43. * @{
  44. * @ingroup ble_sdk_lib_serialization
  45. *
  46. * @brief HAL Transport layer for serialization.
  47. *
  48. * @details The @ref ser_hal_transport declares functions and typedefs used as API of the HAL
  49. * transport layer for serialization. This layer is fully hardware-independent.
  50. * Currently, the HAL transport layer is responsible for controlling the PHY layer and
  51. * memory management. In the future, more features might be added to it, such as CRC
  52. * or retransmission.
  53. *
  54. * \n \n
  55. * \image html ser_hal_transport_rx_state_machine.svg "RX state machine"
  56. * \n \n
  57. * \image html ser_hal_transport_tx_state_machine.svg "TX state machine"
  58. * \n
  59. */
  60. #ifndef SER_HAL_TRANSPORT_H__
  61. #define SER_HAL_TRANSPORT_H__
  62. #include <stdint.h>
  63. #ifdef __cplusplus
  64. extern "C" {
  65. #endif
  66. /**@brief Serialization HAL Transport layer event types. */
  67. typedef enum
  68. {
  69. SER_HAL_TRANSP_EVT_TX_PKT_SENT = 0, /**< An event indicating that TX packet has been
  70. transmitted. */
  71. SER_HAL_TRANSP_EVT_RX_PKT_RECEIVING, /**< An event indicating that RX packet is being
  72. scheduled to receive or to drop. */
  73. SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED, /**< An event indicating that RX packet is ready for
  74. read. */
  75. SER_HAL_TRANSP_EVT_RX_PKT_DROPPED, /**< An event indicating that RX packet was dropped
  76. because it was longer than available buffer. */
  77. SER_HAL_TRANSP_EVT_PHY_ERROR, /**< An event indicating error on PHY layer. */
  78. SER_HAL_TRANSP_EVT_TYPE_MAX /**< Enumeration upper bound. */
  79. } ser_hal_transport_evt_type_t;
  80. /**@brief Serialization PHY layer error types. */
  81. typedef enum
  82. {
  83. SER_HAL_TRANSP_PHY_ERROR_RX_OVERFLOW = 0, /**< An error indicating that more information has
  84. been transmitted than the PHY module could handle. */
  85. SER_HAL_TRANSP_PHY_ERROR_TX_OVERREAD, /**< An error indicating that the PHY module was forced to
  86. transmit more information than possessed. */
  87. SER_HAL_TRANSP_PHY_ERROR_HW_ERROR, /**< An error indicating a hardware error in the PHY
  88. module. */
  89. SER_HAL_TRANSP_PHY_ERROR_TYPE_MAX /**< Enumeration upper bound. */
  90. } ser_hal_transport_phy_error_type_t;
  91. /**@brief Struct containing parameters of event of type
  92. * @ref SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED.
  93. */
  94. typedef struct
  95. {
  96. uint8_t * p_buffer; /**< Pointer to a buffer containing a packet to read. */
  97. uint16_t num_of_bytes; /**< Length of a received packet in octets. */
  98. } ser_hal_transport_evt_rx_pkt_received_params_t;
  99. /**@brief Struct containing parameters of event of type @ref SER_HAL_TRANSP_EVT_PHY_ERROR. */
  100. typedef struct
  101. {
  102. ser_hal_transport_phy_error_type_t error_type; /**< Type of the PHY error. */
  103. uint32_t hw_error_code; /**< Hardware error code - specific for a microcontroller. Parameter
  104. is valid only for the PHY error of type
  105. @ref SER_HAL_TRANSP_PHY_ERROR_HW_ERROR. */
  106. } ser_hal_transport_evt_phy_error_params_t;
  107. /**@brief Struct containing events from the Serialization HAL Transport layer.
  108. *
  109. * @note Some events do not have parameters, then the whole information is contained in the evt_type.
  110. */
  111. typedef struct
  112. {
  113. ser_hal_transport_evt_type_t evt_type; /**< Type of event. */
  114. union /**< Union alternative identified by evt_type in the enclosing struct. */
  115. {
  116. ser_hal_transport_evt_rx_pkt_received_params_t rx_pkt_received; /**< Parameters of event of type @ref SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED. */
  117. ser_hal_transport_evt_phy_error_params_t phy_error; /**< Parameters of event of type @ref SER_HAL_TRANSP_EVT_PHY_ERROR. */
  118. } evt_params;
  119. } ser_hal_transport_evt_t;
  120. /**@brief Generic callback function type to be used by all Serialization HAL Transport layer
  121. * events.
  122. *
  123. * @param[in] event Serialization HAL Transport layer event.
  124. */
  125. typedef void (*ser_hal_transport_events_handler_t)(ser_hal_transport_evt_t event);
  126. /**@brief Function for opening and initializing the Serialization HAL Transport layer.
  127. *
  128. * @note The function opens the transport channel, initializes a PHY layer, and registers the callback
  129. * function to be used by all Serialization HAL Transport layer events.
  130. *
  131. * @warning If the function has been already called, the function @ref ser_hal_transport_close has
  132. * to be called before ser_hal_transport_open can be called again.
  133. *
  134. * @param[in] events_handler Generic callback function to be used by all Serialization HAL
  135. * Transport layer events.
  136. *
  137. * @retval NRF_SUCCESS Operation success.
  138. * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
  139. * @retval NRF_ERROR_INVALID_PARAM Operation failure. Hardware initialization parameters taken from
  140. * the configuration file are wrong.
  141. * @retval NRF_ERROR_INVALID_STATE Operation failure. The function has been already called. To call
  142. * it again the function @ref ser_hal_transport_close has to be
  143. * called first.
  144. * @retval NRF_ERROR_INTERNAL Operation failure. Internal error ocurred.
  145. */
  146. uint32_t ser_hal_transport_open(ser_hal_transport_events_handler_t events_handler);
  147. /**@brief Function for reseting ser_hal_transport. */
  148. void ser_hal_transport_reset(void);
  149. /**@brief Function for closing a transport channel.
  150. *
  151. * @note The function disables the hardware, resets internal module states, and unregisters the events
  152. * callback function. Can be called multiple times, also for a channel that is not opened.
  153. */
  154. void ser_hal_transport_close(void);
  155. /**@brief Function for freeing memory allocated for an RX packet.
  156. *
  157. * @note The function should be called as a response to an event of type
  158. * @ref SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED when the received data has beed processed. The function
  159. * frees the RX memory pointed by p_buffer. The memory, immediately or at a later time, is
  160. * reused by the underlying transport layer.
  161. *
  162. * @param[in] p_buffer A pointer to the beginning of the buffer that has been processed (has to be
  163. * the same address as provided in the event of type
  164. * @ref SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED).
  165. *
  166. * @retval NRF_SUCCESS Operation success.
  167. * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
  168. * @retval NRF_ERROR_INVALID_ADDR Operation failure. Not a valid pointer (provided address is not
  169. * the starting address of a buffer managed by HAL Transport layer).
  170. * @retval NRF_ERROR_INVALID_STATE Operation failure. The function should be called as a response
  171. * to an event of type @ref SER_HAL_TRANSP_EVT_RX_PKT_RECEIVED.
  172. * @retval NRF_ERROR_INTERNAL Operation failure. Internal error ocurred.
  173. */
  174. uint32_t ser_hal_transport_rx_pkt_free(uint8_t * p_buffer);
  175. /**@brief Function for allocating memory for a TX packet.
  176. *
  177. * @param[out] pp_memory A pointer to pointer to which an address of the beginning of the
  178. * allocated buffer is written.
  179. * @param[out] p_num_of_bytes A pointer to a variable to which size in octets of the allocated
  180. * buffer is written.
  181. *
  182. * @retval NRF_SUCCESS Operation success. Memory was allocated.
  183. * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
  184. * @retval NRF_ERROR_NO_MEM Operation failure. No memory available.
  185. * @retval NRF_ERROR_INVALID_STATE Operation failure. The function was called before calling
  186. * @ref ser_hal_transport_open function.
  187. */
  188. uint32_t ser_hal_transport_tx_pkt_alloc(uint8_t ** pp_memory, uint16_t * p_num_of_bytes);
  189. /**@brief Function for transmitting a packet.
  190. *
  191. * @note The function adds a packet pointed by the p_buffer parameter to a transmission queue. A buffer
  192. * provided to this function must be allocated by the @ref ser_hal_transport_tx_pkt_alloc function.
  193. *
  194. * @warning Completion of this method does not guarantee that actual peripheral transmission will be completed.
  195. *
  196. * @param[in] p_buffer Pointer to the buffer to transmit.
  197. * @param[in] num_of_bytes Number of octets to transmit. Must be more than 0.
  198. *
  199. * @retval NRF_SUCCESS Operation success. Packet was added to the transmission queue.
  200. * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
  201. * @retval NRF_ERROR_INVALID_PARAM Operation failure. num_of_bytes is equal to 0.
  202. * @retval NRF_ERROR_INVALID_ADDR Operation failure. Not a valid pointer (provided address is not
  203. * the starting address of a buffer managed by HAL Transport layer).
  204. * @retval NRF_ERROR_DATA_SIZE Operation failure. Packet size exceeds limit.
  205. * @retval NRF_ERROR_BUSY Operation failure. Transmission queue is full so packet was not
  206. * added to the transmission queue.
  207. * @retval NRF_ERROR_INVALID_STATE Operation failure. Transmittion channel was not opened by
  208. * @ref ser_hal_transport_open function or provided buffer was not
  209. * allocated by @ref ser_hal_transport_tx_pkt_alloc function.
  210. * @retval NRF_ERROR_INTERNAL Operation failure. Internal error ocurred.
  211. */
  212. uint32_t ser_hal_transport_tx_pkt_send(const uint8_t * p_buffer, uint16_t num_of_bytes);
  213. /**@brief Function for freeing memory allocated for a TX packet.
  214. *
  215. * @note The function frees the TX memory pointed by p_buffer. Freeing a TX buffer is possible only if
  216. * the buffer was allocated by @ref ser_hal_transport_tx_pkt_alloc function and transmittion
  217. * is not in progress. When transmittion has finished, this function is automatically called by
  218. * the Serialization HAL Transport layer, so the only case when this function should be used
  219. * from outside is when a TX buffer was allocated but a transmittion has not been started
  220. * (@ref ser_hal_transport_tx_pkt_send function has not been called).
  221. *
  222. * @param[in] p_buffer Pointer to the beginning of a buffer that has been allocated by
  223. * @ref ser_hal_transport_tx_pkt_alloc function.
  224. *
  225. * @retval NRF_SUCCESS Operation success. Memory was freed.
  226. * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
  227. * @retval NRF_ERROR_INVALID_ADDR Operation failure. Not a valid pointer (provided address is not
  228. * the starting address of a buffer managed by HAL Transport layer).
  229. * @retval NRF_ERROR_INVALID_STATE Operation failure. Freeing a TX buffer is possible only if the
  230. * buffer was allocated by @ref ser_hal_transport_tx_pkt_alloc
  231. * function and transmittion is not in progress.
  232. */
  233. uint32_t ser_hal_transport_tx_pkt_free(uint8_t * p_buffer);
  234. #ifdef __cplusplus
  235. }
  236. #endif
  237. #endif /* SER_HAL_TRANSPORT_H__ */
  238. /** @} */