1 /* 2 * Copyright (c) 2017, Nordic Semiconductor ASA 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions are met: 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 must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in the 15 * documentation and/or other materials provided with the distribution. 16 * 17 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its 18 * contributors may be used to endorse or promote products derived from this 19 * software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 * IMPLIED WARRANTIES OF MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE 24 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 25 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 26 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 27 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 30 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31 * POSSIBILITY OF SUCH DAMAGE. 32 * 33 */ 34 35 /** 36 * @brief Module that contains core of the nRF IEEE 802.15.4 radio driver. 37 * 38 */ 39 40 #ifndef NRF_802154_CORE_H_ 41 #define NRF_802154_CORE_H_ 42 43 #include <stdbool.h> 44 #include <stdint.h> 45 46 #include "nrf_802154_config.h" 47 #include "nrf_802154_notification.h" 48 #include "nrf_802154_rx_buffer.h" 49 #include "nrf_802154_types_internal.h" 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 /** 56 * @brief States of the nRF 802.15.4 driver. 57 */ 58 typedef enum 59 { 60 // Sleep 61 RADIO_STATE_SLEEP, ///< Low power mode (disabled) - the only state in which all radio preconditions are not requested. 62 RADIO_STATE_FALLING_ASLEEP, ///< Before entering the sleep state, all radio preconditions are requested. 63 64 // Receive 65 RADIO_STATE_RX, ///< The receiver is enabled and it is receiving frames. 66 RADIO_STATE_TX_ACK, ///< The frame is received and the ACK is being transmitted. 67 68 // Transmit 69 RADIO_STATE_CCA_TX, ///< Performing CCA followed by the frame transmission. 70 RADIO_STATE_TX, ///< Transmitting data frame (or beacon). 71 RADIO_STATE_RX_ACK, ///< Receiving ACK after the transmitted frame. 72 73 // Energy Detection 74 RADIO_STATE_ED, ///< Performing the energy detection procedure. 75 76 // CCA 77 RADIO_STATE_CCA, ///< Performing the CCA procedure. 78 79 #if NRF_802154_CARRIER_FUNCTIONS_ENABLED 80 // Continuous carrier 81 RADIO_STATE_CONTINUOUS_CARRIER, ///< Emitting the continuous carrier wave. 82 83 // Modulated carrier 84 RADIO_STATE_MODULATED_CARRIER ///< Emitting the modulated carrier signal. 85 #endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED 86 87 } radio_state_t; 88 89 /** 90 * @brief Initializes the 802.15.4 driver core. 91 */ 92 void nrf_802154_core_init(void); 93 94 /** 95 * @brief Deinitializes the 802.15.4 driver core. 96 */ 97 void nrf_802154_core_deinit(void); 98 99 /** 100 * @brief Gets the current state of the nRF 802.15.4 driver. 101 * 102 * @returns Current state of the 802.15.4 driver. 103 */ 104 radio_state_t nrf_802154_core_state_get(void); 105 106 /*************************************************************************************************** 107 * @section State machine transition requests 108 **************************************************************************************************/ 109 110 /** 111 * @brief Requests the transition to the @ref RADIO_STATE_SLEEP state. 112 * 113 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 114 * 115 * @retval true Entering the sleep state succeeded. 116 * @retval false Entering the sleep state failed (the driver is performing other procedure). 117 */ 118 bool nrf_802154_core_sleep(nrf_802154_term_t term_lvl); 119 120 /** 121 * @brief Requests the transition to the @ref RADIO_STATE_RX state. 122 * 123 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 124 * @param[in] req_orig Module that originates this request. 125 * @param[in] notify_function Function called to notify the status of this procedure. May be NULL. 126 * @param[in] notify_abort If abort notification is to be triggered. 127 * @param[in] id Identifier of reception window. 128 * 129 * @retval true Entering the receive state succeeded. 130 * @retval false Entering the receive state failed (the driver is performing other procedure). 131 */ 132 bool nrf_802154_core_receive(nrf_802154_term_t term_lvl, 133 req_originator_t req_orig, 134 nrf_802154_notification_func_t notify_function, 135 bool notify_abort, 136 uint32_t id); 137 138 /** 139 * @brief Requests the transition to the @ref RADIO_STATE_TX state. 140 * 141 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 142 * @param[in] req_orig Module that originates this request. 143 * @param[in] p_data Pointer to a frame to transmit. 144 * @param[in] p_params Pointer to transmission parameters. 145 * @param[in] notify_function Function called to notify the status of this procedure. May be NULL. 146 * 147 * @retval true Entering the transmit state succeeded. 148 * @retval false Entering the transmit state failed (the driver is performing other procedure). 149 */ 150 bool nrf_802154_core_transmit(nrf_802154_term_t term_lvl, 151 req_originator_t req_orig, 152 uint8_t * p_data, 153 nrf_802154_transmit_params_t * p_params, 154 nrf_802154_notification_func_t notify_function); 155 156 /** 157 * @brief Requests end of waiting for an ACK by the core. 158 * 159 * @param[in] p_param Pointer to the notification parameters; 160 * 161 * @return true Request handled. 162 * @return false Request rejected due to already occupied critical section. 163 */ 164 bool nrf_802154_core_ack_timeout_handle(const nrf_802154_ack_timeout_handle_params_t * p_param); 165 166 /** 167 * @brief Requests the transition to the @ref RADIO_STATE_ED state. 168 * 169 * When the energy detection procedure is finished, the driver transitions 170 * to the @ref RADIO_STATE_RX state. 171 * 172 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 173 * @param[in] time_us Minimal time of energy detection procedure. 174 * 175 * @retval true Entering the energy detection state succeeded. 176 * @retval false Entering the energy detection state failed 177 * (the driver is performing other procedure). 178 */ 179 bool nrf_802154_core_energy_detection(nrf_802154_term_t term_lvl, uint32_t time_us); 180 181 /** 182 * @brief Requests the transition to the @ref RADIO_STATE_CCA state. 183 * 184 * When the CCA procedure is finished, the driver transitions to the @ref RADIO_STATE_RX state. 185 * 186 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 187 * 188 * @retval true Entering the CCA state succeeded. 189 * @retval false Entering the CCA state failed (the driver is performing other procedure). 190 */ 191 bool nrf_802154_core_cca(nrf_802154_term_t term_lvl); 192 193 #if NRF_802154_CARRIER_FUNCTIONS_ENABLED 194 195 /** 196 * @brief Requests the transition to the @ref RADIO_STATE_CONTINUOUS_CARRIER state. 197 * 198 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 199 * 200 * @retval true Entering the continuous carrier state succeeded. 201 * @retval false Entering the continuous carrier state failed 202 * (the driver is performing other procedure). 203 */ 204 bool nrf_802154_core_continuous_carrier(nrf_802154_term_t term_lvl); 205 206 /** 207 * @brief Requests the transition to the @ref RADIO_STATE_MODULATED_CARRIER state. 208 * 209 * @param[in] term_lvl Termination level of this request. Selects procedures to abort. 210 * @param[in] p_data Data buffer to modulate the carrier with. 211 * 212 * @retval true Entering the modulated carrier state succeeded. 213 * @retval false Entering the modulated carrier state failed 214 * (the driver is performing other procedure). 215 */ 216 bool nrf_802154_core_modulated_carrier(nrf_802154_term_t term_lvl, 217 const uint8_t * p_data); 218 219 #endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED 220 221 /*************************************************************************************************** 222 * @section State machine notifications 223 **************************************************************************************************/ 224 225 /** 226 * @brief Notifies the core module that a higher layer freed a frame buffer. 227 * 228 * When there are no free buffers available, the core does not start the receiver. 229 * If the core receives this notification, it changes the internal state to make sure 230 * the receiver is started if requested. 231 * 232 * @param[in] p_data Pointer to buffer that has been freed. 233 */ 234 bool nrf_802154_core_notify_buffer_free(uint8_t * p_data); 235 236 /** 237 * @brief Notifies the core module that the next higher layer requested the change of the channel. 238 * 239 * The core is expected to update the frequency register of the peripheral and, if it is 240 * in the @c RADIO_STATE_RX, in the @c RADIO_STATE_CONTINUOUS_CARRIER 241 * or in the @c RADIO_STATE_MODULATED_CARRIER state, the transceiver is disabled 242 * and enabled again to use the new channel. 243 * 244 * @param[in] req_orig Module that originates this request. 245 */ 246 bool nrf_802154_core_channel_update(req_originator_t req_orig); 247 248 /** 249 * @brief Notifies the core module that the next higher layer requested the change 250 * of the CCA configuration. 251 */ 252 bool nrf_802154_core_cca_cfg_update(void); 253 254 /** 255 * @brief Notifies the core module that the next higher layer requested the RSSI measurement. 256 */ 257 bool nrf_802154_core_rssi_measure(void); 258 259 /** 260 * @brief Gets the last RSSI measurement. 261 * 262 * @param[out] p_rssi RSSI measurement value in dBm. 263 */ 264 bool nrf_802154_core_last_rssi_measurement_get(int8_t * p_rssi); 265 266 /** 267 * Get RSSI of the last received non-ACK frame. 268 * 269 * Returns 0 if no frame was received yet. 270 * 271 * @returns Temperature-corrected RSSI of the last received frame 272 */ 273 int8_t nrf_802154_core_last_frame_rssi_get(void); 274 275 /** 276 * Get LQI of the last received non-ACK frame. 277 * 278 * Returns 0 if no frame was received yet. 279 * 280 * @returns Temperature-corrected LQI of the last received frame 281 */ 282 uint8_t nrf_802154_core_last_frame_lqi_get(void); 283 284 /** 285 * @brief Notifies the core module that the next higher layer requested the change of the antenna. 286 */ 287 bool nrf_802154_core_antenna_update(void); 288 289 #if !NRF_802154_INTERNAL_IRQ_HANDLING 290 /** 291 * @brief Notifies the core module that there is a pending IRQ to be handled. 292 */ 293 void nrf_802154_core_irq_handler(void); 294 #endif // !NRF_802154_INTERNAL_IRQ_HANDLING 295 296 #ifdef __cplusplus 297 } 298 #endif 299 300 #endif /* NRF_802154_CORE_H_ */ 301
