1 /* 2 * Copyright (c) 2019 - 2023, 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 parameter. 309 * When cca==false: 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==true: 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 * - The RADIO disables receive mode 327 * - @ref nrf_802154_trx_transmit_frame_ccabusy from an ISR handler is called 328 * 329 * @param p_transmit_buffer Pointer to a buffer containing frame to transmit. 330 * Must not be NULL. p_transmit_buffer[0] is the number of 331 * bytes following p_transmit_buffer[0] to send. 332 * The number of bytes pointed by p_transmit buffer must 333 * be at least 1 and not less than p_transmit_buffer[0] + 1. 334 * @param rampup_trigg_mode Radio ramp up triggering mode to be used. 335 * If @ref TRX_RAMP_UP_SW_TRIGGER is selected, this function 336 * will trigger radio ramp up in a software manner. 337 * If @ref TRX_RAMP_UP_HW_TRIGGER is selected, this function 338 * will prepare the operation but it will end without starting 339 * radio ramp up. In this case, it is assumed that the trigger 340 * will be generated on the (D)PPI channel specified by 341 * @ref nrf_802154_trx_ramp_up_ppi_channel_get. 342 * It is the user's responsibility to prepare the stimulation 343 * of this (D)PPI. 344 * @param cca Selects if CCA procedure should be performed prior to 345 * real transmission. If false no cca will be performed. 346 * If true, cca will be performed. 347 * @param p_tx_power Transmit power in dBm. 348 * @param notifications_mask Selects additional notifications generated during a frame transmission. 349 * It is bitwise combination of @ref nrf_802154_trx_transmit_notifications_t values. 350 * @note To transmit ack after frame is received use @ref nrf_802154_trx_transmit_ack. 351 */ 352 void nrf_802154_trx_transmit_frame(const void * p_transmit_buffer, 353 nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode, 354 bool cca, 355 const nrf_802154_fal_tx_power_split_t * p_tx_power, 356 nrf_802154_trx_transmit_notifications_t notifications_mask); 357 358 /**@brief Puts the trx module into transmit ACK mode. 359 * 360 * @note This function may be called from @ref nrf_802154_trx_receive_frame_received handler only. 361 * This is because in this condition only the TIMER peripheral is running and allows timed transmission. 362 * 363 * @param[in] p_transmit_buffer Pointer to a buffer containing ACK frame to be transmitted. 364 * Caller is responsible for preparing an ACK frame according to the 802.15.4 protocol. 365 * @param[in] delay_us Delay (in microseconds) 366 * 367 * @retval true If the function was called in time and ACK frame is scheduled for transmission. 368 * When transmission starts the function @ref nrf_802154_trx_transmit_ack_started will be called. 369 * When transmission is finished the function @ref nrf_802154_trx_transmit_ack_transmitted 370 * will be called. 371 * @retval false If the function was called too late and given delay_us time gap 372 * between received frame and ACK frame transmission could not be hold. 373 * The TIMER peripheral is stopped and it is not possible to trigger @ref nrf_802154_trx_transmit_ack 374 * again without receiving another frame again. No handlers will be called. 375 */ 376 bool nrf_802154_trx_transmit_ack(const void * p_transmit_buffer, uint32_t delay_us); 377 378 /**@brief Puts trx module into IDLE mode. 379 * 380 * @retval true If entering into IDLE mode started, @ref nrf_802154_trx_go_idle_finished will be called 381 * (if not aborted by call to @ref nrf_802154_trx_abort or nrf_802154_trx_disable). 382 * @retval false If already in IDLE mode or just requested @ref nrf_802154_trx_go_idle. There will be 383 * no @ref nrf_802154_trx_go_idle_finished handler being result of this function. 384 */ 385 bool nrf_802154_trx_go_idle(void); 386 387 /**@brief Starts standalone cca operation. 388 * 389 * Operation ends with a call to @ref nrf_802154_trx_standalone_cca_finished handler from an ISR. 390 */ 391 void nrf_802154_trx_standalone_cca(void); 392 393 #if NRF_802154_CARRIER_FUNCTIONS_ENABLED 394 395 /**@brief Starts generating continuous carrier. 396 * 397 * @param[in] p_tx_power Transmit power in dBm. 398 * 399 * Generation of a continuous carrier generates no handlers. It may be terminated by a call to 400 * @ref nrf_802154_trx_abort or @ref nrf_802154_trx_disable. 401 */ 402 void nrf_802154_trx_continuous_carrier(const nrf_802154_fal_tx_power_split_t * p_tx_power); 403 404 /**@brief Restarts generating continuous carrier 405 * 406 * When continuous carrier was being generated and channel change was requested by a call to @ref nrf_802154_trx_channel_set. 407 * The frequency is not changed automatically. Use @ref nrf_802154_trx_continuous_carrier_restart to 408 * stop generating continuous carrier on old frequency and start this operation on a new frequency. 409 * @ref nrf_802154_trx_continuous_carrier_restart is usually faster than 410 * call to @ref nrf_802154_trx_abort @ref nrf_802154_trx_continuous_carrier 411 */ 412 void nrf_802154_trx_continuous_carrier_restart(void); 413 414 /**@brief Starts generating modulated carrier with given buffer. 415 * 416 * @param[in] p_transmit_buffer Pointer to a buffer used for modulating the carrier wave. 417 * @param[in] p_tx_power Transmit power in dBm. 418 */ 419 void nrf_802154_trx_modulated_carrier(const void * p_transmit_buffer, 420 const nrf_802154_fal_tx_power_split_t * p_tx_power); 421 422 /** @brief Restarts generating modulated carrier.*/ 423 void nrf_802154_trx_modulated_carrier_restart(void); 424 425 #endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED 426 427 /**@brief Puts trx module into energy detection mode. 428 * 429 * Operation ends up with a call to @ref nrf_802154_trx_energy_detection_finished handler. 430 * 431 * Operation can be terminated with a call to @ref nrf_802154_trx_abort or @ref nrf_802154_trx_disable. 432 * In this case no handler is called. 433 * 434 * @param ed_count Number of iterations to perform. Must be in range 1..2097152. 435 * One iteration takes 128 microseconds. 436 */ 437 void nrf_802154_trx_energy_detection(uint32_t ed_count); 438 439 /**@brief Aborts currently performed operation. 440 * 441 * When trx module is in @c DISABLED, @c IDLE or @c FINISHED state, this function has no effect. 442 * Otherwise current operation is terminated and no handler will be generated by the operation 443 * regardless of its state. In this case trx module will be in @c FINISHED state allowing 444 * commencement of a next operation. 445 */ 446 void nrf_802154_trx_abort(void); 447 448 /**@brief Gets current state of the TRX module. 449 * 450 * @return Current state of the TRX module.*/ 451 trx_state_t nrf_802154_trx_state_get(void); 452 453 /** 454 * @brief Gets (D)PPI channel used to trigger ramp up procedure start. 455 */ 456 uint32_t nrf_802154_trx_ramp_up_ppi_channel_get(void); 457 458 /**@brief Handler called at the beginning of a ACK reception. 459 * 460 * This handler is called from an ISR when receive of an ack has been started, and 461 * the RADIO received synchronization header (SHR). 462 */ 463 extern void nrf_802154_trx_receive_ack_started(void); 464 465 /**@brief Handler called at the beginning of frame reception (earliest possible moment). 466 * 467 * This handler is called from an ISR when: 468 * - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame 469 * - the RADIO peripheral detected energy on channel or started synchronizing to it. 470 * 471 * When this handler is called following holds: 472 * - trx module is in @c RXFRAME state. 473 * 474 * Implementation of @ref nrf_802154_trx_receive_frame_started may call: 475 * - @ref nrf_802154_trx_abort if current receive frame needs to be aborted 476 * (usually followed by a call moving the trx module out of @c FINISHED state) 477 * - @ref nrf_802154_trx_disable 478 * 479 * @note This handler may be triggered several times during receive of a preamble 480 * of a frame. It can be followed by call to @ref nrf_802154_trx_receive_frame_started 481 * (if enabled) and then by @ref nrf_802154_trx_receive_frame_received or 482 * @ref nrf_802154_trx_receive_frame_crcerror, but there is possibility 483 * that it will not be followed by these calls (In case when the RADIO didn't found 484 * full preamble.). If implementation of this handler starts some 485 * activity that must be terminated by a further call, it must implement 486 * its own timeout feature. 487 */ 488 extern void nrf_802154_trx_receive_frame_prestarted(void); 489 490 /**@brief Handler called at the beginning of frame reception. 491 * 492 * This handler is called from an ISR when: 493 * - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame 494 * - the RADIO started receiving a frame and has just received SHR field of the frame. 495 * 496 * When this handler is called following holds: 497 * - trx module is in @c RXFRAME state. 498 * 499 * Implementation of @ref nrf_802154_trx_receive_frame_started may call: 500 * - @ref nrf_802154_trx_abort if current receive frame needs to be aborted 501 * (usually followed by a call moving the trx module out of @c FINISHED state) 502 * - @ref nrf_802154_trx_disable 503 */ 504 extern void nrf_802154_trx_receive_frame_started(void); 505 506 /**@brief Handler called during reception of a frame, when given number of bytes is received. 507 * 508 * This handler is called from an ISR when given number of bytes (see @ref nrf_802154_trx_receive_frame) 509 * have been just received. 510 * 511 * @note If the handler decides to abort receive by a call to @ref nrf_802154_trx_abort or 512 * @ref nrf_802154_trx_disable it must return value equal to original bcc parameter passed. 513 * 514 * @param[in] bcc Number of bytes that have been already received. 515 * 516 * @return Value greater than original value of bcc parameter will cause @ref nrf_802154_trx_receive_frame_bcmatched 517 * to be called again when further data arrive. Value less than or equal to original bcc value will not cause this 518 * behavior. 519 */ 520 extern uint8_t nrf_802154_trx_receive_frame_bcmatched(uint8_t bcc); 521 522 /**@brief Handler called when a frame is received with correct crc. 523 * 524 * This handler is called from an ISR when: 525 * - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame 526 * - the RADIO received a frame on air with correct crc 527 * 528 * When this handler is called following holds: 529 * - trx module is in @c RXFRAME_FINISHED state. 530 * - the RADIO peripheral started ramping down (or it ramped down already) 531 * - TIMER peripheral started counting allowing @ref nrf_802154_trx_transmit_ack 532 * 533 * Implementation of @ref nrf_802154_trx_receive_frame_received is responsible for 534 * leaving @c RXFRAME_FINISHED state. It may do this by call to: 535 * - @ref nrf_802154_trx_transmit_ack, 536 * - @ref nrf_802154_trx_receive_frame, 537 * - @ref nrf_802154_trx_transmit_frame, 538 * - @ref nrf_802154_trx_go_idle, 539 * - @ref nrf_802154_trx_disable. 540 */ 541 extern void nrf_802154_trx_receive_frame_received(void); 542 543 /**@brief Handler called when a frame is received with incorrect crc. 544 * 545 * This handler is called from an ISR when: 546 * - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame 547 * - the RADIO received a frame on air with incorrect crc 548 * 549 * When this handler is called following holds: 550 * - the RADIO peripheral started ramping down (or it ramped down already) 551 * - trx module is in @c FINISHED state. 552 * 553 * Implementation of @ref nrf_802154_trx_receive_frame_crcerror is responsible for 554 * leaving @c FINISHED state. It may do this by call to: 555 * - @ref nrf_802154_trx_receive_frame, 556 * - @ref nrf_802154_trx_transmit_frame, 557 * - @ref nrf_802154_trx_go_idle, 558 * - @ref nrf_802154_trx_disable. 559 * 560 * Implementation of @ref nrf_802154_trx_receive_frame_crcerror should not call 561 * @ref nrf_802154_trx_receive_frame as receive is restarted automatically by the hardware. 562 * If the implementation wishes to change state it should call 563 * @ref nrf_802154_trx_abort first. 564 */ 565 extern void nrf_802154_trx_receive_frame_crcerror(void); 566 567 /**@brief Handler called when an ack is received with correct crc. 568 * 569 * This handler is called from an ISR when: 570 * - receive ack operation has been started with a call to @ref nrf_802154_trx_receive_ack 571 * - the RADIO received a frame on air with correct crc 572 * 573 * When this handler is called following holds: 574 * - the RADIO peripheral started ramping down (or it ramped down already) 575 * - trx module is in @c FINISHED state. 576 * 577 * Implementation is responsible for: 578 * - checking if received frame is an ack and matches previously transmitted frame. 579 * - leaving @c FINISHED state. It may do this by call to: 580 * - @ref nrf_802154_trx_receive_frame, 581 * - @ref nrf_802154_trx_transmit_frame, 582 * - @ref nrf_802154_trx_go_idle, 583 * - @ref nrf_802154_trx_disable. 584 */ 585 extern void nrf_802154_trx_receive_ack_received(void); 586 587 /**@brief Handler called when an ack is received with incorrect crc. 588 * 589 * This handler is called from an ISR when: 590 * - receive ack operation has been started with a call to @ref nrf_802154_trx_receive_ack 591 * - the RADIO received a frame on air with incorrect crc 592 * 593 * When this handler is called following holds: 594 * - the RADIO peripheral started ramping down (or it ramped down already) 595 * - trx module is in @c FINISHED state. 596 * 597 * Implementation is responsible for: 598 * - leaving @c FINISHED state. It may do this by call to: 599 * - @ref nrf_802154_trx_receive_frame, 600 * - @ref nrf_802154_trx_transmit_frame, 601 * - @ref nrf_802154_trx_go_idle, 602 * - @ref nrf_802154_trx_disable. 603 */ 604 extern void nrf_802154_trx_receive_ack_crcerror(void); 605 606 /**@brief Handler called when a cca operation during transmit attempt started. 607 * 608 * This handler is called from an ISR when: 609 * - transmit operation with cca has been started with a call to @ref nrf_802154_trx_transmit_frame(cca=true). 610 * - transmit operation was started with parameter @c notifications_mask containing 611 * TRX_TRANSMIT_NOTIFICATION_CCASTARTED 612 * - the RADIO peripheral started CCA operation. 613 * 614 * Implementation is not responsible for anything related to the trx module since it serves as 615 * a pure notification of the channel assessment started event during transmission. 616 */ 617 extern void nrf_802154_trx_transmit_frame_ccastarted(void); 618 619 /**@brief Handler called when a cca operation during transmit attempt was successful. 620 * 621 * This handler is called from an ISR when: 622 * - transmit operation with cca has been started with a call to @ref nrf_802154_trx_transmit_frame(cca=true). 623 * - the RADIO detected that channel was free. 624 * 625 * When this handler is called following holds: 626 * - the RADIO peripheral started ramping up (or it ramped up already) 627 * - trx module is in @c TXFRAME state. 628 * 629 * Implementation is not responsible for anything since it serves as 630 * a pure notification of the successful channel assessment during transmission. 631 */ 632 extern void nrf_802154_trx_transmit_frame_ccaidle(void); 633 634 /**@brief Handler called when a cca operation during transmit attempt failed. 635 * 636 * This handler is called from an ISR when: 637 * - transmit operation with cca has been started with a call to @ref nrf_802154_trx_transmit_frame(cca=true). 638 * - the RADIO detected that channel was busy. 639 * 640 * When this handler is called following holds: 641 * - the RADIO peripheral started ramping down (or it ramped down already) 642 * - trx module is in @c FINISHED state. 643 * 644 * Implementation is responsible for: 645 * - leaving @c FINISHED state. It may do this by call to: 646 * - @ref nrf_802154_trx_receive_frame, 647 * - @ref nrf_802154_trx_transmit_frame, 648 * - @ref nrf_802154_trx_go_idle, 649 * - @ref nrf_802154_trx_disable. 650 */ 651 extern void nrf_802154_trx_transmit_frame_ccabusy(void); 652 653 /**@brief Handler called when frame transmission has just started. 654 * 655 * This handler is called from an ISR when: 656 * - transmit operation was started by a call to @ref nrf_802154_trx_transmit_frame. 657 * - the RADIO peripheral sent synchronization header 658 * 659 * When this handler is called following holds: 660 * - trx module is in @c TXFRAME state 661 * 662 * Implementation may (but does not need to) terminate transmission if it wishes by a call to: 663 * - @ref nrf_802154_trx_abort, 664 * - @ref nrf_802154_trx_disable. 665 */ 666 extern void nrf_802154_trx_transmit_frame_started(void); 667 668 /**@brief Handler called when frame transmission has just been finished. 669 * 670 * This handler is called from an ISR when: 671 * - transmit operation was started by a call to @ref nrf_802154_trx_transmit_frame. 672 * - the RADIO peripheral sent whole frame on air 673 * 674 * When this handler is called following holds: 675 * - the RADIO peripheral started ramping down (or it ramped down already) 676 * - trx module is in @c FINISHED state 677 * 678 * Implementation is responsible for leaving @c FINISHED state by a call to: 679 * - @ref nrf_802154_trx_receive_frame, 680 * - @ref nrf_802154_trx_transmit_frame, 681 * - @ref nrf_802154_trx_go_idle, 682 * - @ref nrf_802154_trx_disable. 683 */ 684 extern void nrf_802154_trx_transmit_frame_transmitted(void); 685 686 /**@brief Handler called when ack transmission has just been started. 687 * 688 * This handler is called from an ISR when: 689 * - transmit operation was started by a call to @ref nrf_802154_trx_transmit_ack. 690 * - the RADIO peripheral sent synchronization header 691 * 692 * When this handler is called following holds: 693 * - trx module is in @c TXACK state 694 * 695 * Implementation may (but does not need to) terminate transmission if it wishes by a call to: 696 * - @ref nrf_802154_trx_abort, 697 * - @ref nrf_802154_trx_disable. 698 */ 699 extern void nrf_802154_trx_transmit_ack_started(void); 700 701 /**@brief Handler called when ack transmission has just been finished. 702 * 703 * This handler is called from an ISR when: 704 * - transmit operation was started by a call to @ref nrf_802154_trx_transmit_ack. 705 * - the RADIO peripheral sent whole ack frame on air 706 * 707 * When this handler is called following holds: 708 * - the RADIO peripheral started ramping down (or it ramped down already) 709 * - trx module is in @c FINISHED state 710 * 711 * Implementation is responsible for leaving @c FINISHED state by a call to: 712 * - @ref nrf_802154_trx_receive_frame, 713 * - @ref nrf_802154_trx_transmit_frame, 714 * - @ref nrf_802154_trx_go_idle, 715 * - @ref nrf_802154_trx_disable. 716 */ 717 extern void nrf_802154_trx_transmit_ack_transmitted(void); 718 719 /**@brief Handler called when trx module reached @c IDLE state. 720 * 721 * This handler is called from an ISR when: 722 * - transition to idle state was successfully requested by a call to @ref nrf_802154_trx_go_idle. 723 * - the RADIO peripheral reached DISABLED state 724 * - the FEM module has been powered off 725 * 726 * When this handler is called following holds: 727 * - the RADIO is in @c DISABLED state 728 * - the FEM is powered off 729 * - trx module is in @c IDLE state 730 * 731 * Implementation may leave trx in @c IDLE state or it may request: 732 * - @ref nrf_802154_trx_receive_frame, 733 * - @ref nrf_802154_trx_transmit_frame, 734 * - @ref nrf_802154_trx_disable. 735 */ 736 extern void nrf_802154_trx_go_idle_finished(void); 737 738 /**@brief Handler called when standalone cca operaion has been just finished. 739 * 740 * This handler is called from an ISR when: 741 * - standalone cca operation was requested by a call to @ref nrf_802154_trx_standalone_cca 742 * - the RADIO peripheral finished cca operation 743 * 744 * When this handler is called following holds: 745 * - the RADIO peripheral started ramping down (or it ramped down already) 746 * - trx module is in @c FINISHED state 747 * 748 * Implementation is responsible for leaving @c FINISHED state by a call to: 749 * - @ref nrf_802154_trx_receive_frame, 750 * - @ref nrf_802154_trx_transmit_frame, 751 * - @ref nrf_802154_trx_go_idle, 752 * - @ref nrf_802154_trx_disable. 753 * 754 * @param channel_was_idle Informs implementation of the handler if channel was idle. 755 * true means the channel was idle, false means the channel was busy. 756 */ 757 extern void nrf_802154_trx_standalone_cca_finished(bool channel_was_idle); 758 759 /**@brief Handler called when energy detection operation has been just finished. 760 * 761 * This handler is called from an ISR when: 762 * - energy detection operation was requested by a call to @ref nrf_802154_trx_energy_detection 763 * - the RADIO peripheral finished the operation 764 * 765 * When this handler is called following holds: 766 * - the RADIO peripheral started ramping down (or it ramped down already) 767 * - trx module is in @c FINISHED state 768 * 769 * Implementation is responsible for leaving @c FINISHED state by a call to: 770 * - @ref nrf_802154_trx_receive_frame, 771 * - @ref nrf_802154_trx_transmit_frame, 772 * - @ref nrf_802154_trx_go_idle, 773 * - @ref nrf_802154_trx_disable. 774 * 775 * @param ed_sample Sample of detected energy. 776 */ 777 extern void nrf_802154_trx_energy_detection_finished(uint8_t ed_sample); 778 779 /**@brief Returns RADIO->EVENTS_END handle that hardware can subscribe to. 780 * 781 * @return RADIO->EVENTS_END handle that hardware can subscribe to. 782 */ 783 const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_end_event_handle_get(void); 784 785 /**@brief Returns RADIO->EVENTS_READY handle that hardware can subscribe to. 786 * 787 * @return RADIO->EVENTS_READY handle that hardware can subscribe to. 788 */ 789 const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_ready_event_handle_get(void); 790 791 /**@brief Returns RADIO->EVENTS_CRCOK handle that hardware can subscribe to. 792 * 793 * @return RADIO->EVENTS_CRCOK handle that hardware can subscribe to. 794 */ 795 const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_crcok_event_handle_get(void); 796 797 /**@brief Returns RADIO->EVENTS_PHYEND handle that hardware can subscribe to. 798 * 799 * @return RADIO->EVENTS_PHYEND handle that hardware can subscribe to. 800 */ 801 const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_phyend_event_handle_get(void); 802 803 #ifdef __cplusplus 804 } 805 #endif 806 807 #endif /* NRF_802154_TRX_H_ */ 808
