zephyr
/
hal_nordic
mirror of https://github.com/zephyrproject-rtos/hal_nordic.git
1
0
Fork 0
Code Issues Releases Wiki Activity

drivers: nrf_802154: Update the IEEE 802.15.4 component 

This commit updates the nRF 802.15.4 radio driver to feature the latest
changes.

sdk-nrf-802154 commit: d08f6e6e546e23fa5894296ed4859111b3b9dc46

Signed-off-by: Andrzej Kuros <andrzej.kuros@nordicsemi.no>
This commit is contained in:
Andrzej Kuros 2023-08-17 10:52:07 +02:00 committed by Robert Lubos
parent cf6e9fc5f7
commit 9ae7c76598
44 changed files with 1340 additions and 2510 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
drivers/nrf_802154/CMakeLists.txt
View File

@ -35,6 +35,8 @@
add_library(nrf-802154-driver-interface INTERFACE)
add_library(nrf-802154-serialization-interface INTERFACE)
add_subdirectory(common)
add_subdirectory(driver)
add_subdirectory(sl)

54
drivers/nrf_802154/common/CMakeLists.txt Normal file
View File

@ -0,0 +1,54 @@
#
# Copyright (c) 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.
#
#
add_library(nrf-802154-common-interface INTERFACE)
target_include_directories(nrf-802154-common-interface
INTERFACE
include
)
add_library(nrf-802154-common STATIC EXCLUDE_FROM_ALL)
target_sources(nrf-802154-common
PRIVATE
src/nrf_802154_common_utils.c
)
target_link_libraries(nrf-802154-common
PUBLIC
nrf-802154-common-interface
nrf-802154-platform
)

487
drivers/nrf_802154/driver/include/nrf_802154.h → drivers/nrf_802154/common/include/nrf_802154.h
View File

