ral_api.h 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230
  1. /**
  2. * Copyright (c) 2016 - 2020 Nordic Semiconductor ASA and Luxoft Global Operations Gmbh.
  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. *
  10. * 1. Redistributions of source code must retain the above copyright notice, this
  11. * list of conditions and the following disclaimer.
  12. *
  13. * 2. Redistributions in binary form, except as embedded into a Nordic
  14. * Semiconductor ASA integrated circuit in a product or a software update for
  15. * such product, must reproduce the above copyright notice, this list of
  16. * conditions and the following disclaimer in the documentation and/or other
  17. * materials provided with the distribution.
  18. *
  19. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  20. * contributors may be used to endorse or promote products derived from this
  21. * software without specific prior written permission.
  22. *
  23. * 4. This software, with or without modification, must only be used with a
  24. * Nordic Semiconductor ASA integrated circuit.
  25. *
  26. * 5. Any software provided in binary form under this license must not be reverse
  27. * engineered, decompiled, modified and/or disassembled.
  28. *
  29. *
  30. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  31. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  32. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  33. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  34. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  35. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  36. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  37. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  38. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  39. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40. *
  41. */
  42. #ifndef RAL_API_H_INCLUDED
  43. #define RAL_API_H_INCLUDED
  44. #include "ral_api_spec.h"
  45. #include "sys_time.h"
  46. #include "phy_common.h"
  47. #include "phy_pd_data.h"
  48. #include "mac_common.h"
  49. #include "mac_mlme_pib.h"
  50. #include "mac_time.h"
  51. #include <stdint.h>
  52. #include <stdbool.h>
  53. /**@file ral_api.h
  54. *
  55. * @defgroup ral_api Radio Abstraction Layer common API
  56. * @ingroup ral_15_4
  57. * @{
  58. *
  59. * @brief Radio abstraction layer common interface.
  60. *
  61. * @details These are requirements for the implementation code:
  62. *
  63. * - no frames must be received between new frame indication and
  64. * a call to ral_data_ind_read.
  65. */
  66. // various constants to use with MAC/PHY header parsing
  67. #define PHR_POS 0
  68. #define PHR_SIZE 1
  69. #define CRC_SIZE 2
  70. #define MAC_FRAME_CTRL_POS 0
  71. #define MAC_FRAME_CTRL_SIZE 2
  72. #define ACK_REQUEST_MASK 0x20
  73. #define SEQ_NUM_POS (MAC_FRAME_CTRL_POS + MAC_FRAME_CTRL_SIZE)
  74. #define ACK_PD_BIT_MASK 0x0010
  75. #define FRAME_TYPE_MASK 0x0007
  76. #define FRAME_TYPE_BEACON 0x0000
  77. #define FRAME_TYPE_DATA 0x0001
  78. #define FRAME_TYPE_ACK 0x0002
  79. #define FRAME_TYPE_COMMAND 0x0003
  80. #define FRAME_PENDING_MASK 0x0010
  81. /**@brief RAL atomic section */
  82. typedef volatile uint8_t ral_atomic_t;
  83. // private RAL data
  84. typedef struct
  85. {
  86. volatile uint8_t tx_seq_num;
  87. volatile bool ack_needed;
  88. volatile bool waiting_for_ack;
  89. volatile ral_atomic_t ral_atomic;
  90. volatile mac_timestamp_t received_frame_timestamp;
  91. volatile bool spi_transfer;
  92. volatile bool cca_performing;
  93. #if defined(AT86RF231)
  94. volatile int8_t ed_value;
  95. volatile bool unread_frame; /** This flag is used to deny transmission if incoming frame
  96. has not been read from radio buffer.
  97. todo: remove this deny to accelerate data exchange.
  98. */
  99. volatile bool is_promiscuous_mode; /**< Set to true if promiscuous mode is enabled.*/
  100. #elif (defined(NRF52_SERIES) || defined(NRF52))
  101. // pointer to free memory for rx DMA
  102. volatile uint8_t * p_buffer;
  103. volatile sys_time_t calibr_value;
  104. volatile uint8_t bcc_part;
  105. #endif
  106. } ral_mem_t;
  107. /**@brief Initializes radio abstraction layer.
  108. */
  109. void ral_init(void);
  110. /**@brief Resets radio abstraction layer.
  111. */
  112. void ral_reset(void);
  113. /**@brief Performs synchronous ED measurement.
  114. */
  115. uint8_t ral_ed_perform(void);
  116. /**@brief Sends request to change radio state.
  117. *
  118. * @param state - New radio state. One of...
  119. *
  120. * @return PHY_SUCCESS, if state has been successfully achieved;
  121. * current state, if state cannot be reached.*/
  122. phy_enum_t ral_state_set(const phy_enum_t state);
  123. /**@brief Returns current state of radio.
  124. */
  125. phy_enum_t ral_state_get(void);
  126. /**@brief Puts radio into sleep mode
  127. */
  128. void ral_sleep(void);
  129. /**@brief Awakes a radio
  130. */
  131. void ral_wakeup(void);
  132. /**@brief Performs synchronous cca.
  133. */
  134. phy_status_t ral_cca_perform(void);
  135. /**@brief Sends PHY frame.
  136. *
  137. * @param[in] pd_data - full data frame to be send.
  138. *
  139. * @details RAL automatically adds header and FCS control bytes
  140. * to \a pd_data. Caller must reserve 1 byte before \a psdu
  141. * pointer and may leave last two bytes of payload (i.e. FCS
  142. * control field) uninitialized.
  143. *
  144. * RF chip or RAL code is responsible to receive an ACK frame.
  145. * After ACK is handled, device should be restored to the TX state.*/
  146. void ral_data_req(pd_data_req_t * pd_data);
  147. /**@brief Reads indication frame from radio.
  148. *
  149. * @retval Pointer on the structure of a PHY data indication
  150. * with received frame.
  151. */
  152. pd_data_ind_t * ral_data_ind_read(void);
  153. /**@brief Enable data flow from radio hardware after it was disabled
  154. * by ral_data_flow_disable().
  155. */
  156. void ral_data_flow_enable(void);
  157. /**@brief Disable data flow from radio hardware
  158. */
  159. void ral_data_flow_disable(void);
  160. /**@brief This function is used to set attribute from MAC or PHY layer
  161. * without checking of its boundaries.
  162. *
  163. * @param id - one of #MAC_SHORT_ADDRESS, #MAC_EXTENDED_ADDRESS, #MAC_PAN_ID
  164. * and some other values.
  165. * @param p_value - pointer to new value.
  166. */
  167. void ral_attribute_set(uint8_t id, const void * p_value);
  168. /**@brief This function is used to get a copy of attribute value stored inside
  169. * radio module.
  170. *
  171. * @param[in] id - one of #PHY_CURRENT_CHANNEL_ID, #PHY_TRANSMIT_POWER_ID or
  172. * #PHY_CCA_MODE_ID. Other attributes are not supported.
  173. * @param[out] p_attr_value - pointer to value to get.
  174. */
  175. void ral_attribute_get(uint8_t id, void * p_attr_value);
  176. /**@brief This function is used to define frame start time by it's size
  177. * and the timestamp, when RX IRQ has been received.
  178. *
  179. * @param irq_time - moment when IRQ has been received.
  180. * @param frame_size - size of received frame in bytes.
  181. *
  182. * @retval MAC timestamp when PHY header has been started to receive.
  183. */
  184. mac_timestamp_t ral_rx_start_time(mac_timestamp_t irq_time, uint8_t frame_size);
  185. /**@brief This function performs RSSI.
  186. *
  187. * @return RSSI sample value.
  188. */
  189. uint8_t ral_rssi_get(void);
  190. /**@brief This function calculates the adjusted RSSI value using a temperature
  191. * correction factor.
  192. *
  193. * @param[in] rssi - RSSI sample value (as returned by @ref ral_rssi_get).
  194. * @param[in] temp - Temperature value in °C.
  195. *
  196. * @return Temperature-corrected RSSI value.
  197. */
  198. uint8_t ral_rssi_corrected_get(uint8_t rssi, int8_t temp);
  199. /** @} */
  200. #endif /* RAL_API_H_INCLUDED */