ser_phy.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308
  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_phy Serialization PHY
  43. * @{
  44. * @ingroup ble_sdk_lib_serialization
  45. *
  46. * @brief PHY layer for serialization.
  47. *
  48. * @details The @ref ser_phy library declares functions and definitions of data structures and
  49. * identifiers (typedef enum) that are used as API of the serialization PHY layer.
  50. *
  51. * \par Rationale
  52. * Each specific PHY layer (SPI, I2C, UART, low power UART etc.) should provide the same API. This
  53. * allows the layer above (the HAL Transport layer), which is responsible for controlling the PHY
  54. * layer, memory management, CRC, retransmission etc., to be hardware independent.
  55. *
  56. *
  57. * \par Interlayer communication and control
  58. * The PHY layer is controlled by the HAL transport layer by calling functions declared in
  59. * the @ref ser_phy library.
  60. *
  61. * @par
  62. * The PHY layer communicates events to the HAL transport layer by calling a callback function.
  63. * A handler to this function is passed in the @ref ser_phy_open function. This callback function
  64. * should be called with a parameter of type @ref ser_phy_evt_t, filled accordingly to an event to be
  65. * passed. Types of supported events are defined in @ref ser_phy_evt_type_t.
  66. *
  67. * @par
  68. * For example, to pass an event indicating that an RX packet has been successfully received, first a
  69. * struct of type @ref ser_phy_evt_t must be filled:
  70. * @code
  71. * ser_phy_evt_t phy_evt;
  72. * phy_evt.evt_type = SER_PHY_EVT_RX_PKT_RECEIVED;
  73. * phy_evt.evt_params.rx_pkt_received.p_buffer = (pointer to the RX buffer);
  74. * phy_evt.evt_params.rx_pkt_received.num_of_bytes = (number of received bytes);
  75. * @endcode
  76. * Then, the callback function must be called:
  77. * @code
  78. * events_handler(phy_evt);
  79. * @endcode
  80. * All functions declared in the @ref ser_phy file (ser_phy.h) must be implemented. Some events specified in
  81. * @ref ser_phy_evt_type_t are optional to implement.
  82. *
  83. * \par Transmitting a packet
  84. * Each PHY layer is responsible for adding the PHY header to a packet to be sent. This header
  85. * consists of a 16-bit field that carries the packet length (the uint16_encode function defined in
  86. * app_util.h should be used to ensure endianness independence). A pointer to a packet to be sent
  87. * and length of the packet are parameters of the @ref ser_phy_tx_pkt_send function. When a packet
  88. * has been transmitted, an event of type @ref SER_PHY_EVT_TX_PKT_SENT should be emitted.
  89. *
  90. * \image html ser_phy_transport_tx.svg "TX - interlayer communication"
  91. *
  92. * \par Receiving a packet
  93. * The PHY layer should be able to store only the PHY header (16-bit field carrying the packet
  94. * length). After the PHY header has been received, the transmission is stopped and the PHY
  95. * layer must send a request to the HAL transport layer for memory to store the packet - an event
  96. * of type @ref SER_PHY_EVT_RX_BUF_REQUEST with event parameters defined in
  97. * @ref ser_phy_evt_rx_buf_request_params_t (the uint16_decode function defined in app_util.h should
  98. * be used for header decoding to ensure endianness independence). The transmission should be
  99. * resumed when the @ref ser_phy_rx_buf_set function has been called.
  100. *
  101. * @par
  102. * When the @ref ser_phy_rx_buf_set function parameter equals NULL, there is not
  103. * enough memory to store the packet. However, the packet will be received to a dummy location to
  104. * ensure continuous communication. After receiving has finished, an event of type
  105. * @ref SER_PHY_EVT_RX_PKT_DROPPED is generated.
  106. *
  107. * \image html ser_phy_transport_rx_dropped.svg "RX dropping - interlayer communication"
  108. *
  109. * @par
  110. * When the @ref ser_phy_rx_buf_set function parameter is different than NULL, the packet is
  111. * received to a buffer pointed to by it. After receiving has finished, an event of type
  112. * @ref SER_PHY_EVT_RX_PKT_RECEIVED is generated with event parameters defined in
  113. * @ref ser_phy_evt_rx_pkt_received_params_t.
  114. *
  115. * \image html ser_phy_transport_rx_received.svg "RX - interlayer communication"
  116. *
  117. * \par PHY layer errors
  118. * PHY layer errors can be signaled by an event of type @ref SER_PHY_EVT_RX_OVERFLOW_ERROR or
  119. * @ref SER_PHY_EVT_TX_OVERREAD_ERROR or @ref SER_PHY_EVT_HW_ERROR with event parameters defined in
  120. * @ref ser_phy_evt_hw_error_params_t.
  121. *
  122. * @par Available PHY layers
  123. * The following PHY layers are available:
  124. * - @ref ser_phy_spi_page
  125. * - @ref ser_phy_spi_5W_page
  126. * - @ref ser_phy_uart_page
  127. * - @ref ser_phy_uart_hci_page
  128. * <!-- - @ref ser_phy_usb_hci_page -->
  129. *
  130. */
  131. #ifndef SER_PHY_H__
  132. #define SER_PHY_H__
  133. #include <stdint.h>
  134. #ifdef __cplusplus
  135. extern "C" {
  136. #endif
  137. /**@brief Serialization PHY module event types. */
  138. typedef enum
  139. {
  140. SER_PHY_EVT_TX_PKT_SENT = 0, /**< Obligatory to implement. An event indicating that a TX packet
  141. * has been transmitted. */
  142. SER_PHY_EVT_RX_BUF_REQUEST, /**< Obligatory to implement. An event indicating that the PHY layer
  143. * needs a buffer for an RX packet. The PHY flow should be blocked
  144. * until the @ref ser_phy_rx_buf_set function is called. */
  145. SER_PHY_EVT_RX_PKT_RECEIVED, /**< Obligatory to implement. An event indicating that an RX packet
  146. * has been successfully received. */
  147. SER_PHY_EVT_RX_PKT_DROPPED, /**< Obligatory to implement. An event indicating that the RX packet
  148. * receiving has been finished but the packet was discarded because
  149. * it was longer than available the buffer. */
  150. SER_PHY_EVT_RX_OVERFLOW_ERROR, /**< Optional to implement. An event indicating that more
  151. * information has been transmitted than the PHY module could
  152. * handle. */
  153. SER_PHY_EVT_TX_OVERREAD_ERROR, /**< Optional to implement. An event indicating that the PHY module
  154. * was forced to transmit more information than possessed. */
  155. SER_PHY_EVT_HW_ERROR, /**< Optional to implement. An event indicating a hardware error
  156. * in the PHY module. */
  157. SER_PHY_EVT_TYPE_MAX /**< Enumeration upper bound. */
  158. } ser_phy_evt_type_t;
  159. /**@brief A struct containing parameters of event of type @ref SER_PHY_EVT_RX_BUF_REQUEST. */
  160. typedef struct
  161. {
  162. uint16_t num_of_bytes; /**< Length of a buffer in octets that the layer above the PHY module should
  163. * deliver, so that the PHY module can receive a packet. */
  164. } ser_phy_evt_rx_buf_request_params_t;
  165. /**@brief A struct containing parameters of event of type @ref SER_PHY_EVT_RX_PKT_RECEIVED. */
  166. typedef struct
  167. {
  168. uint8_t * p_buffer; /**< Pointer to a buffer containing the received packet. */
  169. uint16_t num_of_bytes; /**< Length of the received packet in octets. */
  170. } ser_phy_evt_rx_pkt_received_params_t;
  171. /**@brief A struct containing parameters of event of type @ref SER_PHY_EVT_HW_ERROR. */
  172. typedef struct
  173. {
  174. uint32_t error_code; /**< Hardware error code - specific for a microcontroller. */
  175. uint8_t * p_buffer; /**< Pointer to the buffer that was processed when error occured. */
  176. } ser_phy_evt_hw_error_params_t;
  177. /**@brief A struct containing events from a Serialization PHY module.
  178. *
  179. * @note Some events do not have parameters, then whole information is contained in the evt_type.
  180. */
  181. typedef struct
  182. {
  183. ser_phy_evt_type_t evt_type; /**< Type of event. */
  184. union /**< Union alternative identified by evt_type in enclosing struct. */
  185. {
  186. /** Parameters of event of type @ref SER_PHY_EVT_RX_BUF_REQUEST. */
  187. ser_phy_evt_rx_buf_request_params_t rx_buf_request;
  188. /** Parameters of event of type @ref SER_PHY_EVT_RX_PKT_RECEIVED. */
  189. ser_phy_evt_rx_pkt_received_params_t rx_pkt_received;
  190. /** Parameters of the event of type @ref SER_PHY_EVT_HW_ERROR. */
  191. ser_phy_evt_hw_error_params_t hw_error;
  192. } evt_params;
  193. } ser_phy_evt_t;
  194. /**@brief A type of generic callback function handler to be used by all PHY module events.
  195. *
  196. * @param[in] event Serialization PHY module event.
  197. */
  198. typedef void (*ser_phy_events_handler_t)(ser_phy_evt_t event);
  199. /**@brief Function for opening and initializing the PHY module.
  200. *
  201. * @note The function initializes hardware and internal module states, and registers callback
  202. * function to be used by all PHY module events.
  203. *
  204. * @warning If the function has been already called, the function @ref ser_phy_close has to be
  205. * called before ser_phy_open can be called again.
  206. *
  207. * @param[in] events_handler Generic callback function handler to be used by all PHY module
  208. * events.
  209. *
  210. * @retval NRF_SUCCESS Operation success.
  211. * @retval NRF_ERROR_INVALID_STATE Operation failure. The function has been already called.
  212. * To call it again, the function @ref ser_phy_close has to be
  213. * called first.
  214. * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
  215. * @retval NRF_ERROR_INVALID_PARAM Operation failure. Hardware initialization parameters are not
  216. * supported.
  217. */
  218. uint32_t ser_phy_open(ser_phy_events_handler_t events_handler);
  219. /**@brief Function for transmitting a packet.
  220. *
  221. * @note The function adds a packet pointed by p_buffer parameter to a transmission queue and
  222. * schedules generation of an event of type @ref SER_PHY_EVT_TX_PKT_SENT upon transmission
  223. * completion.
  224. *
  225. * @param[in] p_buffer Pointer to a buffer to transmit.
  226. * @param[in] num_of_bytes Number of octets to transmit. Must be more than 0.
  227. *
  228. * @retval NRF_SUCCESS Operation success. Packet was added to the transmission queue
  229. * and event will be send upon transmission completion.
  230. * @retval NRF_ERROR_NULL Operation failure. NULL pointer supplied.
  231. * @retval NRF_ERROR_INVALID_PARAM Operation failure. The num_of_bytes parameter equal to 0.
  232. * @retval NRF_ERROR_BUSY Operation failure. Transmitting of a packet in progress.
  233. */
  234. uint32_t ser_phy_tx_pkt_send(const uint8_t * p_buffer, uint16_t num_of_bytes);
  235. /**@brief Function for setting an RX buffer and enabling reception of data (the PHY flow).
  236. *
  237. * @note The function has to be called as a response to an event of type
  238. * @ref SER_PHY_EVT_RX_BUF_REQUEST. The function sets an RX buffer and enables reception of
  239. * data (enables the PHY flow).
  240. * Size of a buffer pointed by the p_buffer parameter should be at least equal to the
  241. * num_of_bytes parameter passed within the event (@ref ser_phy_evt_rx_buf_request_params_t),
  242. * or p_buffer should be equal to NULL if there is not enough memory.
  243. * When p_buffer is different from NULL and num_of_bytes octets have been received, an event of
  244. * type @ref SER_PHY_EVT_RX_PKT_RECEIVED is generated
  245. * (@ref ser_phy_evt_rx_pkt_received_params_t).
  246. * When p_buffer is equal to NULL, data is received to dummy location to ensure continuous
  247. * communication. Then, if num_of_bytes octets have been received, an event of type
  248. * @ref SER_PHY_EVT_RX_PKT_DROPPED is generated.
  249. *
  250. * @param[in] p_buffer Pointer to an RX buffer in which to receive.
  251. *
  252. * @retval NRF_SUCCESS Operation success.
  253. * @retval NRF_ERROR_INVALID_STATE Operation failure. A buffer was set without request.
  254. */
  255. uint32_t ser_phy_rx_buf_set(uint8_t * p_buffer);
  256. /**@brief Function for closing the PHY module.
  257. *
  258. * @note The function disables hardware, resets internal module states, and unregisters the events
  259. * callback function.
  260. */
  261. void ser_phy_close(void);
  262. /**@brief Function for enabling the PHY module interrupts.
  263. *
  264. * @note The function enables all interrupts that are used by the PHY module (and only those).
  265. */
  266. void ser_phy_interrupts_enable(void);
  267. /**@brief Function for disabling the PHY module interrupts.
  268. *
  269. * @note The function disables all interrupts that are used by the PHY module (and only those).
  270. */
  271. void ser_phy_interrupts_disable(void);
  272. #ifdef __cplusplus
  273. }
  274. #endif
  275. #endif /* SER_PHY_H__ */
  276. /** @} */