@ -44,10 +44,15 @@
#include <stdbool.h>
#include <stdint.h>
#include "nrf_802154_callouts.h"
#include "nrf_802154_config.h"
#include "nrf_802154_types.h"
#include "nrf_802154_common_utils.h"
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
#include "nrf_802154_irq_handlers.h"
#include "nrf_802154_sl_ant_div.h"
#endif // !NRF_802154_SERIALIZATION_HOST
#ifdef __cplusplus
extern "C" {
@ -86,53 +91,14 @@ extern "C" {
*/
void nrf_802154_init(void);
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Deinitializes the 802.15.4 driver.
*
* This function deinitializes the RADIO peripheral and resets it to the default state.
*/
void nrf_802154_deinit(void);
/**
* @brief Perform some additional operations during initialization of the RADIO peripheral.
*
* By implementing this function the higher layer can provide some additional operations
* to be performed at the beginning of each new timeslot. These can in particular be
* modifications of RADIO peripheral register values.
*/
extern void nrf_802154_custom_part_of_radio_init(void);
#if !NRF_802154_INTERNAL_RADIO_IRQ_HANDLING || defined(DOXYGEN)
/**
* @brief Handles the interrupt request from the RADIO peripheral.
*
* @note If @ref NRF_802154_INTERNAL_RADIO_IRQ_HANDLING is enabled, the driver internally handles the
* RADIO IRQ, and this function must not be called.
*
* This function is intended for use in an operating system environment, where the OS handles IRQ
* and indirectly passes it to the driver, or with a RAAL implementation that indirectly passes
* radio IRQ to the driver (that is, SoftDevice).
*/
void nrf_802154_radio_irq_handler(void);
#endif // !NRF_802154_INTERNAL_RADIO_IRQ_HANDLING
#if !NRF_802154_INTERNAL_SWI_IRQ_HANDLING || defined(DOXYGEN)
/**
* @brief Handles the interrupt request from the RADIO peripheral.
*
* @note If @ref NRF_802154_INTERNAL_SWI_IRQ_HANDLING is enabled, the driver internally handles the
* SWI IRQ, and this function must not be called.
*
* This function is intended for use in an operating system environment, where the OS handles IRQ
* and indirectly passes it to the driver, or with a RAAL implementation that indirectly passes
* radio IRQ to the driver (that is, SoftDevice).
*/
void nrf_802154_swi_irq_handler(void);
#endif // !NRF_802154_INTERNAL_SWI_IRQ_HANDLING
#endif // !NRF_802154_SERIALIZATION_HOST
/**
* @brief Sets the channel on which the radio is to operate.
@ -165,6 +131,8 @@ void nrf_802154_tx_power_set(int8_t power);
*/
int8_t nrf_802154_tx_power_get(void);
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Sets the antenna diversity rx mode.
*
@ -325,6 +293,8 @@ bool nrf_802154_antenna_diversity_init(void);
*/
void nrf_802154_antenna_diversity_timer_irq_handler(void);
#endif // !NRF_802154_SERIALIZATION_HOST
/**
* @brief Gets the current time.
*
@ -367,89 +337,7 @@ void nrf_802154_extended_address_set(const uint8_t * p_extended_address);
*/
void nrf_802154_short_address_set(const uint8_t * p_short_address);
/**
* @}
* @defgroup nrf_802154_data Functions to calculate data given by the driver
* @{
*/
/**
* @brief Converts the energy level received during the energy detection procedure to a dBm value.
*
* @param[in] energy_level Energy level passed by @ref nrf_802154_energy_detected.
*
* @return Result of the energy detection procedure in dBm.
*/
int8_t nrf_802154_dbm_from_energy_level_calculate(uint8_t energy_level);
/**
* @brief Converts a given dBm level to a CCA energy detection threshold value.
*
* @param[in] dbm Energy level in dBm used to calculate the CCAEDTHRES value.
*
* @return Energy level value corresponding to the given dBm level that is to be written to
* the CCACTRL register.
*/
uint8_t nrf_802154_ccaedthres_from_dbm_calculate(int8_t dbm);
/**
* @brief Calculates the timestamp of the first symbol of the preamble in a received frame.
*
* @deprecated This function is deprecated. Use @ref nrf_802154_timestamp_end_to_phr_convert
* instead and adjust the code that calls this function to rely on the timestamp of the first symbol
* of the PHR, not the timestamp of the first symbol of the frame.
*
* @param[in] end_timestamp Timestamp of the end of the last symbol in the frame,
* in microseconds.
* @param[in] psdu_length Number of bytes in the frame PSDU.
*
* @return Timestamp of the beginning of the first preamble symbol of a given frame,
* in microseconds.
*/
uint64_t nrf_802154_first_symbol_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length);
/**
* @brief Calculates the timestamp of the MAC Header in a received frame.
*
* @deprecated This function is deprecated. Use @ref nrf_802154_timestamp_end_to_phr_convert
* instead and adjust the code that calls this function to rely on the timestamp of the first symbol
* of the PHR, not the MAC Header timestamp.
*
* @param[in] end_timestamp Timestamp of the end of the last symbol in the frame,
* in microseconds.
* @param[in] psdu_length Number of bytes in the frame PSDU.
*
* @return Timestamp of the MHR of a given frame, in microseconds.
*/
uint64_t nrf_802154_mhr_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length);
/**
* @brief Converts the timestamp of the frame's end to the timestamp of the start of its PHR.
*
* This function calculates the time when the first symbol of the PHR is at the local antenna. Note
* that this time is equivalent to: the end of the frame's SFD and RMARKER as defined in'
* IEEE 802.15.4-2020, Section 6.9.1.
*
* @param[in] end_timestamp Timestamp of the end of the last symbol in the frame,
* in microseconds.
* @param[in] psdu_length Number of bytes in the frame PSDU.
*
* @return Timestamp of the start of the PHR of a given frame, in microseconds.
*/
uint64_t nrf_802154_timestamp_end_to_phr_convert(uint64_t end_timestamp, uint8_t psdu_length);
/**
* @brief Converts the timestamp of the frame's PHR to the timestamp of the start of its SHR.
*
* This function converts the time when the first symbol of the frame's PHR is at the local antenna
* to the timestamp of the start of the frame's SHR.
*
* @param[in] phr_timestamp Timestamp of the frame's PHR.
*
* @return Timestamp of the start of the SHR of a given frame, in microseconds.
*/
uint64_t nrf_802154_timestamp_phr_to_shr_convert(uint64_t phr_timestamp);
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @}
* @defgroup nrf_802154_transitions Functions to request FSM transitions and check current state
@ -460,6 +348,7 @@ uint64_t nrf_802154_timestamp_phr_to_shr_convert(uint64_t phr_timestamp);
* @brief Gets the current state of the radio.
*/
nrf_802154_state_t nrf_802154_state_get(void);
#endif // !NRF_802154_SERIALIZATION_HOST
/**
* @brief Changes the radio state to the @ref RADIO_STATE_SLEEP state.
@ -605,6 +494,7 @@ bool nrf_802154_transmit_raw(uint8_t * p_data,
#endif // NRF_802154_USE_RAW_API
#if !NRF_802154_USE_RAW_API || defined(DOXYGEN)
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Changes the radio state to transmit.
@ -655,6 +545,7 @@ bool nrf_802154_transmit(const uint8_t * p_data,
uint8_t length,
const nrf_802154_transmit_metadata_t * p_metadata);
#endif // !NRF_802154_SERIALIZATION_HOST
#endif // !NRF_802154_USE_RAW_API
/**
@ -673,7 +564,36 @@ bool nrf_802154_transmit(const uint8_t * p_data,
* or the requested transmission timeslot is denied, @ref nrf_802154_transmit_failed with the
* @ref NRF_802154_TX_ERROR_TIMESLOT_DENIED argument is called.
*
* This function is designed to transmit the first symbol of SHR at the given time.
* Additional CCA attempts can be requested by the caller through @p p_metadata. In that case CCA
* procedure is repeated back-to-back either until it returns idle channel and the transmission
* starts, or until 1 + @p p_metadata->extra_cca_attempts CCA attempts are performed. The maximum
* allowed number of additional CCA attempts is 254 so that the total number of CCA attempts doesn't
* exceed 255.
*
* This function is designed to transmit the first symbol of SHR at @p tx_time provided that
* the number of CCA attempts that will be performed is deterministic, which is only the case when
* no attempts are performed or when a single attempt is performed. Otherwise, the function assumes
* that @p tx_time points to a moment where the transmission would start if the first CCA attempt
* detected idle channel. If the first CCA detects busy channel and additional CCA attempts follow,
* the moment of transmission (first symbol of SHR) is delayed by the time taken by additional CCA
* attempts, which is a multiple of the duration of a single CCA attempt.
*
* The below diagram shows an example sequence where two additional CCA attempts are performed.
* TT denotes turnaround time necessary to switch from CCA to Tx. @p tx_time points to a moment in
* time that occurs TT after the first CCA finishes.
*
* @verbatim
* tx_time frame start
* | |
* | |
* v v
* +---------+---------+---------+--+----------+-----+-------------------------+
* | CCA | CCA | CCA |TT| SHR | PHR | MAC Header and payload |
* +---------+---------+---------+--+----------+-----+-------------------------+
* | | |
* v v v
* BUSY BUSY IDLE
* @endverbatim
*
* If the requested transmission time is in the past, the function returns @c false and does not
* schedule transmission.
@ -685,15 +605,16 @@ bool nrf_802154_transmit(const uint8_t * p_data,
* the frame length (including FCS). The following bytes contain data.
* The CRC is computed automatically by the radio hardware. Therefore,
* the FCS field can contain any bytes.
* @param[in] tx_time Absolute time used by the SL Timer,
* in microseconds (us).
* @param[in] tx_time Absolute time used by the SL Timer, in microseconds (us).
* @param[in] p_metadata Pointer to metadata structure. Contains detailed properties of data
* to transmit. If @c NULL following metadata are used:
* Field | Value
* ----------------|-----------------------------------------------------
* @c frame_props | @ref NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT
* @c cca | @c true
* @c channel | As returned by @ref nrf_802154_channel_get
* Field | Value
* ----------------------|-----------------------------------------------------
* @c frame_props | @ref NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT
* @c cca | @c true
* @c channel | As returned by @ref nrf_802154_channel_get
* @c tx_power | As set with @ref nrf_802154_tx_power_set
* @c extra_cca_attempts | @c 0
*
* @retval true The transmission procedure was scheduled.
* @retval false The driver could not schedule the transmission procedure.
@ -772,280 +693,14 @@ bool nrf_802154_continuous_carrier(void);
* selected channel. This function is to be called only during radio tests. Do not
* use it during normal device operation.
*
* @param[in] p_data Pointer to a buffer to modulate the carrier with.
* @param[in] p_data Pointer to a buffer to modulate the carrier with. The first byte is the data length.
*
* @retval true The modulated carrier procedure was scheduled.
* @retval false The driver could not schedule the modulated carrier procedure.
*/
bool nrf_802154_modulated_carrier(const uint8_t * p_data);
/**
* @}
* @defgroup nrf_802154_calls Calls to higher layer
* @{
*/
#endif
/**
* @brief Notifies about the start of the ACK frame transmission.
*
* @note This function must be very short to prevent dropping frames by the driver.
*
* @param[in] p_data Pointer to a buffer with PHR and PSDU of the ACK frame.
*/
extern void nrf_802154_tx_ack_started(const uint8_t * p_data);
#if NRF_802154_USE_RAW_API || defined(DOXYGEN)
/**
* @brief Notifies that a frame was received.
*
* @note The buffer pointed to by @p p_data is not modified by the radio driver (and cannot be used
* to receive a frame) until @ref nrf_802154_buffer_free_raw is called.
* @note The buffer pointed to by @p p_data may be modified by the function handler (and other
* modules) until @ref nrf_802154_buffer_free_raw is called.
* @note This callout is called by the nRF 802.15.4 Radio Driver if @ref NRF_802154_USE_RAW_API
* is enabled. Default implementation of this function provided by
* the nRF 802.15.4 Radio Driver calls @ref nrf_802154_received_timestamp_raw .
*
* @verbatim
* p_data
* v
* +-----+-----------------------------------------------------------+------------+
* | PHR | MAC Header and payload | FCS |
* +-----+-----------------------------------------------------------+------------+
* | |
* | <---------------------------- PHR -----------------------------------> |
* @endverbatim
*
* @param[in] p_data Pointer to a buffer that contains PHR and PSDU of the received frame.
* The first byte in the buffer is the length of the frame (PHR). The following
* bytes contain the frame itself (PSDU). The length byte (PHR) includes FCS.
* FCS is already verified by the hardware and may be modified by the hardware.
* @param[in] power RSSI of the received frame.
* @param[in] lqi LQI of the received frame.
*/
extern void nrf_802154_received_raw(uint8_t * p_data, int8_t power, uint8_t lqi);
/**
* @brief Notifies that a frame was received at a given time.
*
* This function works like @ref nrf_802154_received_raw and adds a timestamp to the parameter
* list.
*
* @note The received frame usually contains a timestamp. However, due to a race condition,
* the timestamp may be invalid. This erroneous situation is indicated by
* the @ref NRF_802154_NO_TIMESTAMP value of the @p time parameter.
*
* @note This callout is called by the default implementation of @ref nrf_802154_received_raw.
*
* @param[in] p_data Pointer to a buffer that contains PHR and PSDU of the received frame.
* The first byte in the buffer is the length of the frame (PHR). The following
* bytes contain the frame itself (PSDU). The length byte (PHR) includes FCS.
* FCS is already verified by the hardware and may be modified by the hardware.
* @param[in] power RSSI of the received frame.
* @param[in] lqi LQI of the received frame.
* @param[in] time Timestamp taken when the last symbol of the frame was received, in
* microseconds (us), or @ref NRF_802154_NO_TIMESTAMP if the timestamp
* is invalid.
*/
extern void nrf_802154_received_timestamp_raw(uint8_t * p_data,
int8_t power,
uint8_t lqi,
uint64_t time);
#endif // NRF_802154_USE_RAW_API
#if !NRF_802154_USE_RAW_API || defined(DOXYGEN)
/**
* @brief Notifies that a frame was received.
*
* @note The buffer pointed to by @p p_data is not modified by the radio driver (and cannot
* be used to receive a frame) until @ref nrf_802154_buffer_free is called.
* @note The buffer pointed to by @p p_data can be modified by the function handler (and other
* modules) until @ref nrf_802154_buffer_free is called.
* @note This callout is called by the nRF 802.15.4 Radio Driver if @ref NRF_802154_USE_RAW_API
* is disabled. Default implementation of this function provided by
* the nRF 802.15.4 Radio Driver calls @ref nrf_802154_received_timestamp .
*
* @verbatim
* p_data
* v
* +-----+-----------------------------------------------------------+------------+
* | PHR | MAC Header and payload | FCS |
* +-----+-----------------------------------------------------------+------------+
* | |
* | <------------------ length -----------------------------> |
* @endverbatim
*
* @param[in] p_data Pointer to a buffer that contains only the payload of the received frame
* (PSDU without FCS).
* @param[in] length Length of the received payload.
* @param[in] power RSSI of the received frame.
* @param[in] lqi LQI of the received frame.
*/
extern void nrf_802154_received(uint8_t * p_data, uint8_t length, int8_t power, uint8_t lqi);
/**
* @brief Notifies that a frame was received at a given time.
*
* This function works like @ref nrf_802154_received and adds a timestamp to the parameter list.
*
* @note The received frame usually contains a timestamp. However, due to a race condition,
* the timestamp may be invalid. This erroneous situation is indicated by
* the @ref NRF_802154_NO_TIMESTAMP value of the @p time parameter.
* @note This callout is called by the default implementation of @ref nrf_802154_received .
*
* @param[in] p_data Pointer to a buffer that contains only the payload of the received frame
* (PSDU without FCS).
* @param[in] length Length of the received payload.
* @param[in] power RSSI of the received frame.
* @param[in] lqi LQI of the received frame.
* @param[in] time Timestamp taken when the last symbol of the frame was received,
* in microseconds (us), or @ref NRF_802154_NO_TIMESTAMP if the timestamp
* is invalid.
*/
extern void nrf_802154_received_timestamp(uint8_t * p_data,
uint8_t length,
int8_t power,
uint8_t lqi,
uint32_t time);
#endif // !NRF_802154_USE_RAW_API
/**
* @brief Notifies that the reception of a frame failed.
*
* @param[in] error Error code that indicates the reason of the failure.
* @param[in] id Identifier of reception window the error occurred in.
* If the error is related to a delayed reception window requested through
* @ref nrf_802154_receive_at, the value of @p id equals the identifier
* of the scheduled reception window. Otherwise, the value of @p id equals
* @ref NRF_802154_RESERVED_IMM_RX_WINDOW_ID.
*/
extern void nrf_802154_receive_failed(nrf_802154_rx_error_t error, uint32_t id);
/**
* @brief Notifies that transmitting a frame has started.
*
* @note Usually, @ref nrf_802154_transmitted is called shortly after this function.
* However, if the transmit procedure is interrupted, it might happen that
* @ref nrf_802154_transmitted is not called.
* @note This function should be very short to prevent dropping frames by the driver.
*
* @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame being
* transmitted.
*/
extern void nrf_802154_tx_started(const uint8_t * p_frame);
#if NRF_802154_USE_RAW_API || defined(DOXYGEN)
/**
* @brief Notifies that a frame was transmitted.
*
* @note If ACK was requested for the transmitted frame, this function is called after a proper ACK
* is received. If ACK was not requested, this function is called just after transmission has
* ended.
* @note The buffer pointed to by @c nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack
* is not modified by the radio driver (and cannot be used to receive a frame) until
* @ref nrf_802154_buffer_free_raw is called.
* @note The buffer pointed to by @c nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack
* may be modified by the function handler (and other modules) until
* @ref nrf_802154_buffer_free_raw is called.
* @note @c nrf_802154_transmit_done_metadata_t::data.transmitted.time granularity depends on the
* granularity of the timer driver in the
* platform/timer directory.
* @note This callout is called by the nRF 802.15.4 Radio Driver if @ref NRF_802154_USE_RAW_API
* is enabled.
*
* @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the transmitted frame.
* @param[in] p_metadata Pointer to a metadata structure describing frame passed in @p p_frame.
*/
extern void nrf_802154_transmitted_raw(uint8_t * p_frame,
const nrf_802154_transmit_done_metadata_t * p_metadata);
#endif // NRF_802154_USE_RAW_API
#if !NRF_802154_USE_RAW_API || defined(DOXYGEN)
/**
* @brief Notifies that a frame was transmitted.
*
* @note If ACK was requested for the transmitted frame, this function is called after a proper ACK
* is received. If ACK was not requested, this function is called just after transmission has
* ended.
* @note The buffer pointed to by @c nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack
* is not modified by the radio driver (and cannot be used to receive a frame) until
* @ref nrf_802154_buffer_free is called.
* @note The buffer pointed to by @c nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack
* may be modified by the function handler (and other modules) until
* @ref nrf_802154_buffer_free is called.
* @note The next higher layer must handle either @ref nrf_802154_transmitted or
* @ref nrf_802154_transmitted_raw. It should not handle both functions.
* @note @c nrf_802154_transmit_done_metadata_t::data.transmitted.time granularity depends on the
* granularity of the timer driver in the platform/timer directory.
* @note Including a timestamp for received frames uses resources like CPU time and memory. If the
* timestamp is not required, use @ref nrf_802154_received instead.
* @note This callout is called by the nRF 802.15.4 Radio Driver if @ref NRF_802154_USE_RAW_API
* is disabled.
*
* @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the transmitted frame.
* @param[in] p_metadata Pointer to a metadata structure describing frame passed in @p p_frame.
*/
extern void nrf_802154_transmitted(uint8_t * p_frame,
const nrf_802154_transmit_done_metadata_t * p_metadata);
#endif // !NRF_802154_USE_RAW_API
/**
* @brief Notifies that a frame was not transmitted due to a busy channel.
*
* This function is called if the transmission procedure fails.
*
* @note Frame data values in @ref nrf_802154_transmit_done_metadata_t::data are invalid for
* @ref nrf_802154_transmit_failed callout.
*
* @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame that was not
* transmitted.
* @param[in] error Reason of the failure.
* @param[in] p_metadata Pointer to a metadata structure describing frame passed in @p p_frame.
*/
extern void nrf_802154_transmit_failed(uint8_t * p_frame,
nrf_802154_tx_error_t error,
const nrf_802154_transmit_done_metadata_t * p_metadata);
/**
* @brief Notifies that the energy detection procedure finished.
*
* @note This function passes the EnergyLevel defined in the 802.15.4-2006 specification:
* 0x00 - 0xff, where 0x00 represents -75dBm (10dBm above the worst allowed sensitivity level,
* which is -85dBm) and 0xff is the highest possible energy detection level, for which
* the measurements are guaranteed map linearly to the real energy level in dBm.
* To calculate the result in dBm, use @ref nrf_802154_dbm_from_energy_level_calculate.
*
* @param[in] result Maximum energy detected during the energy detection procedure.
*/
extern void nrf_802154_energy_detected(uint8_t result);
/**
* @brief Notifies that the energy detection procedure failed.
*
* @param[in] error Reason of the failure.
*/
extern void nrf_802154_energy_detection_failed(nrf_802154_ed_error_t error);
/**
* @brief Notifies that the CCA procedure has finished.
*
* @param[in] channel_free Indication if the channel is free.
*/
extern void nrf_802154_cca_done(bool channel_free);
/**
* @brief Notifies that the CCA procedure failed.
*
* @param[in] error Reason of the failure.
*/
extern void nrf_802154_cca_failed(nrf_802154_cca_error_t error);
#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED
/**
* @}
@ -1068,6 +723,7 @@ extern void nrf_802154_cca_failed(nrf_802154_cca_error_t error);
*/
void nrf_802154_buffer_free_raw(uint8_t * p_data);
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Notifies the driver that the buffer containing the received frame is not used anymore.
*
@ -1084,10 +740,12 @@ void nrf_802154_buffer_free_raw(uint8_t * p_data);
* @retval false Buffer cannot be freed right now due to ongoing operation.
*/
bool nrf_802154_buffer_free_immediately_raw(uint8_t * p_data);
#endif // !NRF_802154_SERIALIZATION_HOST
#endif // NRF_802154_USE_RAW_API
#if !NRF_802154_USE_RAW_API || defined(DOXYGEN)
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Notifies the driver that the buffer containing the received frame is not used anymore.
@ -1119,6 +777,7 @@ void nrf_802154_buffer_free(uint8_t * p_data);
*/
bool nrf_802154_buffer_free_immediately(uint8_t * p_data);
#endif // !NRF_802154_SERIALIZATION_HOST
#endif // !NRF_802154_USE_RAW_API
/**
@ -1127,6 +786,7 @@ bool nrf_802154_buffer_free_immediately(uint8_t * p_data);
* @{
*/
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Begins the RSSI measurement.
*
@ -1148,6 +808,8 @@ bool nrf_802154_rssi_measure_begin(void);
*/
int8_t nrf_802154_rssi_last_get(void);
#endif // !NRF_802154_SERIALIZATION_HOST
/**
* @}
* @defgroup nrf_802154_prom Promiscuous mode
@ -1169,6 +831,7 @@ int8_t nrf_802154_rssi_last_get(void);
*/
void nrf_802154_promiscuous_set(bool enabled);
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Checks if the radio is in the promiscuous mode.
*
@ -1209,6 +872,8 @@ void nrf_802154_auto_ack_set(bool enabled);
*/
bool nrf_802154_auto_ack_get(void);
#endif // !NRF_802154_SERIALIZATION_HOST
/**
* @brief Configures the device as the PAN coordinator.
*
@ -1218,6 +883,7 @@ bool nrf_802154_auto_ack_get(void);
*/
void nrf_802154_pan_coord_set(bool enabled);
#if NRF_802154_PAN_COORD_GET_ENABLED || defined(DOXYGEN)
/**
* @brief Checks if the radio is configured as the PAN coordinator.
*
@ -1226,11 +892,17 @@ void nrf_802154_pan_coord_set(bool enabled);
*/
bool nrf_802154_pan_coord_get(void);
#endif // NRF_802154_PAN_COORD_GET_ENABLED
/**
* @brief Select the source matching algorithm.
*
* @note This method should be called after driver initialization, but before transceiver is enabled.
*
* When calling @ref nrf_802154_ack_data_pending_bit_should_be_set, one of several algorithms
* for source address matching will be chosen. To ensure a specific algorithm is selected,
* call this function before @ref nrf_802154_ack_data_pending_bit_should_be_set.
*
* @param[in] match_method Source address matching method to be used.
*/
void nrf_802154_src_addr_matching_method_set(nrf_802154_src_addr_match_t match_method);
@ -1462,6 +1134,7 @@ bool nrf_802154_transmit_csma_ca_raw(uint8_t
#else // NRF_802154_USE_RAW_API
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Performs the CSMA-CA procedure and transmits a frame in case of success.
*
@ -1492,6 +1165,7 @@ bool nrf_802154_transmit_csma_ca_raw(uint8_t
bool nrf_802154_transmit_csma_ca(const uint8_t * p_data,
uint8_t length,
const nrf_802154_transmit_csma_ca_metadata_t * p_metadata);
#endif // !NRF_802154_SERIALIZATION_HOST
#endif // NRF_802154_USE_RAW_API
@ -1559,6 +1233,7 @@ uint8_t nrf_802154_csma_ca_max_backoffs_get(void);
#endif // NRF_802154_CSMA_CA_ENABLED
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @}
* @defgroup nrf_802154_timeout ACK timeout procedure
@ -1578,6 +1253,8 @@ uint8_t nrf_802154_csma_ca_max_backoffs_get(void);
*/
void nrf_802154_ack_timeout_set(uint32_t time);
#endif // !NRF_802154_SERIALIZATION_HOST
#endif // NRF_802154_ACK_TIMEOUT_ENABLED
/**
@ -1586,6 +1263,8 @@ void nrf_802154_ack_timeout_set(uint32_t time);
* @{
*/
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Enables wifi coex signaling.
*
@ -1657,12 +1336,15 @@ bool nrf_802154_coex_tx_request_mode_set(nrf_802154_coex_tx_request_mode_t mode)
*/
nrf_802154_coex_tx_request_mode_t nrf_802154_coex_tx_request_mode_get(void);
#endif // !NRF_802154_SERIALIZATION_HOST
/**
* @}
* @defgroup nrf_802154_stats Statistics and measurements
* @{
*/
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Gets current statistics.
*
@ -1690,6 +1372,8 @@ void nrf_802154_stat_counters_get(nrf_802154_stat_counters_t * p_stat_counters);
*/
void nrf_802154_stat_counters_subtract(const nrf_802154_stat_counters_t * p_stat_counters);
#endif // !NRF_802154_SERIALIZATION_HOST
/**
* @brief Get time stamps of events gathered by the last operation.
*
@ -1697,6 +1381,7 @@ void nrf_802154_stat_counters_subtract(const nrf_802154_stat_counters_t * p_stat
*/
void nrf_802154_stat_timestamps_get(nrf_802154_stat_timestamps_t * p_stat_timestamps);
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Resets current stat counters to 0.
*
@ -1706,6 +1391,8 @@ void nrf_802154_stat_timestamps_get(nrf_802154_stat_timestamps_t * p_stat_timest
*/
void nrf_802154_stat_counters_reset(void);
#endif // !NRF_802154_SERIALIZATION_HOST
/**
* @}
* @defgroup nrf_802154_ifs Inter-frame spacing feature

356
drivers/nrf_802154/common/include/nrf_802154_callouts.h Normal file
View File

@ -0,0 +1,356 @@
/*
* Copyright (c) 2017 - 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.
*
*/
/**@file nrf_802154_callouts.h
* @brief Provides function prototypes required by nRF 802.15.4 Radio Driver
*
* Functions whose prototypes are defined in this file are to be implemented
* by an application using the nRF 802.15.4 Radio Driver.
*/
/**
* @defgroup nrf_802154_calls Calls to higher layer
* @{
*/
#ifndef NRF_802154_CALLOUTS_H_
#define NRF_802154_CALLOUTS_H_
#include <stdint.h>
#include <stdbool.h>
#include "nrf_802154_config.h"
#include "nrf_802154_types.h"
/**
* @brief Notifies that the CCA procedure has finished.
*
* @param[in] channel_free Indication if the channel is free.
*/
extern void nrf_802154_cca_done(bool channel_free);
/**
* @brief Notifies that the CCA procedure failed.
*
* @param[in] error Reason of the failure.
*/
extern void nrf_802154_cca_failed(nrf_802154_cca_error_t error);
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
/**
* @brief Notifies that the energy detection procedure finished.
*
* @param[in] p_result Pointer to structure containing the result of the operation.
* The pointer is valid within the @ref nrf_802154_energy_detected only.
*/
extern void nrf_802154_energy_detected(const nrf_802154_energy_detected_t * p_result);
#else
/**
* @brief Notifies that the energy detection procedure finished.
*
* @note This function passes the EnergyLevel defined in the 802.15.4-2006 specification:
* 0x00 - 0xff, where 0x00 represents -75dBm (10dBm above the worst allowed sensitivity level,
* which is -85dBm) and 0xff is the highest possible energy detection level, for which
* the measurements are guaranteed map linearly to the real energy level in dBm.
* To calculate the result in dBm, use @ref nrf_802154_dbm_from_energy_level_calculate.
*
* @param[in] result Maximum energy detected during the energy detection procedure.
*/
extern void nrf_802154_energy_detected(uint8_t result);
#endif
/**
* @brief Notifies that the energy detection procedure failed.
*
* @param[in] error Reason of the failure.
*/
extern void nrf_802154_energy_detection_failed(nrf_802154_ed_error_t error);
/**
* @brief Notifies about the start of the ACK frame transmission.
*
* @note If a call to this function is performed by the same CPU running core
* of nRF 802.15.4 Radio Driver (non serialized call to @ref nrf_802154_tx_ack_started)
* the function must be very short to prevent dropping frames by the driver.
* If a call to this function is performed by a CPU through a serialization layer
* the call can be slightly delayed. The call can happen even after an ACK frame
* is fully transmitted. It is guaranteed that a call to @ref nrf_802154_tx_ack_started
* occurs before a call to @ref nrf_802154_received_timestamp_raw related to
* the same received frame.
*
* @param[in] p_data Pointer to a buffer with PHR and PSDU of the ACK frame.
*/
extern void nrf_802154_tx_ack_started(const uint8_t * p_data);
#if NRF_802154_USE_RAW_API || defined(DOXYGEN)
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Notifies that a frame was received.
*
* @note Currently this callout is only available on the CPU which is running the core of the radio driver.
* If the higher layer runs on a different core it should use nrf_802154_received_timestamp_raw instead.
* @note The buffer pointed to by @p p_data is not modified by the radio driver (and cannot be used
* to receive a frame) until @ref nrf_802154_buffer_free_raw is called.
* @note The buffer pointed to by @p p_data may be modified by the function handler (and other
* modules) until @ref nrf_802154_buffer_free_raw is called.
* @note This callout is called by the nRF 802.15.4 Radio Driver if @ref NRF_802154_USE_RAW_API
* is enabled. Default implementation of this function provided by
* the nRF 802.15.4 Radio Driver calls @ref nrf_802154_received_timestamp_raw .
*
* @verbatim
* p_data
* v
* +-----+-----------------------------------------------------------+------------+
* | PHR | MAC Header and payload | FCS |
* +-----+-----------------------------------------------------------+------------+
* | |
* | <---------------------------- PHR -----------------------------------> |
* @endverbatim
*
* @param[in] p_data Pointer to a buffer that contains PHR and PSDU of the received frame.
* The first byte in the buffer is the length of the frame (PHR). The following
* bytes contain the frame itself (PSDU). The length byte (PHR) includes FCS.
* FCS is already verified by the hardware and may be modified by the hardware.
* @param[in] power RSSI of the received frame.
* @param[in] lqi LQI of the received frame.
*/
extern void nrf_802154_received_raw(uint8_t * p_data, int8_t power, uint8_t lqi);
#endif // !NRF_802154_SERIALIZATION_HOST
/**
* @brief Notifies that a frame was received at a given time.
*
* This function works like @ref nrf_802154_received_raw and adds a timestamp to the parameter
* list.
*
* @note The received frame usually contains a timestamp. However, due to a race condition,
* the timestamp may be invalid. This erroneous situation is indicated by
* the @ref NRF_802154_NO_TIMESTAMP value of the @p time parameter.
*
* @param[in] p_data Pointer to a buffer that contains PHR and PSDU of the received frame.
* The first byte in the buffer is the length of the frame (PHR). The following
* bytes contain the frame itself (PSDU). The length byte (PHR) includes FCS.
* FCS is already verified by the hardware and may be modified by the hardware.
* @param[in] power RSSI of the received frame.
* @param[in] lqi LQI of the received frame.
* @param[in] time Timestamp taken when the last symbol of the frame was received, in
* microseconds (us), or @ref NRF_802154_NO_TIMESTAMP if the timestamp
* is invalid.
*/
extern void nrf_802154_received_timestamp_raw(uint8_t * p_data,
int8_t power,
uint8_t lqi,
uint64_t time);
#endif // NRF_802154_USE_RAW_API
#if !NRF_802154_USE_RAW_API || defined(DOXYGEN)
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Notifies that a frame was received.
*
* @note The buffer pointed to by @p p_data is not modified by the radio driver (and cannot
* be used to receive a frame) until @ref nrf_802154_buffer_free is called.
* @note The buffer pointed to by @p p_data can be modified by the function handler (and other
* modules) until @ref nrf_802154_buffer_free is called.
* @note This callout is called by the nRF 802.15.4 Radio Driver if @ref NRF_802154_USE_RAW_API
* is disabled. Default implementation of this function provided by
* the nRF 802.15.4 Radio Driver calls @ref nrf_802154_received_timestamp .
*
* @verbatim
* p_data
* v
* +-----+-----------------------------------------------------------+------------+
* | PHR | MAC Header and payload | FCS |
* +-----+-----------------------------------------------------------+------------+
* | |
* | <------------------ length -----------------------------> |
* @endverbatim
*
* @param[in] p_data Pointer to a buffer that contains only the payload of the received frame
* (PSDU without FCS).
* @param[in] length Length of the received payload.
* @param[in] power RSSI of the received frame.
* @param[in] lqi LQI of the received frame.
*/
extern void nrf_802154_received(uint8_t * p_data, uint8_t length, int8_t power, uint8_t lqi);
/**
* @brief Notifies that a frame was received at a given time.
*
* This function works like @ref nrf_802154_received and adds a timestamp to the parameter list.
*
* @note The received frame usually contains a timestamp. However, due to a race condition,
* the timestamp may be invalid. This erroneous situation is indicated by
* the @ref NRF_802154_NO_TIMESTAMP value of the @p time parameter.
* @note This callout is called by the default implementation of @ref nrf_802154_received .
*
* @param[in] p_data Pointer to a buffer that contains only the payload of the received frame
* (PSDU without FCS).
* @param[in] length Length of the received payload.
* @param[in] power RSSI of the received frame.
* @param[in] lqi LQI of the received frame.
* @param[in] time Timestamp taken when the last symbol of the frame was received,
* in microseconds (us), or @ref NRF_802154_NO_TIMESTAMP if the timestamp
* is invalid.
*/
extern void nrf_802154_received_timestamp(uint8_t * p_data,
uint8_t length,
int8_t power,
uint8_t lqi,
uint32_t time);
#endif // !NRF_802154_SERIALIZATION_HOST
#endif // !NRF_802154_USE_RAW_API
/**
* @brief Notifies that the reception of a frame failed.
*
* @param[in] error Error code that indicates the reason of the failure.
* @param[in] id Identifier of reception window the error occurred in.
* If the error is related to a delayed reception window requested through
* @ref nrf_802154_receive_at, the value of @p id equals the identifier
* of the scheduled reception window. Otherwise, the value of @p id equals
* @ref NRF_802154_RESERVED_IMM_RX_WINDOW_ID.
*/
extern void nrf_802154_receive_failed(nrf_802154_rx_error_t error, uint32_t id);
#if NRF_802154_USE_RAW_API || defined(DOXYGEN)
/**
* @brief Notifies that a frame was transmitted.
*
* @note If ACK was requested for the transmitted frame, this function is called after a proper ACK
* is received. If ACK was not requested, this function is called just after transmission has
* ended.
* @note The buffer pointed to by @c nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack
* is not modified by the radio driver (and cannot be used to receive a frame) until
* @ref nrf_802154_buffer_free_raw is called.
* @note The buffer pointed to by @c nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack
* may be modified by the function handler (and other modules) until
* @ref nrf_802154_buffer_free_raw is called.
* @note @c nrf_802154_transmit_done_metadata_t::data.transmitted.time granularity depends on the
* granularity of the timer driver in the
* platform/timer directory.
* @note This callout is called by the nRF 802.15.4 Radio Driver if @ref NRF_802154_USE_RAW_API
* is enabled.
*
* @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the transmitted frame.
* @param[in] p_metadata Pointer to a metadata structure describing frame passed in @p p_frame.
*/
extern void nrf_802154_transmitted_raw(uint8_t * p_frame,
const nrf_802154_transmit_done_metadata_t * p_metadata);
#endif // NRF_802154_USE_RAW_API
#if !NRF_802154_USE_RAW_API || defined(DOXYGEN)
/**
* @brief Notifies that a frame was transmitted.
*
* @note If ACK was requested for the transmitted frame, this function is called after a proper ACK
* is received. If ACK was not requested, this function is called just after transmission has
* ended.
* @note The buffer pointed to by @c nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack
* is not modified by the radio driver (and cannot be used to receive a frame) until
* @ref nrf_802154_buffer_free is called.
* @note The buffer pointed to by @c nrf_802154_transmit_done_metadata_t::data.transmitted.p_ack
* may be modified by the function handler (and other modules) until
* @ref nrf_802154_buffer_free is called.
* @note The next higher layer must handle either @ref nrf_802154_transmitted or
* @ref nrf_802154_transmitted_raw. It should not handle both functions.
* @note @c nrf_802154_transmit_done_metadata_t::data.transmitted.time granularity depends on the
* granularity of the timer driver in the platform/timer directory.
* @note Including a timestamp for received frames uses resources like CPU time and memory. If the
* timestamp is not required, use @ref nrf_802154_received instead.
* @note This callout is called by the nRF 802.15.4 Radio Driver if @ref NRF_802154_USE_RAW_API
* is disabled.
*
* @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the transmitted frame.
* @param[in] p_metadata Pointer to a metadata structure describing frame passed in @p p_frame.
*/
extern void nrf_802154_transmitted(uint8_t * p_frame,
const nrf_802154_transmit_done_metadata_t * p_metadata);
#endif // !NRF_802154_USE_RAW_API
/**
* @brief Notifies that a frame was not transmitted due to a busy channel.
*
* This function is called if the transmission procedure fails.
*
* @note Frame data values in @ref nrf_802154_transmit_done_metadata_t::data are invalid for
* @ref nrf_802154_transmit_failed callout.
*
* @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame that was not
* transmitted.
* @param[in] error Reason of the failure.
* @param[in] p_metadata Pointer to a metadata structure describing frame passed in @p p_frame.
*/
extern void nrf_802154_transmit_failed(uint8_t * p_frame,
nrf_802154_tx_error_t error,
const nrf_802154_transmit_done_metadata_t * p_metadata);
#if !NRF_802154_SERIALIZATION_HOST || defined(DOXYGEN)
/**
* @brief Notifies that transmitting a frame has started.
*
* @note Currently this callout is only available on the CPU which is running the core of the radio driver.
* If the higher layer runs on a different core it should use nrf_802154_received_timestamp_raw instead.
* @note Usually, @ref nrf_802154_transmitted is called shortly after this function.
* However, if the transmit procedure is interrupted, it might happen that
* @ref nrf_802154_transmitted is not called.
* @note This function should be very short to prevent dropping frames by the driver.
*
* @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame being
* transmitted.
*/
extern void nrf_802154_tx_started(const uint8_t * p_frame);
/**
* @brief Perform some additional operations during initialization of the RADIO peripheral.
*
* By implementing this function the higher layer can provide some additional operations
* to be performed at the beginning of each new timeslot. These can in particular be
* modifications of RADIO peripheral register values.
*/
extern void nrf_802154_custom_part_of_radio_init(void);
#endif // !NRF_802154_SERIALIZATION_HOST
#endif /* NRF_802154_CALLOUTS_H_ */
/** @} */

141
drivers/nrf_802154/common/include/nrf_802154_common_utils.h Normal file
View File

@ -0,0 +1,141 @@
/*
* Copyright (c) 2017 - 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.
*
*/
#ifndef NRF_802154_COMMON_UTILS_H__
#define NRF_802154_COMMON_UTILS_H__
#include <stdint.h>
#include "nrf_802154_config.h"
/**
* @defgroup nrf_802154_data Functions to calculate data given by the driver
* @{
*/
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
/**
* @brief Converts energy level received during the energy detection procedure to IEEE Std. 802.15.4-2015 compliant value.
*
* @param ed_dbm Energy level in dBm
*
* @return uint8_t Energy level in units compliant to IEEE Std. 802.15.4-2015 chapter 10.2.5.
*/
uint8_t nrf_802154_energy_level_from_dbm_calculate(int8_t ed_dbm);
#else
/**
* @brief Converts the energy level received during the energy detection procedure to a dBm value.
*
* @param[in] energy_level Energy level passed by @ref nrf_802154_energy_detected.
*
* @return Result of the energy detection procedure in dBm.
*/
int8_t nrf_802154_dbm_from_energy_level_calculate(uint8_t energy_level);
#endif // NRF_802154_ENERGY_DETECTED_VERSION != 0
/**
* @brief Converts a given dBm level to a CCA energy detection threshold value.
*
* @param[in] dbm Energy level in dBm used to calculate the CCAEDTHRES value.
*
* @return Energy level value corresponding to the given dBm level that is to be written to
* the CCACTRL register.
*/
uint8_t nrf_802154_ccaedthres_from_dbm_calculate(int8_t dbm);
/**
* @brief Calculates the timestamp of the first symbol of the preamble in a received frame.
*
* @deprecated This function is deprecated. Use @ref nrf_802154_timestamp_end_to_phr_convert
* instead and adjust the code that calls this function to rely on the timestamp of the first symbol
* of the PHR, not the timestamp of the first symbol of the frame.
*
* @param[in] end_timestamp Timestamp of the end of the last symbol in the frame,
* in microseconds.
* @param[in] psdu_length Number of bytes in the frame PSDU.
*
* @return Timestamp of the beginning of the first preamble symbol of a given frame,
* in microseconds.
*/
uint64_t nrf_802154_first_symbol_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length);
/**
* @brief Calculates the timestamp of the MAC Header in a received frame.
*
* @deprecated This function is deprecated. Use @ref nrf_802154_timestamp_end_to_phr_convert
* instead and adjust the code that calls this function to rely on the timestamp of the first symbol
* of the PHR, not the MAC Header timestamp.
*
* @param[in] end_timestamp Timestamp of the end of the last symbol in the frame,
* in microseconds.
* @param[in] psdu_length Number of bytes in the frame PSDU.
*
* @return Timestamp of the MHR of a given frame, in microseconds.
*/
uint64_t nrf_802154_mhr_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length);
/**
* @brief Converts the timestamp of the frame's end to the timestamp of the start of its PHR.
*
* This function calculates the time when the first symbol of the PHR is at the local antenna. Note
* that this time is equivalent to: the end of the frame's SFD and RMARKER as defined in'
* IEEE 802.15.4-2020, Section 6.9.1.
*
* @param[in] end_timestamp Timestamp of the end of the last symbol in the frame,
* in microseconds.
* @param[in] psdu_length Number of bytes in the frame PSDU.
*
* @return Timestamp of the start of the PHR of a given frame, in microseconds.
*/
uint64_t nrf_802154_timestamp_end_to_phr_convert(uint64_t end_timestamp, uint8_t psdu_length);
/**
* @brief Converts the timestamp of the frame's PHR to the timestamp of the start of its SHR.
*
* This function converts the time when the first symbol of the frame's PHR is at the local antenna
* to the timestamp of the start of the frame's SHR.
*
* @param[in] phr_timestamp Timestamp of the frame's PHR.
*
* @return Timestamp of the start of the SHR of a given frame, in microseconds.
*/
uint64_t nrf_802154_timestamp_phr_to_shr_convert(uint64_t phr_timestamp);
/**
* @}
*/
#endif // NRF_802154_COMMON_UTILS_H__

22
drivers/nrf_802154/driver/include/nrf_802154_config.h → drivers/nrf_802154/common/include/nrf_802154_config.h
View File

