808 lines
36 KiB
C
808 lines
36 KiB
C
/*
|
|
* Copyright (c) 2019 - 2023, 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 Radio ramp up procedure triggering modes. */
|
|
typedef enum
|
|
{
|
|
TRX_RAMP_UP_SW_TRIGGER, ///< Triggering by RADIO_DISABLED, which is a software generated event.
|
|
TRX_RAMP_UP_HW_TRIGGER ///< Triggering by some other event that needs to publish to a dedicated (D)PPI channel.
|
|
} nrf_802154_trx_ramp_up_trigger_mode_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.
|
|
*
|
|
* - 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 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.
|
|
* @param[in] rampup_trigg_mode Radio ramp up triggering mode to be used.
|
|
* If @ref TRX_RAMP_UP_SW_TRIGGER is selected, this function will trigger radio ramp up in a software manner
|
|
* and the caller is guaranteed that ramp up is ongoing when the function ends.
|
|
* If @ref TRX_RAMP_UP_HW_TRIGGER is selected, this function will prepare the operation but it will end
|
|
* without starting radio ramp up. In this case, it is assumed that the trigger will be generated
|
|
* on the (D)PPI channel specified by @ref nrf_802154_trx_ramp_up_ppi_channel_get. It is the user's
|
|
* responsibility to prepare the stimulation of this (D)PPI.
|
|
* @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.
|
|
* @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_ramp_up_trigger_mode_t rampup_trigg_mode,
|
|
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
|
|
*
|
|
* 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
|
|
* - 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 rampup_trigg_mode Radio ramp up triggering mode to be used.
|
|
* If @ref TRX_RAMP_UP_SW_TRIGGER is selected, this function
|
|
* will trigger radio ramp up in a software manner.
|
|
* If @ref TRX_RAMP_UP_HW_TRIGGER is selected, this function
|
|
* will prepare the operation but it will end without starting
|
|
* radio ramp up. In this case, it is assumed that the trigger
|
|
* will be generated on the (D)PPI channel specified by
|
|
* @ref nrf_802154_trx_ramp_up_ppi_channel_get.
|
|
* It is the user's responsibility to prepare the stimulation
|
|
* of this (D)PPI.
|
|
* @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,
|
|
nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode,
|
|
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 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 Gets (D)PPI channel used to trigger ramp up procedure start.
|
|
*/
|
|
uint32_t nrf_802154_trx_ramp_up_ppi_channel_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
|
|
*
|
|
* 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.
|
|
*
|
|
* 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:
|
|
* - 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:
|
|
* - 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_ */
|