Skip to content

drivers: nrf_802154: Update the IEEE 802.15.4 component #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 9, 2021
Merged

drivers: nrf_802154: Update the IEEE 802.15.4 component #96

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 29 additions & 1 deletion drivers/nrf_802154/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,36 @@
#
# Copyright (c) 2021 Nordic Semiconductor ASA
# Copyright (c) 2021, 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-driver-interface INTERFACE)
add_library(nrf-802154-serialization-interface INTERFACE)
Expand Down
56 changes: 39 additions & 17 deletions drivers/nrf_802154/driver/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,36 @@
#
# Copyright (c) 2021 Nordic Semiconductor ASA
# Copyright (c) 2021, 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.
#
#

target_include_directories(nrf-802154-driver-interface INTERFACE include)

Expand All @@ -16,11 +44,13 @@ target_include_directories(nrf-802154-driver
target_sources(nrf-802154-driver
PRIVATE
src/nrf_802154.c
src/nrf_802154_aes_ccm.c
src/nrf_802154_core.c
src/nrf_802154_core_hooks.c
src/nrf_802154_critical_section.c
src/nrf_802154_debug.c
src/nrf_802154_debug_assert.c
src/nrf_802154_encrypt.c
src/nrf_802154_pib.c
src/nrf_802154_peripherals_alloc.c
src/nrf_802154_queue.c
Expand All @@ -29,24 +59,24 @@ target_sources(nrf-802154-driver
src/nrf_802154_stats.c
src/nrf_802154_swi.c
src/nrf_802154_trx.c
src/nrf_802154_trx_dppi.c
src/nrf_802154_trx_ppi.c
src/mac_features/nrf_802154_csma_ca.c
src/mac_features/nrf_802154_delayed_trx.c
src/mac_features/nrf_802154_filter.c
src/mac_features/nrf_802154_frame_parser.c
src/mac_features/nrf_802154_ie_writer.c
src/mac_features/nrf_802154_ifs.c
src/mac_features/nrf_802154_security_pib_ram.c
src/mac_features/nrf_802154_security_writer.c
src/mac_features/nrf_802154_precise_ack_timeout.c
src/mac_features/ack_generator/nrf_802154_ack_data.c
src/mac_features/ack_generator/nrf_802154_ack_generator.c
src/mac_features/ack_generator/nrf_802154_enh_ack_generator.c
src/mac_features/ack_generator/nrf_802154_imm_ack_generator.c
src/platform/temperature/nrf_802154_temperature_none.c
)

if (NRF52_SERIES)
target_sources(nrf-802154-driver PRIVATE src/nrf_802154_trx_ppi.c)
elseif (NRF53_SERIES)
target_sources(nrf-802154-driver PRIVATE src/nrf_802154_trx_dppi.c)
endif()
)

if (SL_OPENSOURCE)
target_sources(nrf-802154-driver
Expand All @@ -72,16 +102,8 @@ if (SL_OPENSOURCE OR NRF53_SERIES)
NRF_802154_DELAYED_TRX_ENABLED=0
# Disable IFS
NRF_802154_IFS_ENABLED=0
)
else()
target_compile_definitions(nrf-802154-driver-interface
INTERFACE
# Enable Frame Timestamps
NRF_802154_FRAME_TIMESTAMP_ENABLED=1
# Enable DTRX
NRF_802154_DELAYED_TRX_ENABLED=1
# Enable IFS
NRF_802154_IFS_ENABLED=1
# Disable IE writer
NRF_802154_IE_WRITER_ENABLED=0
)
endif()

Expand Down
202 changes: 200 additions & 2 deletions drivers/nrf_802154/driver/include/nrf_802154.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -635,6 +635,57 @@ bool nrf_802154_transmit_raw_at(const uint8_t * p_data,
uint32_t dt,
uint8_t channel);

/**
* @brief Requests retransmission at the specified time.
*
* @note This function is implemented in a zero-copy fashion. It passes the given buffer pointer to
* the RADIO peripheral.
*
* @note This function is meant specifically to be used for transmitting frames for which
* @ref nrf_802154_transmit_failed was reported in the original transmission attempt. This
* function does not perform any modifications to the provided frame's content. In particular,
* it performs neither authentication nor confidentiality transform of the frame's content.
* Therefore it must not be called to execute the first transmission attempt of a given frame.
* Doing so might lead to a number of issues such as security breaches and transmissions of
* malformed or incorrect frames.
*
* @note Only a single transmission or only a single retransmission can be scheduled at a time.
*
* This function is asynchronous. It queues the delayed transmission using the Radio Scheduler
* module and performs it at the specified time.
*
* If the delayed retransmission is successfully performed, @ref nrf_802154_transmitted is called.
* If the delayed retransmission cannot be performed 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 retransmission time is in the past, the function returns false and does not
* schedule retransmission.
*
* A successfully scheduled retransmission can be cancelled by a call
* to @ref nrf_802154_transmit_at_cancel, similarly to a successfully scheduled transmission.
*
* @param[in] p_data Pointer to the array with data to transmit. The first byte must contain
* the frame length (including PHR and 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] cca If the driver is to perform a CCA procedure before transmission.
* @param[in] t0 Base of delay time - absolute time used by the Timer Scheduler,
* in microseconds (us).
* @param[in] dt Delta of delay time from @p t0, in microseconds (us).
* @param[in] channel Radio channel on which the frame is to be transmitted.
*
* @retval true The retransmission procedure was scheduled.
* @retval false The driver could not schedule the retransmission procedure.
*/
bool nrf_802154_retransmit_raw_at(const uint8_t * p_data,
bool cca,
uint32_t t0,
uint32_t dt,
uint8_t channel);

/**
* @brief Cancels a delayed transmission scheduled by a call to @ref nrf_802154_transmit_raw_at.
*
Expand Down Expand Up @@ -1207,7 +1258,9 @@ void nrf_802154_src_addr_matching_method_set(nrf_802154_src_addr_match_t match_m

/**
* @brief Adds the address of a peer node for which the provided ACK data
* is to be added to the pending bit list.
* is to be injected into generated ACKs.
*
* Data passed to this function can be either pending bit data or Header IE data.
*
* The pending bit list works differently, depending on the upper layer for which the source
* address matching method is selected:
Expand All @@ -1216,6 +1269,36 @@ void nrf_802154_src_addr_matching_method_set(nrf_802154_src_addr_match_t match_m
* - For Standard-compliant, @ref NRF_802154_SRC_ADDR_MATCH_ALWAYS_1
* For more information, see @ref nrf_802154_src_addr_match_t.
*
* For IE data, specific cases are supported, where additional data will be injected into the IE on pre-transmission:
* - CSL IE - CSL phase will be injected if IE ID is set to @ref IE_CSL_ID
* - Thread link metrics - Link metrics will be injected if
* - IE ID is set to IE_VENDOR_ID
* - OUI is set to IE_VENDOR_THREAD_OUI
* - Thread IE subtype is set to IE_VENDOR_THREAD_ACK_PROBING_ID
*
* For Link metrics to be injected, additional preparation is required. Each byte of injected link metrics needs to be filled
* with a token, indicating what type of data is to be injected pre-transmission. Supported tokens are:
* - @ref IE_VENDOR_THREAD_RSSI_TOKEN - RSSI of the last received frame will be injected,
* - @ref IE_VENDOR_THREAD_MARGIN_TOKEN - RSSI above sensitivity margin of the last received frame will be injected,
* - @ref IE_VENDOR_THREAD_LQI_TOKEN - LQI of the last received frame will be injected.
* Additionally, tokens must be unique in given IE, all bytes prepared for link metrics must be filled with tokens and no more
* than two bytes must be prepared for link metrics.
* If any of those conditions is not met, no data will be injected into the ACK pre-transmission.
*
* To better illustrate, if RSSI is to be inserted into ACKs for specific address,
* following ie data needs to be prepared:
*
* +------------+----------------------+---------------------------------+-----------------------------+
* | Bytes: 0-1 | 2-4 | 5 | 6 |
* +------------+----------------------+---------------------------------+-----------------------------+
* | IE header | IE_VENDOR_THREAD_OUI | IE_VENDOR_THREAD_ACK_PROBING_ID | IE_VENDOR_THREAD_RSSI_TOKEN |
* +------------+----------------------+---------------------------------+-----------------------------+
* | |
* | <------------------IE Vendor-specific data------------------> |
*
* When sending ACK with this data, before transmission, RSSI of the last received frame
* will be written into byte 6.
*
* The method can be set during initialization phase by calling @ref nrf_802154_src_matching_method.
*
* @param[in] p_addr Array of bytes containing the address of the node (little-endian).
Expand Down Expand Up @@ -1385,6 +1468,32 @@ void nrf_802154_cca_cfg_get(nrf_802154_cca_cfg_t * p_cca_cfg);
*/
void nrf_802154_transmit_csma_ca_raw(const uint8_t * p_data);

/**
* @brief Performs the CSMA-CA procedure and retransmits 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 This function is meant specifically to be used for transmitting frames for which
* @ref nrf_802154_transmit_failed was reported in the original transmission attempt. This
* function does not perform any modifications to the provided frame's content. In particular,
* it performs neither authentication nor confidentiality transform of the frame's content.
* Therefore it must not be called to execute the first transmission attempt of a given frame.
* Doing so might lead to a number of issues such as security breaches and transmissions of
* malformed or incorrect frames.
*
* @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.
*/
void nrf_802154_retransmit_csma_ca_raw(const uint8_t * p_data);

#else // NRF_802154_USE_RAW_API

/**
Expand All @@ -1406,6 +1515,33 @@ void nrf_802154_transmit_csma_ca_raw(const uint8_t * p_data);
*/
void nrf_802154_transmit_csma_ca(const uint8_t * p_data, uint8_t length);

/**
* @brief Performs the CSMA-CA procedure and retransmits 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 This function is meant specifically to be used for transmitting frames for which
* @ref nrf_802154_transmit_failed was reported in the original transmission attempt. This
* function does not perform any modifications to the provided frame's content. In particular,
* it performs neither authentication nor confidentiality transform of the frame's content.
* Therefore it must not be called to execute the first transmission attempt of a given frame.
* Doing so might lead to a number of issues such as security breaches and transmissions of
* malformed or incorrect frames.
*
* @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.
* @param[in] length Length of the given frame. See also @ref nrf_802154_transmit.
*/
void nrf_802154_retransmit_csma_ca(const uint8_t * p_data, uint8_t length);

#endif // NRF_802154_USE_RAW_API

/**
Expand Down Expand Up @@ -1674,14 +1810,76 @@ void nrf_802154_ifs_min_lifs_period_set(uint16_t period);
*/

/**
* @brief Gets nRF 802.15.4 Radio Diver Capabilities.
* @brief Gets nRF 802.15.4 Radio Driver Capabilities.
*
* @return Capabilities of the radio driver.
*/
nrf_802154_capabilities_t nrf_802154_capabilities_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 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);

/** @} */

#ifdef __cplusplus
}
#endif
Expand Down
Loading