zephyr
/
hal_nordic
mirror of https://github.com/zephyrproject-rtos/hal_nordic.git
1
0
Fork 0
Code Issues Releases Wiki Activity
hal_nordic/drivers/nrf_802154/driver/src/nrf_802154_trx.h

806 lines
35 KiB
C
Raw Blame History

/*
* Copyright (c) 2019 - 2022, Nordic Semiconductor ASA
* All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1. Redistributions of source code must retain the above copyright notice, this
* list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* 3. Neither the name of Nordic Semiconductor ASA nor the names of its
* contributors may be used to endorse or promote products derived from this
* software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*
*/
/**
* @brief Module that contains radio hardware-related functions
* of the nRF IEEE 802.15.4 radio driver.
*
* @details
*/
#ifndef NRF_802154_TRX_H_
#define NRF_802154_TRX_H_
#include <stdbool.h>
#include <stdint.h>
#include "nrf_802154_config.h"
#include "nrf_802154_sl_types.h"
#include "nrf_802154_types_internal.h"
#ifdef __cplusplus
extern "C" {
#endif
/**@brief States of the FSM of the TRX module. */
typedef enum
{
TRX_STATE_DISABLED = 0,
TRX_STATE_IDLE,
TRX_STATE_GOING_IDLE,
TRX_STATE_RXFRAME,
/* PPIS disabled deconfigured
* RADIO is DISABLED, RXDISABLE
* RADIO shorts are 0
* TIMER is running
* FEM is going to powered or is powered depending if RADIO reached DISABLED
*/
TRX_STATE_RXFRAME_FINISHED,
TRX_STATE_RXACK,
TRX_STATE_TXFRAME,
TRX_STATE_TXACK,
TRX_STATE_STANDALONE_CCA,
TRX_STATE_CONTINUOUS_CARRIER,
TRX_STATE_MODULATED_CARRIER,
TRX_STATE_ENERGY_DETECTION,
/* PPIS disabled deconfigured
* RADIO is DISABLED, TXDISABLE, RXDISABLE
* RADIO shorts are 0
* TIMER is stopped
* FEM is going to powered or is powered depending if RADIO reached DISABLED
*/
TRX_STATE_FINISHED
} trx_state_t;
/**@brief Notifications that can be enabled for @ref nrf_802154_trx_receive_frame operation. */
typedef enum
{
/**@brief No notifications during frame receive provided. */
TRX_RECEIVE_NOTIFICATION_NONE = 0U,
/**@brief Notification @ref nrf_802154_trx_receive_frame_prestarted enabled. */
TRX_RECEIVE_NOTIFICATION_PRESTARTED = (1U << 0),
/**@brief Notification @ref nrf_802154_trx_receive_frame_started enabled. */
TRX_RECEIVE_NOTIFICATION_STARTED = (1U << 1),
} nrf_802154_trx_receive_notifications_t;
/**@brief Notifications that can be enabled for @ref nrf_802154_trx_transmit_frame operation. */
typedef enum
{
/**@brief No notifications during frame transmission provided. */
TRX_TRANSMIT_NOTIFICATION_NONE = 0U,
/**@brief Notification @ref nrf_802154_trx_transmit_frame_ccaidle */
TRX_TRANSMIT_NOTIFICATION_CCAIDLE = (1U << 1),
/**@brief Notification @ref nrf_802154_trx_transmit_frame_ccastarted */
TRX_TRANSMIT_NOTIFICATION_CCASTARTED = (1U << 2)
} nrf_802154_trx_transmit_notifications_t;
/**@brief Initializes trx module.
*
* This function must be called exactly once, before any other API call. This function sets internal state
* of trx module into @c DISABLED. It initializes also those peripherals that are used exclusively
* by trx module and are not shared when trx module is in @c DISABLED state.
*/
void nrf_802154_trx_init(void);
/**@brief Enables trx module.
*
* Effects of call to this function:
* - The RADIO peripheral is fully reset and configured into 802.15.4 mode.
* - FEM module state is set to powered off.
* - PPIs used by trx module are disabled.
* - TIMER used by trx module is shutdown.
* - Trx module is in @c IDLE state
*
* @warning This function may be called when:
* - Trx module was in @c DISABLED state (after @ref nrf_802154_trx_init or after @ref nrf_802154_trx_disable).
* - HFCLK clock is activated.
* - Access to the RADIO peripheral is granted (applicable when the RADIO is shared with other drivers).
*
* @note When trx was in @c DISABLED state, the RADIO might have been controlled by other drivers. Thus
* full reset of the RADIO peripheral is performed.
*/
void nrf_802154_trx_enable(void);
/**@brief Disables trx module.
*
* This function has no effects when the trx module is in @c DISABLED state.
* Otherwise following effects apply:
* - The RADIO peripheral is fully reset.
* - FEM module state is set to powered off.
* - all PPSs used by trx module are disabled and cleared.
* - TIMER used by trx module is shutdown.
* - Trx module is in @c DISABLED state
*
* @note On call to this function any activity of trx module is stopped. If any operation was executing, it
* will be stopped and no handler will be called. After call HFCLK may be deactivated and
* the RADIO peripheral may be passed to other driver.
*/
void nrf_802154_trx_disable(void);
/**
* @brief Updates currently used antenna.
*
* This function sets the antenna to be used based on antenna diversity interface
* configuration and TRX state.
*/
void nrf_802154_trx_antenna_update(void);
/**@brief Sets radio channel to use.
*
* @param[in] channel Channel number to set (11-26).
*/
void nrf_802154_trx_channel_set(uint8_t channel);
/**@brief Updates CCA configuration in the RADIO peripheral according to PIB. */
void nrf_802154_trx_cca_configuration_update(void);
/**@brief Puts the trx module into receive frame mode.
*
* The frame will be received into buffer set by @ref nrf_802154_trx_receive_buffer_set.
*
* When NRF_802154_DISABLE_BCC_MATCHING == 0
* - during receive @ref nrf_802154_trx_receive_frame_started handler is called when
* SHR field of a frame being received is received (only when @p notifications_mask contained @ref TRX_RECEIVE_NOTIFICATION_STARTED flag)
* - during receive @ref nrf_802154_trx_receive_frame_bcmatched handler is called when
* @p bcc octets are received.
* - when a frame is received with correct crc, @ref nrf_802154_trx_receive_frame_received is called
* - when a frame is received with incorrect crc, @ref nrf_802154_trx_receive_frame_crcerror is called
*
* When NRF_802154_DISABLE_BCC_MATCHING != 0
* - @ref nrf_802154_trx_receive_frame_prestarted handler is called when the RADIO initially syncs on received frame.
* This handler is called when @p notifications_mask contains @ref TRX_RECEIVE_NOTIFICATION_PRESTARTED.
* - @ref nrf_802154_trx_receive_frame_started handler is called when
* SHR field of a frame being received is received (only when @p notifications_mask contained @ref TRX_RECEIVE_NOTIFICATION_STARTED flag)
* - after the frame is received with correct crc, @ref nrf_802154_trx_receive_frame_received is called
* - after the frame is received with incorrect crc:
* - when NRF_802154_NOTIFY_CRCERROR == 0:
* - the hardware restarts receive automatically
* - no handler is called
* - when NRF_802154_NOTIFY_CRCERROR != 0:
* - the hardware restarts receive automatically
* - @ref nrf_802154_trx_receive_frame_crcerror is called
*
* When in @ref nrf_802154_trx_receive_frame_received, the TIMER is running allowing sending response (e.g. ACK frame)
* in time regime by a call to nrf_802154_trx_transmit_after_frame_received.
*
* @note To receive ACK use @ref nrf_802154_trx_receive_ack
*
* @param[in] bcc Number of received bytes after which @ref nrf_802154_trx_receive_frame_bcmatched will be called.
* This must not be zero if @ref NRF_802154_DISABLE_BCC_MATCHING == 0.
* When @ref NRF_802154_DISABLE_BCC_MATCHING != 0, this value must be zero.
* @param[in] notifications_mask Selects additional notifications generated during a frame reception.
* It is bitwise combination of @ref nrf_802154_trx_receive_notifications_t values.
* When NRF_802154_DISABLE_BCC_MATCHING != 0, flag @ref TRX_RECEIVE_NOTIFICATION_PRESTARTED is forbidden.
* @param[in] p_ack_tx_power Selects the power which should be used to transmitted an ACK if required.
*/
void nrf_802154_trx_receive_frame(uint8_t bcc,
nrf_802154_trx_receive_notifications_t notifications_mask,
const nrf_802154_fal_tx_power_split_t * p_ack_tx_power);
/**@brief Puts the trx module into receive ACK mode.
*
* The ack frame will be received into buffer set by @ref nrf_802154_trx_receive_buffer_set.
*
* During receive of an ack:
* - @ref nrf_802154_trx_receive_ack_started is called when a frame has just started being received.
* - when a frame is received with correct crc, @ref nrf_802154_trx_receive_ack_received is called.
* - when a frame is received with incorrect crc, @ref nrf_802154_trx_receive_ack_crcerror is called.
* - no bcmatch events are generated.
*/
void nrf_802154_trx_receive_ack(void);
/**@brief Starts RSSI measurement.
*
* @note This function succeeds when TRX module is in receive frame state only (started with @ref nrf_802154_trx_receive_frame)
*
* @retval true When RSSI measurement has been started.
* @retval false When TRX state didn't allow start of RSSI measurement.
*/
bool nrf_802154_trx_rssi_measure(void);
/**@brief Checks if RSSI measurement is currently started.
*
* @retval true When RSSI measurement is currently started. In this case user can
* check if RSSI sample is already available by call to @ref nrf_802154_trx_rssi_sample_is_available.
* @retval false When RSSI measurement is not started.
*/
bool nrf_802154_trx_rssi_measure_is_started(void);
/**@brief Checks if RSSI sample is available.
*
* @retval true When RSSI sample is available. The sample may be read by a call to @ref nrf_802154_trx_rssi_last_sample_get
* @retval false When RSSI sample is unavailable.
*/
bool nrf_802154_trx_rssi_sample_is_available(void);
/**@brief Returns last measured RSSI sample.
*
* @return RSSI sample. Returned value must be scaled using API provided by nrf_802154_rssi.h.
*/
uint8_t nrf_802154_trx_rssi_last_sample_get(void);
/**@brief Check if PSDU is currently being received.
*
* @retval true If trx is in receive mode triggered by @ref nrf_802154_trx_receive_frame and
* a frame receive on air has been started but not finished yet.
* @retval false Otherwise.
*
* @note This function returns false when receive has been triggered by @ref nrf_802154_trx_receive_ack
* regardless of the fact if the frame on air has been started or not.
*/
bool nrf_802154_trx_psdu_is_being_received(void);
/**@brief Checks if current receive operation was started without providing receive buffer.
*
* It may happen that @ref nrf_802154_trx_receive_frame or @ref nrf_802154_trx_receive_ack have been started
* when there was no receive buffer set. The RADIO peripheral will start ramping up, but it will remain
* in @c RXIDLE state, because of missing receive buffer. This function allows to check if such situation
* occurred.
*
* Usually this function may be called by buffer management subsystem when buffer becomes available.
* Consider following code snippet:
* @code
* void buffer_is_available_callback(void * p_buffer)
* {
* if (nrf_802154_trx_receive_is_buffer_missing())
* {
* nrf_802154_trx_receive_buffer_set(p_buffer);
* }
* }
* @endcode
*
* @retval true When in receive mode and receive buffer is missing
* @retval false Otherwise.
*/
bool nrf_802154_trx_receive_is_buffer_missing(void);
/**@brief Sets pointer to a receive buffer.
*
* @param p_receive_buffer If NULL the next call to @ref nrf_802154_trx_receive_frame or
* @ref nrf_802154_trx_receive_ack will not be able to receive.
* If not NULL it must point to MAX_PACKET_SIZE + 1 (see nrf_802154_const.h)
* buffer where received frame will be stored.
*
* @retval true If operation solved missing buffer condition (see @ref nrf_802154_trx_receive_is_buffer_missing)
* and provided buffer will be used in current receive operation.
* @retval false If operation didn't solve missing buffer condition (either no missing buffer or currently
* not in receive mode). Provided buffer will be used in next receive operation.
*/
bool nrf_802154_trx_receive_buffer_set(void * p_receive_buffer);
/**@brief Begins frame transmit operation.
*
* This operation performs differently according to cca parameter.
* When cca==false:
* - The RADIO starts ramp up in transmit mode.
* - The RADIO starts sending synchronization header (SHR).
* - @ref nrf_802154_trx_transmit_frame_started handler is called from an ISR just after SHR is sent
* (only when @ref NRF_802154_TX_STARTED_NOTIFY_ENABLED == 1).
* - @ref nrf_802154_trx_transmit_frame_transmitted handler is called from an ISR after full frame is sent on air.
*
* When cca==true:
* - The radio starts ramp up in receive mode, then it starts cca procedure.
* - The @ref nrf_802154_trx_transmit_frame_ccastarted handler is called from an ISR when
* the RADIO started CCA procedure and @p notifications_mask contained
* @ref TRX_TRANSMIT_NOTIFICATION_CCASTARTED flag.
* - If cca succeded (channel was idle):
* - The RADIO switches to transmit mode (disables receive mode, starts ramp up in transmit mode).
* - The RADIO starts sending sending synchronization header (SHR).
* - If @ref TRX_TRANSMIT_NOTIFICATION_CCAIDLE was present in notifications_mask,
* the @ref nrf_802154_trx_transmit_frame_ccaidle is called.
* - @ref nrf_802154_trx_transmit_frame_started handler is called from an ISR just after SHR is sent
* (only when @ref NRF_802154_TX_STARTED_NOTIFY_ENABLED == 1).
* - @ref nrf_802154_trx_transmit_frame_transmitted handler is called from an ISR after full frame is sent on air.
* - If cca failed (channel was busy):
* - The RADIO disables receive mode
* - @ref nrf_802154_trx_transmit_frame_ccabusy from an ISR handler is called
*
* @param p_transmit_buffer Pointer to a buffer containing frame to transmit.
* Must not be NULL. p_transmit_buffer[0] is the number of
* bytes following p_transmit_buffer[0] to send.
* The number of bytes pointed by p_transmit buffer must
* be at least 1 and not less than p_transmit_buffer[0] + 1.
* @param cca Selects if CCA procedure should be performed prior to
* real transmission. If false no cca will be performed.
* If true, cca will be performed.
* @param p_tx_power Transmit power in dBm.
* @param notifications_mask Selects additional notifications generated during a frame transmission.
* It is bitwise combination of @ref nrf_802154_trx_transmit_notifications_t values.
* @note To transmit ack after frame is received use @ref nrf_802154_trx_transmit_ack.
*/
void nrf_802154_trx_transmit_frame(const void * p_transmit_buffer,
bool cca,
const nrf_802154_fal_tx_power_split_t * p_tx_power,
nrf_802154_trx_transmit_notifications_t notifications_mask);
/**@brief Puts the trx module into transmit ACK mode.
*
* @note This function may be called from @ref nrf_802154_trx_receive_frame_received handler only.
* This is because in this condition only the TIMER peripheral is running and allows timed transmission.
*
* @param[in] p_transmit_buffer Pointer to a buffer containing ACK frame to be transmitted.
* Caller is responsible for preparing an ACK frame according to the 802.15.4 protocol.
* @param[in] delay_us Delay (in microseconds)
*
* @retval true If the function was called in time and ACK frame is scheduled for transmission.
* When transmission starts and @ref NRF_802154_TX_STARTED_NOTIFY_ENABLED != 0
* the function @ref nrf_802154_trx_transmit_ack_started will be called.
* When transmission is finished the function @ref nrf_802154_trx_transmit_ack_transmitted
* will be called.
* @retval false If the function was called too late and given delay_us time gap
* between received frame and ACK frame transmission could not be hold.
* The TIMER peripheral is stopped and it is not possible to trigger @ref nrf_802154_trx_transmit_ack
* again without receiving another frame again. No handlers will be called.
*/
bool nrf_802154_trx_transmit_ack(const void * p_transmit_buffer, uint32_t delay_us);
/**@brief Puts trx module into IDLE mode.
*
* @retval true If entering into IDLE mode started, @ref nrf_802154_trx_go_idle_finished will be called
* (if not aborted by call to @ref nrf_802154_trx_abort or nrf_802154_trx_disable).
* @retval false If already in IDLE mode or just requested @ref nrf_802154_trx_go_idle. There will be
* no @ref nrf_802154_trx_go_idle_finished handler being result of this function.
*/
bool nrf_802154_trx_go_idle(void);
/**@brief Starts standalone cca operation.
*
* Operation ends with a call to @ref nrf_802154_trx_standalone_cca_finished handler from an ISR.
*/
void nrf_802154_trx_standalone_cca(void);
#if NRF_802154_CARRIER_FUNCTIONS_ENABLED
/**@brief Starts generating continuous carrier.
*
* @param[in] p_tx_power Transmit power in dBm.
*
* Generation of a continuous carrier generates no handlers. It may be terminated by a call to
* @ref nrf_802154_trx_abort or @ref nrf_802154_trx_disable.
*/
void nrf_802154_trx_continuous_carrier(const nrf_802154_fal_tx_power_split_t * p_tx_power);
/**@brief Restarts generating continuous carrier
*
* When continuous carrier was being generated and channel change was requested by a call to @ref nrf_802154_trx_channel_set.
* The frequency is not changed automatically. Use @ref nrf_802154_trx_continuous_carrier_restart to
* stop generating continuous carrier on old frequency and start this operation on a new frequency.
* @ref nrf_802154_trx_continuous_carrier_restart is usually faster than
* call to @ref nrf_802154_trx_abort @ref nrf_802154_trx_continuous_carrier
*/
void nrf_802154_trx_continuous_carrier_restart(void);
/**@brief Starts generating modulated carrier with given buffer.
*
* @param[in] p_transmit_buffer Pointer to a buffer used for modulating the carrier wave.
* @param[in] p_tx_power Transmit power in dBm.
*/
void nrf_802154_trx_modulated_carrier(const void * p_transmit_buffer,
const nrf_802154_fal_tx_power_split_t * p_tx_power);
/** @brief Restarts generating modulated carrier.*/
void nrf_802154_trx_modulated_carrier_restart(void);
#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED
/**@brief Puts trx module into energy detection mode.
*
* Operation ends up with a call to @ref nrf_802154_trx_energy_detection_finished handler.
*
* Operation can be terminated with a call to @ref nrf_802154_trx_abort or @ref nrf_802154_trx_disable.
* In this case no handler is called.
*
* @param ed_count Number of iterations to perform. Must be in range 1..2097152.
* One iteration takes 128 microseconds.
*/
void nrf_802154_trx_energy_detection(uint32_t ed_count);
/**@brief Aborts currently performed operation.
*
* When trx module is in @c DISABLED, @c IDLE or @c FINISHED state, this function has no effect.
* Otherwise current operation is terminated and no handler will be generated by the operation
* regardless of its state. In this case trx module will be in @c FINISHED state allowing
* commencement of a next operation.
*/
void nrf_802154_trx_abort(void);
/**@brief Gets current state of the TRX module.
*
* @return Current state of the TRX module.*/
trx_state_t nrf_802154_trx_state_get(void);
/**@brief Handler called at the beginning of a ACK reception.
*
* This handler is called from an ISR when receive of an ack has been started, and
* the RADIO received synchronization header (SHR).
*/
extern void nrf_802154_trx_receive_ack_started(void);
/**@brief Handler called at the beginning of frame reception (earliest possible moment).
*
* This handler is called from an ISR when:
* - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame
* - the RADIO peripheral detected energy on channel or started synchronizing to it.
*
* When this handler is called following holds:
* - trx module is in @c RXFRAME state.
*
* Implementation of @ref nrf_802154_trx_receive_frame_started may call:
* - @ref nrf_802154_trx_abort if current receive frame needs to be aborted
* (usually followed by a call moving the trx module out of @c FINISHED state)
* - @ref nrf_802154_trx_disable
*
* @note This handler may be triggered several times during receive of a preamble
* of a frame. It can be followed by call to @ref nrf_802154_trx_receive_frame_started
* (if enabled) and then by @ref nrf_802154_trx_receive_frame_received or
* @ref nrf_802154_trx_receive_frame_crcerror, but there is possibility
* that it will not be followed by these calls (In case when the RADIO didn't found
* full preamble.). If implementation of this handler starts some
* activity that must be terminated by a further call, it must implement
* its own timeout feature.
*/
extern void nrf_802154_trx_receive_frame_prestarted(void);
/**@brief Handler called at the beginning of frame reception.
*
* This handler is called from an ISR when:
* - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame
* - the RADIO started receiving a frame and has just received SHR field of the frame.
*
* When this handler is called following holds:
* - trx module is in @c RXFRAME state.
*
* Implementation of @ref nrf_802154_trx_receive_frame_started may call:
* - @ref nrf_802154_trx_abort if current receive frame needs to be aborted
* (usually followed by a call moving the trx module out of @c FINISHED state)
* - @ref nrf_802154_trx_disable
*/
extern void nrf_802154_trx_receive_frame_started(void);
/**@brief Handler called during reception of a frame, when given number of bytes is received.
*
* This handler is called from an ISR when given number of bytes (see @ref nrf_802154_trx_receive_frame)
* have been just received.
*
* @note If the handler decides to abort receive by a call to @ref nrf_802154_trx_abort or
* @ref nrf_802154_trx_disable it must return value equal to original bcc parameter passed.
*
* @param[in] bcc Number of bytes that have been already received.
*
* @return Value greater than original value of bcc parameter will cause @ref nrf_802154_trx_receive_frame_bcmatched
* to be called again when further data arrive. Value less than or equal to original bcc value will not cause this
* behavior.
*/
extern uint8_t nrf_802154_trx_receive_frame_bcmatched(uint8_t bcc);
/**@brief Handler called when a frame is received with correct crc.
*
* This handler is called from an ISR when:
* - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame
* - the RADIO received a frame on air with correct crc
*
* When this handler is called following holds:
* - trx module is in @c RXFRAME_FINISHED state.
* - the RADIO peripheral started ramping down (or it ramped down already)
* - TIMER peripheral started counting allowing @ref nrf_802154_trx_transmit_ack
*
* Implementation of @ref nrf_802154_trx_receive_frame_received is responsible for
* leaving @c RXFRAME_FINISHED state. It may do this by call to:
* - @ref nrf_802154_trx_transmit_ack,
* - @ref nrf_802154_trx_receive_frame,
* - @ref nrf_802154_trx_transmit_frame,
* - @ref nrf_802154_trx_go_idle,
* - @ref nrf_802154_trx_disable.
*/
extern void nrf_802154_trx_receive_frame_received(void);
/**@brief Handler called when a frame is received with incorrect crc.
*
* This handler is called from an ISR when:
* - receive operation has been started with a call to @ref nrf_802154_trx_receive_frame
* - the RADIO received a frame on air with incorrect crc
*
* If NRF_802154_DISABLE_BCC_MATCHING == 0:
* When this handler is called following holds:
* - the RADIO peripheral started ramping down (or it ramped down already)
* - trx module is in @c FINISHED state.
*
* Implementation of @ref nrf_802154_trx_receive_frame_crcerror is responsible for
* leaving @c FINISHED state. It may do this by call to:
* - @ref nrf_802154_trx_receive_frame,
* - @ref nrf_802154_trx_transmit_frame,
* - @ref nrf_802154_trx_go_idle,
* - @ref nrf_802154_trx_disable.
*
* If NRF_802154_DISABLE_BCC_MATCHING != 0:
* - the RADIO peripheral is restarted automatically (by hardware) in receive mode
* - trx module stays in @c RXFRAME state
* Implementation of @ref nrf_802154_trx_receive_frame_crcerror should not call
* @ref nrf_802154_trx_receive_frame as receive is restarted automatically by the hardware.
* If the implementation wishes to change state it should call
* @ref nrf_802154_trx_abort first.
*/
extern void nrf_802154_trx_receive_frame_crcerror(void);
/**@brief Handler called when an ack is received with correct crc.
*
* This handler is called from an ISR when:
* - receive ack operation has been started with a call to @ref nrf_802154_trx_receive_ack
* - the RADIO received a frame on air with correct crc
*
* When this handler is called following holds:
* - the RADIO peripheral started ramping down (or it ramped down already)
* - trx module is in @c FINISHED state.
*
* Implementation is responsible for:
* - checking if received frame is an ack and matches previously transmitted frame.
* - leaving @c FINISHED state. It may do this by call to:
* - @ref nrf_802154_trx_receive_frame,
* - @ref nrf_802154_trx_transmit_frame,
* - @ref nrf_802154_trx_go_idle,
* - @ref nrf_802154_trx_disable.
*/
extern void nrf_802154_trx_receive_ack_received(void);
/**@brief Handler called when an ack is received with incorrect crc.
*
* This handler is called from an ISR when:
* - receive ack operation has been started with a call to @ref nrf_802154_trx_receive_ack
* - the RADIO received a frame on air with incorrect crc
*
* When this handler is called following holds:
* - the RADIO peripheral started ramping down (or it ramped down already)
* - trx module is in @c FINISHED state.
*
* Implementation is responsible for:
* - leaving @c FINISHED state. It may do this by call to:
* - @ref nrf_802154_trx_receive_frame,
* - @ref nrf_802154_trx_transmit_frame,
* - @ref nrf_802154_trx_go_idle,
* - @ref nrf_802154_trx_disable.
*/
extern void nrf_802154_trx_receive_ack_crcerror(void);
/**@brief Handler called when a cca operation during transmit attempt started.
*
* This handler is called from an ISR when:
* - transmit operation with cca has been started with a call to @ref nrf_802154_trx_transmit_frame(cca=true).
* - transmit operation was started with parameter @c notifications_mask containing
* TRX_TRANSMIT_NOTIFICATION_CCASTARTED
* - the RADIO peripheral started CCA operation.
*
* Implementation is not responsible for anything related to the trx module since it serves as
* a pure notification of the channel assessment started event during transmission.
*/
extern void nrf_802154_trx_transmit_frame_ccastarted(void);
/**@brief Handler called when a cca operation during transmit attempt was successful.
*
* This handler is called from an ISR when:
* - transmit operation with cca has been started with a call to @ref nrf_802154_trx_transmit_frame(cca=true).
* - the RADIO detected that channel was free.
*
* When this handler is called following holds:
* - the RADIO peripheral started ramping up (or it ramped up already)
* - trx module is in @c TXFRAME state.
*
* Implementation is not responsible for anything since it serves as
* a pure notification of the successful channel assessment during transmission.
*/
extern void nrf_802154_trx_transmit_frame_ccaidle(void);
/**@brief Handler called when a cca operation during transmit attempt failed.
*
* This handler is called from an ISR when:
* - transmit operation with cca has been started with a call to @ref nrf_802154_trx_transmit_frame(cca=true).
* - the RADIO detected that channel was busy.
*
* When this handler is called following holds:
* - the RADIO peripheral started ramping down (or it ramped down already)
* - trx module is in @c FINISHED state.
*
* Implementation is responsible for:
* - leaving @c FINISHED state. It may do this by call to:
* - @ref nrf_802154_trx_receive_frame,
* - @ref nrf_802154_trx_transmit_frame,
* - @ref nrf_802154_trx_go_idle,
* - @ref nrf_802154_trx_disable.
*/
extern void nrf_802154_trx_transmit_frame_ccabusy(void);
/**@brief Handler called when frame transmission has just started.
*
* This handler is called from an ISR when:
* - @ref NRF_802154_TX_STARTED_NOTIFY_ENABLED == 1 (see nrf_802154_config.h)
* - transmit operation was started by a call to @ref nrf_802154_trx_transmit_frame.
* - the RADIO peripheral sent synchronization header
*
* When this handler is called following holds:
* - trx module is in @c TXFRAME state
*
* Implementation may (but does not need to) terminate transmission if it wishes by a call to:
* - @ref nrf_802154_trx_abort,
* - @ref nrf_802154_trx_disable.
*/
extern void nrf_802154_trx_transmit_frame_started(void);
/**@brief Handler called when frame transmission has just been finished.
*
* This handler is called from an ISR when:
* - transmit operation was started by a call to @ref nrf_802154_trx_transmit_frame.
* - the RADIO peripheral sent whole frame on air
*
* When this handler is called following holds:
* - the RADIO peripheral started ramping down (or it ramped down already)
* - trx module is in @c FINISHED state
*
* Implementation is responsible for leaving @c FINISHED state by a call to:
* - @ref nrf_802154_trx_receive_frame,
* - @ref nrf_802154_trx_transmit_frame,
* - @ref nrf_802154_trx_go_idle,
* - @ref nrf_802154_trx_disable.
*/
extern void nrf_802154_trx_transmit_frame_transmitted(void);
/**@brief Handler called when ack transmission has just been started.
*
* This handler is called from an ISR when:
* - @ref NRF_802154_TX_STARTED_NOTIFY_ENABLED == 1 (see nrf_802154_config.h)
* - transmit operation was started by a call to @ref nrf_802154_trx_transmit_ack.
* - the RADIO peripheral sent synchronization header
*
* When this handler is called following holds:
* - trx module is in @c TXACK state
*
* Implementation may (but does not need to) terminate transmission if it wishes by a call to:
* - @ref nrf_802154_trx_abort,
* - @ref nrf_802154_trx_disable.
*/
extern void nrf_802154_trx_transmit_ack_started(void);
/**@brief Handler called when ack transmission has just been finished.
*
* This handler is called from an ISR when:
* - transmit operation was started by a call to @ref nrf_802154_trx_transmit_ack.
* - the RADIO peripheral sent whole ack frame on air
*
* When this handler is called following holds:
* - the RADIO peripheral started ramping down (or it ramped down already)
* - trx module is in @c FINISHED state
*
* Implementation is responsible for leaving @c FINISHED state by a call to:
* - @ref nrf_802154_trx_receive_frame,
* - @ref nrf_802154_trx_transmit_frame,
* - @ref nrf_802154_trx_go_idle,
* - @ref nrf_802154_trx_disable.
*/
extern void nrf_802154_trx_transmit_ack_transmitted(void);
/**@brief Handler called when trx module reached @c IDLE state.
*
* This handler is called from an ISR when:
* - transition to idle state was successfully requested by a call to @ref nrf_802154_trx_go_idle.
* - the RADIO peripheral reached DISABLED state
* - the FEM module has been powered off
*
* When this handler is called following holds:
* - the RADIO is in @c DISABLED state
* - the FEM is powered off
* - trx module is in @c IDLE state
*
* Implementation may leave trx in @c IDLE state or it may request:
* - @ref nrf_802154_trx_receive_frame,
* - @ref nrf_802154_trx_transmit_frame,
* - @ref nrf_802154_trx_disable.
*/
extern void nrf_802154_trx_go_idle_finished(void);
/**@brief Handler called when standalone cca operaion has been just finished.
*
* This handler is called from an ISR when:
* - standalone cca operation was requested by a call to @ref nrf_802154_trx_standalone_cca
* - the RADIO peripheral finished cca operation
*
* When this handler is called following holds:
* - the RADIO peripheral started ramping down (or it ramped down already)
* - trx module is in @c FINISHED state
*
* Implementation is responsible for leaving @c FINISHED state by a call to:
* - @ref nrf_802154_trx_receive_frame,
* - @ref nrf_802154_trx_transmit_frame,
* - @ref nrf_802154_trx_go_idle,
* - @ref nrf_802154_trx_disable.
*
* @param channel_was_idle Informs implementation of the handler if channel was idle.
* true means the channel was idle, false means the channel was busy.
*/
extern void nrf_802154_trx_standalone_cca_finished(bool channel_was_idle);
/**@brief Handler called when energy detection operation has been just finished.
*
* This handler is called from an ISR when:
* - energy detection operation was requested by a call to @ref nrf_802154_trx_energy_detection
* - the RADIO peripheral finished the operation
*
* When this handler is called following holds:
* - the RADIO peripheral started ramping down (or it ramped down already)
* - trx module is in @c FINISHED state
*
* Implementation is responsible for leaving @c FINISHED state by a call to:
* - @ref nrf_802154_trx_receive_frame,
* - @ref nrf_802154_trx_transmit_frame,
* - @ref nrf_802154_trx_go_idle,
* - @ref nrf_802154_trx_disable.
*
* @param ed_sample Sample of detected energy.
*/
extern void nrf_802154_trx_energy_detection_finished(uint8_t ed_sample);
/**@brief Returns RADIO->EVENTS_END handle that hardware can subscribe to.
*
* @return RADIO->EVENTS_END handle that hardware can subscribe to.
*/
const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_end_event_handle_get(void);
/**@brief Returns RADIO->EVENTS_READY handle that hardware can subscribe to.
*
* @return RADIO->EVENTS_READY handle that hardware can subscribe to.
*/
const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_ready_event_handle_get(void);
/**@brief Returns RADIO->EVENTS_CRCOK handle that hardware can subscribe to.
*
* @return RADIO->EVENTS_CRCOK handle that hardware can subscribe to.
*/
const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_crcok_event_handle_get(void);
/**@brief Returns RADIO->EVENTS_PHYEND handle that hardware can subscribe to.
*
* @return RADIO->EVENTS_PHYEND handle that hardware can subscribe to.
*/
const nrf_802154_sl_event_handle_t * nrf_802154_trx_radio_phyend_event_handle_get(void);
#ifdef __cplusplus
}
#endif
#endif /* NRF_802154_TRX_H_ */
Reference in New Issue View Git Blame Copy Permalink