1 /* 2 * Copyright (c) 2019, 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 radio hardware-related functions 37 * of the nRF IEEE 802.15.4 radio driver. 38 * 39 * @details 40 */ 41 42 #ifndef NRF_802154_TRX_H_ 43 #define NRF_802154_TRX_H_ 44 45 #include <stdbool.h> 46 #include <stdint.h> 47 48 #include "nrf_802154_config.h" 49 #include "nrf_802154_sl_types.h" 50 #include "nrf_802154_types_internal.h" 51 52 #ifdef __cplusplus 53 extern "C" { 54 #endif 55 56 /**@brief States of the FSM of the TRX module. */ 57 typedef enum 58 { 59 TRX_STATE_DISABLED = 0, 60 TRX_STATE_IDLE, 61 TRX_STATE_GOING_IDLE, 62 TRX_STATE_RXFRAME, 63 64 /* PPIS disabled deconfigured 65 * RADIO is DISABLED, RXDISABLE 66 * RADIO shorts are 0 67 * TIMER is running 68 * FEM is going to powered or is powered depending if RADIO reached DISABLED 69 */ 70 TRX_STATE_RXFRAME_FINISHED, 71 72 TRX_STATE_RXACK, 73 TRX_STATE_TXFRAME, 74 TRX_STATE_TXACK, 75 TRX_STATE_STANDALONE_CCA, 76 TRX_STATE_CONTINUOUS_CARRIER, 77 TRX_STATE_MODULATED_CARRIER, 78 TRX_STATE_ENERGY_DETECTION, 79 80 /* PPIS disabled deconfigured 81 * RADIO is DISABLED, TXDISABLE, RXDISABLE 82 * RADIO shorts are 0 83 * TIMER is stopped 84 * FEM is going to powered or is powered depending if RADIO reached DISABLED 85 */ 86 TRX_STATE_FINISHED 87 } trx_state_t; 88 89 /**@brief Radio ramp up procedure triggering modes. */ 90 typedef enum 91 { 92 TRX_RAMP_UP_SW_TRIGGER, ///< Triggering by RADIO_DISABLED, which is a software generated event. 93 TRX_RAMP_UP_HW_TRIGGER ///< Triggering by some other event that needs to publish to a dedicated (D)PPI channel. 94 } nrf_802154_trx_ramp_up_trigger_mode_t; 95 96 /**@brief Notifications that can be enabled for @ref nrf_802154_trx_receive_frame operation. */ 97 typedef enum 98 { 99 /**@brief No notifications during frame receive provided. */ 100 TRX_RECEIVE_NOTIFICATION_NONE = 0U, 101 102 /**@brief Notification @ref nrf_802154_trx_receive_frame_prestarted enabled. */ 103 TRX_RECEIVE_NOTIFICATION_PRESTARTED = (1U << 0), 104 105 /**@brief Notification @ref nrf_802154_trx_receive_frame_started enabled. */ 106 TRX_RECEIVE_NOTIFICATION_STARTED = (1U << 1), 107 } nrf_802154_trx_receive_notifications_t; 108 109 /**@brief Notifications that can be enabled for @ref nrf_802154_trx_transmit_frame operation. */ 110 typedef enum 111 { 112 /**@brief No notifications during frame transmission provided. */ 113 TRX_TRANSMIT_NOTIFICATION_NONE = 0U, 114 115 /**@brief Notification @ref nrf_802154_trx_transmit_frame_ccaidle */ 116 TRX_TRANSMIT_NOTIFICATION_CCAIDLE = (1U << 1), 117 118 /**@brief Notification @ref nrf_802154_trx_transmit_frame_ccastarted */ 119 TRX_TRANSMIT_NOTIFICATION_CCASTARTED = (1U << 2) 120 } nrf_802154_trx_transmit_notifications_t; 121 122 /**@brief Initializes trx module. 123 * 124 * This function must be called exactly once, before any other API call. This function sets internal state 125 * of trx module into @c DISABLED. It initializes also those peripherals that are used exclusively 126 * by trx module and are not shared when trx module is in @c DISABLED state. 127 */ 128 void nrf_802154_trx_init(void); 129 130 /**@brief Enables trx module. 131 * 132 * Effects of call to this function: 133 * - The RADIO peripheral is fully reset and configured into 802.15.4 mode. 134 * - FEM module state is set to powered off. 135 * - PPIs used by trx module are disabled. 136 * - TIMER used by trx module is shutdown. 137 * - Trx module is in @c IDLE state 138 * 139 * @warning This function may be called when: 140 * - Trx module was in @c DISABLED state (after @ref nrf_802154_trx_init or after @ref nrf_802154_trx_disable). 141 * - HFCLK clock is activated. 142 * - Access to the RADIO peripheral is granted (applicable when the RADIO is shared with other drivers). 143 * 144 * @note When trx was in @c DISABLED state, the RADIO might have been controlled by other drivers. Thus 145 * full reset of the RADIO peripheral is performed. 146 */ 147 void nrf_802154_trx_enable(void); 148 149 /**@brief Disables trx module. 150 * 151 * This function has no effects when the trx module is in @c DISABLED state. 152 * Otherwise following effects apply: 153 * - The RADIO peripheral is fully reset. 154 * - FEM module state is set to powered off. 155 * - all PPSs used by trx module are disabled and cleared. 156 * - TIMER used by trx module is shutdown. 157 * - Trx module is in @c DISABLED state 158 * 159 * @note On call to this function any activity of trx module is stopped. If any operation was executing, it 160 * will be stopped and no handler will be called. After call HFCLK may be deactivated and 161 * the RADIO peripheral may be passed to other driver. 162 */ 163 void nrf_802154_trx_disable(void); 164 165 /** 166 * @brief Updates currently used antenna. 167 * 168 * This function sets the antenna to be used based on antenna diversity interface 169 * configuration and TRX state. 170 */ 171 void nrf_802154_trx_antenna_update(void); 172 173 /**@brief Sets radio channel to use. 174 * 175 * @param[in] channel Channel number to set (11-26). 176 */ 177 void nrf_802154_trx_channel_set(uint8_t channel); 178 179 /**@brief Updates CCA configuration in the RADIO peripheral according to PIB. */ 180 void nrf_802154_trx_cca_configuration_update(void); 181 182 /**@brief Puts the trx module into receive frame mode. 183 * 184 * The frame will be received into buffer set by @ref nrf_802154_trx_receive_buffer_set. 185 * 186 * - during receive @ref nrf_802154_trx_receive_frame_started handler is called when 187 * SHR field of a frame being received is received (only when @p notifications_mask contained @ref TRX_RECEIVE_NOTIFICATION_STARTED flag) 188 * - during receive @ref nrf_802154_trx_receive_frame_bcmatched handler is called when 189 * @p bcc octets are received. 190 * - when a frame is received with correct crc, @ref nrf_802154_trx_receive_frame_received is called 191 * - when a frame is received with incorrect crc, @ref nrf_802154_trx_receive_frame_crcerror is called 192 * 193 * When in @ref nrf_802154_trx_receive_frame_received, the TIMER is running allowing sending response (e.g. ACK frame) 194 * in time regime by a call to nrf_802154_trx_transmit_after_frame_received. 195 * 196 * @note To receive ACK use @ref nrf_802154_trx_receive_ack 197 * 198 * @param[in] bcc Number of received bytes after which @ref nrf_802154_trx_receive_frame_bcmatched will be called. 199 * @param[in] rampup_trigg_mode Radio ramp up triggering mode to be used. 200 * If @ref TRX_RAMP_UP_SW_TRIGGER is selected, this function will trigger radio ramp up in a software manner 201 * and the caller is guaranteed that ramp up is ongoing when the function ends. 202 * If @ref TRX_RAMP_UP_HW_TRIGGER is selected, this function will prepare the operation but it will end 203 * without starting radio ramp up. In this case, it is assumed that the trigger will be generated 204 * on the (D)PPI channel specified by @ref nrf_802154_trx_ramp_up_ppi_channel_get. It is the user's 205 * responsibility to prepare the stimulation of this (D)PPI. 206 * @param[in] notifications_mask Selects additional notifications generated during a frame reception. 207 * It is bitwise combination of @ref nrf_802154_trx_receive_notifications_t values. 208 * @param[in] p_ack_tx_power Selects the power which should be used to transmitted an ACK if required. 209 */ 210 void nrf_802154_trx_receive_frame(uint8_t bcc, 211 nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode, 212 nrf_802154_trx_receive_notifications_t notifications_mask, 213 const nrf_802154_fal_tx_power_split_t * p_ack_tx_power); 214 215 /**@brief Puts the trx module into receive ACK mode. 216 * 217 * The ack frame will be received into buffer set by @ref nrf_802154_trx_receive_buffer_set. 218 * 219 * During receive of an ack: 220 * - @ref nrf_802154_trx_receive_ack_started is called when a frame has just started being received. 221 * - when a frame is received with correct crc, @ref nrf_802154_trx_receive_ack_received is called. 222 * - when a frame is received with incorrect crc, @ref nrf_802154_trx_receive_ack_crcerror is called. 223 * - no bcmatch events are generated. 224 */ 225 void nrf_802154_trx_receive_ack(void); 226 227 /**@brief Starts RSSI measurement. 228 * 229 * @note This function succeeds when TRX module is in receive frame state only (started with @ref nrf_802154_trx_receive_frame) 230 * 231 * @retval true When RSSI measurement has been started. 232 * @retval false When TRX state didn't allow start of RSSI measurement. 233 */ 234 bool nrf_802154_trx_rssi_measure(void); 235 236 /**@brief Checks if RSSI measurement is currently started. 237 * 238 * @retval true When RSSI measurement is currently started. In this case user can 239 * check if RSSI sample is already available by call to @ref nrf_802154_trx_rssi_sample_is_available. 240 * @retval false When RSSI measurement is not started. 241 */ 242 bool nrf_802154_trx_rssi_measure_is_started(void); 243 244 /**@brief Checks if RSSI sample is available. 245 * 246 * @retval true When RSSI sample is available. The sample may be read by a call to @ref nrf_802154_trx_rssi_last_sample_get 247 * @retval false When RSSI sample is unavailable. 248 */ 249 bool nrf_802154_trx_rssi_sample_is_available(void); 250 251 /**@brief Returns last measured RSSI sample. 252 * 253 * @return RSSI sample. Returned value must be scaled using API provided by nrf_802154_rssi.h. 254 */ 255 uint8_t nrf_802154_trx_rssi_last_sample_get(void); 256 257 /**@brief Check if PSDU is currently being received. 258 * 259 * @retval true If trx is in receive mode triggered by @ref nrf_802154_trx_receive_frame and 260 * a frame receive on air has been started but not finished yet. 261 * @retval false Otherwise. 262 * 263 * @note This function returns false when receive has been triggered by @ref nrf_802154_trx_receive_ack 264 * regardless of the fact if the frame on air has been started or not. 265 */ 266 bool nrf_802154_trx_psdu_is_being_received(void); 267 268 /**@brief Checks if current receive operation was started without providing receive buffer. 269 * 270 * It may happen that @ref nrf_802154_trx_receive_frame or @ref nrf_802154_trx_receive_ack have been started 271 * when there was no receive buffer set. The RADIO peripheral will start ramping up, but it will remain 272 * in @c RXIDLE state, because of missing receive buffer. This function allows to check if such situation 273 * occurred. 274 * 275 * Usually this function may be called by buffer management subsystem when buffer becomes available. 276 * Consider following code snippet: 277 * @code 278 * void buffer_is_available_callback(void * p_buffer) 279 * { 280 * if (nrf_802154_trx_receive_is_buffer_missing()) 281 * { 282 * nrf_802154_trx_receive_buffer_set(p_buffer); 283 * } 284 * } 285 * @endcode 286 * 287 * @retval true When in receive mode and receive buffer is missing 288 * @retval false Otherwise. 289 */ 290 bool nrf_802154_trx_receive_is_buffer_missing(void); 291 292 /**@brief Sets pointer to a receive buffer. 293 * 294 * @param p_receive_buffer If NULL the next call to @ref nrf_802154_trx_receive_frame or 295 * @ref nrf_802154_trx_receive_ack will not be able to receive. 296 * If not NULL it must point to MAX_PACKET_SIZE + 1 (see nrf_802154_const.h) 297 * buffer where received frame will be stored. 298 * 299 * @retval true If operation solved missing buffer condition (see @ref nrf_802154_trx_receive_is_buffer_missing) 300 * and provided buffer will be used in current receive operation. 301 * @retval false If operation didn't solve missing buffer condition (either no missing buffer or currently 302 * not in receive mode). Provided buffer will be used in next receive operation. 303 */ 304 bool nrf_802154_trx_receive_buffer_set(void * p_receive_buffer); 305 306 /**@brief Begins frame transmit operation. 307 * 308 * This operation performs differently according to cca_attempts parameter. 309 * When cca_attempts==0: 310 * - The RADIO starts ramp up in transmit mode. 311 * - The RADIO starts sending synchronization header (SHR). 312 * - @ref nrf_802154_trx_transmit_frame_started handler is called from an ISR just after SHR is sent 313 * 314 * When cca_attempts>=1: 315 * - The radio starts ramp up in receive mode, then it starts cca procedure. 316 * - The @ref nrf_802154_trx_transmit_frame_ccastarted handler is called from an ISR when 317 * the RADIO started CCA procedure and @p notifications_mask contained 318 * @ref TRX_TRANSMIT_NOTIFICATION_CCASTARTED flag. 319 * - If cca succeded (channel was idle): 320 * - The RADIO switches to transmit mode (disables receive mode, starts ramp up in transmit mode). 321 * - The RADIO starts sending sending synchronization header (SHR). 322 * - If @ref TRX_TRANSMIT_NOTIFICATION_CCAIDLE was present in notifications_mask, 323 * the @ref nrf_802154_trx_transmit_frame_ccaidle is called. 324 * - @ref nrf_802154_trx_transmit_frame_started handler is called from an ISR just after SHR is sent 325 * - If cca failed (channel was busy): 326 * If cca_attempts==1: 327 * - The RADIO disables receive mode 328 * - @ref nrf_802154_trx_transmit_frame_ccabusy from an ISR handler is called 329 * If cca_attempts>1: 330 * - Decrease cca_attempts and repeat the entire procedure 331 * 332 * @param p_transmit_buffer Pointer to a buffer containing frame to transmit. 333 * Must not be NULL. p_transmit_buffer[0] is the number of 334 * bytes following p_transmit_buffer[0] to send. 335 * The number of bytes pointed by p_transmit buffer must 336 * be at least 1 and not less than p_transmit_buffer[0] + 1. 337 * @param rampup_trigg_mode Radio ramp up triggering mode to be used. 338 * If @ref TRX_RAMP_UP_SW_TRIGGER is selected, this function 339 * will trigger radio ramp up in a software manner. 340 * If @ref TRX_RAMP_UP_HW_TRIGGER is selected, this function 341 * will prepare the operation but it will end without starting 342 * radio ramp up. In this case, it is assumed that the trigger 343 * will be generated on the (D)PPI channel specified by 344 * @ref nrf_802154_trx_ramp_up_ppi_channel_get. 345 * It is the user's responsibility to prepare the stimulation 346 * of this (D)PPI. 347 * @param cca_attempts The maximum number of CCA procedures that can be performed prior to the 348 * transmission before the medium is considered busy. If 0, no CCA will be 349 * performed. Otherwise, CCA procedures will be performed back to back until 350 * idle channel is detected or @p cca_attempts attempts detect busy channel. 351 * @param p_tx_power Transmit power in dBm. 352 * @param notifications_mask Selects additional notifications generated during a frame transmission. 353 * It is bitwise combination of @ref nrf_802154_trx_transmit_notifications_t values. 354 * @note To transmit ack after frame is received use @ref nrf_802154_trx_transmit_ack. 355 */ 356 void nrf_802154_trx_transmit_frame(const void * p_transmit_buffer, 357 nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode, 358 uint8_t cca_attempts, 359 const nrf_802154_fal_tx_power_split_t * p_tx_power, 360 nrf_802154_trx_transmit_notifications_t notifications_mask); 361 362 /**@brief Puts the trx module into transmit ACK mode. 363 * 364 * @note This function may be called from @ref nrf_802154_trx_receive_frame_received handler only. 365 * This is because in this condition only the TIMER peripheral is running and allows timed transmission. 366 * 367 * @param[in] p_transmit_buffer Pointer to a buffer containing ACK frame to be transmitted. 368 * Caller is responsible for preparing an ACK frame according to the 802.15.4 protocol. 369 * @param[in] delay_us Delay (in microseconds) 370 * 371 * @retval true If the function was called in time and ACK frame is scheduled for transmission. 372 * When transmission starts the function @ref nrf_802154_trx_transmit_ack_started will be called. 373 * When transmission is finished the function @ref nrf_802154_trx_transmit_ack_transmitted 374 * will be called. 375 * @retval false If the function was called too late and given delay_us time gap 376 * between received frame and ACK frame transmission could not be hold. 377 * The TIMER peripheral is stopped and it is not possible to trigger @ref nrf_802154_trx_transmit_ack 378 * again without receiving another frame again. No handlers will be called. 379 */ 380 bool nrf_802154_trx_transmit_ack(const void * p_transmit_buffer, uint32_t delay_us); 381 382 /**@brief Puts trx module into IDLE mode. 383 * 384 * @retval true If entering into IDLE mode started, @ref nrf_802154_trx_go_idle_finished will be called 385 * (if not aborted by call to @ref nrf_802154_trx_abort or nrf_802154_trx_disable). 386 * @retval false If already in IDLE mode or just requested @ref nrf_802154_trx_go_idle. There will be 387 * no @ref nrf_802154_trx_go_idle_finished handler being result of this function. 388 */ 389 bool nrf_802154_trx_go_idle(void); 390 391 /**@brief Starts standalone cca operation. 392 * 393 * Operation ends with a call to @ref nrf_802154_trx_standalone_cca_finished handler from an ISR. 394 */ 395 void nrf_802154_trx_standalone_cca(void); 396 397 #if NRF_802154_CARRIER_FUNCTIONS_ENABLED 398 399 /**@brief Starts generating continuous carrier. 400 * 401 * @param[in] p_tx_power Transmit power in dBm. 402 * 403 * Generation of a continuous carrier generates no handlers. It may be terminated by a call to 404 * @ref nrf_802154_trx_abort or @ref nrf_802154_trx_disable. 405 */ 406 void nrf_802154_trx_continuous_carrier(const nrf_802154_fal_tx_power_split_t * p_tx_power); 407 408 /**@brief Restarts generating continuous carrier 409 * 410 * When continuous carrier was being generated and channel change was requested by a call to @ref nrf_802154_trx_channel_set. 411 * The frequency is not changed automatically. Use @ref nrf_802154_trx_continuous_carrier_restart to 412 * stop generating continuous carrier on old frequency and start this operation on a new frequency. 413 * @ref nrf_802154_trx_continuous_carrier_restart is usually faster than 414 * call to @ref nrf_802154_trx_abort @ref nrf_802154_trx_continuous_carrier 415 */ 416 void nrf_802154_trx_continuous_carrier_restart(void); 417 418 /**@brief Starts generating modulated carrier with given buffer. 419 * 420 * @param[in] p_transmit_buffer Pointer to a buffer used for modulating the carrier wave. 421 * @param[in] p_tx_power Transmit power in dBm. 422 */ 423 void nrf_802154_trx_modulated_carrier(const void * p_transmit_buffer, 424 const nrf_802154_fal_tx_power_split_t * p_tx_power); 425 426 /** @brief Restarts generating modulated carrier.*/ 427 void nrf_802154_trx_modulated_carrier_restart(void); 428 429 #endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED 430 431 /**@brief Puts trx module into energy detection mode. 432 * 433 * Operation ends up with a call to @ref nrf_802154_trx_energy_detection_finished handler. 434 * 435 * Operation can be terminated with a call to @ref nrf_802154_trx_abort or @ref nrf_802154_trx_disable. 436 * In this case no handler is called. 437 * 438 * @param ed_count Number of iterations to perform. Must be in range 1..2097152. 439 * One iteration takes 128 microseconds. 440 */ 441 void nrf_802154_trx_energy_detection(uint32_t ed_count); 442 443 /**@brief Aborts currently performed operation. 444 * 445 * When trx module is in @c DISABLED, @c IDLE or @c FINISHED state, this function has no effect. 446 * Otherwise current operation is terminated and no handler will be generated by the operation 447 * regardless of its state. In this case trx module will be in @c FINISHED state allowing 448 * commencement of a next operation. 449 */ 450 void nrf_802154_trx_abort(void); 451 452 /**@brief Gets current state of the TRX module. 453 * 454 * @return Current state of the TRX module.*/ 455 trx_state_t nrf_802154_trx_state_get(void); 456 457 /** 458 * @brief Gets (D)PPI channel used to trigger ramp up procedure start. 459 */ 460 uint32_t nrf_802154_trx_ramp_up_ppi_channel_get(void); 461 462 /**@brief Handler called at the beginning of a ACK reception. 463 * 464 * This handler is called from an ISR when receive of an ack has been started, and 465 * the RADIO received synchronization header (SHR). 466 */ 467 extern void nrf_802154_trx_receive_ack_started(void); 468 469 /**@brief Handler called at the beginning of frame reception (earliest possible moment). 470 * 471 * This handler is called from an ISR when: 472 * - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame 473 * - the RADIO peripheral detected energy on channel or started synchronizing to it. 474 * 475 * When this handler is called following holds: 476 * - trx module is in @c RXFRAME state. 477 * 478 * Implementation of @ref nrf_802154_trx_receive_frame_started may call: 479 * - @ref nrf_802154_trx_abort if current receive frame needs to be aborted 480 * (usually followed by a call moving the trx module out of @c FINISHED state) 481 * - @ref nrf_802154_trx_disable 482 * 483 * @note This handler may be triggered several times during receive of a preamble 484 * of a frame. It can be followed by call to @ref nrf_802154_trx_receive_frame_started 485 * (if enabled) and then by @ref nrf_802154_trx_receive_frame_received or 486 * @ref nrf_802154_trx_receive_frame_crcerror, but there is possibility 487 * that it will not be followed by these calls (In case when the RADIO didn't found 488 * full preamble.). If implementation of this handler starts some 489 * activity that must be terminated by a further call, it must implement 490 * its own timeout feature. 491 */ 492 extern void nrf_802154_trx_receive_frame_prestarted(void); 493 494 /**@brief Handler called at the beginning of frame reception. 495 * 496 * This handler is called from an ISR when: 497 * - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame 498 * - the RADIO started receiving a frame and has just received SHR field of the frame. 499 * 500 * When this handler is called following holds: 501 * - trx module is in @c RXFRAME state. 502 * 503 * Implementation of @ref nrf_802154_trx_receive_frame_started may call: 504 * - @ref nrf_802154_trx_abort if current receive frame needs to be aborted 505 * (usually followed by a call moving the trx module out of @c FINISHED state) 506 * - @ref nrf_802154_trx_disable 507 */ 508 extern void nrf_802154_trx_receive_frame_started(void); 509 510 /**@brief Handler called during reception of a frame, when given number of bytes is received. 511 * 512 * This handler is called from an ISR when given number of bytes (see @ref nrf_802154_trx_receive_frame) 513 * have been just received. 514 * 515 * @note If the handler decides to abort receive by a call to @ref nrf_802154_trx_abort or 516 * @ref nrf_802154_trx_disable it must return value equal to original bcc parameter passed. 517 * 518 * @param[in] bcc Number of bytes that have been already received. 519 * 520 * @return Value greater than original value of bcc parameter will cause @ref nrf_802154_trx_receive_frame_bcmatched 521 * to be called again when further data arrive. Value less than or equal to original bcc value will not cause this 522 * behavior. 523 */ 524 extern uint8_t nrf_802154_trx_receive_frame_bcmatched(uint8_t bcc); 525 526 /**@brief Handler called when a frame is received with correct crc. 527 * 528 * This handler is called from an ISR when: 529 * - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame 530 * - the RADIO received a frame on air with correct crc 531 * 532 * When this handler is called following holds: 533 * - trx module is in @c RXFRAME_FINISHED state. 534 * - the RADIO peripheral started ramping down (or it ramped down already) 535 * - TIMER peripheral started counting allowing @ref nrf_802154_trx_transmit_ack 536 * 537 * Implementation of @ref nrf_802154_trx_receive_frame_received is responsible for 538 * leaving @c RXFRAME_FINISHED state. It may do this by call to: 539 * - @ref nrf_802154_trx_transmit_ack, 540 * - @ref nrf_802154_trx_receive_frame, 541 * - @ref nrf_802154_trx_transmit_frame, 542 * - @ref nrf_802154_trx_go_idle, 543 * - @ref nrf_802154_trx_disable. 544 */ 545 extern void nrf_802154_trx_receive_frame_received(void); 546 547 /**@brief Handler called when a frame is received with incorrect crc. 548 * 549 * This handler is called from an ISR when: 550 * - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame 551 * - the RADIO received a frame on air with incorrect crc 552 * 553 * When this handler is called following holds: 554 * - the RADIO peripheral started ramping down (or it ramped down already) 555 * - trx module is in @c FINISHED state. 556 * 557 * Implementation of @ref nrf_802154_trx_receive_frame_crcerror is responsible for 558 * leaving @c FINISHED state. It may do this by call to: 559 * - @ref nrf_802154_trx_receive_frame, 560 * - @ref nrf_802154_trx_transmit_frame, 561 * - @ref nrf_802154_trx_go_idle, 562 * - @ref nrf_802154_trx_disable. 563 * 564 * Implementation of @ref nrf_802154_trx_receive_frame_crcerror should not call 565 * @ref nrf_802154_trx_receive_frame as receive is restarted automatically by the hardware. 566 * If the implementation wishes to change state it should call 567 * @ref nrf_802154_trx_abort first. 568 */ 569 extern void nrf_802154_trx_receive_frame_crcerror(void); 570 571 /**@brief Handler called when an ack is received with correct crc. 572 * 573 * This handler is called from an ISR when: 574 * - receive ack operation has been started with a call to @ref nrf_802154_trx_receive_ack 575 * - the RADIO received a frame on air with correct crc 576 * 577 * When this handler is called following holds: 578 * - the RADIO peripheral started ramping down (or it ramped down already) 579 * - trx module is in @c FINISHED state. 580 * 581 * Implementation is responsible for: 582 * - checking if received frame is an ack and matches previously transmitted frame. 583 * - leaving @c FINISHED state. It may do this by call to: 584 * - @ref nrf_802154_trx_receive_frame, 585 * - @ref nrf_802154_trx_transmit_frame, 586 * - @ref nrf_802154_trx_go_idle, 587 * - @ref nrf_802154_trx_disable. 588 */ 589 extern void nrf_802154_trx_receive_ack_received(void); 590 591 /**@brief Handler called when an ack is received with incorrect crc. 592 * 593 * This handler is called from an ISR when: 594 * - receive ack operation has been started with a call to @ref nrf_802154_trx_receive_ack 595 * - the RADIO received a frame on air with incorrect crc 596 * 597 * When this handler is called following holds: 598 * - the RADIO peripheral started ramping down (or it ramped down already) 599 * - trx module is in @c FINISHED state. 600 * 601 * Implementation is responsible for: 602 * - leaving @c FINISHED state. It may do this by call to: 603 * - @ref nrf_802154_trx_receive_frame, 604 * - @ref nrf_802154_trx_transmit_frame, 605 * - @ref nrf_802154_trx_go_idle, 606 * - @ref nrf_802154_trx_disable. 607 */ 608 extern void nrf_802154_trx_receive_ack_crcerror(void); 609 610 /**@brief Handler called when a cca operation during transmit attempt started. 611 * 612 * This handler is called from an ISR when: 613 * - transmit operation with cca has been started with a call to @ref nrf_802154_trx_transmit_frame(cca=true). 614 * - transmit operation was started with parameter @c notifications_mask containing 615 * TRX_TRANSMIT_NOTIFICATION_CCASTARTED 616 * - the RADIO peripheral started CCA operation. 617 * 618 * Implementation is not responsible for anything related to the trx module since it serves as 619 * a pure notification of the channel assessment started event during transmission. 620 */ 621 extern void nrf_802154_trx_transmit_frame_ccastarted(void); 622 623 /**@brief Handler called when a cca operation during transmit attempt was successful. 624 * 625 * This handler is called from an ISR when: 626 * - transmit operation with cca has been started with a call to @ref nrf_802154_trx_transmit_frame(cca=true). 627 * - the RADIO detected that channel was free. 628 * 629 * When this handler is called following holds: 630 * - the RADIO peripheral started ramping up (or it ramped up already) 631 * - trx module is in @c TXFRAME state. 632 * 633 * Implementation is not responsible for anything since it serves as 634 * a pure notification of the successful channel assessment during transmission. 635 */ 636 extern void nrf_802154_trx_transmit_frame_ccaidle(void); 637 638 /**@brief Handler called when a cca operation during transmit attempt failed. 639 * 640 * This handler is called from an ISR when: 641 * - transmit operation with cca has been started with a call to @ref nrf_802154_trx_transmit_frame(cca=true). 642 * - the RADIO detected that channel was busy. 643 * 644 * When this handler is called following holds: 645 * - the RADIO peripheral started ramping down (or it ramped down already) 646 * - trx module is in @c FINISHED state. 647 * 648 * Implementation is responsible for: 649 * - leaving @c FINISHED state. It may do this by call to: 650 * - @ref nrf_802154_trx_receive_frame, 651 * - @ref nrf_802154_trx_transmit_frame, 652 * - @ref nrf_802154_trx_go_idle, 653 * - @ref nrf_802154_trx_disable. 654 */ 655 extern void nrf_802154_trx_transmit_frame_ccabusy(void); 656 657 /**@brief Handler called when frame transmission has just started. 658 * 659 * This handler is called from an ISR when: 660 * - transmit operation was started by a call to @ref nrf_802154_trx_transmit_frame. 661 * - the RADIO peripheral sent synchronization header 662 * 663 * When this handler is called following holds: 664 * - trx module is in @c TXFRAME state 665 * 666 * Implementation may (but does not need to) terminate transmission if it wishes by a call to: 667 * - @ref nrf_802154_trx_abort, 668 * - @ref nrf_802154_trx_disable. 669 */ 670 extern void nrf_802154_trx_transmit_frame_started(void); 671 672 /**@brief Handler called when frame transmission has just been finished. 673 * 674 * This handler is called from an ISR when: 675 * - transmit operation was started by a call to @ref nrf_802154_trx_transmit_frame. 676 * - the RADIO peripheral sent whole frame on air 677 * 678 * When this handler is called following holds: 679 * - the RADIO peripheral started ramping down (or it ramped down already) 680 * - trx module is in @c FINISHED state 681 * 682 * Implementation is responsible for leaving @c FINISHED state by a call to: 683 * - @ref nrf_802154_trx_receive_frame, 684 * - @ref nrf_802154_trx_transmit_frame, 685 * - @ref nrf_802154_trx_go_idle, 686 * - @ref nrf_802154_trx_disable. 687 */ 688 extern void nrf_802154_trx_transmit_frame_transmitted(void); 689 690 /**@brief Handler called when ack transmission has just been started. 691 * 692 * This handler is called from an ISR when: 693 * - transmit operation was started by a call to @ref nrf_802154_trx_transmit_ack. 694 * - the RADIO peripheral sent synchronization header 695 * 696 * When this handler is called following holds: 697 * - trx module is in @c TXACK state 698 * 699 * Implementation may (but does not need to) terminate transmission if it wishes by a call to: 700 * - @ref nrf_802154_trx_abort, 701 * - @ref nrf_802154_trx_disable. 702 */ 703 extern void nrf_802154_trx_transmit_ack_started(void); 704 705 /**@brief Handler called when ack transmission has just been finished. 706 * 707 * This handler is called from an ISR when: 708 * - transmit operation was started by a call to @ref nrf_802154_trx_transmit_ack. 709 * - the RADIO peripheral sent whole ack frame on air 710 * 711 * When this handler is called following holds: 712 * - the RADIO peripheral started ramping down (or it ramped down already) 713 * - trx module is in @c FINISHED state 714 * 715 * Implementation is responsible for leaving @c FINISHED state by a call to: 716 * - @ref nrf_802154_trx_receive_frame, 717 * - @ref nrf_802154_trx_transmit_frame, 718 * - @ref nrf_802154_trx_go_idle, 719 * - @ref nrf_802154_trx_disable. 720 */ 721 extern void nrf_802154_trx_transmit_ack_transmitted(void); 722 723 /**@brief Handler called when trx module reached @c IDLE state. 724 * 725 * This handler is called from an ISR when: 726 * - transition to idle state was successfully requested by a call to @ref nrf_802154_trx_go_idle. 727 * - the RADIO peripheral reached DISABLED state 728 * - the FEM module has been powered off 729 * 730 * When this handler is called following holds: 731 * - the RADIO is in @c DISABLED state 732 * - the FEM is powered off 733 * - trx module is in @c IDLE state 734 * 735 * Implementation may leave trx in @c IDLE state or it may request: 736 * - @ref nrf_802154_trx_receive_frame, 737 * - @ref nrf_802154_trx_transmit_frame, 738 * - @ref nrf_802154_trx_disable. 739 */ 740 extern void nrf_802154_trx_go_idle_finished(void); 741 742 /**@brief Handler called when standalone cca operaion has been just finished. 743 * 744 * This handler is called from an ISR when: 745 * - standalone cca operation was requested by a call to @ref nrf_802154_trx_standalone_cca 746 * - the RADIO peripheral finished cca operation 747 * 748 * When this handler is called following holds: 749 * - the RADIO peripheral started ramping down (or it ramped down already) 750 * - trx module is in @c FINISHED state 751 * 752 * Implementation is responsible for leaving @c FINISHED state by a call to: 753 * - @ref nrf_802154_trx_receive_frame, 754 * - @ref nrf_802154_trx_transmit_frame, 755 * - @ref nrf_802154_trx_go_idle, 756 * - @ref nrf_802154_trx_disable. 757 * 758 * @param channel_was_idle Informs implementation of the handler if channel was idle. 759 * true means the channel was idle, false means the channel was busy. 760 */ 761 extern void nrf_802154_trx_standalone_cca_finished(bool channel_was_idle); 762 763 /**@brief Handler called when energy detection operation has been just finished. 764 * 765 * This handler is called from an ISR when: 766 * - energy detection operation was requested by a call to @ref nrf_802154_trx_energy_detection 767 * - the RADIO peripheral finished the operation 768 * 769 * When this handler is called following holds: 770 * - the RADIO peripheral started ramping down (or it ramped down already) 771 * - trx module is in @c FINISHED state 772 * 773 * Implementation is responsible for leaving @c FINISHED state by a call to: 774 * - @ref nrf_802154_trx_receive_frame, 775 * - @ref nrf_802154_trx_transmit_frame, 776 * - @ref nrf_802154_trx_go_idle, 777 * - @ref nrf_802154_trx_disable. 778 * 779 * @param ed_sample Sample of detected energy. 780 */ 781 extern void nrf_802154_trx_energy_detection_finished(uint8_t ed_sample); 782 783 /**@brief Returns RADIO->EVENTS_END handle that hardware can subscribe to. 784 * 785 * @return RADIO->EVENTS_END handle that hardware can subscribe to. 786 */ 787 const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_end_event_handle_get(void); 788 789 /**@brief Returns RADIO->EVENTS_READY handle that hardware can subscribe to. 790 * 791 * @return RADIO->EVENTS_READY handle that hardware can subscribe to. 792 */ 793 const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_ready_event_handle_get(void); 794 795 /**@brief Returns RADIO->EVENTS_CRCOK handle that hardware can subscribe to. 796 * 797 * @return RADIO->EVENTS_CRCOK handle that hardware can subscribe to. 798 */ 799 const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_crcok_event_handle_get(void); 800 801 /**@brief Returns RADIO->EVENTS_PHYEND handle that hardware can subscribe to. 802 * 803 * @return RADIO->EVENTS_PHYEND handle that hardware can subscribe to. 804 */ 805 const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_phyend_event_handle_get(void); 806 807 #ifdef __cplusplus 808 } 809 #endif 810 811 #endif /* NRF_802154_TRX_H_ */ 812
