Skip to content

Commit

Permalink
drivers: ieee802154: cc13/26xx_subg: inline documentation
Browse files Browse the repository at this point in the history 
This change introduces inline documentation with references to the
current version of the IEEE 802.15.4 standard.

Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
  • Loading branch information
@fgrandel
fgrandel committed May 30, 2023
1 parent 3e87cea commit ce258ad
Show file tree
Hide file tree
Showing 2 changed files with 49 additions and 15 deletions.
11 changes: 7 additions & 4 deletions drivers/ieee802154/ieee802154_cc13xx_cc26xx.h
View file
Expand Up @@ -2,6 +2,8 @@
* Copyright (c) 2019 Brett Witherspoon
*
* SPDX-License-Identifier: Apache-2.0
*
* References are to the IEEE 802.15.4-2020 standard.
*/

#ifndef ZEPHYR_DRIVERS_IEEE802154_IEEE802154_CC13XX_CC26XX_H_
Expand All @@ -19,17 +21,18 @@
#include <driverlib/rf_ieee_cmd.h>
#include <driverlib/rf_mailbox.h>

/* IEEE 802.15.4-2006 2450 MHz O-QPSK PHY symbol rate (6.5.3.2) */
/* For O-QPSK the physical and MAC timing symbol rates are the same, see section 12.3.3. */
#define IEEE802154_2450MHZ_OQPSK_SYMBOLS_PER_SECOND \
IEEE802154_PHY_SYMBOLS_PER_SECOND(IEEE802154_PHY_OQPSK_2450MHZ_SYMBOL_PERIOD_US)

/* IEEE 802.15.4-2006 PHY PIB attributes (6.4.2) */
/* PHY PIB attribute phyCcaMode - CCA Mode 3: Carrier sense with energy above threshold, see
* section 11.3, table 11-2 and section 10.2.8
*/
#define IEEE802154_PHY_CCA_MODE 3

#define IEEE802154_PHY_SHR_DURATION 10
#define IEEE802154_PHY_SHR_DURATION 10 /* in symbols, 8 preamble and 2 SFD, see section 12.1.2 */

#define IEEE802154_PHY_SYMBOLS_PER_OCTET 2
#define IEEE802154_PHY_SYMBOLS_PER_OCTET 2 /* see section 12.2.1 */

