477 lines
16 KiB
C
477 lines
16 KiB
C
/*
|
|
* Copyright (c) 2017 - 2022, Nordic Semiconductor ASA
|
|
* All rights reserved.
|
|
*
|
|
* SPDX-License-Identifier: BSD-3-Clause
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions are met:
|
|
*
|
|
* 1. Redistributions of source code must retain the above copyright notice, this
|
|
* list of conditions and the following disclaimer.
|
|
*
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in the
|
|
* documentation and/or other materials provided with the distribution.
|
|
*
|
|
* 3. Neither the name of Nordic Semiconductor ASA nor the names of its
|
|
* contributors may be used to endorse or promote products derived from this
|
|
* software without specific prior written permission.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
* POSSIBILITY OF SUCH DAMAGE.
|
|
*
|
|
*/
|
|
|
|
/**
|
|
* @file
|
|
* This file implements CSMA-CA procedure for the 802.15.4 driver.
|
|
*
|
|
*/
|
|
|
|
#define NRF_802154_MODULE_ID NRF_802154_DRV_MODULE_ID_CSMACA
|
|
|
|
#include "nrf_802154_csma_ca.h"
|
|
|
|
#include "nrf_802154_config.h"
|
|
#if NRF_802154_CSMA_CA_ENABLED
|
|
|
|
#include <assert.h>
|
|
#include <stdbool.h>
|
|
#include <stdint.h>
|
|
|
|
#include "nrf_802154_const.h"
|
|
#include "nrf_802154_debug.h"
|
|
#include "nrf_802154_notification.h"
|
|
#include "nrf_802154_pib.h"
|
|
#include "nrf_802154_request.h"
|
|
#include "nrf_802154_tx_power.h"
|
|
#include "nrf_802154_stats.h"
|
|
#include "platform/nrf_802154_random.h"
|
|
#include "rsch/nrf_802154_rsch.h"
|
|
#include "nrf_802154_sl_timer.h"
|
|
#include "nrf_802154_sl_atomics.h"
|
|
|
|
/**
|
|
* @brief States of the CSMA-CA procedure.
|
|
*/
|
|
typedef enum
|
|
{
|
|
CSMA_CA_STATE_IDLE, ///< The CSMA-CA procedure is inactive.
|
|
CSMA_CA_STATE_BACKOFF, ///< The CSMA-CA procedure is in backoff stage.
|
|
CSMA_CA_STATE_ONGOING, ///< The frame is being sent.
|
|
CSMA_CA_STATE_ABORTED ///< The CSMA-CA procedure is being aborted.
|
|
} csma_ca_state_t;
|
|
|
|
static uint8_t m_nb; ///< The number of times the CSMA-CA algorithm was required to back off while attempting the current transmission.
|
|
static uint8_t m_be; ///< Backoff exponent, which is related to how many backoff periods a device shall wait before attempting to assess a channel.
|
|
|
|
static uint8_t * mp_data; ///< Pointer to a buffer containing PHR and PSDU of the frame being transmitted.
|
|
static nrf_802154_transmitted_frame_props_t m_data_props; ///< Structure containing detailed properties of data in buffer.
|
|
static nrf_802154_fal_tx_power_split_t m_tx_power; ///< Power to be used when transmitting the frame split into components.
|
|
static csma_ca_state_t m_state; ///< The current state of the CSMA-CA procedure.
|
|
|
|
/**
|
|
* @brief Perform appropriate actions for busy channel conditions.
|
|
*
|
|
* According to CSMA-CA description in 802.15.4 specification, when channel is busy NB and BE shall
|
|
* be incremented and the device shall wait random delay before next CCA procedure. If NB reaches
|
|
* macMaxCsmaBackoffs procedure fails.
|
|
*
|
|
* @retval true Procedure failed and TX failure should be notified to the next higher layer.
|
|
* @retval false Procedure is still ongoing and TX failure should be handled internally.
|
|
*/
|
|
static bool channel_busy(void);
|
|
|
|
static bool csma_ca_state_set(csma_ca_state_t expected, csma_ca_state_t desired)
|
|
{
|
|
nrf_802154_sl_log_function_enter(NRF_802154_LOG_VERBOSITY_HIGH);
|
|
|
|
bool result = nrf_802154_sl_atomic_cas_u8(&m_state, &expected, desired);
|
|
|
|
if (result)
|
|
{
|
|
nrf_802154_sl_log_local_event(NRF_802154_LOG_VERBOSITY_LOW,
|
|
NRF_802154_LOG_LOCAL_EVENT_ID_CSMACA__SET_STATE,
|
|
(uint32_t)desired);
|
|
}
|
|
|
|
nrf_802154_sl_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
|
|
|
|
return result;
|
|
}
|
|
|
|
static void priority_leverage(void)
|
|
{
|
|
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_HIGH);
|
|
|
|
bool first_transmit_attempt = (0 == m_nb);
|
|
bool coex_requires_boosted_prio = (nrf_802154_pib_coex_tx_request_mode_get() ==
|
|
NRF_802154_COEX_TX_REQUEST_MODE_CCA_START);
|
|
|
|
// Leverage priority only after the first backoff in the specified Coex TX request mode
|
|
if (first_transmit_attempt && coex_requires_boosted_prio)
|
|
{
|
|
// It should always be possible to update this timeslot's priority here
|
|
if (!nrf_802154_rsch_delayed_timeslot_priority_update(NRF_802154_RESERVED_CSMACA_ID,
|
|
RSCH_PRIO_TX))
|
|
{
|
|
assert(false);
|
|
}
|
|
}
|
|
|
|
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
|
|
}
|
|
|
|
/**
|
|
* @brief Notify MAC layer that CSMA-CA failed
|
|
*
|
|
* @param[in] error The error that caused the failure
|
|
*/
|
|
static void notify_failed(nrf_802154_tx_error_t error)
|
|
{
|
|
// core rejected attempt, use my current frame_props
|
|
nrf_802154_transmit_done_metadata_t metadata = {};
|
|
|
|
metadata.frame_props = m_data_props;
|
|
|
|
nrf_802154_notify_transmit_failed(mp_data, error, &metadata);
|
|
}
|
|
|
|
/**
|
|
* @brief Notify MAC layer that channel is busy if tx request failed and there are no retries left.
|
|
*
|
|
* @param[in] result Result of TX request.
|
|
*/
|
|
static void notify_busy_channel(bool result)
|
|
{
|
|
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_HIGH);
|
|
|
|
nrf_802154_rsch_delayed_timeslot_cancel(NRF_802154_RESERVED_CSMACA_ID, true);
|
|
|
|
// The 802.15.4 specification requires CSMA-CA to continue until m_nb is strictly greater
|
|
// than nrf_802154_pib_csmaca_max_backoffs_get(), but at the moment this function is executed
|
|
// the value of m_nb has not yet been incremented to reflect the latest attempt. Therefore
|
|
// the comparison uses `greater or equal` instead of `greater than`.
|
|
if (!result && (m_nb >= nrf_802154_pib_csmaca_max_backoffs_get()))
|
|
{
|
|
notify_failed(NRF_802154_TX_ERROR_BUSY_CHANNEL);
|
|
}
|
|
|
|
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
|
|
}
|
|
|
|
/**
|
|
* @brief Perform CCA procedure followed by frame transmission.
|
|
*
|
|
* If transmission is requested, CSMA-CA module waits for notification from the FSM module.
|
|
* If transmission request fails, CSMA-CA module performs procedure for busy channel condition
|
|
* @sa channel_busy().
|
|
*
|
|
* @param[in] dly_ts_id Delayed timeslot identifier.
|
|
*/
|
|
static void frame_transmit(rsch_dly_ts_id_t dly_ts_id)
|
|
{
|
|
assert(dly_ts_id == NRF_802154_RESERVED_CSMACA_ID);
|
|
|
|
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW);
|
|
|
|
if (csma_ca_state_set(CSMA_CA_STATE_BACKOFF, CSMA_CA_STATE_ONGOING))
|
|
{
|
|
priority_leverage();
|
|
|
|
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,
|
|
};
|
|
|
|
if (!nrf_802154_request_transmit(NRF_802154_TERM_NONE,
|
|
REQ_ORIG_CSMA_CA,
|
|
mp_data,
|
|
¶ms,
|
|
notify_busy_channel))
|
|
{
|
|
(void)channel_busy();
|
|
}
|
|
}
|
|
else
|
|
{
|
|
nrf_802154_rsch_delayed_timeslot_cancel(dly_ts_id, true);
|
|
}
|
|
|
|
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW);
|
|
}
|
|
|
|
/**
|
|
* @brief Calculates number of backoff periods as random value according to IEEE Std. 802.15.4.
|
|
*/
|
|
static uint8_t backoff_periods_calc_random(void)
|
|
{
|
|
return nrf_802154_random_get() % (1U << m_be);
|
|
}
|
|
|
|
/**
|
|
* @brief Calculates number of backoff periods to wait before the next CCA attempt of CSMA/CA
|
|
*
|
|
* @return Number of backoff periods
|
|
*/
|
|
static uint8_t backoff_periods_calc(void)
|
|
{
|
|
uint8_t result;
|
|
|
|
#if NRF_802154_TEST_MODES_ENABLED
|
|
|
|
switch (nrf_802154_pib_test_mode_csmaca_backoff_get())
|
|
{
|
|
case NRF_802154_TEST_MODE_CSMACA_BACKOFF_RANDOM:
|
|
result = backoff_periods_calc_random();
|
|
break;
|
|
|
|
case NRF_802154_TEST_MODE_CSMACA_BACKOFF_ALWAYS_MAX:
|
|
result = (1U << m_be) - 1U;
|
|
break;
|
|
|
|
case NRF_802154_TEST_MODE_CSMACA_BACKOFF_ALWAYS_MIN:
|
|
result = 0U;
|
|
break;
|
|
|
|
default:
|
|
result = backoff_periods_calc_random();
|
|
assert(false);
|
|
break;
|
|
}
|
|
#else
|
|
result = backoff_periods_calc_random();
|
|
#endif
|
|
|
|
return result;
|
|
}
|
|
|
|
/**
|
|
* @brief Delay CCA procedure for random (2^BE - 1) unit backoff periods.
|
|
*/
|
|
static void random_backoff_start(void)
|
|
{
|
|
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_HIGH);
|
|
|
|
uint64_t backoff_us = backoff_periods_calc() * UNIT_BACKOFF_PERIOD;
|
|
|
|
rsch_dly_ts_param_t backoff_ts_param =
|
|
{
|
|
.trigger_time = nrf_802154_sl_timer_current_time_get() + backoff_us,
|
|
.op = RSCH_DLY_TS_OP_CSMACA,
|
|
.type = RSCH_DLY_TS_TYPE_RELAXED,
|
|
.started_callback = frame_transmit,
|
|
.id = NRF_802154_RESERVED_CSMACA_ID,
|
|
};
|
|
|
|
switch (nrf_802154_pib_coex_tx_request_mode_get())
|
|
{
|
|
case NRF_802154_COEX_TX_REQUEST_MODE_FRAME_READY:
|
|
// To request Coex precondition immediately, priority must be leveraged
|
|
backoff_ts_param.prio = RSCH_PRIO_TX;
|
|
break;
|
|
|
|
case NRF_802154_COEX_TX_REQUEST_MODE_CCA_START:
|
|
// Coex should be requested for all backoff periods but the first one
|
|
backoff_ts_param.prio = (m_nb == 0) ? RSCH_PRIO_IDLE_LISTENING : RSCH_PRIO_TX;
|
|
break;
|
|
|
|
case NRF_802154_COEX_TX_REQUEST_MODE_CCA_DONE:
|
|
case NRF_802154_COEX_TX_REQUEST_MODE_ON_CCA_TOGGLE:
|
|
// Coex should not be requested during backoff periods
|
|
backoff_ts_param.prio = RSCH_PRIO_IDLE_LISTENING;
|
|
break;
|
|
|
|
default:
|
|
assert(false);
|
|
break;
|
|
}
|
|
|
|
// Delayed timeslot with these parameters should always be scheduled
|
|
if (!nrf_802154_rsch_delayed_timeslot_request(&backoff_ts_param))
|
|
{
|
|
assert(false);
|
|
}
|
|
|
|
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_HIGH);
|
|
}
|
|
|
|
static bool channel_busy(void)
|
|
{
|
|
bool result = true;
|
|
|
|
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW);
|
|
|
|
if (csma_ca_state_set(CSMA_CA_STATE_ONGOING, CSMA_CA_STATE_BACKOFF))
|
|
{
|
|
m_nb++;
|
|
|
|
if (m_be < nrf_802154_pib_csmaca_max_be_get())
|
|
{
|
|
m_be++;
|
|
}
|
|
|
|
if (m_nb > nrf_802154_pib_csmaca_max_backoffs_get())
|
|
{
|
|
mp_data = NULL;
|
|
bool ret = csma_ca_state_set(CSMA_CA_STATE_BACKOFF, CSMA_CA_STATE_IDLE);
|
|
|
|
assert(ret);
|
|
(void)ret;
|
|
}
|
|
else
|
|
{
|
|
random_backoff_start();
|
|
result = false;
|
|
}
|
|
}
|
|
|
|
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW);
|
|
return result;
|
|
}
|
|
|
|
bool nrf_802154_csma_ca_start(uint8_t * p_data,
|
|
const nrf_802154_transmit_csma_ca_metadata_t * p_metadata)
|
|
{
|
|
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW);
|
|
|
|
#if (NRF_802154_FRAME_TIMESTAMP_ENABLED)
|
|
uint64_t ts = nrf_802154_sl_timer_current_time_get();
|
|
|
|
nrf_802154_stat_timestamp_write(last_csmaca_start_timestamp, ts);
|
|
#endif
|
|
|
|
bool result = csma_ca_state_set(CSMA_CA_STATE_IDLE, CSMA_CA_STATE_BACKOFF);
|
|
|
|
assert(result);
|
|
(void)result;
|
|
|
|
mp_data = p_data;
|
|
m_data_props = p_metadata->frame_props;
|
|
m_nb = 0;
|
|
m_be = nrf_802154_pib_csmaca_min_be_get();
|
|
(void)nrf_802154_tx_power_convert_metadata_to_tx_power_split(nrf_802154_pib_channel_get(),
|
|
p_metadata->tx_power,
|
|
&m_tx_power);
|
|
|
|
random_backoff_start();
|
|
|
|
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW);
|
|
|
|
return true;
|
|
}
|
|
|
|
bool nrf_802154_csma_ca_abort(nrf_802154_term_t term_lvl, req_originator_t req_orig)
|
|
{
|
|
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW);
|
|
|
|
bool result = true;
|
|
|
|
if (((req_orig != REQ_ORIG_CORE) && (req_orig != REQ_ORIG_HIGHER_LAYER)) ||
|
|
(CSMA_CA_STATE_IDLE == nrf_802154_sl_atomic_load_u8(&m_state)))
|
|
{
|
|
// The request does not originate from core or the higher layer or the procedure
|
|
// is stopped already. Ignore the abort request and return success, no matter
|
|
// the termination level.
|
|
}
|
|
else if (term_lvl >= NRF_802154_TERM_802154)
|
|
{
|
|
// The procedure is active and the termination level allows the abort
|
|
// request to be executed. Force aborted state. Don't clear the frame
|
|
// pointer - it might be needed to notify failure.
|
|
nrf_802154_sl_atomic_store_u8(&m_state, CSMA_CA_STATE_ABORTED);
|
|
nrf_802154_rsch_delayed_timeslot_cancel(NRF_802154_RESERVED_CSMACA_ID, false);
|
|
}
|
|
else
|
|
{
|
|
// The procedure is active and the termination level does not allow
|
|
// the abort request to be executed. Return failure
|
|
result = false;
|
|
}
|
|
|
|
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW);
|
|
|
|
return result;
|
|
}
|
|
|
|
bool nrf_802154_csma_ca_tx_failed_hook(uint8_t * p_frame, nrf_802154_tx_error_t error)
|
|
{
|
|
bool result = true;
|
|
|
|
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW);
|
|
|
|
switch (error)
|
|
{
|
|
// Below errors mean a failure occurred during the frame processing and the frame cannot be
|
|
// transmitted unless a higher layer takes appropriate actions, hence the CSMA-CA procedure
|
|
// shall be stopped.
|
|
|
|
case NRF_802154_TX_ERROR_KEY_ID_INVALID:
|
|
/* Fallthrough. */
|
|
case NRF_802154_TX_ERROR_FRAME_COUNTER_ERROR:
|
|
if (mp_data == p_frame)
|
|
{
|
|
mp_data = NULL;
|
|
nrf_802154_sl_atomic_store_u8(&m_state, CSMA_CA_STATE_IDLE);
|
|
}
|
|
break;
|
|
|
|
default:
|
|
if (csma_ca_state_set(CSMA_CA_STATE_ABORTED, CSMA_CA_STATE_IDLE))
|
|
{
|
|
// The procedure was successfully aborted.
|
|
|
|
if (p_frame != mp_data)
|
|
{
|
|
// The procedure was aborted while another operation was holding
|
|
// frame pointer in the core - hence p_frame points to a different
|
|
// frame than mp_data. CSMA-CA failure must be notified directly.
|
|
notify_failed(error);
|
|
}
|
|
}
|
|
else if (p_frame == mp_data)
|
|
{
|
|
// The procedure is active and transmission attempt failed. Try again
|
|
result = channel_busy();
|
|
}
|
|
else
|
|
{
|
|
// Intentionally empty.
|
|
}
|
|
break;
|
|
}
|
|
|
|
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW);
|
|
|
|
return result;
|
|
}
|
|
|
|
bool nrf_802154_csma_ca_tx_started_hook(uint8_t * p_frame)
|
|
{
|
|
nrf_802154_log_function_enter(NRF_802154_LOG_VERBOSITY_LOW);
|
|
|
|
if (mp_data == p_frame)
|
|
{
|
|
mp_data = NULL;
|
|
nrf_802154_sl_atomic_store_u8(&m_state, CSMA_CA_STATE_IDLE);
|
|
}
|
|
|
|
nrf_802154_log_function_exit(NRF_802154_LOG_VERBOSITY_LOW);
|
|
return true;
|
|
}
|
|
|
|
#endif // NRF_802154_CSMA_CA_ENABLED
|