@ -235,9 +235,11 @@ extern "C" {
* If the delayed transmission and the receive window features are available.
*
*/
#if !defined(CONFIG_NRF_802154_SL_OPENSOURCE)
#ifndef NRF_802154_DELAYED_TRX_ENABLED
#define NRF_802154_DELAYED_TRX_ENABLED 1
#endif
#endif
/**
* @def NRF_802154_TEST_MODES_ENABLED
@ -274,9 +276,11 @@ extern "C" {
* the driver performance.
*
*/
#if !defined(CONFIG_NRF_802154_SL_OPENSOURCE)
#ifndef NRF_802154_CSMA_CA_ENABLED
#define NRF_802154_CSMA_CA_ENABLED 1
#endif
#endif
/**
* @def NRF_802154_CSMA_CA_MIN_BE_DEFAULT
@ -405,9 +409,11 @@ extern "C" {
* Indicates whether the Short/Long Interframe spacing feature is to be enabled in the driver.
*
*/
#if !defined(CONFIG_NRF_802154_SL_OPENSOURCE)
#ifndef NRF_802154_IFS_ENABLED
#define NRF_802154_IFS_ENABLED 1
#endif
#endif
/**
* @}
@ -534,6 +540,22 @@ extern "C" {
#define NRF_802154_CARRIER_FUNCTIONS_ENABLED 1
#endif
/**
* @}
* @defgroup nrf_802154_config_apiversions API version configuration options
* @{
*/
/**
* @def NRF_802154_ENERGY_DETECTED_VERSION
*
* Selects API for @ref nrf_802154_energy_detected callout
* This is a temporary switch to perform API migration in external integration.
*/
#ifndef NRF_802154_ENERGY_DETECTED_VERSION
#define NRF_802154_ENERGY_DETECTED_VERSION 0
#endif
/**
*@}
**/

0
drivers/nrf_802154/driver/include/nrf_802154_const.h → drivers/nrf_802154/common/include/nrf_802154_const.h
View File

34
drivers/nrf_802154/driver/src/nrf_802154_nrfx_addons.h → drivers/nrf_802154/common/include/nrf_802154_nrfx_addons.h
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2020 - 2023, Nordic Semiconductor ASA
* Copyright (c) 2017 - 2023, Nordic Semiconductor ASA
* All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
@ -36,6 +36,7 @@
#define NRF_802154_NRFX_ADDONS_H__
#include "nrfx.h"
#include "nrf_802154_config.h"
#include "nrf_802154_const.h"
/* The usage of ED_RSSISCALE is described imprecisely in the nRF product specifications. The meaning of
@ -55,6 +56,35 @@
#define EDSAMPLE_MIN_REPORTED_VALUE (PHY_MIN_RECEIVER_SENSITIVITY - ED_RSSIOFFS + 10) ///< Minimal reported EDSAMPLE value (reported as 0)
#define EDSAMPLE_MAX_REPORTED_VALUE (ED_RESULT_MAX / ED_RSSISCALE) ///< Maximal reported EDSAMPLE value (reported as 255)
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
/** Minimum value of ED in dBm for conversion to units conforming IEEE Std. 802.15.4-2015 chapter 10.2.5. */
#define ED_DBM_MIN (PHY_MIN_RECEIVER_SENSITIVITY + 10)
/** Maximum value of ED in dBm for conversion to units conforming IEEE Std. 802.15.4-2015 chapter 10.2.5. */
#define ED_DBM_MAX (EDSAMPLE_MAX_REPORTED_VALUE + ED_RSSIOFFS)
static inline uint8_t nrf_802154_addons_energy_level_from_dbm_calculate(int8_t ed_dbm)
{
uint32_t r;
if (ed_dbm < ED_DBM_MIN)
{
return 0;
}
r = ((uint32_t)(ed_dbm - ED_DBM_MIN)) * ED_RESULT_MAX / (ED_DBM_MAX - ED_DBM_MIN);
if (r > ED_RESULT_MAX)
{
r = ED_RESULT_MAX;
}
return r;
}
#else
/**
* @brief Converts the energy level received during the energy detection procedure to a dBm value.
*
@ -69,4 +99,6 @@ static inline int8_t nrf_802154_addons_dbm_from_energy_level_calculate(uint8_t e
ED_RESULT_MAX + EDSAMPLE_MIN_REPORTED_VALUE + ED_RSSIOFFS;
}
#endif // NRF_802154_ENERGY_DETECTED_VERSION != 0
#endif // NRF_802154_NRFX_ADDONS_H__

34
drivers/nrf_802154/driver/include/nrf_802154_types.h → drivers/nrf_802154/common/include/nrf_802154_types.h
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2018 - 2023, Nordic Semiconductor ASA
* Copyright (c) 2017 - 2023, Nordic Semiconductor ASA
* All rights reserved.
*
* SPDX-License-Identifier: BSD-3-Clause
@ -35,16 +35,24 @@
#ifndef NRF_802154_TYPES_H__
#define NRF_802154_TYPES_H__
#include <stdbool.h>
#include <stdint.h>
#include <nrf_802154_config.h>
/**
* Avoid including nrfx dependencies in a unit test build.
* Avoid including nrfx dependencies in a build only containing
* serialization commands
*/
#if !defined(UNIT_TEST)
#if !NRF_802154_SERIALIZATION_HOST
#include "hal/nrf_radio.h"
#else
typedef uint8_t nrf_radio_cca_mode_t;
/** @brief RADIO Clear Channel Assessment modes. */
#define NRF_RADIO_CCA_MODE_ED 0x00
#define NRF_RADIO_CCA_MODE_CARRIER 0x01
#define NRF_RADIO_CCA_MODE_CARRIER_AND_ED 0x02
#define NRF_RADIO_CCA_MODE_CARRIER_OR_ED 0x03
#endif
/**
@ -427,10 +435,11 @@ typedef struct
*/
typedef struct
{
nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the frame to be transmitted.
bool cca; // !< If the driver is to perform a CCA procedure before transmission.
uint8_t channel; // !< Radio channel on which the frame is to be transmitted.
nrf_802154_tx_power_metadata_t tx_power; // !< Information about the TX power to be used
nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the frame to be transmitted.
bool cca; // !< If the driver is to perform a CCA procedure before transmission.
uint8_t channel; // !< Radio channel on which the frame is to be transmitted.
nrf_802154_tx_power_metadata_t tx_power; // !< Information about the TX power to be used
uint8_t extra_cca_attempts; // !< Maximum number of additional CCA attempts that can be performed if the first attempt returns busy channel. Ignored if @ref cca equals @c false.
} nrf_802154_transmit_at_metadata_t;
/**
@ -474,6 +483,17 @@ typedef void (* nrf_802154_transmit_failed_notification_t)(
nrf_802154_tx_error_t error,
const nrf_802154_transmit_done_metadata_t * p_meta);
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
/**
* @brief Structure that holds results of energy detection procedure.
*/
typedef struct
{
int8_t ed_dbm; // !< Maximum detected ED in dBm.
} nrf_802154_energy_detected_t;
#endif
/**
*@}
**/

83
drivers/nrf_802154/common/src/nrf_802154_common_utils.c Normal file
View File

@ -0,0 +1,83 @@
/*
* Copyright (c) 2017 - 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.
*
*/
#include "nrf_802154_common_utils.h"
#include "nrf_802154_const.h"
#include "nrf_802154_nrfx_addons.h"
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
uint8_t nrf_802154_energy_level_from_dbm_calculate(int8_t ed_dbm)
{
return nrf_802154_addons_energy_level_from_dbm_calculate(ed_dbm);
}
#else
int8_t nrf_802154_dbm_from_energy_level_calculate(uint8_t energy_level)
{
return nrf_802154_addons_dbm_from_energy_level_calculate(energy_level);
}
#endif // NRF_802154_ENERGY_DETECTED_VERSION != 0
uint8_t nrf_802154_ccaedthres_from_dbm_calculate(int8_t dbm)
{
return dbm - ED_RSSIOFFS;
}
uint64_t nrf_802154_first_symbol_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length)
{
uint32_t frame_symbols = PHY_SHR_SYMBOLS;
frame_symbols += (PHR_SIZE + psdu_length) * PHY_SYMBOLS_PER_OCTET;
return end_timestamp - (frame_symbols * PHY_US_PER_SYMBOL);
}
uint64_t nrf_802154_mhr_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length)
{
return end_timestamp - (psdu_length * PHY_SYMBOLS_PER_OCTET * PHY_US_PER_SYMBOL);
}
uint64_t nrf_802154_timestamp_end_to_phr_convert(uint64_t end_timestamp, uint8_t psdu_length)
{
uint32_t frame_symbols = (PHR_SIZE + psdu_length) * PHY_SYMBOLS_PER_OCTET;
return end_timestamp - (frame_symbols * PHY_US_PER_SYMBOL);
}
uint64_t nrf_802154_timestamp_phr_to_shr_convert(uint64_t phr_timestamp)
{
return phr_timestamp - (PHY_SHR_SYMBOLS * PHY_US_PER_SYMBOL);
}

12
drivers/nrf_802154/driver/CMakeLists.txt
View File

@ -115,9 +115,21 @@ if (NRF_802154_PROJECT_CONFIG)
)
endif()
target_compile_definitions(nrf-802154-driver-interface
INTERFACE
# The core for which the code is compiled contains the 802.15.4 radio driver
NRF_802154_SERIALIZATION_HOST=0
)
target_link_libraries(nrf-802154-driver-interface
INTERFACE
nrf-802154-common-interface
)
target_link_libraries(nrf-802154-driver
PUBLIC
nrf-802154-driver-interface
nrf-802154-platform
nrf-802154-sl
nrf-802154-common
)

90
drivers/nrf_802154/driver/include/nrf_802154_irq_handlers.h Normal file
View File

@ -0,0 +1,90 @@
/*
* Copyright (c) 2017 - 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.
*
*/
/**@file nrf_802154_irq_handlers.h
*
* @brief Provides irq handler prototypes.
*
* These functions are intended for use in an operating system environment, where the OS handles IRQ
* and indirectly passes it to the driver, or with a RAAL implementation that indirectly passes
* radio IRQ to the driver.
*
*/
#ifndef NRF_802154_IRQ_HANDLERS_H__
#define NRF_802154_IRQ_HANDLERS_H__
#include "nrf_802154_config.h"
/**
* @defgroup nrf_802154_irq Interrupt handlers
* @{
*
*/
#if !NRF_802154_INTERNAL_RADIO_IRQ_HANDLING || defined(DOXYGEN)
/**
* @brief Handles the interrupt request from the RADIO peripheral.
*
* @note If @ref NRF_802154_INTERNAL_RADIO_IRQ_HANDLING is enabled, the driver internally handles the
* RADIO IRQ, and this function must not be called.
*
* This function is intended for use in an operating system environment, where the OS handles IRQ
* and indirectly passes it to the driver, or with a RAAL implementation that indirectly passes
* radio IRQ to the driver.
*/
void nrf_802154_radio_irq_handler(void);
#endif // !NRF_802154_INTERNAL_RADIO_IRQ_HANDLING
#if !NRF_802154_INTERNAL_SWI_IRQ_HANDLING || defined(DOXYGEN)
/**
* @brief Handles the interrupt request from the RADIO peripheral.
*
* @note If @ref NRF_802154_INTERNAL_SWI_IRQ_HANDLING is enabled, the driver internally handles the
* SWI IRQ, and this function must not be called.
*
* This function is intended for use in an operating system environment, where the OS handles IRQ
* and indirectly passes it to the driver, or with a RAAL implementation that indirectly passes
* radio IRQ to the driver.
*/
void nrf_802154_swi_irq_handler(void);
#endif // !NRF_802154_INTERNAL_SWI_IRQ_HANDLING
/** @} */
#endif // NRF_802154_IRQ_HANDLERS_H__

9
drivers/nrf_802154/driver/src/mac_features/nrf_802154_csma_ca.c
View File