/* ACK is 2 bytes for PHY header + 2 bytes MAC header + 2 bytes MAC footer */
#define IEEE802154_ACK_FRAME_OCTETS 6
Expand Down
53 changes: 42 additions & 11 deletions drivers/ieee802154/ieee802154_cc13xx_cc26xx_subg.c
View file
Expand Up @@ -168,7 +168,8 @@ static volatile rfc_CMD_PROP_RADIO_DIV_SETUP_PA_t ieee802154_cc13xx_subg_radio_d
},
.config.biasMode = true, /* Rely on an external antenna biasing network. */
.txPower = 0x013f, /* 14 dBm, see TRM 25.3.3.2.16 */
.centerFreq = 906, /* Set channel page zero, channel 1 by default,
.centerFreq = 906, /* Set channel page zero, channel 1 by default, see IEEE 802.15.4,
* section 10.1.3.3.
* TODO: Use compliant SUN PHY frequencies from channel page 9.
*/
.intFreq = 0x8000, /* Use default intermediate frequency. */
Expand Down Expand Up @@ -258,6 +259,7 @@ static inline int ieee802154_cc13xx_cc26xx_subg_channel_to_frequency(
__ASSERT_NO_MSG(frequency != NULL);
__ASSERT_NO_MSG(fractFreq != NULL);

/* See IEEE 802.15.4, section 10.1.3.3. */
if (channel == IEEE802154_SUB_GHZ_CHANNEL_MIN) {
*frequency = 868;
/*
Expand All @@ -274,6 +276,27 @@ static inline int ieee802154_cc13xx_cc26xx_subg_channel_to_frequency(
return -EINVAL;
}

/* TODO: This incorrectly mixes up legacy O-QPSK SubGHz PHY channel page zero
* frequency calculation with SUN FSK operating mode #3 PHY radio settings.
*
* The correct channel frequency calculation for this PHY is on channel page 9,
* using the formula ChanCenterFreq = ChanCenterFreq0 + channel * ChanSpacing.
*
* Assuming operating mode #3, the parameters for some frequently used bands
* on this channel page are:
* 863 MHz: ChanSpacing 0.2, TotalNumChan 35, ChanCenterFreq0 863.1
* 915 MHz: ChanSpacing 0.4, TotalNumChan 64, ChanCenterFreq0 902.4
*
* See IEEE 802.15.4, section 10.1.3.9.
*
* Setting the PHY, channel page, band and operating mode requires additional
* radio configuration settings.
*
* Making derived MAC/PHY PIB attributes available to L2 requires an additional
* attribute getter, see
* https://github.com/zephyrproject-rtos/zephyr/issues/50336#issuecomment-1251122582.
*/

return 0;
}

Expand Down Expand Up @@ -467,7 +490,7 @@ static int ieee802154_cc13xx_cc26xx_subg_set_txpower(
return 0;
}

/* See IEEE 802.15.4 section 6.2.5.1 and TRM section 25.5.4.3 */
/* See IEEE 802.15.4 section 6.7.1 and TRM section 25.5.4.3 */
static int ieee802154_cc13xx_cc26xx_subg_tx(const struct device *dev,
enum ieee802154_tx_mode mode,
struct net_pkt *pkt,
Expand All @@ -485,12 +508,14 @@ static int ieee802154_cc13xx_cc26xx_subg_tx(const struct device *dev,

k_mutex_lock(&drv_data->tx_mutex, K_FOREVER);

/* Prepend data with the SUN FSK PHY header */
/* Prepend data with the SUN FSK PHY header,
* see IEEE 802.15.4, section 19.2.4.
*/
drv_data->tx_data[0] = buf->len + IEEE802154_PHY_SUN_FSK_PHR_LEN;
/* 20.2.2 PHR field format. 802.15.4-2015 */
drv_data->tx_data[1] = 0;
drv_data->tx_data[1] |= BIT(3); /* FCS Type: 2-octet FCS */
drv_data->tx_data[1] |= BIT(4); /* DW: Enable Data Whitening */
/* TODO: Zero-copy TX, see discussion in #49775. */
memcpy(&drv_data->tx_data[IEEE802154_PHY_SUN_FSK_PHR_LEN], buf->data, buf->len);

/* Chain commands */
Expand Down Expand Up @@ -618,7 +643,7 @@ static void ieee802154_cc13xx_cc26xx_subg_rx_done(

drv_data->rx_entry[i].status = DATA_ENTRY_PENDING;

/* TODO determine LQI in PROP mode */
/* TODO: determine LQI in PROP mode */
net_pkt_set_ieee802154_lqi(pkt, 0xff);
net_pkt_set_ieee802154_rssi(
pkt,
Expand Down Expand Up @@ -696,7 +721,7 @@ uint16_t ieee802154_cc13xx_cc26xx_subg_get_subg_channel_count(
{
ARG_UNUSED(dev);

/* IEEE 802.15.4 SubGHz channels range from 0 to 10*/
/* IEEE 802.15.4 SubGHz channels range from 0 to 10 for channel page zero. */
return 11;
}

Expand Down Expand Up @@ -729,7 +754,7 @@ static void ieee802154_cc13xx_cc26xx_subg_data_init(
{
uint8_t *mac;

/* FIXME do multi-protocol devices need more than one IEEE MAC? */
/* TODO: Do multi-protocol devices need more than one IEEE MAC? */
if (sys_read32(CCFG_BASE + CCFG_O_IEEE_MAC_0) != 0xFFFFFFFF &&
sys_read32(CCFG_BASE + CCFG_O_IEEE_MAC_1) != 0xFFFFFFFF) {
mac = (uint8_t *)(CCFG_BASE + CCFG_O_IEEE_MAC_0);
Expand Down Expand Up @@ -850,9 +875,12 @@ static struct ieee802154_cc13xx_cc26xx_subg_data ieee802154_cc13xx_cc26xx_subg_d
.bAppendRssi = true,
.bAppendStatus = true,
},
/* Preamble & SFD for 2-FSK SUN PHY. 802.15.4-2015, 20.2.1 */
/* Last preamble byte and SFD for uncoded 2-FSK SUN PHY, phySunFskSfd = 0,
* see IEEE 802.15.4, section 19.2.3.2, table 19-2.
*/
.syncWord0 = 0x55904E,
.maxPktLen = IEEE802154_MAX_PHY_PACKET_SIZE,
/* PHR field format, see IEEE 802.15.4, section 19.2.4 */
.hdrConf = {
.numHdrBits = 16,
.numLenBits = 11,
Expand All @@ -865,11 +893,12 @@ static struct ieee802154_cc13xx_cc26xx_subg_data ieee802154_cc13xx_cc26xx_subg_d
.cmd_prop_rx_adv_output,
},

/* TODO: Support correlation CCA modes, see section 10.2.8. */
.cmd_prop_cs = {
.commandNo = CMD_PROP_CS,
.startTrigger.pastTrig = true,
.condition.rule = COND_NEVER,
/* CCA Mode 1: Energy above threshold */
/* CCA Mode 1: Energy above threshold, see section 10.2.8 */
.csConf = {
.bEnaRssi = true,
.busyOp = true,
Expand All @@ -889,11 +918,13 @@ static struct ieee802154_cc13xx_cc26xx_subg_data ieee802154_cc13xx_cc26xx_subg_d
.startTrigger.pastTrig = true,
.condition.rule = COND_NEVER,
.pktConf.bUseCrc = true,
/* PHR field format. 802.15.4-2015, 20.2.2 */
/* PHR field format, see IEEE 802.15.4, section 19.2.4 */
.numHdrBits = 16,
.preTrigger.triggerType = TRIG_REL_START,
.preTrigger.pastTrig = true,
/* Preamble & SFD for 2-FSK SUN PHY. 802.15.4-2015, 20.2.1 */
/* Last preamble byte and SFD for uncoded 2-FSK SUN PHY, phySunFskSfd = 0,
* see IEEE 802.15.4, section 19.2.3.2, table 19-2.
*/
.syncWord = 0x55904E,
},
};
Expand Down

0 comments on commit ce258ad

Please sign in to comment.