@ -191,10 +191,11 @@ static void frame_transmit(rsch_dly_ts_id_t dly_ts_id)
nrf_802154_transmit_params_t params =
{
.frame_props = m_data_props,
.tx_power = m_tx_power,
.cca = true,
.immediate = NRF_802154_CSMA_CA_WAIT_FOR_TIMESLOT ? false : true,
.frame_props = m_data_props,
.tx_power = m_tx_power,
.cca = true,
.immediate = NRF_802154_CSMA_CA_WAIT_FOR_TIMESLOT ? false : true,
.extra_cca_attempts = 0,
};
if (!nrf_802154_request_transmit(NRF_802154_TERM_NONE,

9
drivers/nrf_802154/driver/src/mac_features/nrf_802154_delayed_trx.c
View File

@ -793,10 +793,11 @@ bool nrf_802154_delayed_trx_transmit(uint8_t * p
(void)nrf_802154_tx_power_convert_metadata_to_tx_power_split(p_metadata->channel,
p_metadata->tx_power,
&p_dly_tx_data->tx.params.tx_power);
p_dly_tx_data->tx.params.cca = p_metadata->cca;
p_dly_tx_data->tx.params.immediate = true;
p_dly_tx_data->tx.channel = p_metadata->channel;
p_dly_tx_data->id = NRF_802154_RESERVED_DTX_ID;
p_dly_tx_data->tx.params.cca = p_metadata->cca;
p_dly_tx_data->tx.params.immediate = true;
p_dly_tx_data->tx.params.extra_cca_attempts = p_metadata->extra_cca_attempts;
p_dly_tx_data->tx.channel = p_metadata->channel;
p_dly_tx_data->id = NRF_802154_RESERVED_DTX_ID;
rsch_dly_ts_param_t dly_ts_param =
{

1
drivers/nrf_802154/driver/src/mac_features/nrf_802154_ie_writer.c
View File

@ -44,7 +44,6 @@
#include "mac_features/nrf_802154_delayed_trx.h"
#include "nrf_802154_core.h"
#include "nrf_802154_nrfx_addons.h"
#include "nrf_802154_procedures_duration.h"
#include "nrf_802154_tx_work_buffer.h"
#include "nrf_802154_utils_byteorder.h"
#include "nrf_802154_sl_timer.h"

4
drivers/nrf_802154/driver/src/mac_features/nrf_802154_ifs.c
View File

@ -276,9 +276,7 @@ bool nrf_802154_ifs_pretransmission(
else
{
m_context.p_data = p_frame;
m_context.params.frame_props = p_params->frame_props;
m_context.params.cca = p_params->cca;
m_context.params.tx_power = p_params->tx_power;
m_context.params = *p_params;
m_context.params.immediate = true;
m_timer.trigger_time = m_last_frame_timestamp + dt;
m_timer.action_type = NRF_802154_SL_TIMER_ACTION_TYPE_CALLBACK;

1
drivers/nrf_802154/driver/src/mac_features/nrf_802154_precise_ack_timeout.c
View File

@ -50,7 +50,6 @@
#include "nrf_802154_notification.h"
#include "nrf_802154_procedures_duration.h"
#include "nrf_802154_request.h"
#include "nrf_802154_tx_work_buffer.h"
#include "nrf_802154_sl_timer.h"
#if defined(CONFIG_SOC_SERIES_BSIM_NRFXX)

80
drivers/nrf_802154/driver/src/nrf_802154.c
View File

@ -49,12 +49,12 @@
#include <string.h>
#include "nrf_802154_config.h"
#include "nrf_802154_utils.h"
#include "nrf_802154_const.h"
#include "nrf_802154_core.h"
#include "nrf_802154_critical_section.h"
#include "nrf_802154_debug.h"
#include "nrf_802154_notification.h"
#include "nrf_802154_nrfx_addons.h"
#include "nrf_802154_pib.h"
#include "nrf_802154_request.h"
#include "nrf_802154_rx_buffer.h"
@ -132,6 +132,11 @@ static inline bool are_frame_properties_valid(const nrf_802154_transmitted_frame
return p_props->dynamic_data_is_set || !(p_props->is_secured);
}
static inline bool are_extra_cca_attempts_valid(const nrf_802154_transmit_at_metadata_t * p_data)
{
return !p_data->cca || (p_data->extra_cca_attempts < UINT8_MAX);
}
void nrf_802154_channel_set(uint8_t channel)
{
bool changed = nrf_802154_pib_channel_get() != channel;
@ -201,42 +206,6 @@ void nrf_802154_short_address_set(const uint8_t * p_short_address)
nrf_802154_pib_short_address_set(p_short_address);
}
int8_t nrf_802154_dbm_from_energy_level_calculate(uint8_t energy_level)
{
return nrf_802154_addons_dbm_from_energy_level_calculate(energy_level);
}
uint8_t nrf_802154_ccaedthres_from_dbm_calculate(int8_t dbm)
{
return dbm - ED_RSSIOFFS;
}
uint64_t nrf_802154_first_symbol_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length)
{
uint32_t frame_symbols = PHY_SHR_SYMBOLS;
frame_symbols += (PHR_SIZE + psdu_length) * PHY_SYMBOLS_PER_OCTET;
return end_timestamp - (frame_symbols * PHY_US_PER_SYMBOL);
}
uint64_t nrf_802154_mhr_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length)
{
return end_timestamp - (psdu_length * PHY_SYMBOLS_PER_OCTET * PHY_US_PER_SYMBOL);
}
uint64_t nrf_802154_timestamp_end_to_phr_convert(uint64_t end_timestamp, uint8_t psdu_length)
{
uint32_t frame_symbols = (PHR_SIZE + psdu_length) * PHY_SYMBOLS_PER_OCTET;
return end_timestamp - (frame_symbols * PHY_US_PER_SYMBOL);
}
uint64_t nrf_802154_timestamp_phr_to_shr_convert(uint64_t phr_timestamp)
{
return phr_timestamp - (PHY_SHR_SYMBOLS * PHY_US_PER_SYMBOL);
}
void nrf_802154_init(void)
{
static const nrf_802154_sl_crit_sect_interface_t crit_sect_int =
@ -508,10 +477,11 @@ bool nrf_802154_transmit_raw(uint8_t * p_data,
nrf_802154_transmit_params_t params =
{
.frame_props = p_metadata->frame_props,
.tx_power = {0},
.cca = p_metadata->cca,
.immediate = false
.frame_props = p_metadata->frame_props,
.tx_power = {0},
.cca = p_metadata->cca,
.immediate = false,
.extra_cca_attempts = 0U,
};
(void)nrf_802154_tx_power_convert_metadata_to_tx_power_split(nrf_802154_pib_channel_get(),
@ -556,10 +526,11 @@ bool nrf_802154_transmit(const uint8_t * p_data,
nrf_802154_transmit_params_t params =
{
.frame_props = p_metadata->frame_props,
.tx_power = {0},
.cca = p_metadata->cca,
.immediate = false
.frame_props = p_metadata->frame_props,
.tx_power = {0},
.cca = p_metadata->cca,
.immediate = false,
.extra_cca_attempts = 0U,
};
(void)nrf_802154_tx_power_convert_metadata_to_tx_power_split(nrf_802154_pib_channel_get(),
@ -591,9 +562,10 @@ bool nrf_802154_transmit_raw_at(uint8_t * p_data
bool result;
nrf_802154_transmit_at_metadata_t metadata_default =
{
.frame_props = NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT,
.cca = true,
.tx_power = {.use_metadata_value = false}
.frame_props = NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT,
.cca = true,
.tx_power = {.use_metadata_value = false},
.extra_cca_attempts = 0,
};
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW);
@ -604,7 +576,8 @@ bool nrf_802154_transmit_raw_at(uint8_t * p_data
p_metadata = &metadata_default;
}
result = are_frame_properties_valid(&p_metadata->frame_props);
result = are_frame_properties_valid(&p_metadata->frame_props) &&
are_extra_cca_attempts_valid(p_metadata);
if (result)
{
result = nrf_802154_request_transmit_raw_at(p_data, tx_time, p_metadata);
@ -1217,11 +1190,20 @@ __WEAK void nrf_802154_transmit_failed(uint8_t
(void)p_metadata;
}
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
__WEAK void nrf_802154_energy_detected(const nrf_802154_energy_detected_t * p_result)
{
(void)p_result;
}
#else
__WEAK void nrf_802154_energy_detected(uint8_t result)
{
(void)result;
}
#endif
__WEAK void nrf_802154_energy_detection_failed(nrf_802154_ed_error_t error)
{
(void)error;

29
drivers/nrf_802154/driver/src/nrf_802154_core.c
View File

@ -418,11 +418,19 @@ static void transmit_failed_notify_and_nesting_allow(
}
/** Notify MAC layer that energy detection procedure ended. */
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
static void energy_detected_notify(const nrf_802154_energy_detected_t * p_result)
#else
static void energy_detected_notify(uint8_t result)
#endif
{
nrf_802154_critical_section_nesting_allow();
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
nrf_802154_notify_energy_detected(p_result);
#else
nrf_802154_notify_energy_detected(result);
#endif
nrf_802154_critical_section_nesting_deny();
}
@ -1022,8 +1030,10 @@ static void rx_init(nrf_802154_trx_ramp_up_trigger_mode_t ru_tr_mode, bool * p_a
/** Initialize TX operation. */
static bool tx_init(const uint8_t * p_data,
nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode,
bool cca)
uint8_t cca_attempts)
{
bool cca = cca_attempts > 0;
if (!timeslot_is_granted() || !nrf_802154_rsch_timeslot_request(
nrf_802154_tx_duration_get(p_data[0], cca, ack_is_requested(p_data))))
{
@ -1053,7 +1063,7 @@ static bool tx_init(const uint8_t * p_data,
m_flags.tx_with_cca = cca;
nrf_802154_trx_transmit_frame(nrf_802154_tx_work_buffer_get(p_data),
rampup_trigg_mode,
cca,
cca_attempts,
&m_tx_power,
m_trx_transmit_frame_notifications_mask);
#if defined(CONFIG_SOC_SERIES_BSIM_NRFXX)
@ -1076,6 +1086,7 @@ static bool tx_init(const uint8_t * p_data,
if (cca)
{
// Assume that the first CCA succeeds
adjustments.tx_started.time_to_radio_address_us +=
RX_RAMP_UP_TIME + CCA_TIME + RX_TX_TURNAROUND_TIME;
}
@ -1299,7 +1310,7 @@ static void on_preconditions_denied(radio_state_t state)
bool result;
result = nrf_802154_core_hooks_terminate(NRF_802154_TERM_802154, REQ_ORIG_CORE);
result = nrf_802154_core_hooks_terminate(NRF_802154_TERM_802154, REQ_ORIG_RSCH);
assert(result);
(void)result;
@ -2416,7 +2427,15 @@ void nrf_802154_trx_energy_detection_finished(uint8_t ed_sample)
state_set(RADIO_STATE_RX);
rx_init(TRX_RAMP_UP_SW_TRIGGER, NULL);
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
nrf_802154_energy_detected_t ed_result = {};
ed_result.ed_dbm = nrf_802154_rssi_ed_sample_to_dbm_convert(m_ed_result);
energy_detected_notify(&ed_result);
#else
energy_detected_notify(nrf_802154_rssi_ed_sample_convert(m_ed_result));
#endif
}
@ -2609,8 +2628,10 @@ bool nrf_802154_core_transmit(nrf_802154_term_t term_lvl,
mp_tx_data = p_data;
m_tx_power = p_params->tx_power;
uint8_t cca_attempts = p_params->cca ? (1 + p_params->extra_cca_attempts) : 0;
// coverity[check_return]
result = tx_init(p_data, ramp_up_mode_choose(req_orig), p_params->cca);
result = tx_init(p_data, ramp_up_mode_choose(req_orig), cca_attempts);
if (p_params->immediate)
{

9
drivers/nrf_802154/driver/src/nrf_802154_notification.h
View File

@ -119,12 +119,21 @@ void nrf_802154_notify_transmit_failed(uint8_t
nrf_802154_tx_error_t error,
const nrf_802154_transmit_done_metadata_t * p_metadata);
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
/**
* @brief Notifies the next higher layer that the energy detection procedure ended.
*
* @param[in] p_result Pointer to structure containing the result of the ED operation.
*/
void nrf_802154_notify_energy_detected(const nrf_802154_energy_detected_t * p_result);
#else
/**
* @brief Notifies the next higher layer that the energy detection procedure ended.
*
* @param[in] result Detected energy level.
*/
void nrf_802154_notify_energy_detected(uint8_t result);
#endif
/**
* @brief Notifies the next higher layer that the energy detection procedure failed.

8
drivers/nrf_802154/driver/src/nrf_802154_notification_direct.c
View File

@ -125,11 +125,19 @@ void nrf_802154_notify_transmit_failed(uint8_t
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW);
}
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
void nrf_802154_notify_energy_detected(const nrf_802154_energy_detected_t * p_result)
#else
void nrf_802154_notify_energy_detected(uint8_t result)
#endif
{
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW);
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
nrf_802154_energy_detected(p_result);
#else
nrf_802154_energy_detected(result);
#endif
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW);
}

43
drivers/nrf_802154/driver/src/nrf_802154_notification_swi.c
View File

@ -165,8 +165,14 @@ typedef struct
struct
{
int8_t result; ///< Energy detection result.
} energy_detected; ///< Energy detection details.
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
nrf_802154_energy_detected_t result; ///< Energy detection result.
#else
int8_t result; ///< Energy detection result.
#endif
} energy_detected; ///< Energy detection details.
struct
{
@ -444,6 +450,18 @@ bool swi_notify_transmit_failed(uint8_t * p_fr
return true;
}
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
/**
* @brief Notifies the next higher layer that the energy detection procedure ended from
* the SWI priority level.
*
* @param[in] p_result Structure holding the result of energy detection procedure.
*
* @retval true Notification enqueued successfully.
* @retval false Notification could not be performed.
*/
bool swi_notify_energy_detected(const nrf_802154_energy_detected_t * p_result)
#else
/**
* @brief Notifies the next higher layer that the energy detection procedure ended from
* the SWI priority level.
@ -454,6 +472,7 @@ bool swi_notify_transmit_failed(uint8_t * p_fr
* @retval false Notification could not be performed.
*/
bool swi_notify_energy_detected(uint8_t result)
#endif
{
uint8_t slot_id = ntf_slot_alloc(m_primary_ntf_pool, NTF_PRIMARY_POOL_SIZE);
@ -465,8 +484,12 @@ bool swi_notify_energy_detected(uint8_t result)
nrf_802154_ntf_data_t * p_slot = &m_primary_ntf_pool[slot_id];
p_slot->type = NTF_TYPE_ENERGY_DETECTED;
p_slot->type = NTF_TYPE_ENERGY_DETECTED;
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
p_slot->data.energy_detected.result = *p_result;
#else
p_slot->data.energy_detected.result = result;
#endif
ntf_push(slot_id | NTF_PRIMARY_POOL_ID_MASK);
@ -631,12 +654,22 @@ void nrf_802154_notify_transmit_failed(uint8_t
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW);
}
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
void nrf_802154_notify_energy_detected(const nrf_802154_energy_detected_t * p_result)
#else
void nrf_802154_notify_energy_detected(uint8_t result)
#endif
{
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW);
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
bool notified = swi_notify_energy_detected(p_result);
#else
bool notified = swi_notify_energy_detected(result);
#endif
// It should always be possible to notify energy detection result
assert(notified);
(void)notified;
@ -751,7 +784,11 @@ static void irq_handler_ntf_event(void)
break;
case NTF_TYPE_ENERGY_DETECTED:
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
nrf_802154_energy_detected(&p_slot->data.energy_detected.result);
#else
nrf_802154_energy_detected(p_slot->data.energy_detected.result);
#endif
break;
case NTF_TYPE_ENERGY_DETECTION_FAILED:

11
drivers/nrf_802154/driver/src/nrf_802154_peripherals_nrf52.h
View File

@ -195,15 +195,16 @@ extern "C" {
#endif
/**
* @def NRF_802154_PPI_RADIO_CRCOK_TO_PPI_GRP_DISABLE
* @def NRF_802154_PPI_RADIO_CCABUSY_TO_RADIO_CCASTART
*
* The PPI channel that connects RADIO_CRCOK event with the task that disables the whole PPI group.
* The PPI channel that connects RADIO_CCABUSY event to RADIO_CCASTART task. This PPI is used to
* perform multiple back-to-back CCA attempts before a transmission.
*
* @note This option is used by the core module regardless of the driver configuration.
*
*/
#ifndef NRF_802154_PPI_RADIO_CRCOK_TO_PPI_GRP_DISABLE
#define NRF_802154_PPI_RADIO_CRCOK_TO_PPI_GRP_DISABLE NRF_PPI_CHANNEL10
#ifndef NRF_802154_PPI_RADIO_CCABUSY_TO_RADIO_CCASTART
#define NRF_802154_PPI_RADIO_CCABUSY_TO_RADIO_CCASTART NRF_PPI_CHANNEL10
#endif
/**
@ -307,7 +308,7 @@ extern "C" {
(1 << NRF_802154_PPI_RADIO_CRCERROR_TO_TIMER_CLEAR) | \
(1 << NRF_802154_PPI_RADIO_CCAIDLE_TO_FEM_GPIOTE) | \
(1 << NRF_802154_PPI_TIMER_COMPARE_TO_RADIO_TXEN) | \
(1 << NRF_802154_PPI_RADIO_CRCOK_TO_PPI_GRP_DISABLE) | \
(1 << NRF_802154_PPI_RADIO_CCABUSY_TO_RADIO_CCASTART) | \
NRF_802154_DISABLE_BCC_MATCHING_PPI_CHANNELS_USED_MASK | \
NRF_802154_TIMESTAMP_PPI_CHANNELS_USED_MASK | \
NRF_802154_DEBUG_PPI_CHANNELS_USED_MASK)

6
drivers/nrf_802154/driver/src/nrf_802154_peripherals_nrf53.h
View File

@ -229,7 +229,6 @@ extern "C" {
#define NRF_802154_DPPI_RADIO_CCAIDLE 9U
#endif
#if NRF_802154_TEST_MODES_ENABLED
/**
* @def NRF_802154_DPPI_RADIO_CCABUSY
*
@ -244,11 +243,7 @@ extern "C" {
*
* Helper bit mask of DPPI channels used by the 802.15.4 driver's test mode.
*/
#define NRF_802154_DPPI_RADIO_TEST_MODE_USED_MASK \
(1UL << NRF_802154_DPPI_RADIO_CCABUSY)
#else // NRF_802154_TEST_MODES_ENABLED
#define NRF_802154_DPPI_RADIO_TEST_MODE_USED_MASK 0U
#endif // NRF_802154_TEST_MODES_ENABLED
/**
* @def NRF_802154_DPPI_RADIO_HW_TRIGGER
@ -288,6 +283,7 @@ extern "C" {
(1UL << NRF_802154_DPPI_TIMER_COMPARE_TO_RADIO_TXEN) | \
(1UL << NRF_802154_DPPI_RADIO_SYNC_TO_EGU_SYNC) | \
(1UL << NRF_802154_DPPI_RADIO_CCAIDLE) | \
(1UL << NRF_802154_DPPI_RADIO_CCABUSY) | \
(1UL << NRF_802154_DPPI_RADIO_HW_TRIGGER) | \
NRF_802154_DPPI_RADIO_TEST_MODE_USED_MASK | \
NRF_802154_DPPI_TIMESTAMPS_USED_MASK)

1
drivers/nrf_802154/driver/src/nrf_802154_pib.c
View File

@ -47,7 +47,6 @@
#include "nrf_802154_config.h"
#include "nrf_802154_const.h"
#include "nrf_802154_utils.h"
#define CSMACA_BE_MAXIMUM 8 ///< The maximum allowed CSMA-CA backoff exponent (BE) that results from the implementation

10
drivers/nrf_802154/driver/src/nrf_802154_rssi.c
View File

@ -203,3 +203,13 @@ int8_t nrf_802154_rssi_dbm_from_energy_level_calculate(uint8_t energy_level)
((int16_t)energy_level)) /
ED_RESULT_MAX + EDSAMPLE_MIN_REPORTED_VALUE + ED_RSSIOFFS;
}
int8_t nrf_802154_rssi_ed_sample_to_dbm_convert(uint8_t ed_sample)
{
int16_t result;
result = nrf_802154_rssi_ed_corrected_get(ed_sample);
result = ED_RSSIOFFS + result;
return result;
}

11
drivers/nrf_802154/driver/src/nrf_802154_rssi.h
View File

@ -109,6 +109,17 @@ uint8_t nrf_802154_rssi_ed_sample_convert(uint8_t ed_sample);
*/
int8_t nrf_802154_rssi_dbm_from_energy_level_calculate(uint8_t energy_level);
/**
* @brief Converts the EDSAMPLE value to a dBm value.
*
* @note Performs temperature correction internally.
*
* @param[int] ed_sample The hardware reported value.
*
* @return Result of the energy detection procedure in dBm.
*/
int8_t nrf_802154_rssi_ed_sample_to_dbm_convert(uint8_t ed_sample);
/**
*@}
**/

120
drivers/nrf_802154/driver/src/nrf_802154_trx.c
View File

@ -101,6 +101,11 @@
#define SHORTS_TX_ACK (NRF_RADIO_SHORT_TXREADY_START_MASK | \
NRF_RADIO_SHORT_PHYEND_DISABLE_MASK)
#define SHORTS_MULTI_CCA_TX (NRF_RADIO_SHORT_RXREADY_CCASTART_MASK | \
NRF_RADIO_SHORT_CCAIDLE_TXEN_MASK | \
NRF_RADIO_SHORT_TXREADY_START_MASK | \
NRF_RADIO_SHORT_PHYEND_DISABLE_MASK)
#define SHORTS_CCA_TX (NRF_RADIO_SHORT_RXREADY_CCASTART_MASK | \
NRF_RADIO_SHORT_CCABUSY_DISABLE_MASK | \
NRF_RADIO_SHORT_CCAIDLE_TXEN_MASK | \
@ -220,6 +225,7 @@ static nrf_802154_flags_t m_flags; ///< Flags used to store the current driver s
/** @brief Value of TIMER internal counter from which the counting is resumed on RADIO.EVENTS_END event. */
static volatile uint32_t m_timer_value_on_radio_end_event;
static volatile bool m_transmit_with_cca;
static volatile uint8_t m_remaining_cca_attempts;
static void timer_frequency_set_1mhz(void);
@ -1069,13 +1075,6 @@ void nrf_802154_trx_receive_frame(uint8_t bcc,
uint32_t ints_to_enable = 0U;
uint32_t shorts = SHORTS_RX;
if (nrf_radio_event_check(NRF_RADIO, NRF_RADIO_EVENT_DISABLED))
{
// For DRX a DISABLE event might be pending as a leftover from
// an aborted operation. Clear it to avoid spurious interrupts.
nrf_radio_event_clear(NRF_RADIO, NRF_RADIO_EVENT_DISABLED);
}
// Force the TIMER to be stopped and count from 0.
nrf_timer_task_trigger(NRF_802154_TIMER_INSTANCE, NRF_TIMER_TASK_SHUTDOWN);
@ -1304,26 +1303,21 @@ bool nrf_802154_trx_rssi_sample_is_available(void)
void nrf_802154_trx_transmit_frame(const void * p_transmit_buffer,
nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode,
bool cca,
uint8_t cca_attempts,
const nrf_802154_fal_tx_power_split_t * p_tx_power,
nrf_802154_trx_transmit_notifications_t notifications_mask)
{
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW);
uint32_t ints_to_enable = 0U;
if (nrf_radio_event_check(NRF_RADIO, NRF_RADIO_EVENT_DISABLED))
{
// For DTX a DISABLE event might be pending as a leftover from
// an aborted operation. Clear it to avoid spurious interrupts.
nrf_radio_event_clear(NRF_RADIO, NRF_RADIO_EVENT_DISABLED);
}
bool cca = cca_attempts > 0;
// Force the TIMER to be stopped and count from 0.
nrf_timer_task_trigger(NRF_802154_TIMER_INSTANCE, NRF_TIMER_TASK_SHUTDOWN);
m_trx_state = TRX_STATE_TXFRAME;
m_transmit_with_cca = cca;
m_trx_state = TRX_STATE_TXFRAME;
m_transmit_with_cca = cca;
m_remaining_cca_attempts = cca_attempts;
m_flags.ccastarted_notif_en = false;
@ -1332,7 +1326,12 @@ void nrf_802154_trx_transmit_frame(const void * p_tra
nrf_radio_packetptr_set(NRF_RADIO, p_transmit_buffer);
// Set shorts
if (cca)
if (cca_attempts > 1)
{
nrf_radio_shorts_set(NRF_RADIO, SHORTS_MULTI_CCA_TX);
nrf_802154_trx_ppi_for_extra_cca_attempts_set();
}
else if (cca_attempts == 1)
{
nrf_radio_shorts_set(NRF_RADIO, SHORTS_CCA_TX);
}
@ -2159,6 +2158,11 @@ static void irq_handler_address(void)
{
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW);
// At this point we can be certain that no more DISABLED events
// comming from the time before the transmission/reception started
// will arrive. We can safely disable the DISABLED interrupt.
nrf_radio_int_disable(NRF_RADIO, NRF_RADIO_INT_DISABLED_MASK);
switch (m_trx_state)
{
case TRX_STATE_RXFRAME:
@ -2284,6 +2288,7 @@ static void txframe_finish_disable_ppis(bool cca)
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_HIGH);
nrf_802154_trx_ppi_for_ramp_up_clear(cca ? NRF_RADIO_TASK_RXEN : NRF_RADIO_TASK_TXEN, false);
nrf_802154_trx_ppi_for_extra_cca_attempts_clear(); // fine to call unconditionally
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
}
@ -2492,9 +2497,13 @@ static void irq_handler_disabled(void)
// Robust radio ramp-down requires that RADIO.DISABLE is cleared. If the ramp-up was
// triggered by software, the event was cleared already immediately after triggering
// RADIO.DISABLE task. If the ramp-up was triggered by (D)PPI, the event would need
// to be cleared. The IRQ handler does that on entry to irq_handler_disabled. What
// remains to be done is disabling the DISABLED interrupt, as it won't be needed.
nrf_radio_int_disable(NRF_RADIO, NRF_RADIO_INT_DISABLED_MASK);
// to be cleared. The IRQ handler does that on entry to irq_handler_disabled.
// The interrupt must not be disabled here though. It is possible that this handler is executed
// before the radio ramp-up finishes as a result of a ramp-down triggered earlier. This is more
// probable on platforms where code execution is fast and the critical section that configures
// radio ramp-up is exited before that ramp-up finishes. To allow for this interrupt to fire again
// when the ramp-up finishes and for the DISABLED event to be cleared once more, do not disable
// the interrupt now. It's disabled in ADDRESS event handler.
break;
default:
@ -2535,9 +2544,72 @@ static void irq_handler_ccabusy(void)
{
case TRX_STATE_TXFRAME:
assert(m_transmit_with_cca);
txframe_finish();
m_trx_state = TRX_STATE_FINISHED;
nrf_802154_trx_transmit_frame_ccabusy();
if (m_remaining_cca_attempts > 1)
{
/* There are still remaining CCA attempts to be performed.
* Start of next CCA has already been triggered by (D)PPI.
*
* Assumptions:
* - RADIO is in RXIDLE and will transition to TX on CCAIDLE
* - TIMER is stopped
* - FEM has LNA ramped up and will ramp-up PA on CCAIDLE
*/
m_remaining_cca_attempts--;
if (m_remaining_cca_attempts == 1)
{
/* The last CCA attempt was just triggered through a (D)PPI that connects
* RADIO->EVENTS_CCABUSY to RADIO->TASKS_CCASTART. Clear that (D)PPI so that
* there's no next CCA attempt. Also, configure an additional short that will
* disable the RADIO in case busy channel is detected so that consistency with
* single CCA approach is maintained. The RADIO is expected to be disabled
* when CCA concludes with result busy.
*/
nrf_802154_trx_ppi_for_extra_cca_attempts_clear();
nrf_radio_shorts_set(
NRF_RADIO,
SHORTS_MULTI_CCA_TX | NRF_RADIO_SHORT_CCABUSY_DISABLE_MASK);
/* If the handler was delayed for the duration of a single CCA procedure, a race
* condition between the lines above and the end of CCA might occur. If that CCA
* detects busy channel, there are three cases how the CCABUSY might be placed in
* time relatively to the lines above:
* - before (D)PPI is disconnected and the shorts are reconfigured;
* - after (D)PPI is disconnected and before the shorts are reconfigured;
* - after (D)PPI id disconnected and the shorts are reconfigured;
*
* The recovery procedure for the last case is to manually trigger
* RADIO->TASKS_CCASTOP and RADIO->TASKS_DISABLE. For the second case it would
* be enough to only trigger RADIO->TASKS_DISABLE, but the cases cannot be
* distinguished in code and RADIO->TASKS_CCASTOP is harmless in the second case,
* so the same recovery procedure fixes both the second and the third case.
* For the first case such procedure will cause one fewer CCA attempt than
* requested. That's a low price to pay to ensure the RADIO always ends
* up in the expected, well-defined state, especially that this race should
* happen extremely rarely.
*/
if (nrf_radio_event_check(NRF_RADIO, NRF_RADIO_EVENT_CCABUSY))
{
/* RADIO->EVENTS_CCABUSY occurred during IRQ handler execution. Manually
* drive RADIO to state that should have been achieved through hardware and
* finish the procedure.
*/
nrf_radio_task_trigger(NRF_RADIO, NRF_RADIO_TASK_CCASTOP);
nrf_radio_task_trigger(NRF_RADIO, NRF_RADIO_TASK_DISABLE);
nrf_radio_event_clear(NRF_RADIO, NRF_RADIO_EVENT_CCABUSY);
txframe_finish();
m_trx_state = TRX_STATE_FINISHED;
nrf_802154_trx_transmit_frame_ccabusy();
}
}
}
else
{
txframe_finish();
m_trx_state = TRX_STATE_FINISHED;
nrf_802154_trx_transmit_frame_ccabusy();
}
break;
case TRX_STATE_STANDALONE_CCA:

22
drivers/nrf_802154/driver/src/nrf_802154_trx.h
View File

@ -305,13 +305,13 @@ 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:
* This operation performs differently according to cca_attempts parameter.
* When cca_attempts==0:
* - 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:
* When cca_attempts>=1:
* - 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
@ -323,8 +323,11 @@ bool nrf_802154_trx_receive_buffer_set(void * p_receive_buffer);
* 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
* If cca_attempts==1:
* - The RADIO disables receive mode
* - @ref nrf_802154_trx_transmit_frame_ccabusy from an ISR handler is called
* If cca_attempts>1:
* - Decrease cca_attempts and repeat the entire procedure
*
* @param p_transmit_buffer Pointer to a buffer containing frame to transmit.
* Must not be NULL. p_transmit_buffer[0] is the number of
@ -341,9 +344,10 @@ bool nrf_802154_trx_receive_buffer_set(void * p_receive_buffer);
* @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 cca_attempts The maximum number of CCA procedures that can be performed prior to the
* transmission before the medium is considered busy. If 0, no CCA will be
* performed. Otherwise, CCA procedures will be performed back to back until
* idle channel is detected or @p cca_attempts attempts detect busy channel.
* @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.
@ -351,7 +355,7 @@ bool nrf_802154_trx_receive_buffer_set(void * p_receive_buffer);
*/
void nrf_802154_trx_transmit_frame(const void * p_transmit_buffer,
nrf_802154_trx_ramp_up_trigger_mode_t rampup_trigg_mode,
bool cca,
uint8_t cca_attempts,
const nrf_802154_fal_tx_power_split_t * p_tx_power,
nrf_802154_trx_transmit_notifications_t notifications_mask);

25
drivers/nrf_802154/driver/src/nrf_802154_trx_dppi.c
View File

@ -67,17 +67,13 @@ void nrf_802154_trx_ppi_for_enable(void)
nrf_radio_publish_set(NRF_RADIO, NRF_RADIO_EVENT_END, NRF_802154_DPPI_RADIO_END);
nrf_radio_publish_set(NRF_RADIO, NRF_RADIO_EVENT_PHYEND, NRF_802154_DPPI_RADIO_PHYEND);
nrf_radio_publish_set(NRF_RADIO, NRF_RADIO_EVENT_CCAIDLE, NRF_802154_DPPI_RADIO_CCAIDLE);
#if NRF_802154_TEST_MODES_ENABLED
nrf_radio_publish_set(NRF_RADIO, NRF_RADIO_EVENT_CCABUSY, NRF_802154_DPPI_RADIO_CCABUSY);
#endif // NRF_802154_TEST_MODES_ENABLED
#if defined(NRF_802154_DPPI_RADIO_TXREADY)
nrf_radio_publish_set(NRF_RADIO, NRF_RADIO_EVENT_TXREADY, NRF_802154_DPPI_RADIO_TXREADY);
#endif
nrf_dppi_channels_enable(NRF_802154_DPPIC_INSTANCE,
#if NRF_802154_TEST_MODES_ENABLED
(1UL << NRF_802154_DPPI_RADIO_CCABUSY) |
#endif // NRF_802154_TEST_MODES_ENABLED
(1UL << PPI_DISABLED_EGU) |
(1UL << NRF_802154_DPPI_RADIO_READY) |
#if defined(NRF_802154_DPPI_RADIO_TXREADY)
@ -93,9 +89,7 @@ void nrf_802154_trx_ppi_for_enable(void)
void nrf_802154_trx_ppi_for_disable(void)
{
nrf_dppi_channels_disable(NRF_802154_DPPIC_INSTANCE,
#if NRF_802154_TEST_MODES_ENABLED
(1UL << NRF_802154_DPPI_RADIO_CCABUSY) |
#endif // NRF_802154_TEST_MODES_ENABLED
(1UL << PPI_DISABLED_EGU) |
(1UL << NRF_802154_DPPI_RADIO_READY) |
#if defined(NRF_802154_DPPI_RADIO_TXREADY)
@ -164,6 +158,16 @@ void nrf_802154_trx_ppi_for_ramp_up_set(nrf_radio_task_t ra
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
}
void nrf_802154_trx_ppi_for_extra_cca_attempts_set(void)
{
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_HIGH);
// Assume that NRF_802154_DPPI_RADIO_CCABUSY is enabled and NRF_RADIO_EVENT_CCABUSY publishes to it
nrf_radio_subscribe_set(NRF_RADIO, NRF_RADIO_TASK_CCASTART, NRF_802154_DPPI_RADIO_CCABUSY);
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
}
void nrf_802154_trx_ppi_for_ramp_up_reconfigure(void)
{
// Intentionally empty
@ -194,6 +198,15 @@ void nrf_802154_trx_ppi_for_ramp_up_clear(nrf_radio_task_t ramp_up_task, bool st
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
}
void nrf_802154_trx_ppi_for_extra_cca_attempts_clear(void)
{
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_HIGH);
nrf_radio_subscribe_clear(NRF_RADIO, NRF_RADIO_TASK_CCASTART);
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
}
void nrf_802154_trx_ppi_for_ramp_up_propagation_delay_wait(void)
{
__ASM("nop");

24
drivers/nrf_802154/driver/src/nrf_802154_trx_ppi.c
View File

@ -136,6 +136,20 @@ void nrf_802154_trx_ppi_for_ramp_up_set(nrf_radio_task_t ra
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
}
void nrf_802154_trx_ppi_for_extra_cca_attempts_set(void)
{
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_HIGH);
nrf_ppi_channel_endpoint_setup(NRF_PPI,
NRF_802154_PPI_RADIO_CCABUSY_TO_RADIO_CCASTART,
nrf_radio_event_address_get(NRF_RADIO, NRF_RADIO_EVENT_CCABUSY),
nrf_radio_task_address_get(NRF_RADIO, NRF_RADIO_TASK_CCASTART));
nrf_ppi_channels_enable(NRF_PPI, 1UL << NRF_802154_PPI_RADIO_CCABUSY_TO_RADIO_CCASTART);
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
}
void nrf_802154_trx_ppi_for_ramp_up_reconfigure(void)
{
nrf_egu_event_clear(NRF_802154_EGU_INSTANCE, EGU_EVENT);
@ -174,6 +188,16 @@ void nrf_802154_trx_ppi_for_ramp_up_clear(nrf_radio_task_t ramp_up_task, bool st
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
}
void nrf_802154_trx_ppi_for_extra_cca_attempts_clear(void)
{
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_HIGH);
nrf_ppi_channel_disable(NRF_PPI, NRF_802154_PPI_RADIO_CCABUSY_TO_RADIO_CCASTART);
nrf_ppi_channel_endpoint_setup(NRF_PPI, NRF_802154_PPI_RADIO_CCABUSY_TO_RADIO_CCASTART, 0, 0);
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
}
void nrf_802154_trx_ppi_for_ramp_up_propagation_delay_wait(void)
{
__ASM("nop");

10
drivers/nrf_802154/driver/src/nrf_802154_trx_ppi_api.h
View File

@ -110,6 +110,11 @@ void nrf_802154_trx_ppi_for_ramp_up_set(nrf_radio_task_t ra
nrf_802154_trx_ramp_up_trigger_mode_t trigg_mode,
bool start_timer);
/**
* @brief Set (D)PPIs to perform CCA procedures back-to-back.
*/
void nrf_802154_trx_ppi_for_extra_cca_attempts_set(void);
/**
* @brief Reconfigure (D)PPIs for the next steps in receiving or transmitting.
*
@ -129,6 +134,11 @@ void nrf_802154_trx_ppi_for_ramp_up_reconfigure(void);
*/
void nrf_802154_trx_ppi_for_ramp_up_clear(nrf_radio_task_t ramp_up_task, bool start_timer);
/**
* @brief Clear (D)PPIs to perform CCA procedures back-to-back.
*/
void nrf_802154_trx_ppi_for_extra_cca_attempts_clear(void);
/**
* @brief Get (D)PPI channel used to trigger ramp up procedure start.
*

11
drivers/nrf_802154/driver/src/nrf_802154_types_internal.h
View File

@ -40,11 +40,12 @@
typedef struct
{
nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the frame to be transmitted.
nrf_802154_fal_tx_power_split_t tx_power; // !< Power to be used when transmitting the frame, split into components to be applied on each stage on transmit path.
bool cca; // !< If the driver is to perform CCA procedure before transmission.
bool immediate; // !< If true, the driver schedules transmission immediately or never. If false, the transmission may be postponed
// until its preconditions are met.
nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the frame to be transmitted.
nrf_802154_fal_tx_power_split_t tx_power; // !< Power to be used when transmitting the frame, split into components to be applied on each stage on transmit path.
bool cca; // !< If the driver is to perform CCA procedure before transmission.
bool immediate; // !< If true, the driver schedules transmission immediately or never. If false, the transmission may be postponed
// until its preconditions are met.
uint8_t extra_cca_attempts; // !< Maximum number of additional CCA attempts that can be performed if the first attempt returns busy channel. Ignored if @ref cca equals @c false.
} nrf_802154_transmit_params_t;
typedef struct

16
drivers/nrf_802154/serialization/CMakeLists.txt
View File

@ -58,15 +58,17 @@ target_sources(nrf-802154-serialization
)
if (SER_HOST)
target_include_directories(nrf-802154-serialization-interface
INTERFACE
include/host
)
target_sources(nrf-802154-serialization
PRIVATE
src/nrf_802154_spinel_app.c
src/nrf_802154_spinel_dec_app.c
)
target_compile_definitions(nrf-802154-serialization-interface
INTERFACE
# The core for which the code is compiled does not contain the 802.15.4 radio driver
# It contains the serialized radio driver functions.
NRF_802154_SERIALIZATION_HOST=1
)
else ()
target_sources(nrf-802154-serialization
PRIVATE
@ -75,8 +77,14 @@ else ()
)
endif()
target_link_libraries(nrf-802154-serialization-interface
INTERFACE
nrf-802154-common-interface
)
target_link_libraries(nrf-802154-serialization
PRIVATE
nrf-802154-serialization-interface
nrf-802154-platform
nrf-802154-common
)

988
drivers/nrf_802154/serialization/include/host/nrf_802154.h
View File

@ -1,988 +0,0 @@
/*
* Copyright (c) 2020 - 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.
*
*/
/**
* @file nrf_802154.h
* @brief This file mimics API provided by nrf_802154.h but provides only serialized functions.
* We are trying to keep them as simillar as currently possible.
*/
#ifndef NRF_802154_H_
#define NRF_802154_H_
#include <stdint.h>
#include <stdbool.h>
#include "nrf_802154_callouts.h"
#include "nrf_802154_config.h"
#include "nrf_802154_types.h"
/**
* @brief Timestamp value indicating that the timestamp is inaccurate.
*/
#define NRF_802154_NO_TIMESTAMP 0
/**
* @brief Invalid delayed timeslot identifier.
*/
#define NRF_802154_RESERVED_INVALID_ID UINT32_MAX
/**
* @brief Reception window identifier reserved for immediate reception.
*/
#define NRF_802154_RESERVED_IMM_RX_WINDOW_ID (UINT32_MAX - 1)
/**
* @brief Upper bound for delayed reception window identifiers used by the application.
*
* All integers ranging from 0 to @ref NRF_802154_RESERVED_DRX_ID_UPPER_BOUND (inclusive)
* can be used by the application as identifiers of delayed reception windows.
*/
#define NRF_802154_RESERVED_DRX_ID_UPPER_BOUND (UINT32_MAX - 4)
/**
* @brief Select the source matching algorithm.
*
* @note This method should be called after driver initialization, but before transceiver is enabled.
*
* When calling @ref nrf_802154_ack_data_pending_bit_should_be_set, one of several algorithms
* for source address matching will be chosen. To ensure a specific algorithm is selected,
* call this function before @ref rf_802154_ack_data_pending_bit_should_be_set.
*
* @param[in] match_method Source address matching method to be used.
*/
void nrf_802154_src_addr_matching_method_set(nrf_802154_src_addr_match_t match_method);
/**
* @brief Adds the address of a peer node for which the provided ACK data
* is to be added to the pending bit list.
*
* The pending bit list works differently, depending on the upper layer for which the source
* address matching method is selected:
* - For Thread, @ref NRF_802154_SRC_ADDR_MATCH_THREAD
* - For Zigbee, @ref NRF_802154_SRC_ADDR_MATCH_ZIGBEE
* - For Standard-compliant, @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1
* For more information, see @ref nrf_802154_src_addr_match_t.
*
* The method can be set during initialization phase by calling @ref nrf_802154_src_addr_matching_method_set.
*
* @param[in] p_addr Array of bytes containing the address of the node (little-endian).
* @param[in] extended If the given address is an extended MAC address or a short MAC address.
* @param[in] p_data Pointer to the buffer containing data to be set.
* @param[in] length Length of @p p_data.
* @param[in] data_type Type of data to be set. Refer to the @ref nrf_802154_ack_data_t type.
*
* @retval True Address successfully added to the list.
* @retval False Not enough memory to store this address in the list.
*/
bool nrf_802154_ack_data_set(const uint8_t * p_addr,
bool extended,
const void * p_data,
uint16_t length,
nrf_802154_ack_data_t data_type);
/**
* @brief Removes the address of a peer node for which the ACK data is set from the pending bit list.
*
* The ACK data that was previously set for the given address is automatically removed.
*
* The pending bit list works differently, depending on the upper layer for which the source
* address matching method is selected:
* - For Thread, @ref NRF_802154_SRC_ADDR_MATCH_THREAD
* - For Zigbee, @ref NRF_802154_SRC_ADDR_MATCH_ZIGBEE
* - For Standard-compliant, @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1
* For more information, see @ref nrf_802154_src_addr_match_t.
*
* The method can be set during initialization phase by calling @ref nrf_802154_src_addr_matching_method_set.
*
* @param[in] p_addr Array of bytes containing the address of the node (little-endian).
* @param[in] extended If the given address is an extended MAC address or a short MAC address.
* @param[in] data_type Type of data to be removed. Refer to the @ref nrf_802154_ack_data_t type.
*
* @retval True Address removed from the list.
* @retval False Address not found in the list.
*/
bool nrf_802154_ack_data_clear(const uint8_t * p_addr,
bool extended,
nrf_802154_ack_data_t data_type);
/**
* @brief Enables or disables setting a pending bit in automatically transmitted ACK frames.
*
* @note Setting a pending bit in automatically transmitted ACK frames is enabled by default.
*
* The radio driver automatically sends ACK frames in response frames destined for this node with
* the ACK Request bit set. The pending bit in the ACK frame can be set or cleared regarding data
* in the indirect queue destined for the ACK destination.
*
* If setting a pending bit in ACK frames is disabled, the pending bit in every ACK frame is set.
* If setting a pending bit in ACK frames is enabled, the radio driver checks if there is data
* in the indirect queue destined for the ACK destination. If there is no such data,
* the pending bit is cleared.
*
* @note Due to the ISR latency, the radio driver might not be able to verify if there is data
* in the indirect queue before ACK is sent. In this case, the pending bit is set.
*
* @param[in] enabled If setting a pending bit in ACK frames is enabled.
*/
void nrf_802154_auto_pending_bit_set(bool enabled);
/**
* @brief Adds the address of a peer node to the pending bit list.
*
* The pending bit list works differently, depending on the upper layer for which the source
* address matching method is selected:
* - For Thread, @ref NRF_802154_SRC_ADDR_MATCH_THREAD
* - For Zigbee, @ref NRF_802154_SRC_ADDR_MATCH_ZIGBEE
* - For Standard-compliant, @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1
* For more information, see @ref nrf_802154_src_addr_match_t.
*
* The method can be set during initialization phase by calling @ref nrf_802154_src_addr_matching_method_set.
*
* @note This function makes a copy of the given address.
*
* @param[in] p_addr Array of bytes containing the address of the node (little-endian).
* @param[in] extended If the given address is an extended MAC address or a short MAC address.
*
* @retval True The address is successfully added to the list.
* @retval False Not enough memory to store the address in the list.
*/
bool nrf_802154_pending_bit_for_addr_set(const uint8_t * p_addr, bool extended);
/**
* @brief Removes address of a peer node from the pending bit list.
*
* The pending bit list works differently, depending on the upper layer for which the source
* address matching method is selected:
* - For Thread, @ref NRF_802154_SRC_ADDR_MATCH_THREAD
* - For Zigbee, @ref NRF_802154_SRC_ADDR_MATCH_ZIGBEE
* - For Standard-compliant, @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1
* For more information, see @ref nrf_802154_src_addr_match_t.
*
* The method can be set during initialization phase by calling @ref nrf_802154_src_addr_matching_method_set.
*
* @param[in] p_addr Array of bytes containing the address of the node (little-endian).
* @param[in] extended If the given address is an extended MAC address or a short MAC address.
*
* @retval True The address is successfully removed from the list.
* @retval False No such address in the list.
*/
bool nrf_802154_pending_bit_for_addr_clear(const uint8_t * p_addr, bool extended);
/**
* @brief Removes all addresses of a given type from the pending bit list.
*
* The pending bit list works differently, depending on the upper layer for which the source
* address matching method is selected:
* - For Thread, @ref NRF_802154_SRC_ADDR_MATCH_THREAD
* - For Zigbee, @ref NRF_802154_SRC_ADDR_MATCH_ZIGBEE
* - For Standard-compliant, @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1
* For more information, see @ref nrf_802154_src_addr_match_t.
*
* The method can be set during initialization phase by calling @ref nrf_802154_src_addr_matching_method_set.
*
* @param[in] extended If the function is to remove all extended MAC addresses or all short
* addresses.
*/
void nrf_802154_pending_bit_for_addr_reset(bool extended);
/**
* @brief Configures the radio CCA mode and threshold.
*
* @param[in] p_cca_cfg Pointer to the CCA configuration structure. Only fields relevant to
* the selected mode are updated.
*/
void nrf_802154_cca_cfg_set(const nrf_802154_cca_cfg_t * p_cca_cfg);
/**
* @brief Gets the current radio CCA configuration.
*
* @param[out] p_cca_cfg Pointer to the structure for the current CCA configuration.
*/
void nrf_802154_cca_cfg_get(nrf_802154_cca_cfg_t * p_cca_cfg);
/**
* @brief Initializes the 802.15.4 driver.
*
* This function initializes the RADIO peripheral in the @ref RADIO_STATE_SLEEP state.
*
* @note This function is to be called once, before any other functions from this module.
*/
void nrf_802154_init(void);
/**
* @brief Changes the radio state to the @ref RADIO_STATE_SLEEP state.
*
* The sleep state is the lowest power state. In this state, the radio cannot transmit or receive
* frames. It is the only state in which the driver releases the high-frequency clock and does not
* request timeslots from a radio arbiter.
*
* @note If another module requests it, the high-frequency clock may be enabled even in the radio
* sleep state.
*
* @retval true The radio changes its state to the low power mode.
* @retval false The driver could not schedule changing state.
*/
bool nrf_802154_sleep(void);
/**
* @brief Changes the radio state to the @ref RADIO_STATE_SLEEP state if the radio is idle.
*
* The sleep state is the lowest power state. In this state, the radio cannot transmit or receive
* frames. It is the only state in which the driver releases the high-frequency clock and does not
* request timeslots from a radio arbiter.
*
* @note If another module requests it, the high-frequency clock may be enabled even in the radio
* sleep state.
*
* @retval NRF_802154_SLEEP_ERROR_NONE The radio changes its state to the low power mode.
* @retval NRF_802154_SLEEP_ERROR_BUSY The driver could not schedule changing state.
*/
nrf_802154_sleep_error_t nrf_802154_sleep_if_idle(void);
/**
* @brief Changes the radio state to @ref RADIO_STATE_RX.
*
* In the receive state, the radio receives frames and may automatically send ACK frames when
* appropriate. The received frame is reported to the higher layer by a call to
* @ref nrf_802154_received.
*
* @retval true The radio enters the receive state.
* @retval false The driver could not enter the receive state.
*/
bool nrf_802154_receive(void);
/**
* @brief Requests reception at the specified time.
*
* This function works as a delayed version of @ref nrf_802154_receive. It is asynchronous.
* It queues the delayed reception using the Radio Scheduler module.
* If the delayed reception cannot be performed (@ref nrf_802154_receive_at would return false)
* or the requested reception timeslot is denied, @ref nrf_802154_receive_failed is called
* with the @ref NRF_802154_RX_ERROR_DELAYED_TIMESLOT_DENIED argument.
*
* If the requested reception time is in the past, the function returns false and does not
* schedule reception.
*
* A scheduled reception can be cancelled by a call to @ref nrf_802154_receive_at_cancel.
*
* @note The identifier @p id must be unique. It must not have the same value as identifiers
* of other delayed timeslots active at the moment, so that it can be mapped unambiguously
* to an active delayed operation if the request is successful. In particular, none of the reserved
* identifiers can be used.
*
* @param[in] rx_time Absolute time used by the SL Timer, in microseconds (us).
* @param[in] timeout Reception timeout (counted from @p rx_time), in microseconds (us).
* @param[in] channel Radio channel on which the frame is to be received.
* @param[in] id Identifier of the scheduled reception window. If the reception has been
* scheduled successfully, the value of this parameter can be used in
* @ref nrf_802154_receive_at_cancel to cancel it.
*
* @retval true The reception procedure was scheduled.
* @retval false The driver could not schedule the reception procedure.
*/
bool nrf_802154_receive_at(uint64_t rx_time,
uint32_t timeout,
uint8_t channel,
uint32_t id);
/**
* @brief Cancels a delayed reception scheduled by a call to @ref nrf_802154_receive_at.
*
* If the receive window has been scheduled but has not started yet, this function prevents
* entering the receive window. If the receive window has been scheduled and has already started,
* the radio remains in the receive state, but a window timeout will not be reported.
*
* @param[in] id Identifier of the delayed reception window to be cancelled. If the provided
* value does not refer to any scheduled or active receive window, the function
* returns false.
*
* @retval true The delayed reception was scheduled and successfully cancelled.
* @retval false No delayed reception was scheduled.
*/
bool nrf_802154_receive_at_cancel(uint32_t id);
/** @brief Sets the channel on which the radio is to operate.
*
* @param[in] channel Channel number (11-26).
*/
void nrf_802154_channel_set(uint8_t channel);
/**
* @brief Gets the channel on which the radio operates.
*
* @returns Channel number (11-26).
*/
uint8_t nrf_802154_channel_get(void);
/**
* @brief Sets the PAN ID used by the device.
*
* @param[in] p_pan_id Pointer to the PAN ID (2 bytes, little-endian).
*
* This function makes a copy of the PAN ID.
*/
void nrf_802154_pan_id_set(const uint8_t * p_pan_id);
/**
* @brief Sets the short address of the device.
*
* @param[in] p_short_address Pointer to the short address (2 bytes, little-endian).
*
* This function makes a copy of the address.W
*/
void nrf_802154_short_address_set(const uint8_t * p_short_address);
/**
* @brief Sets the extended address of the device.
*
* @param[in] p_extended_address Pointer to the extended address (8 bytes, little-endian).
*
* This function makes a copy of the address.
*/
void nrf_802154_extended_address_set(const uint8_t * p_extended_address);
/**
* @brief Configures the device as the PAN coordinator.
*
* @note That information is used for packet filtering.
*
* @param[in] enabled The radio is configured as the PAN coordinator.
*/
void nrf_802154_pan_coord_set(bool enabled);
#if NRF_802154_PAN_COORD_GET_ENABLED
/**
* @brief Checks if the radio is configured as the PAN coordinator.
*
* @retval true The radio is configured as the PAN coordinator.
* @retval false The radio is not configured as the PAN coordinator.
*/
bool nrf_802154_pan_coord_get(void);
#endif // NRF_802154_PAN_COORD_GET_ENABLED
/**
* @brief Enables or disables the promiscuous radio mode.
*
* @note The promiscuous mode is disabled by default.
*
* In the promiscuous mode, the driver notifies the higher layer that it received any frame
* (regardless frame type or destination address).
* In normal mode (not promiscuous), the higher layer is not notified about ACK frames and frames
* with unknown type. Also, frames with a destination address not matching the device address are
* ignored.
*
* @param[in] enabled If the promiscuous mode is to be enabled.
*/
void nrf_802154_promiscuous_set(bool enabled);
/*
* @brief Changes the radio state to @ref RADIO_STATE_CCA.
*
* @note @ref nrf_802154_cca_done can be called before this function returns a result.
*
* In the CCA state, the radio verifies if the channel is clear. The result of the verification is
* reported to the higher layer by @ref nrf_802154_cca_done.
*
* @retval true The CCA procedure was scheduled.
* @retval false The driver could not schedule the CCA procedure.
*/
bool nrf_802154_cca(void);
#if NRF_802154_CARRIER_FUNCTIONS_ENABLED
/**
* @brief Changes the radio state to continuous carrier.
*
* @note When the radio is emitting continuous carrier signals, it blocks all transmissions on the
* selected channel. This function is to be called only during radio tests. Do not
* use it during normal device operation.
*
* @retval true The continuous carrier procedure was scheduled.
* @retval false The driver could not schedule the continuous carrier procedure.
*/
bool nrf_802154_continuous_carrier(void);
/**
* @brief Changes the radio state to modulated carrier.
*
* @note When the radio is emitting modulated carrier signals, it blocks all transmissions on the
* selected channel. This function is to be called only during radio tests. Do not
* use it during normal device operation.
*
* @param[in] p_data Pointer to a buffer to modulate the carrier with. The first byte is the data length.
*
* @retval true The modulated carrier procedure was scheduled.
* @retval false The driver could not schedule the modulated carrier procedure.
*/
bool nrf_802154_modulated_carrier(const uint8_t * p_data);
#endif // NRF_802154_CARRIER_FUNCTIONS_ENABLED
/**
* @brief Changes the radio state to energy detection.
*
* In the energy detection state, the radio detects the maximum energy for a given time.
* The result of the detection is reported to the higher layer by @ref nrf_802154_energy_detected.
*
* @note @ref nrf_802154_energy_detected can be called before this function returns a result.
* @note Performing the energy detection procedure can take longer than requested in @p time_us.
* The procedure is performed only during the timeslots granted by a radio arbiter.
* It can be interrupted by other protocols using the radio hardware. If the procedure is
* interrupted, it is automatically continued and the sum of time periods during which the
* procedure is carried out is not less than the requested @p time_us.
*
* @param[in] time_us Duration of energy detection procedure. The given value is rounded up to
* multiplication of 8 symbols (128 us).
*
* @retval true The energy detection procedure was scheduled.
* @retval false The driver could not schedule the energy detection procedure.
*/
bool nrf_802154_energy_detection(uint32_t time_us);
/**
* @brief Changes the radio state to @ref RADIO_STATE_TX.
*
* @note If the CPU is halted or interrupted while this function is executed,
* @ref nrf_802154_transmitted or @ref nrf_802154_transmit_failed can be called before this
* function returns a result.
*
* @note This function is implemented in zero-copy fashion. It passes the given buffer pointer to
* the RADIO peripheral.
*
* In the transmit state, the radio transmits a given frame. If requested, it waits for
* an ACK frame. Depending on @ref NRF_802154_ACK_TIMEOUT_ENABLED, the radio driver automatically
* stops waiting for an ACK frame or waits indefinitely for an ACK frame. If it is configured to
* wait, the MAC layer is responsible for calling @ref nrf_802154_receive or
* @ref nrf_802154_sleep after the ACK timeout.
* The transmission result is reported to the higher layer by calls to @ref nrf_802154_transmitted
* or @ref nrf_802154_transmit_failed.
*
* @verbatim
* p_data
* v
* +-----+-----------------------------------------------------------+------------+
* | PHR | MAC header and payload | FCS |
* +-----+-----------------------------------------------------------+------------+
* | |
* | <---------------------------- PHR -----------------------------------> |
* @endverbatim
*
* @param[in] p_data Pointer to the array with data to transmit. The first byte must contain
* frame length (including FCS). The following bytes contain data.
* The CRC is computed automatically by the radio hardware. Therefore,
* the FCS field can contain any bytes.
* @param[in] p_metadata Pointer to metadata structure. Contains detailed properties of data
* to transmit. If @c NULL following metadata are used:
* Field | Value
* ----------------|-----------------------------------------------------
* @c frame_props | @ref NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT
* @c cca | @c true
*
* @retval true The transmission procedure was scheduled.
* @retval false The driver could not schedule the transmission procedure.
*/
bool nrf_802154_transmit_raw(uint8_t * p_data,
const nrf_802154_transmit_metadata_t * p_metadata);
/**
* @}
* @defgroup nrf_802154_csma CSMA-CA procedure
* @{
*/
#if NRF_802154_CSMA_CA_ENABLED || defined(DOXYGEN)
/**
* @brief Performs the CSMA-CA procedure and transmits a frame in case of success.
*
* The end of the CSMA-CA procedure is notified by @ref nrf_802154_transmitted_raw or
* @ref nrf_802154_transmit_failed.
*
* @note The driver may be configured to automatically time out waiting for an ACK frame depending
* on @ref NRF_802154_ACK_TIMEOUT_ENABLED. If the automatic ACK timeout is disabled,
* the CSMA-CA procedure does not time out waiting for an ACK frame if a frame
* with the ACK request bit set was transmitted. The MAC layer is expected to manage the timer
* to time out waiting for the ACK frame. This timer can be started
* by @ref nrf_802154_tx_started. When the timer expires, the MAC layer is expected
* to call @ref nrf_802154_receive or @ref nrf_802154_sleep to stop waiting for the ACK frame.
*
* @param[in] p_data Pointer to the frame to transmit. See also @ref nrf_802154_transmit_raw.
* @param[in] p_metadata Pointer to metadata structure. Contains detailed properties of data
* to transmit. If @c NULL following metadata are used:
* Field | Value
* ----------------|-----------------------------------------------------
* @c frame_props | @ref NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT
*
* @retval true The chain of CSMA-CA and transmission procedure was scheduled.
* @retval false The driver could not schedule the procedure chain.
*/
bool nrf_802154_transmit_csma_ca_raw(uint8_t * p_data,
const nrf_802154_transmit_csma_ca_metadata_t * p_metadata);
/**
* @brief Sets the minimum value of the backoff exponent (BE) in the CSMA-CA algorithm.
*
* @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled.
*
* @param[in] min_be Minimum value of the backoff exponent.
*
* @retval true When value provided by @p min_be has been set successfully.
* @retval false Otherwise.
*/
bool nrf_802154_csma_ca_min_be_set(uint8_t min_be);
/**
* @brief Gets the minimum value of the backoff exponent (BE) in the CSMA-CA algorithm.
*
* @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled.
*
* @return Current minimum value of the backoff exponent.
*/
uint8_t nrf_802154_csma_ca_min_be_get(void);
/**
* @brief Sets the maximum value of the backoff exponent (BE) in the CSMA-CA algorithm.
*
* @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled.
*
* @param[in] max_be Maximum value of the backoff exponent.
*
* @retval true When value provided by @p max_be has been set successfully.
* @retval false Otherwise.
*/
bool nrf_802154_csma_ca_max_be_set(uint8_t max_be);
/**
* @brief Gets the maximum value of the backoff exponent (BE) in the CSMA-CA algorithm.
*
* @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled.
*
* @return Current maximum value of the backoff exponent.
*/
uint8_t nrf_802154_csma_ca_max_be_get(void);
/**
* @brief Sets the maximum number of backoffs the CSMA-CA algorithm will attempt before declaring
* a channel access failure.
*
* @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled.
*
* @param[in] max_backoffs Maximum number of backoffs.
*/
void nrf_802154_csma_ca_max_backoffs_set(uint8_t max_backoffs);
/**
* @brief Gets the maximum number of backoffs the CSMA-CA algorithm will attempt before declaring
* a channel access failure.
*
* @note This function is available if @ref NRF_802154_CSMA_CA_ENABLED is enabled.
*
* @return Current maximum number of backoffs.
*/
uint8_t nrf_802154_csma_ca_max_backoffs_get(void);
#endif // NRF_802154_CSMA_CA_ENABLED
/**
* @brief Requests transmission at the specified time.
*
* @note This function is implemented in a zero-copy fashion. It passes the given buffer pointer to
* the RADIO peripheral.
*
*
* This function works as a delayed version of @ref nrf_802154_transmit_raw. It is asynchronous.
* It queues the delayed transmission using the Radio Scheduler module and performs it
* at the specified time.
*
* If the delayed transmission is successfully performed, @ref nrf_802154_transmitted_raw is called.
* If the delayed transmission cannot be performed ( @ref nrf_802154_transmit_raw would return @c false)
* or the requested transmission timeslot is denied, @ref nrf_802154_transmit_failed with the
* @ref NRF_802154_TX_ERROR_TIMESLOT_DENIED argument is called.
*
* This function is designed to transmit the first symbol of SHR at the given time.
*
* If the requested transmission time is in the past, the function returns @c false and does not
* schedule transmission.
*
* A successfully scheduled transmission can be cancelled by a call
* to @ref nrf_802154_transmit_at_cancel.
*
* @param[in] p_data Pointer to the array with data to transmit. The first byte must contain
* the frame length (including FCS). The following bytes contain data.
* The CRC is computed automatically by the radio hardware. Therefore,
* the FCS field can contain any bytes.
* @param[in] tx_time Absolute time used by the SL Timer, in microseconds (us).
* @param[in] p_metadata Pointer to metadata structure. Contains detailed properties of data
* to transmit. If @c NULL following metadata are used:
* Field | Value
* ----------------|-----------------------------------------------------
* @c frame_props | @ref NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT
* @c cca | @c true
* @c channel | As returned by @ref nrf_802154_channel_get
*
* @retval true The transmission procedure was scheduled.
* @retval false The driver could not schedule the transmission procedure.
*/
bool nrf_802154_transmit_raw_at(uint8_t * p_data,
uint64_t tx_time,
const nrf_802154_transmit_at_metadata_t * p_metadata);
/**
* @brief Cancels a delayed transmission scheduled by a call to @ref nrf_802154_transmit_raw_at.
*
* If a delayed transmission has been scheduled but the transmission has not been started yet,
* a call to this function prevents the transmission. If the transmission is ongoing,
* it will not be aborted.
*
* If a delayed transmission has not been scheduled (or has already finished), this function does
* not change state and returns false.
*
* @retval true The delayed transmission was scheduled and successfully cancelled.
* @retval false No delayed transmission was scheduled.
*/
bool nrf_802154_transmit_at_cancel(void);
/**
* @brief Notifies the driver that the buffer containing the received frame is not used anymore.
*
* @note The buffer pointed to by @p p_data may be modified by this function.
* @note This function can be safely called only from the main context. To free the buffer from
* a callback or the IRQ context, use @ref nrf_802154_buffer_free_immediately_raw.
*
* @param[in] p_data Pointer to the buffer containing the received data that is no longer needed
* by the higher layer.
*/
void nrf_802154_buffer_free_raw(uint8_t * p_data);
/**
* @brief Sets the transmit power.
*
* @note The driver recalculates the requested value to the nearest value accepted by the hardware.
* The calculation result is rounded up.
*
* @param[in] power Transmit power in dBm.
*/
void nrf_802154_tx_power_set(int8_t power);
/**
* @brief Gets the currently set transmit power.
*
* @returns Currently used transmit power, in dBm.
*/
int8_t nrf_802154_tx_power_get(void);
/**
* @brief Converts the energy level received during the energy detection procedure to a dBm value.
*
* @param[in] energy_level Energy level passed by @ref nrf_802154_energy_detected.
*
* @return Result of the energy detection procedure in dBm.
*/
int8_t nrf_802154_dbm_from_energy_level_calculate(uint8_t energy_level);
/**
* @brief Calculates the timestamp of the first symbol of the preamble in a received frame.
*
* @deprecated This function is deprecated. Use @ref nrf_802154_timestamp_end_to_phr_convert
* instead and adjust the code that calls this function to rely on the timestamp of the first symbol
* of the PHR, not the timestamp of the first symbol of the frame.
*
* @param[in] end_timestamp Timestamp of the end of the last symbol in the frame,
* in microseconds.
* @param[in] psdu_length Number of bytes in the frame PSDU.
*
* @return Timestamp of the beginning of the first preamble symbol of a given frame,
* in microseconds.
*/
uint64_t nrf_802154_first_symbol_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length);
/**
* @brief Calculates the timestamp of the MAC Header in a received frame.
*
* @deprecated This function is deprecated. Use @ref nrf_802154_timestamp_end_to_phr_convert
* instead and adjust the code that calls this function to rely on the timestamp of the first symbol
* of the PHR, not the MAC Header timestamp.
*
* @param[in] end_timestamp Timestamp of the end of the last symbol in the frame,
* in microseconds.
* @param[in] psdu_length Number of bytes in the frame PSDU.
*
* @return Timestamp of the MHR of a given frame, in microseconds.
*/
uint64_t nrf_802154_mhr_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length);
/**
* @brief Converts the timestamp of the frame's end to the timestamp of the start of its PHR.
*
* This function calculates the time when the first symbol of the PHR is at the local antenna.
*
* @param[in] end_timestamp Timestamp of the end of the last symbol in the frame,
* in microseconds.
* @param[in] psdu_length Number of bytes in the frame PSDU.
*
* @return Timestamp of the start of the PHR of a given frame, in microseconds.
*/
uint64_t nrf_802154_timestamp_end_to_phr_convert(uint64_t end_timestamp, uint8_t psdu_length);
/**
* @brief Converts the timestamp of the frame's PHR to the timestamp of the start of its SHR.
*
* This function converts the time when the first symbol of the frame's PHR is at the local antenna
* to the timestamp of the start of the frame's SHR.
*
* @param[in] phr_timestamp Timestamp of the frame's PHR.
*
* @return Timestamp of the start of the SHR of a given frame, in microseconds.
*/
uint64_t nrf_802154_timestamp_phr_to_shr_convert(uint64_t phr_timestamp);
/**
* @}
* @defgroup nrf_802154_ifs Inter-frame spacing feature
* @{
*/
#if NRF_802154_IFS_ENABLED || defined(DOXYGEN)
/**
* @brief Gets IFS operation mode.
*
* @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled.
*
* @return Current IFS operation mode. Refer to @ref nrf_802154_ifs_mode_t for details.
*/
nrf_802154_ifs_mode_t nrf_802154_ifs_mode_get(void);
/**
* @brief Sets IFS operation mode.
*
* @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled.
*
* @param[in] mode IFS operation mode. Refer to @ref nrf_802154_ifs_mode_t for details.
*
* @retval true The update of IFS operation mode was successful.
* @retval false The update of IFS operation mode failed. Provided mode is unsupported
*/
bool nrf_802154_ifs_mode_set(nrf_802154_ifs_mode_t mode);
/**
* @brief Gets Short IFS period in microseconds.
*
* @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled.
*
* @return Current Short IFS period in microseconds.
*/
uint16_t nrf_802154_ifs_min_sifs_period_get(void);
/**
* @brief Sets Short IFS period in microseconds.
*
* @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled.
*
* @param[in] period Short IFS period in microseconds.
*/
void nrf_802154_ifs_min_sifs_period_set(uint16_t period);
/**
* @brief Gets Long IFS period in microseconds.
*
* @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled.
*
* @return Current Long IFS period in microseconds.
*/
uint16_t nrf_802154_ifs_min_lifs_period_get(void);
/**
* @brief Sets Long IFS period in microseconds.
*
* @note This function is available if @ref NRF_802154_IFS_ENABLED is enabled.
*
* @param[in] period Long IFS period in microseconds.
*/
void nrf_802154_ifs_min_lifs_period_set(uint16_t period);
#endif // NRF_802154_IFS_ENABLED
/**
* @}
* @defgroup nrf_802154_capabilities Radio driver run-time capabilities feature.
* @{
*/
/**
* @brief Gets nRF 802.15.4 Radio Driver Capabilities.
*
* @return Capabilities of the radio driver.
*/
nrf_802154_capabilities_t nrf_802154_capabilities_get(void);
/**
* @brief Gets the current time.
*
* The time returned by this function is to be used to calculate timing parameters for
* @ref nrf_802154_transmit_at and @ref nrf_802154_receive_at functions.
*
* @returns Current time in microseconds.
*/
uint64_t nrf_802154_time_get(void);
/**
* @}
* @defgroup nrf_802154_security Radio driver MAC security feature.
* @{
*/
/**
* @brief Sets nRF 802.15.4 Radio Driver Global MAC Frame Counter.
*
* The driver automatically increments the counter in every outgoing frame
* which uses the Global MAC Frame Counter.
* This call is meant to set the initial value of the frame counter.
*
* @param[in] frame_counter Global MAC Frame Counter to set.
*/
void nrf_802154_security_global_frame_counter_set(uint32_t frame_counter);
/**
* @brief Sets nRF 802.15.4 Radio Driver MAC Global Frame Counter if the value passed is larger than current.
*
* @param[in] frame_counter Frame counter to set.
*/
void nrf_802154_security_global_frame_counter_set_if_larger(uint32_t frame_counter);
/**
* @brief Store the 802.15.4 MAC Security Key inside the nRF 802.15.4 Radio Driver.
*
* @param[in] p_key Pointer to the key to store. Refer to @ref nrf_802154_key_t for details.
* Storing the key copies the content of the key and key ID into the Radio Driver.
* This input parameter can be destroyed after the call.
*
* @note This function is not reentrant and must be called from thread context only.
*
* @retval NRF_802154_SECURITY_ERROR_NONE Storing of key is successful.
* @retval NRF_802154_SECURITY_ERROR_TYPE_NOT_SUPPORTED Type of the key is not supported.
* @retval NRF_802154_SECURITY_ERROR_MODE_NOT_SUPPORTED ID mode of the key is not supported.
* @retval NRF_802154_SECURITY_ERROR_ALREADY_PRESENT Failed to store the key - key of such id is already
* present. Remove the key first to overwrite.
* @retval NRF_802154_SECURITY_ERROR_STORAGE_FULL Failed to store the key - storage full.
*/
nrf_802154_security_error_t nrf_802154_security_key_store(nrf_802154_key_t * p_key);
/**
* @brief Remove the 802.15.4 MAC Security Key from the nRF 802.15.4 Radio Driver.
*
* @param[in] p_id Pointer to the ID of the key to remove.
*
* @note This function is not reentrant and must be called from thread context only.
*
* @retval NRF_802154_SECURITY_ERROR_NONE Removal of key is successful.
* @retval NRF_802154_SECURITY_ERROR_KEY_NOT_FOUND Failed to remove the key - no such key found.
*/
nrf_802154_security_error_t nrf_802154_security_key_remove(nrf_802154_key_id_t * p_id);
/**
* @}
* @defgroup nrf_802154_ie_writer Radio driver Information Element data injection feature.
* @{
*/
/**
* @brief Sets the value of CSL period to inject into the CSL information element.
*
* @param[in] period CSL period value.
*/
void nrf_802154_csl_writer_period_set(uint16_t period);
/**
* @brief Sets the anchor time based on which the next CSL window time and the CSL phase is calculated.
*
* This function sets an anchor time based on which the times of future CSL windows are calculated.
* When this anchor time is used for calculations, it is assumed that it points to a time where
* the first bit of MAC header of the frame received from a peer happens. In other words, the anchor
* time should point to a time where CSL phase would be equal 0. As a result, CSL phase can always
* be calculated relatively to a time given by the equation @c anchor_time + @c n * @c csl_period
* where @c n is an integer. Note that the reasoning holds irrespectively of signedness of @c n
* so the anchor time can be either in the past or in the future.
*
* This function should be called after calling @ref nrf_802154_csl_writer_period_set and every time
* when the CSL communication desynchronizes.
*
* If this function is not called a legacy CSL operation mode is chosen. The CSL phase is then
* calculated based on the time of the nearest scheduled CSL reception window and can be undefined,
* if no such window was scheduled.
*
* @param[in] anchor_time Anchor time in microseconds.
*/
void nrf_802154_csl_writer_anchor_time_set(uint64_t anchor_time);
/**
* @}
* @defgroup nrf_802154_stats Statistics and measurements
* @{
*/
/**
* @brief Get time stamps of events gathered by the last operation.
*
* @param[out] p_stat_timestamps Structure that will be filled with current time stamps of events.
*/
void nrf_802154_stat_timestamps_get(nrf_802154_stat_timestamps_t * p_stat_timestamps);
/**
* @}
* @defgroup nrf_802154_test_modes Test modes
* @{
*/
#if NRF_802154_TEST_MODES_ENABLED
/**
* @brief Gets the current CSMA/CA backoff test mode.
*
* @return Current CSMA/CA backoff test mode.
*/
nrf_802154_test_mode_csmaca_backoff_t nrf_802154_test_mode_csmaca_backoff_get(void);
/**
* @brief Sets the csmaca backoff test mode.
*
* @param[in] value CSMA/CA backoff test mode (See @ref nrf_802154_test_mode_csmaca_backoff_t
* for defined values).
*/
void nrf_802154_test_mode_csmaca_backoff_set(nrf_802154_test_mode_csmaca_backoff_t value);
#endif // NRF_802154_TEST_MODES_ENABLED
/** @} */
#endif

184
drivers/nrf_802154/serialization/include/host/nrf_802154_callouts.h
View File

@ -1,184 +0,0 @@
/*
* Copyright (c) 2020 - 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.
*
*/
/**@file nrf_802154_callouts.h
* @brief Provides function prototypes required by nRF 802.15.4 Radio Driver
*
* Functions whose prototypes are defined in this file are to be implemented
* by an application using the nRF 802.15.4 Radio Driver.
*/
/**
* @defgroup nrf_802154_callouts
* 802.15.4 radio driver callouts
* @{
*
*/
#ifndef NRF_802154_CALLOUTS_H_
#define NRF_802154_CALLOUTS_H_
#include <stdint.h>
#include <stdbool.h>
#include "nrf_802154_types.h"
/**
* @brief Notifies that the CCA procedure has finished.
*
* @param[in] channel_free Indication if the channel is free.
*/
extern void nrf_802154_cca_done(bool channel_free);
/**
* @brief Notifies that the CCA procedure failed.
*
* @param[in] error Reason of the failure.
*/
extern void nrf_802154_cca_failed(nrf_802154_cca_error_t error);
/**
* @brief Notifies that the energy detection procedure finished.
*
* @note This function passes the EnergyLevel defined in the 802.15.4-2006 specification:
* 0x00 - 0xff, where 0x00 represents -75dBm (10dBm above the worst allowed sensitivity level,
* which is -85dBm) and 0xff is the highest possible energy detection level, for which
* the measurements are guaranteed map linearly to the real energy level in dBm.
* To calculate the result in dBm, use @ref nrf_802154_dbm_from_energy_level_calculate.
*
* @param[in] result Maximum energy detected during the energy detection procedure.
*/
extern void nrf_802154_energy_detected(uint8_t result);
/**
* @brief Notifies that the energy detection procedure failed.
*
* @param[in] error Reason of the failure.
*/
extern void nrf_802154_energy_detection_failed(nrf_802154_ed_error_t error);
/**
* @brief Notifies about the start of the ACK frame transmission.
*
* @note If a call to this function is performed by the same CPU running core
* of nRF 802.15.4 Radio Driver (non serialized call to @ref nrf_802154_tx_ack_started)
* the function must be very short to prevent dropping frames by the driver.
* If a call to this function is performed by a CPU through a serialization layer
* the call can be slightly delayed. The call can happen even after an ACK frame
* is fully transmitted. It is guaranteed that a call to @ref nrf_802154_tx_ack_started
* occurs before a call to @ref nrf_802154_received_timestamp_raw related to
* the same received frame.
*
* @param[in] p_data Pointer to a buffer with PHR and PSDU of the ACK frame.
*/
extern void nrf_802154_tx_ack_started(const uint8_t * p_data);
/**
* @brief Notifies that a frame was received at a given time.
*
* This function works like @ref nrf_802154_received_raw and adds a timestamp to the parameter
* list.
*
* @note The received frame usually contains a timestamp. However, due to a race condition,
* the timestamp may be invalid. This erroneous situation is indicated by
* the @ref NRF_802154_NO_TIMESTAMP value of the @p time parameter.
*
* @param[in] p_data Pointer to a buffer that contains PHR and PSDU of the received frame.
* The first byte in the buffer is the length of the frame (PHR). The following
* bytes contain the frame itself (PSDU). The length byte (PHR) includes FCS.
* FCS is already verified by the hardware and may be modified by the hardware.
* @param[in] power RSSI of the received frame.
* @param[in] lqi LQI of the received frame.
* @param[in] time Timestamp taken when the last symbol of the frame was received, in
* microseconds (us), or @ref NRF_802154_NO_TIMESTAMP if the timestamp
* is invalid.
*/
extern void nrf_802154_received_timestamp_raw(uint8_t * p_data,
int8_t power,
uint8_t lqi,
uint64_t time);
/**
* @brief Notifies that the reception of a frame failed.
*
* @param[in] error Error code that indicates the reason of the failure.
* @param[in] id Identifier of reception window the error occurred in.
* If the error is related to a delayed reception window requested through
* @ref nrf_802154_receive_at, the value of @p id equals the identifier
* of the scheduled reception window. Otherwise, the value of @p id equals
* @ref NRF_802154_RESERVED_IMM_RX_WINDOW_ID.
*/
extern void nrf_802154_receive_failed(nrf_802154_rx_error_t error, uint32_t id);
/**
* @brief Notifies that a frame was transmitted.
*
* @note If ACK was requested for the transmitted frame, this function is called after a proper ACK
* is received. If ACK was not requested, this function is called just after transmission has
* ended.
* @note The buffer pointed to by @ref nrf_802154_transmit_done_metadata_t.data.transmitted.p_ack
* is not modified by the radio driver (and cannot be used to receive a frame) until
* @ref nrf_802154_buffer_free_raw is called.
* @note The buffer pointed to by @ref nrf_802154_transmit_done_metadata_t.data.transmitted.p_ack
* may be modified by the function handler (and other modules) until
* @ref nrf_802154_buffer_free_raw is called.
* @note @ref nrf_802154_transmit_done_metadata_t.data.transmitted.time will have value of
* @ref NRF_802154_NO_TIMESTAMP as timestamping is not supported for nRF53 family.
*
* @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the transmitted frame.
* @param[in] p_metadata Pointer to a metadata structure describing frame passed in @p p_frame.
*/
extern void nrf_802154_transmitted_raw(uint8_t * p_frame,
const nrf_802154_transmit_done_metadata_t * p_metadata);
/**
* @brief Notifies that a frame was not transmitted due to a busy channel.
*
* This function is called if the transmission procedure fails.
*
* @note Frame data values in @ref nrf_802154_transmit_done_metadata_t.data are invalid for
* @ref nrf_802154_transmit_failed callout.
*
* @param[in] p_frame Pointer to a buffer that contains PHR and PSDU of the frame that was not
* transmitted.
* @param[in] error Reason of the failure.
* @param[in] p_metadata Pointer to a metadata structure describing frame passed in @p p_frame.
*/
extern void nrf_802154_transmit_failed(uint8_t * p_frame,
nrf_802154_tx_error_t error,
const nrf_802154_transmit_done_metadata_t * p_metadata);
#endif /* NRF_802154_CALLOUTS_H_ */
/** @} */

150
drivers/nrf_802154/serialization/include/host/nrf_802154_config.h
View File

@ -1,150 +0,0 @@
/*
* Copyright (c) 2017 - 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.
*
*/
#ifndef NRF_802154_CONFIG_H__
#define NRF_802154_CONFIG_H__
#ifdef NRF_802154_PROJECT_CONFIG
#include NRF_802154_PROJECT_CONFIG
#endif
#ifdef __cplusplus
extern "C" {
#endif
/**
* @defgroup nrf_802154_config_csma CSMA/CA procedure configuration
* @{
*/
/**
* @def NRF_802154_CSMA_CA_ENABLED
*
* If CSMA-CA is to be enabled by the driver. Disabling CSMA-CA improves
* the driver performance.
*
*/
#if !defined(CONFIG_NRF_802154_SL_OPENSOURCE)
#ifndef NRF_802154_CSMA_CA_ENABLED
#define NRF_802154_CSMA_CA_ENABLED 1
#endif
#endif
/**
*@}
**/
/**
* @defgroup nrf_802154_config_dtrx Delayed operations configuration
* @{
*/
/**
* @def NRF_802154_DELAYED_TRX_ENABLED
*
* If the delayed transmission and the receive window features are available.
*
*/
#if !defined(CONFIG_NRF_802154_SL_OPENSOURCE)
#ifndef NRF_802154_DELAYED_TRX_ENABLED
#define NRF_802154_DELAYED_TRX_ENABLED 1
#endif
#endif
/**
* @}
* @defgroup nrf_802154_config_ifs Interframe spacing feature configuration
* @{
*/
/**
* @def NRF_802154_IFS_ENABLED
*
* Indicates whether the Short/Long Interframe spacing feature is to be enabled in the driver.
*
*/
#if !defined(CONFIG_NRF_802154_SL_OPENSOURCE)
#ifndef NRF_802154_IFS_ENABLED
#define NRF_802154_IFS_ENABLED 1
#endif
#endif
/**
* @}
* @defgroup nrf_802154_config_security Security configuration
* @{
*/
/**
* @def NRF_802154_SECURITY_KEY_STORAGE_SIZE
*
* Configures the number of keys which are available in the Key Storage.
* This configuration is implementation-independent.
*/
#ifndef NRF_802154_SECURITY_KEY_STORAGE_SIZE
#define NRF_802154_SECURITY_KEY_STORAGE_SIZE 3
#endif
/**
*@}
**/
/**
* @def NRF_802154_CARRIER_FUNCTIONS_ENABLED
*
* Enables functions used for test purposes: nrf_802154_continuous_carrier and
* nrf_802154_modulated_carrier
*/
#ifndef NRF_802154_CARRIER_FUNCTIONS_ENABLED
#define NRF_802154_CARRIER_FUNCTIONS_ENABLED 1
#endif
/**
* @def NRF_802154_TEST_MODES_ENABLED
*
* Enables test modes. Test modes are normally disabled in end products.
* When @ref NRF_802154_TEST_MODES_ENABLED is set to 1, nRF 802.15.4 Radio Driver
* provides additional API to enable certain test modes. Setting
* @ref NRF_802154_TEST_MODES_ENABLED to 1 without using test mode API does not
* change any behavior of the Radio Driver.
*/
#ifndef NRF_802154_TEST_MODES_ENABLED
#define NRF_802154_TEST_MODES_ENABLED 0
#endif
#ifdef __cplusplus
}
#endif
#endif // NRF_802154_CONFIG_H__

228
drivers/nrf_802154/serialization/include/host/nrf_802154_const.h
View File

@ -1,228 +0,0 @@
/*
* Copyright (c) 2020 - 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 definitions of constant values used by the nRF 802.15.4 driver.
*
*/
#ifndef NRF_802154_CONST_H_
#define NRF_802154_CONST_H_
#define RAW_LENGTH_OFFSET 0 ///< Byte containing the frame length in a raw frame.
#define RAW_PAYLOAD_OFFSET 1 ///< Offset of the frame payload in a raw frame
#define ACK_HEADER_WITH_PENDING 0x12 ///< The first byte of an ACK frame containing a pending bit.
#define ACK_HEADER_WITHOUT_PENDING 0x02 ///< The first byte of an ACK frame without a pending bit.
#define ACK_REQUEST_OFFSET 1 ///< Byte containing the ACK request bit (+1 for the frame length byte).
#define ACK_REQUEST_BIT (1 << 5) ///< ACK request bit.
#define ASN_IN_NONCE_BIT 0x40 ///< Bit containing the ASN in Nonce field.
#define DEST_ADDR_TYPE_OFFSET 2 ///< Byte containing the destination address type (+1 for the frame length byte).
#define DEST_ADDR_TYPE_MASK 0x0c ///< Mask of bits containing the destination address type.
#define DEST_ADDR_TYPE_EXTENDED 0x0c ///< Bits containing the extended destination address type.
#define DEST_ADDR_TYPE_NONE 0x00 ///< Bits containing a not-present destination address type.
#define DEST_ADDR_TYPE_SHORT 0x08 ///< Bits containing the short destination address type.
#define DEST_ADDR_OFFSET 6 ///< Offset of the destination address in the Data frame (+1 for the frame length byte).
#define DSN_OFFSET 3 ///< Byte containing the DSN value (+1 for the frame length byte).
#define DSN_SUPPRESS_OFFSET 2 ///< Byte containing the DSN suppression field.
#define DSN_SUPPRESS_BIT 0x01 ///< Bits containing the DSN suppression field.
#define FRAME_COUNTER_SUPPRESS_BIT 0x20 ///< Bit containing the Frame Counter Suppression field.
#define FRAME_PENDING_OFFSET 1 ///< Byte containing a pending bit (+1 for the frame length byte).
#define FRAME_PENDING_BIT (1 << 4) ///< Pending bit.
#define FRAME_TYPE_OFFSET 1 ///< Byte containing the frame type bits (+1 for the frame length byte).
#define FRAME_TYPE_MASK 0x07 ///< Mask of bits containing the frame type.
#define FRAME_TYPE_ACK 0x02 ///< Bits containing the ACK frame type.
#define FRAME_TYPE_BEACON 0x00 ///< Bits containing the Beacon frame type.
#define FRAME_TYPE_COMMAND 0x03 ///< Bits containing the Command frame type.
#define FRAME_TYPE_DATA 0x01 ///< Bits containing the Data frame type.
#define FRAME_TYPE_EXTENDED 0x07 ///< Bits containing the Extended frame type.
#define FRAME_TYPE_FRAGMENT 0x06 ///< Bits containing the Fragment or the Frak frame type.
#define FRAME_TYPE_MULTIPURPOSE 0x05 ///< Bits containing the Multipurpose frame type.
#define FRAME_VERSION_OFFSET 2 ///< Byte containing the frame version bits (+1 for the frame length byte).
#define FRAME_VERSION_MASK 0x30 ///< Mask of bits containing the frame version.
#define FRAME_VERSION_0 0x00 ///< Bits containing the frame version 0b00.
#define FRAME_VERSION_1 0x10 ///< Bits containing the frame version 0b01.
#define FRAME_VERSION_2 0x20 ///< Bits containing the frame version 0b10.
#define FRAME_VERSION_3 0x30 ///< Bits containing the frame version 0b11.
#define IE_HEADER_LENGTH_MASK 0x3f ///< Mask of bits containing the length of an IE header content.
#define IE_PRESENT_OFFSET 2 ///< Byte containing the IE Present bit.
#define IE_PRESENT_BIT 0x02 ///< Bits containing the IE Present field.
#define KEY_ID_MODE_0 0 ///< Value of the 0x00 Key Identifier Mode.
#define KEY_ID_MODE_1 1 ///< Value of the 0x01 Key Identifier Mode.
#define KEY_ID_MODE_2 2 ///< Value of the 0x10 Key Identifier Mode.
#define KEY_ID_MODE_3 3 ///< Value of the 0x11 Key Identifier Mode.
#define KEY_ID_MODE_MASK 0x18 ///< Mask of bits containing Key Identifier Mode in the Security Control field.
#define KEY_ID_MODE_BIT_OFFSET 3 ///< Number of bits the Key Identifier Mode is offset in the Security Control field.
#define KEY_ID_MODE_0_MASK 0 ///< Bits containing the 0x00 Key Identifier Mode.
#define KEY_ID_MODE_1_MASK 0x08 ///< Bits containing the 0x01 Key Identifier Mode.
#define KEY_ID_MODE_2_MASK 0x10 ///< Bits containing the 0x10 Key Identifier Mode.
#define KEY_ID_MODE_3_MASK 0x18 ///< Bits containing the 0x11 Key Identifier Mode.
#define KEY_SRC_KEY_ID_MODE_0_SIZE 0 ///< Size of the Key Source field when Key Identifier Mode equals 0.
#define KEY_SRC_KEY_ID_MODE_1_SIZE 0 ///< Size of the Key Source field when Key Identifier Mode equals 1.
#define KEY_SRC_KEY_ID_MODE_2_SIZE 4 ///< Size of the Key Source field when Key Identifier Mode equals 2.
#define KEY_SRC_KEY_ID_MODE_3_SIZE 8 ///< Size of the Key Source field when Key Identifier Mode equals 3.
#define KEY_IDX_SIZE 1 ///< Size of the Key Index field
#define MAC_CMD_COMMAND_ID_SIZE 1 ///< Size of the MAC Command ID field.
#define MAC_CMD_ASSOC_REQ 0x01 ///< Command frame identifier for MAC Association request.
#define MAC_CMD_ASSOC_RESP 0x02 ///< Command frame identifier for MAC Association response.
#define MAC_CMD_DISASSOC_NOTIFY 0x03 ///< Command frame identifier for MAC Disaccociation notification.
#define MAC_CMD_DATA_REQ 0x04 ///< Command frame identifier for MAC Data Requests.
#define MAC_CMD_PANID_CONFLICT 0x05 ///< Command frame identifier for MAC PAN ID conflict notification.
#define MAC_CMD_ORPHAN_NOTIFY 0x06 ///< Command frame identifier for MAC Orphan notification.
#define MAC_CMD_BEACON_REQ 0x07 ///< Command frame identifier for MAC Beacon.
#define MAC_CMD_COORD_REALIGN 0x08 ///< Command frame identifier for MAC Coordinator realignment.
#define MAC_CMD_GTS_REQUEST 0x09 ///< Command frame identifier for MAC GTS request.
#define PAN_ID_COMPR_OFFSET 1 ///< Byte containing the PAN ID compression bit (+1 for the frame length byte).
#define PAN_ID_COMPR_MASK 0x40 ///< PAN ID compression bit.
#define PAN_ID_OFFSET 4 ///< Offset of PAN ID in the Data frame (+1 for the frame length byte).
#define PHR_OFFSET 0 ///< Offset of the PHY header in a frame.
#define PHR_LENGTH_MASK 0x7f ///< Mask of the PHR length field
#define PSDU_OFFSET 1 ///< Offset of the PHY payload.
#define SECURITY_ENABLED_OFFSET 1 ///< Byte containing the Security Enabled bit.
#define SECURITY_ENABLED_BIT 0x08 ///< Bits containing the Security Enabled field.
#define SECURITY_LEVEL_MASK 0x07 ///< Mask of bits containing the Security level field.
#define SECURITY_LEVEL_NONE 0x00 ///< Bits indicating a frame with no security attributes (0b000).
#define SECURITY_LEVEL_MIC_32 0x01 ///< Bits containing the 32-bit Message Integrity Code (0b001).
#define SECURITY_LEVEL_MIC_64 0x02 ///< Bits containing the 64-bit Message Integrity Code (0b010).
#define SECURITY_LEVEL_MIC_128 0x03 ///< Bits containing the 128-bit Message Integrity Code (0b011).
#define SECURITY_LEVEL_ENC_MIC_32 0x05 ///< Bits containing the 32-bit Encrypted Message Integrity Code (0b101).
#define SECURITY_LEVEL_ENC_MIC_64 0x06 ///< Bits containing the 64-bit Encrypted Message Integrity Code (0b110).
#define SECURITY_LEVEL_ENC_MIC_128 0x07 ///< Bits containing the 128-bit Encrypted Message Integrity Code (0b111).
#define SECURITY_LEVEL_MIC_LEVEL_MASK 0x03 ///< Mask of bits encoding the Message Integrity Code length.
#define SRC_ADDR_TYPE_EXTENDED 0xc0 ///< Bits containing the extended source address type.
#define SRC_ADDR_TYPE_NONE 0x00 ///< Bits containing a not-present source address type.
#define SRC_ADDR_TYPE_MASK 0xc0 ///< Mask of bits containing the source address type.
#define SRC_ADDR_TYPE_OFFSET 2 ///< Byte containing the source address type (+1 for the frame length byte).
#define SRC_ADDR_TYPE_SHORT 0x80 ///< Bits containing the short source address type.
#define SRC_ADDR_OFFSET_SHORT_DST 8 ///< Offset of the source address in the Data frame if the destination address is short.
#define SRC_ADDR_OFFSET_EXTENDED_DST 14 ///< Offset of the source address in the Data frame if the destination address is extended.
#define DSN_SIZE 1 ///< Size of the Sequence Number field.
#define FCF_SIZE 2 ///< Size of the FCF field.
#define FCS_SIZE 2 ///< Size of the FCS field.
#define FRAME_COUNTER_SIZE 4 ///< Size of the Frame Counter field.
#define IE_HEADER_SIZE 2 ///< Size of the obligatory IE Header field elements.
#define IMM_ACK_LENGTH 5 ///< Length of the ACK frame.
#define KEY_ID_MODE_1_SIZE 1 ///< Size of the 0x01 Key Identifier Mode field.
#define KEY_ID_MODE_2_SIZE 5 ///< Size of the 0x10 Key Identifier Mode field.
#define KEY_ID_MODE_3_SIZE 9 ///< Size of the 0x11 Key Identifier Mode field.
#define MAX_PACKET_SIZE 127 ///< Maximum size of the radio packet.
#define MIC_32_SIZE 4 ///< Size of MIC with the MIC-32 and ENC-MIC-32 security attributes.
#define MIC_64_SIZE 8 ///< Size of MIC with the MIC-64 and ENC-MIC-64 security attributes.
#define MIC_128_SIZE 16 ///< Size of MIC with the MIC-128 and ENC-MIC-128 security attributes.
#define PAN_ID_SIZE 2 ///< Size of the PAN ID.
#define PHR_SIZE 1 ///< Size of the PHR field.
#define SECURITY_CONTROL_SIZE 1 ///< Size of the Security Control field.
#define AES_CCM_KEY_SIZE 16 ///< Size of AES CCM Key.
#define EXTENDED_ADDRESS_SIZE 8 ///< Size of the Extended Mac Address.
#define SHORT_ADDRESS_SIZE 2 ///< Size of the Short Mac Address.
#define TURNAROUND_TIME 192UL ///< RX-to-TX or TX-to-RX turnaround time (aTurnaroundTime), in microseconds (us).
#define CCA_TIME 128UL ///< Time required to perform CCA detection (aCcaTime), in microseconds (us).
#define UNIT_BACKOFF_PERIOD (TURNAROUND_TIME + CCA_TIME) ///< Number of symbols in the basic time period used by CSMA-CA algorithm (aUnitBackoffPeriod), in (us).
#define PHY_US_PER_SYMBOL 16 ///< Duration of a single symbol in microseconds (us).
#define PHY_SYMBOLS_PER_OCTET 2 ///< Number of symbols in a single byte (octet).
#define PHY_SHR_SYMBOLS 10 ///< Number of symbols in the Synchronization Header (SHR).
#define PHY_MIN_RECEIVER_SENSITIVITY -85 ///< Lowest receiver sensitivity level in dBm according to 802.15.4-2020 specification, chapter 12.3.4
#define ED_RESULT_MAX 0xff ///< Maximal ED result.
#define BROADCAST_ADDRESS ((uint8_t[SHORT_ADDRESS_SIZE]) {0xff, 0xff}) ///< Broadcast short address.
#define MIN_SIFS_PERIOD_US 192 ///< Minimum Short IFS period default value in us.
#define MIN_LIFS_PERIOD_US 640 ///< Minimum Long IFS period default value in us.
#define MAX_SIFS_FRAME_SIZE 18 ///< Maximum frame length which can be followed by the Short Interframe Space.
#define NRF_802154_RESERVED_CSMACA_ID (UINT32_MAX - 2) ///< Delayed timeslot identifier reserved for CSMA/CA procedure.
#define NRF_802154_RESERVED_DTX_ID (UINT32_MAX - 3) ///< Delayed timeslot identifier reserved for delayed transmissions.
#define IE_VENDOR_ID 0x00 ///< Vendor-specific IE identifier
#define IE_VENDOR_SIZE_MIN 3 ///< Vendor-specific IE minimum length
#define IE_VENDOR_OUI_OFFSET 0 ///< Vendor-specific IE OUI offset
#define IE_VENDOR_THREAD_SUBTYPE_OFFSET 3 ///< Thread Vendor-specific IE subtype offset
#define IE_VENDOR_THREAD_DATA_OFFSET 4 ///< Thread Vendor-specific IE DATA offset
#define IE_VENDOR_THREAD_OUI 0xeab89b ///< Thread Vendor-specific IE OUI
#define IE_VENDOR_THREAD_SIZE_MIN 4 ///< Thread Vendor-specific IE minimum length
#define IE_VENDOR_THREAD_ACK_PROBING_ID 0x00 ///< Thread Vendor-specific ACK Probing IE subtype ID
#define IE_VENDOR_THREAD_ACK_SIZE_MIN 5 ///< Thread Vendor-specific ACK Probing IE minimum size
#define IE_VENDOR_THREAD_ACK_SIZE_MAX 6 ///< Thread Vendor-specific ACK Probing IE maximum size
#define IE_VENDOR_THREAD_RSSI_TOKEN 0x01 ///< Thread Vendor-specific ACK Probing IE RSSI value placeholder
#define IE_VENDOR_THREAD_MARGIN_TOKEN 0x02 ///< Thread Vendor-specific ACK Probing IE Link margin value placeholder
#define IE_VENDOR_THREAD_LQI_TOKEN 0x03 ///< Thread Vendor-specific ACK Probing IE LQI value placeholder
#define IE_VENDOR_THREAD_RSSI_FLOOR -130 ///< Thread Vendor-specific ACK Probing RSSI floor value used for scaling
#define IE_VENDOR_THREAD_MARGIN_FLOOR 0 ///< Thread Vendor-specific ACK Probing margin floor value used for scaling
#define IE_VENDOR_THREAD_RSSI_CEIL 0 ///< Thread Vendor-specific ACK Probing RSSI ceil value used for scaling
#define IE_VENDOR_THREAD_MARGIN_CEIL 130 ///< Thread Vendor-specific ACK Probing margin ceil value used for scaling
#define IE_CSL_SYMBOLS_PER_UNIT 10 ///< Number of symbols per phase/period unit
#define IE_CSL_PERIOD_MAX 0xffff ///< Maximum CSL IE phase/period value
#define IE_CSL_SIZE_MIN 4 ///< Minimal size of the CSL IE
#define IE_CSL_ID 0x1a ///< CSL IE identifier
#define IE_HT1 0x7e ///< Information Element Header Termination type 1
#define IE_HT2 0x7f ///< Information Element Header Termination type 2
#define IE_LENGTH_MASK 0x7f ///< Information element length mask
#define IE_LENGTH_OFFSET 0x00 ///< Information element length offset
#define IE_ID_OFFSET_0 0x00 ///< Offset of the octet containing the first part of the IE identifier.
#define IE_ID_OFFSET_1 0x01 ///< Offset of the octed containing the second part of the IE identifier.
#define IE_DATA_OFFSET 0x02 ///< Information element data offset
#define IE_HEADER_ELEMENT_ID_OFFSET 0x07 ///< Bit offset of Element ID field in a Header IE header.
#endif // NRF_802154_CONST_H_

371
drivers/nrf_802154/serialization/include/host/nrf_802154_types.h
View File

@ -1,371 +0,0 @@
/*
* Copyright (c) 2020 - 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.
*
*/
#ifndef NRF_802154_TYPES_H__
#define NRF_802154_TYPES_H__
#include <stdbool.h>
#include <stdint.h>
/**
* @defgroup nrf_802154_types Type definitions used in the 802.15.4 driver
* @{
* @ingroup nrf_802154
* @brief Definitions of types used in the 802.15.4 driver.
*/
/**
* @brief Errors reported during the frame transmission.
*/
typedef uint8_t nrf_802154_tx_error_t;
#define NRF_802154_TX_ERROR_NONE 0x00 // !< There is no transmit error.
#define NRF_802154_TX_ERROR_BUSY_CHANNEL 0x01 // !< CCA reported busy channel before the transmission.
#define NRF_802154_TX_ERROR_INVALID_ACK 0x02 // !< Received ACK frame is other than expected.
#define NRF_802154_TX_ERROR_NO_MEM 0x03 // !< No receive buffer is available to receive an ACK.
#define NRF_802154_TX_ERROR_TIMESLOT_ENDED 0x04 // !< Radio timeslot ended during the transmission procedure.
#define NRF_802154_TX_ERROR_NO_ACK 0x05 // !< ACK frame was not received during the timeout period.
#define NRF_802154_TX_ERROR_ABORTED 0x06 // !< Procedure was aborted by another operation.
#define NRF_802154_TX_ERROR_TIMESLOT_DENIED 0x07 // !< Transmission did not start due to a denied timeslot request.
#define NRF_802154_TX_ERROR_TIMEOUT 0x08 // !< Timeout specified for a transmission has been reached.
/**
* @brief Possible errors during the frame reception.
*/
typedef uint8_t nrf_802154_rx_error_t;
#define NRF_802154_RX_ERROR_NONE 0x00 // !< There is no receive error.
#define NRF_802154_RX_ERROR_INVALID_FRAME 0x01 // !< Received a malformed frame.
#define NRF_802154_RX_ERROR_INVALID_FCS 0x02 // !< Received a frame with an invalid checksum.
#define NRF_802154_RX_ERROR_INVALID_DEST_ADDR 0x03 // !< Received a frame with a mismatched destination address.
#define NRF_802154_RX_ERROR_RUNTIME 0x04 // !< Runtime error occurred (for example, CPU was held for too long).
#define NRF_802154_RX_ERROR_TIMESLOT_ENDED 0x05 // !< Radio timeslot ended during the frame reception.
#define NRF_802154_RX_ERROR_ABORTED 0x06 // !< Procedure was aborted by another operation.
#define NRF_802154_RX_ERROR_DELAYED_TIMESLOT_DENIED 0x07 // !< Delayed reception request was rejected due to a denied timeslot request.
#define NRF_802154_RX_ERROR_DELAYED_TIMEOUT 0x08 // !< Delayed reception timeslot ended.
#define NRF_802154_RX_ERROR_INVALID_LENGTH 0x09 // !< Received a frame with invalid length.
#define NRF_802154_RX_ERROR_DELAYED_ABORTED 0x0A // !< Delayed operation in the ongoing state was aborted by other request.
/**
*/
typedef uint8_t nrf_802154_ed_error_t;
#define NRF_802154_ED_ERROR_ABORTED 0x01 // !< Procedure was aborted by another operation.
/**
* @brief Possible errors during sleep procedure call.
*/
typedef uint8_t nrf_802154_sleep_error_t;
#define NRF_802154_SLEEP_ERROR_NONE 0x00 // !< There is no error.
#define NRF_802154_SLEEP_ERROR_BUSY 0x01 // !< The driver cannot enter the sleep state due to the ongoing operation.
/**
* @brief Possible errors during the CCA procedure.
*/
typedef uint8_t nrf_802154_cca_error_t;
#define NRF_802154_CCA_ERROR_ABORTED 0x01 // !< Procedure was aborted by another operation.
/** @brief RADIO Clear Channel Assessment modes. */
#define NRF_RADIO_CCA_MODE_ED 0x00
#define NRF_RADIO_CCA_MODE_CARRIER 0x01
#define NRF_RADIO_CCA_MODE_CARRIER_AND_ED 0x02
#define NRF_RADIO_CCA_MODE_CARRIER_OR_ED 0x03
/**
* @brief Structure for configuring CCA.
*/
typedef struct
{
uint8_t mode; // !< CCA mode.
uint8_t ed_threshold; // !< Busy threshold of the CCA energy. Not used in @ref NRF_RADIO_CCA_MODE_CARRIER.
uint8_t corr_threshold; // !< Busy threshold of the CCA correlator. Not used in @ref NRF_RADIO_CCA_MODE_ED.
uint8_t corr_limit; // !< Limit of occurrences above the busy threshold of the CCA correlator. Not used in @ref NRF_RADIO_CCA_MODE_ED.
} nrf_802154_cca_cfg_t;
/**
* @brief Types of data that can be set in an ACK message.
*/
typedef uint8_t nrf_802154_ack_data_t;
#define NRF_802154_ACK_DATA_PENDING_BIT 0x00
#define NRF_802154_ACK_DATA_IE 0x01
/**
* @brief Type holding the CSMA/CA backoff control test mode
*
* Possible values:
* - @ref NRF_802154_TEST_MODE_CSMACA_BACKOFF_RANDOM
* - @ref NRF_802154_TEST_MODE_CSMACA_BACKOFF_ALWAYS_MAX
* - @ref NRF_802154_TEST_MODE_CSMACA_BACKOFF_ALWAYS_MIN
*/
typedef uint8_t nrf_802154_test_mode_csmaca_backoff_t;
#define NRF_802154_TEST_MODE_CSMACA_BACKOFF_RANDOM 0x00 // !< The CSMA/CA uses random number of backoff periods (IEEE Std. 802.15.4 compliant)
#define NRF_802154_TEST_MODE_CSMACA_BACKOFF_ALWAYS_MAX 0x01 // !< The CSMA/CA uses always maximum backoff periods (Test mode, non-compliant to IEEE Std. 802.15.4)
#define NRF_802154_TEST_MODE_CSMACA_BACKOFF_ALWAYS_MIN 0x02 // !< The CSMA/CA uses always minimum backoff periods (Test mode, non-compliant to IEEE Std. 802.15.4)
/**
* @brief Methods of source address matching.
*
* You can use one of the following methods that can be set during the initialization phase
* by calling @ref nrf_802154_src_addr_matching_method_set:
* - For Thread: @ref NRF_802154_SRC_ADDR_MATCH_THREAD -- The pending bit is set only for the addresses found in the list.
* - For Zigbee: @ref NRF_802154_SRC_ADDR_MATCH_ZIGBEE -- The pending bit is cleared only for the short addresses found in the list.\n
* This method does not set pending bit in non-command and non-data-request frames.
* - For standard-compliant implementation: @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 -- The pending bit is always set to 1.\n
* This requires an empty data frame with AR set to 0 to be transmitted immediately afterwards.
*/
typedef uint8_t nrf_802154_src_addr_match_t;
#define NRF_802154_SRC_ADDR_MATCH_THREAD 0x00 // !< Implementation for the Thread protocol.
#define NRF_802154_SRC_ADDR_MATCH_ZIGBEE 0x01 // !< Implementation for the Zigbee protocol.
#define NRF_802154_SRC_ADDR_MATCH_ALWAYS_1 0x02 // !< Standard compliant implementation.
/**
* @brief Mode of handling Interframe spacing.
*
* Possible values:
* - @ref NRF_802154_IFS_MODE_DISABLED,
* - @ref NRF_802154_IFS_MODE_MATCHING_ADDRESSES,
* - @ref NRF_802154_IFS_MODE_ALWAYS
*/
typedef uint8_t nrf_802154_ifs_mode_t;
#define NRF_802154_IFS_MODE_DISABLED 0x00 // !< Interframe spacing is never inserted.
#define NRF_802154_IFS_MODE_MATCHING_ADDRESSES 0x01 // !< Interframe spacing is inserted only on matching addresses.
#define NRF_802154_IFS_MODE_ALWAYS 0x02 // !< Interframe spacing is always inserted.
/**
* @brief Capabilites of nrf 802.15.4 radio driver
*
* Possible values:
* - @ref NRF_802154_CAPABILITY_CSMA,
* - @ref NRF_802154_CAPABILITY_DELAYED_TX,
* - @ref NRF_802154_CAPABILITY_DELAYED_RX,
* - @ref NRF_802154_CAPABILITY_ACK_TIMEOUT,
* - @ref NRF_802154_CAPABILITY_ANT_DIVERSITY,
* - @ref NRF_802154_CAPABILITY_IFS,
* - @ref NRF_802154_CAPABILITY_TIMESTAMP
* - @ref NRF_802154_CAPABILITY_SECURITY
*
*/
typedef uint32_t nrf_802154_capabilities_t;
#define NRF_802154_CAPABILITY_CSMA (1UL << 0UL) // !< CSMA-CA supported
#define NRF_802154_CAPABILITY_DELAYED_TX (1UL << 1UL) // !< TX at specified time supported
#define NRF_802154_CAPABILITY_DELAYED_RX (1UL << 2UL) // !< RX at specified time supported
#define NRF_802154_CAPABILITY_ACK_TIMEOUT (1UL << 3UL) // !< ACK timeout supported
#define NRF_802154_CAPABILITY_ANT_DIVERSITY (1UL << 4UL) // !< Antenna diversity supported
#define NRF_802154_CAPABILITY_IFS (1UL << 5UL) // !< Inter-frame spacing supported
#define NRF_802154_CAPABILITY_TIMESTAMP (1UL << 6UL) // !< Frame timestamping supported
#define NRF_802154_CAPABILITY_SECURITY (1UL << 7UL) // !< Frame security supported
/**
* @brief Type of structure holding time stamps of certain events.
*/
typedef struct
{
/**@brief Time stamp of last CSMA/CA procedure started. */
uint64_t last_csmaca_start_timestamp;
/**@brief Time stamp of last CCA start attempt. */
uint64_t last_cca_start_timestamp;
/**@brief Time stamp of last CCA attempt finished with CCA IDLE (channel was free to transmit). */
uint64_t last_cca_idle_timestamp;
/**@brief Time stamp when last bit of transmitted frame was sent on the air. */
uint64_t last_tx_end_timestamp;
/**@brief Time stamp when last bit of acknowledge frame was received */
uint64_t last_ack_end_timestamp;
/**@brief Time stamp when last bit of received frame was received. */
uint64_t last_rx_end_timestamp;
} nrf_802154_stat_timestamps_t;
/**
* @brief Structure with frame properties associated with the transmission operation.
*
* @note When using to request transmission, parameters contained here influence whether or not
* the security related data transformation will be performed. In particular, the driver may:
* - update frame counter field if the dynamic parts of the frame are not yet updated
* - secure a non-secured frame on-the-fly
* If performed, the above operations are configured by the IEEE 802.15.4 Auxiliary Security
* Header present in the transmitted frame.
*
* @note It is recommended to use values defined in @ref NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT
* to perform the first transmission attempt. Using other values may result in transmitting
* malformed or incorrect frames and creating security breaches.
*
* @note The combination with is_secured = true and dynamic_data_is_set = false is not allowed.
* An attempt to transmit a frame with such parameters will fail unconditionally.
*/
typedef struct
{
bool is_secured; // !< If the frame to be transmitted is already secured (in the sense of IEEE 802.15.4 security operations).
bool dynamic_data_is_set; // !< If dynamic data of the frame frame to be transmitted is set.
} nrf_802154_transmitted_frame_props_t;
/**
* @brief Structure passed in transmit metadata with information needed to set transmission power.
*
* If the @p use_metadata_value field is set to true the power in dBm used to transmit the frame is set to the value of the
* field @p power.
* Otherwise the value from PIB set by @ref nrf_802154_tx_power_set is used
*/
typedef struct
{
bool use_metadata_value; // !< Set to true if the value in @p power should be used as the TX power in dBm
int8_t power; // !< Transmission power in dBm
} nrf_802154_tx_power_metadata_t;
/**
* @brief Default initializer for nrf_802154_transmitted_frame_props_t.
*/
#define NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT \
(nrf_802154_transmitted_frame_props_t){ \
.is_secured = false, \
.dynamic_data_is_set = false \
}
/**
* @brief Structure with transmit request metadata for simple transmission request.
*/
typedef struct
{
nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the frame to be transmitted.
bool cca; // !< If the driver is to perform a CCA procedure before transmission.
nrf_802154_tx_power_metadata_t tx_power; // !< Information about the TX power to be used
} nrf_802154_transmit_metadata_t;
/**
* @brief Structure with transmit request metadata for scheduling transmission at a specific time.
*/
typedef struct
{
nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the frame to be transmitted.
bool cca; // !< If the driver is to perform a CCA procedure before transmission.
uint8_t channel; // !< Radio channel on which the frame is to be transmitted.
nrf_802154_tx_power_metadata_t tx_power; // !< Information about the TX power to be used
} nrf_802154_transmit_at_metadata_t;
/**
* @brief Structure with transmit request metadata for transmission preceded by CSMA-CA procedure.
*/
typedef struct
{
nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the frame to be transmitted.
nrf_802154_tx_power_metadata_t tx_power; // !< Information about the TX power to be used
} nrf_802154_transmit_csma_ca_metadata_t;
/**
* @brief Structure that holds transmission result metadata.
*/
typedef struct
{
nrf_802154_transmitted_frame_props_t frame_props; // !< Properties of the returned frame.
union
{
struct
{
uint8_t * p_ack; // !< If NRF_802154_USE_RAW_API is disabled, p_ack is a pointer to a buffer that contains only the received ACK payload (PSDU excluding FCS).
// If NRF_802154_USE_RAW_API is enabled, p_ack is a pointer to a buffer that contains PHR and PSDU of the received ACK. The first byte
// in the buffer is the length of the frame (PHR). The following bytes contain the ACK frame itself (PSDU). The length byte
// (PHR) includes FCS. FCS is already verified by the hardware and may be modified by the hardware.
// If ACK was not requested or requested but not received, @ref p_ack is set to NULL.
uint8_t length; // !< Length of the received ACK payload or 0 if @ref p_ack is NULL.
int8_t power; // !< RSSI of the received frame or 0 if @ref p_ack is NULL.
uint8_t lqi; // !< LQI of the received frame or 0 if @ref p_ack is NULL.
uint64_t time; // !< Timestamp taken when the last symbol of ACK is received. If @ref p_ack is NULL, this field is set to 0, but is considered invalid.
} transmitted; // !< Result values for a successful frame transmission.
} data; // !< Result values that are valid only for successful operations.
} nrf_802154_transmit_done_metadata_t;
/**
* @brief Possible errors during key handling.
*/
typedef uint8_t nrf_802154_security_error_t;
#define NRF_802154_SECURITY_ERROR_NONE 0x00 // !< There is no error.
#define NRF_802154_SECURITY_ERROR_STORAGE_FULL 0x01 // !< The key storage is full - removal of stored keys is needed.
#define NRF_802154_SECURITY_ERROR_KEY_NOT_FOUND 0x02 // !< The provided key was not found inside the storage.
#define NRF_802154_SECURITY_ERROR_ALREADY_PRESENT 0x03 // !< The storage already has the key of the same ID.
#define NRF_802154_SECURITY_ERROR_TYPE_NOT_SUPPORTED 0x04 // !< The provided key type is not supported.
#define NRF_802154_SECURITY_ERROR_MODE_NOT_SUPPORTED 0x05 // !< The provided key id mode is not supported.
#define NRF_802154_SECURITY_ERROR_FRAME_COUNTER_OVERFLOW 0x06 // !< The associated frame counter overflowed.
/**
* @brief Types of keys which can be used with the nRF 802.15.4 Radio Driver.
*
* Possible values:
* - @ref NRF_802154_KEY_CLEARTEXT,
*
*/
typedef uint32_t nrf_802154_key_type_t;
#define NRF_802154_KEY_CLEARTEXT 0x00 // !< Key stored in clear text.
/**
* @brief Type holding the value of Key Id Mode of the key stored in nRF 802.15.4 Radio Driver.
*/
typedef uint8_t nrf_802154_key_id_mode_t;
/**
* @brief Type holding the value of Key Id for the keys stored in nRF 802.15.4 Radio Driver.
*/
typedef struct
{
nrf_802154_key_id_mode_t mode; // !< Key Id Mode (0..3)
uint8_t * p_key_id; // !< Pointer to the Key Id field
} nrf_802154_key_id_t;
/**
* @brief Type of structure holding a 802.15.4 MAC Security Key.
*/
typedef struct
{
union
{
uint8_t * p_cleartext_key; // !< Pointer to the cleartext representation of the key.
} value; // !< Union holding different representations of the key.
nrf_802154_key_id_t id; // !< Key Id of the key.
nrf_802154_key_type_t type; // !< @ref nrf_802154_key_type_t type of the key used.
uint32_t frame_counter; // !< Frame counter to use in case @ref use_global_frame_counter is set to false.
bool use_global_frame_counter; // !< Whether to use the global frame counter instead of the one defined in this structure.
} nrf_802154_key_t;
/**
*@}
**/
#endif // NRF_802154_TYPES_H__

32
drivers/nrf_802154/serialization/src/include/nrf_802154_nrfx_addons.h
View File

@ -36,6 +36,7 @@
#define NRF_802154_NRFX_ADDONS_H__
#include "nrfx.h"
#include "nrf_802154_config.h"
#include "nrf_802154_const.h"
/* The usage of ED_RSSISCALE is described imprecisely in the nRF product specifications. The meaning of
@ -55,6 +56,35 @@
#define EDSAMPLE_MIN_REPORTED_VALUE (PHY_MIN_RECEIVER_SENSITIVITY - ED_RSSIOFFS + 10) ///< Minimal reported EDSAMPLE value (reported as 0)
#define EDSAMPLE_MAX_REPORTED_VALUE (ED_RESULT_MAX / ED_RSSISCALE) ///< Maximal reported EDSAMPLE value (reported as 255)
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
/** Minimum value of ED in dBm for conversion to units conforming IEEE Std. 802.15.4-2015 chapter 10.2.5. */
#define ED_DBM_MIN (PHY_MIN_RECEIVER_SENSITIVITY + 10)
/** Maximum value of ED in dBm for conversion to units conforming IEEE Std. 802.15.4-2015 chapter 10.2.5. */
#define ED_DBM_MAX (EDSAMPLE_MAX_REPORTED_VALUE + ED_RSSIOFFS)
static inline uint8_t nrf_802154_addons_energy_level_from_dbm_calculate(int8_t ed_dbm)
{
uint32_t r;
if (ed_dbm < ED_DBM_MIN)
{
return 0;
}
r = ((uint32_t)(ed_dbm - ED_DBM_MIN)) * ED_RESULT_MAX / (ED_DBM_MAX - ED_DBM_MIN);
if (r > ED_RESULT_MAX)
{
r = ED_RESULT_MAX;
}
return r;
}
#else
/**
* @brief Converts the energy level received during the energy detection procedure to a dBm value.
*
@ -69,4 +99,6 @@ static inline int8_t nrf_802154_addons_dbm_from_energy_level_calculate(uint8_t e
ED_RESULT_MAX + EDSAMPLE_MIN_REPORTED_VALUE + ED_RSSIOFFS;
}
#endif // NRF_802154_ENERGY_DETECTED_VERSION != 0
#endif // NRF_802154_NRFX_ADDONS_H__

50
drivers/nrf_802154/serialization/src/include/nrf_802154_spinel_datatypes.h
View File

@ -671,7 +671,8 @@ typedef enum
SPINEL_DATATYPE_NRF_802154_TRANSMITTED_FRAME_PROPS_S /* frame_props */ \
SPINEL_DATATYPE_BOOL_S /* cca */ \
SPINEL_DATATYPE_UINT8_S /* channel */ \
SPINEL_DATATYPE_NRF_802154_TX_POWER_METADATA_S /* tx_power */
SPINEL_DATATYPE_NRF_802154_TX_POWER_METADATA_S /* tx_power */ \
SPINEL_DATATYPE_UINT8_S /* extra_cca_attempts */
/**
* @brief Encodes an instance of @ref SPINEL_DATATYPE_NRF_802154_TRANSMIT_AT_METADATA_S data type.
@ -680,7 +681,8 @@ typedef enum
NRF_802154_TRANSMITTED_FRAME_PROPS_ENCODE((tx_at_metadata).frame_props), \
((tx_at_metadata).cca), \
((tx_at_metadata).channel), \
NRF_802154_TX_POWER_METADATA_ENCODE((tx_at_metadata).tx_power)
NRF_802154_TX_POWER_METADATA_ENCODE((tx_at_metadata).tx_power), \
((tx_at_metadata).extra_cca_attempts)
/**
* @brief Decodes an instance of @ref SPINEL_DATATYPE_NRF_802154_TRANSMIT_AT_METADATA_S data type.
@ -689,7 +691,8 @@ typedef enum
NRF_802154_TRANSMITTED_FRAME_PROPS_DECODE((tx_at_metadata).frame_props), \
(&(tx_at_metadata).cca), \
(&(tx_at_metadata).channel), \
NRF_802154_TX_POWER_METADATA_DECODE((tx_at_metadata).tx_power)
NRF_802154_TX_POWER_METADATA_DECODE((tx_at_metadata).tx_power), \
(&(tx_at_metadata).extra_cca_attempts)
/**
* @brief Spinel data type description for nrf_802154_cca_cfg_t.
@ -795,87 +798,94 @@ typedef enum
/**
* @brief Spinel data type description for nrf_802154_receive_at result.
*/
#define SPINEL_DATATYPE_NRF_802154_RECEIVE_AT_RET SPINEL_DATATYPE_BOOL_S
#define SPINEL_DATATYPE_NRF_802154_RECEIVE_AT_RET SPINEL_DATATYPE_BOOL_S
/**
* @brief Spinel data type description for nrf_802154_receive_at_cancel.
*/
#define SPINEL_DATATYPE_NRF_802154_RECEIVE_AT_CANCEL SPINEL_DATATYPE_UINT32_S
#define SPINEL_DATATYPE_NRF_802154_RECEIVE_AT_CANCEL SPINEL_DATATYPE_UINT32_S
/**
* @brief Spinel data type description for nrf_802154_receive_at_cancel result.
*/
#define SPINEL_DATATYPE_NRF_802154_RECEIVE_AT_CANCEL_RET SPINEL_DATATYPE_BOOL_S
#define SPINEL_DATATYPE_NRF_802154_RECEIVE_AT_CANCEL_RET SPINEL_DATATYPE_BOOL_S
/**
* @brief Spinel data type description for nrf_802154_pan_id_set.
*/
#define SPINEL_DATATYPE_NRF_802154_PAN_ID_SET SPINEL_DATATYPE_DATA_S
#define SPINEL_DATATYPE_NRF_802154_PAN_ID_SET SPINEL_DATATYPE_DATA_S
/**
* @brief Spinel data type description for nrf_802154_short_address_set.
*/
#define SPINEL_DATATYPE_NRF_802154_SHORT_ADDRESS_SET SPINEL_DATATYPE_DATA_S
#define SPINEL_DATATYPE_NRF_802154_SHORT_ADDRESS_SET SPINEL_DATATYPE_DATA_S
/**
* @brief Spinel data type description for nrf_802154_extended_address_set.
*/
#define SPINEL_DATATYPE_NRF_802154_EXTENDED_ADDRESS_SET SPINEL_DATATYPE_DATA_S
#define SPINEL_DATATYPE_NRF_802154_EXTENDED_ADDRESS_SET SPINEL_DATATYPE_DATA_S
/**
* @brief Spinel data type description for nrf_802154_pan_coord_set.
*/
#define SPINEL_DATATYPE_NRF_802154_PAN_COORD_SET SPINEL_DATATYPE_BOOL_S
#define SPINEL_DATATYPE_NRF_802154_PAN_COORD_SET SPINEL_DATATYPE_BOOL_S
/**
* @brief Spinel data type description for nrf_802154_pan_coord_get result.
*/
#define SPINEL_DATATYPE_NRF_802154_PAN_COORD_GET_RET SPINEL_DATATYPE_BOOL_S
#define SPINEL_DATATYPE_NRF_802154_PAN_COORD_GET_RET SPINEL_DATATYPE_BOOL_S
/**
* @brief Spinel data type description for nrf_802154_pan_coord_get.
*/
#define SPINEL_DATATYPE_NRF_802154_PAN_COORD_GET SPINEL_DATATYPE_NULL_S
#define SPINEL_DATATYPE_NRF_802154_PAN_COORD_GET SPINEL_DATATYPE_NULL_S
/**
* @brief Spinel data type description for nrf_802154_promiscuous_set.
*/
#define SPINEL_DATATYPE_NRF_802154_PROMISCUOUS_SET SPINEL_DATATYPE_BOOL_S
#define SPINEL_DATATYPE_NRF_802154_PROMISCUOUS_SET SPINEL_DATATYPE_BOOL_S
/**
* @brief Spinel data type description for nrf_802154_cca.
*/
#define SPINEL_DATATYPE_NRF_802154_CCA SPINEL_DATATYPE_NULL_S
#define SPINEL_DATATYPE_NRF_802154_CCA SPINEL_DATATYPE_NULL_S
/**
* @brief Spinel data type description for nrf_802154_cca result.
*/
#define SPINEL_DATATYPE_NRF_802154_CCA_RET SPINEL_DATATYPE_BOOL_S
#define SPINEL_DATATYPE_NRF_802154_CCA_RET SPINEL_DATATYPE_BOOL_S
/**
* @brief Spinel data type description for nrf_802154_cca_done.
*/
#define SPINEL_DATATYPE_NRF_802154_CCA_DONE SPINEL_DATATYPE_BOOL_S
#define SPINEL_DATATYPE_NRF_802154_CCA_DONE SPINEL_DATATYPE_BOOL_S
/**
* @brief Spinel data type description for nrf_802154_cca_failed.
*/
#define SPINEL_DATATYPE_NRF_802154_CCA_FAILED SPINEL_DATATYPE_UINT8_S
#define SPINEL_DATATYPE_NRF_802154_CCA_FAILED SPINEL_DATATYPE_UINT8_S
/**
* @brief Spinel data type description for nrf_802154_energy_detection.
*/
#define SPINEL_DATATYPE_NRF_802154_ENERGY_DETECTION SPINEL_DATATYPE_UINT32_S
#define SPINEL_DATATYPE_NRF_802154_ENERGY_DETECTION SPINEL_DATATYPE_UINT32_S
/**
* @brief Spinel data type description for nrf_802154_energy_detection result.
*/
#define SPINEL_DATATYPE_NRF_802154_ENERGY_DETECTION_RET SPINEL_DATATYPE_BOOL_S
#define SPINEL_DATATYPE_NRF_802154_ENERGY_DETECTION_RET SPINEL_DATATYPE_BOOL_S
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
/**
* @brief Spinel data type description for nrf_802154_energy_detected.
*/
#define SPINEL_DATATYPE_NRF_802154_ENERGY_DETECTED SPINEL_DATATYPE_UINT8_S
#define SPINEL_DATATYPE_NRF_802154_ENERGY_DETECTED SPINEL_DATATYPE_INT8_S
#else
/**
* @brief Spinel data type description for nrf_802154_energy_detected.
*/
#define SPINEL_DATATYPE_NRF_802154_ENERGY_DETECTED SPINEL_DATATYPE_UINT8_S
#endif
/**
* @brief Spinel data type description for nrf_802154_energy_detection_failed.

36
drivers/nrf_802154/serialization/src/nrf_802154_spinel_app.c
View File

@ -1525,8 +1525,9 @@ bool nrf_802154_transmit_raw_at(uint8_t * p_data
.frame_props = NRF_802154_TRANSMITTED_FRAME_PROPS_DEFAULT_INIT,
.cca = true,
// channel set to 0 will be replaced on net core by the current channel from PIB
.channel = 0,
.tx_power = {.use_metadata_value = false}
.channel = 0,
.tx_power = {.use_metadata_value = false},
.extra_cca_attempts = 0U,
};
p_metadata = &metadata_default;
@ -1809,37 +1810,6 @@ bail:
SERIALIZATION_ERROR_RAISE_IF_FAILED(error);
}
int8_t nrf_802154_dbm_from_energy_level_calculate(uint8_t energy_level)
{
return nrf_802154_addons_dbm_from_energy_level_calculate(energy_level);
}
uint64_t nrf_802154_first_symbol_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length)
{
uint32_t frame_symbols = PHY_SHR_SYMBOLS;
frame_symbols += (PHR_SIZE + psdu_length) * PHY_SYMBOLS_PER_OCTET;
return end_timestamp - (frame_symbols * PHY_US_PER_SYMBOL);
}
uint64_t nrf_802154_mhr_timestamp_get(uint64_t end_timestamp, uint8_t psdu_length)
{
return end_timestamp - (psdu_length * PHY_SYMBOLS_PER_OCTET * PHY_US_PER_SYMBOL);
}
uint64_t nrf_802154_timestamp_end_to_phr_convert(uint64_t end_timestamp, uint8_t psdu_length)
{
uint32_t frame_symbols = (PHR_SIZE + psdu_length) * PHY_SYMBOLS_PER_OCTET;
return end_timestamp - (frame_symbols * PHY_US_PER_SYMBOL);
}
uint64_t nrf_802154_timestamp_phr_to_shr_convert(uint64_t phr_timestamp)
{
return phr_timestamp - (PHY_SHR_SYMBOLS * PHY_US_PER_SYMBOL);
}
void nrf_802154_security_global_frame_counter_set(uint32_t frame_counter)
{
nrf_802154_ser_err_t res;

25
drivers/nrf_802154/serialization/src/nrf_802154_spinel_dec_app.c
View File

@ -117,6 +117,15 @@ static nrf_802154_ser_err_t spinel_decode_prop_nrf_802154_energy_detected(
const void * p_property_data,
size_t property_data_len)
{
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
nrf_802154_energy_detected_t result = {};
spinel_ssize_t siz = spinel_datatype_unpack(p_property_data,
property_data_len,
SPINEL_DATATYPE_NRF_802154_ENERGY_DETECTED,
&result.ed_dbm);
#else
uint8_t result;
spinel_ssize_t siz = spinel_datatype_unpack(p_property_data,
@ -124,12 +133,18 @@ static nrf_802154_ser_err_t spinel_decode_prop_nrf_802154_energy_detected(
SPINEL_DATATYPE_NRF_802154_ENERGY_DETECTED,
&result);
#endif
if (siz < 0)
{
return NRF_802154_SERIALIZATION_ERROR_DECODING_FAILURE;
}
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
nrf_802154_energy_detected(&result);
#else
nrf_802154_energy_detected(result);
#endif
return NRF_802154_SERIALIZATION_ERROR_OK;
}
@ -780,12 +795,22 @@ __WEAK void nrf_802154_cca_failed(nrf_802154_cca_error_t error)
// Intentionally empty
}
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
__WEAK void nrf_802154_energy_detected(const nrf_802154_energy_detected_t * p_result)
{
(void)p_result;
// Intentionally empty
}
#else
__WEAK void nrf_802154_energy_detected(uint8_t ed_level)
{
(void)ed_level;
// Intentionally empty
}
#endif // NRF_802154_ENERGY_DETECTED_VERSION != 0
__WEAK void nrf_802154_energy_detection_failed(nrf_802154_ed_error_t error)
{
(void)error;

11
drivers/nrf_802154/serialization/src/nrf_802154_spinel_net.c
View File

@ -125,7 +125,11 @@ bail:
return;
}
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
void nrf_802154_energy_detected(const nrf_802154_energy_detected_t * p_result)
#else
void nrf_802154_energy_detected(uint8_t result)
#endif
{
nrf_802154_ser_err_t res;
@ -134,10 +138,17 @@ void nrf_802154_energy_detected(uint8_t result)
NRF_802154_SPINEL_LOG_BANNER_CALLING();
NRF_802154_SPINEL_LOG_VAR("%u", result);
#if (NRF_802154_ENERGY_DETECTED_VERSION != 0)
res = nrf_802154_spinel_send_cmd_prop_value_is(
SPINEL_PROP_VENDOR_NORDIC_NRF_802154_ENERGY_DETECTED,
SPINEL_DATATYPE_NRF_802154_ENERGY_DETECTED,
p_result->ed_dbm);
#else
res = nrf_802154_spinel_send_cmd_prop_value_is(
SPINEL_PROP_VENDOR_NORDIC_NRF_802154_ENERGY_DETECTED,
SPINEL_DATATYPE_NRF_802154_ENERGY_DETECTED,
result);
#endif
SERIALIZATION_ERROR_CHECK(res, error, bail);