Added more doxygen comments to ieee802154 radio header file in
order to improve documentation coverage percentage.
Signed-off-by: Jukka Rissanen <jukka.rissanen@nordicsemi.no>
Extend ieee802154 transmit function documentation with the expected
return code for correctly received invalid ACK packets.
Signed-off-by: Jędrzej Ciupis <jedrzej.ciupis@nordicsemi.no>
Based on information from doc/develop/api/overview.rst, add current
version for some groups representing APIs, following the following
table:
- Experimental: 0.1.0
- Unstable: 0.8.0
- Stable: 1.0.0
Also based on doc/develop/api/overview.rst, add 'since' tag to the
groups.
Signed-off-by: Ederson de Souza <ederson.desouza@intel.com>
Signed-off-by: Anas Nashif <anas.nashif@intel.com>
IEEE 802.15.4-2020 defines four possible values for Key Identifier Mode
field of the Auxiliary Security Header. The current ieee802154 driver
API only supports two of them: b00 and b01. This commit adds support for
the two remaining Key Identifier Mode values. It's done by replacing a
field that can only hold Key Index into a field that can holds a pointer
to the entire Key Identifier field.
See IEEE 802.15.4-2020, sections 9.4.2.3 and 9.4.4 for further reference.
Signed-off-by: Jędrzej Ciupis <jedrzej.ciupis@nordicsemi.no>
This change slightly simplifies the configuration of a CSL receiver and
generalized CSL_RX_TIME to EXPECTED_RX_TIME as a re-usable primitive
across several timing-sensitive IEEE 802.15.4 standard sub-protocols
(namely BE-PANs/DSME/CSL/RIT/TSCH).
This API change is based on the rules outlined in RFC #61227.
Fixes: #62918
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
Improves standard conformance of the IEEE802154_CONFIG_ENH_ACK_HEADER_IE
option and introduces certain "soft MAC" capabilities around header IEs:
* Introduces types and helpers that allow driver maintainers to
represent, parse, write and validate header IEs.
* Introduces helper functions to access non-aligned fields in header
IEs, namely element IDs.
Updates the only existing L2 and driver pair that uses
IEEE802154_CONFIG_ENH_ACK_HEADER_IE: OpenThread platform radio and nRF5
and improves header IE validation in the nRF5 driver.
This change should help further driver maintainers to support
OpenThread's CSL and vendor IE extensions. It is based on the rules
specified in RFC #61227.
It is also a precondition to generically support both, "soft MAC" and
"hard MAC", approaches to header IEs in the TSCH protocol, namely the
time synchronization IE.
Fixes: #62940
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
"Sleeping" has a well defined meaning in Zephyr related to threading and
power management. This differs from OpenThread's definition:
- Deprecates the "SLEEP_TO_TX" capability as it is redundant and
conflicts with all of Zephyr's nomenclature, #61227, RFC 2863, Thread
standard and IEEE 802.15.4. This binds the API to an implementation
detail of OpenThread, instead. See #63670 for the agreed migration path.
- Renames the "SLEEP" event to "RX_OFF" which conforms to the
nomenclature in Zephyr, this API and IEEE 802.15.4.
Fixes: #62995
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
Fixes a few minor documentation issues that slipped through in the
recent large documentation update:
- Fixes the ordering of sections to follow the ordering of the
correspondig sections in the IEEE 802.15.4 standard.
- Fixes a few note/detail sections that were not recognized as such.
- Removes internal TODO markers from the publicly visible docs.
- Fixes wording and typos in a few instances.
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
Hides types in the IEEE 802.15.4 driver sub-API that are of no public
interest and improves documentation of the remainder.
Apart from extending and clarifying many details of the driver API, this
change also specifies certain formal properties of API calls, such as
"sleeps" or "isr-ok". Plus it removes semantic ambivalence that had been
resolved and hidden in existing implementation details but is highly
relevant to the way the API can be used and shall be implemented.
As far as possible this change introduces formal requirements language
(MAY, SHALL/MUST, SHOULD) to specify driver implementation requirements.
This change also introduces two definitions - for the moment being of
purely documentary relevance (i.e. to be referred in the documentation):
* IEEE802154_CONFIG_RX_SLOT_NONE
* IEEE802154_CONFIG_RX_SLOT_OFF
These "magic" values are required to clarify the exact semantics of RX
slots as to receiver activity.
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
Improves the API documentation including it's structure and integration
into the Zephyr documentation.
Previously the API status of the IEEE 802.15.4 API (and its sub-APIs)
was unclear.
This change adds three APIs in an "unstable" state:
- IEEE 802.15.4 L2 for subsystem developers
- IEEE 802.15.4 drivers for driver developers
- IEEE 802.15.4 net_mgmt for application developers
The corresponding APIs are documented at a group level.
These sub-APIs need to be separately versioned as they have different
audiences, change velocities and levels of stability.
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
Replaces the previous approach to define bands via hardware capabilities
by the standard conforming concept of channel pages.
In the short term this allows us to correctly calculate the PHY specific
symbol rate and several parameters that directly depend from the symbol
rate and were previously not being correctly calculated for some of the
drivers whose channel pages could not be represented previously:
* We now support sub-nanosecond precision symbol rates for UWB. Rounding
errors are being minimized by switching from a divide-then-multiply
approach to a multiply-then-divide approach.
* UWB HRP: symbol rate depends on channel page specific preamble symbol
rate which again requires the pulse repetition value to be known
* Several MAC timings are being corrected based on the now correctly
calculated symbol rates, namely aTurnaroundTime, aUnitBackoffPeriod,
aBaseSuperframeDuration.
In the long term, this change unlocks such highly promising functional
areas as UWB ranging and SUN-PHY channel hopping in the SubG area (plus
of course any other PHY specific feature).
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
Based on the standard based definitions given in previous commits, the
TX timestamp used for timed TX now refers to the start of PHR. As OT
continues to calculate timestamps based on a "start of SHR" definition,
the duration of the PHY specific SHR is added in the OT adaptation layer
to make up for this OT quirk.
Fixes: #59245
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
The IEEE 802.15.4 API and networking subsystem were using several
inconsistent timestamp resolutions and types. This change defines all
timestamps with nanosecond resolution and reduces the number of
available types to represent timestamps to two:
* `struct net_ptp_time` for PTP timestamps
* `net_time_t` for all other high resolution timestamps
All timestamps (including PTP timestamps) are now referred to a
"virtual" local network subsystem clock source based on the well-defined
types above. It is the responsibility of network subsystem L2/driver
implementations (notably Ethernet and IEEE 802.15.4 L2 stacks) to ensure
consistency of all timestamps and radio timer values exposed by the
driver API to such a network subsystem uptime reference clock
independent of internal implementation details.
The "virtual" network clock source may be implemented based on arbitrary
hardware peripherals (e.g. a coarse low power RTC counter during sleep
time plus a high resolution/high precision radio timer while receiving
or sending). Such implementation details must be hidden from API
clients, as if the driver used a single high resolution clock source
instead.
For IEEE 802.15.4, whenever timestamps refer to packet send or receive
times, they are measured when the end of the IEEE 802.15.4 SFD (message
timestamp point) is present at the local antenna (reference plane).
Due to its limited range of ~290 years, net_time_t timestamps (and
therefore net_pkt timestamps and times) must not be used to represent
absolute points in time referred to an external epoch independent of
system uptime (e.g. UTC, TAI, PTP, NTP, ...).
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
The `attr_get` method is added to the ieee802154_radio to allow
reading of driver specific attributes of given device.
The enum `ieee802154_attr` provides common extension pattern
allowing to extend the attribute set.
Accessor function `ieee802154_radio_attr_get` is provided.
Signed-off-by: Andrzej Kuroś <andrzej.kuros@nordicsemi.no>
The ieee802154_tx_mode and ieee802154_config_type types are given
values allowing to extend these types elsewhere.
Signed-off-by: Andrzej Kuroś <andrzej.kuros@nordicsemi.no>
Calculates macResponseWaitTime and applies it to the association
process.
As the timing calculation re-uses symbol period calculations and other
PHY timing constants previously introduced, these are now shared as
utility functions.
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
Acknowledgment is mandatory if legitimately requested by the package's
"ACK requested" flag. The L2 layer will have to ensure that compliant
ACK packages will always be sent out automatically as required by the
standard.
For IEEE 802.15.4 compliance, the NET_L2_IEEE802154_ACK_REPLY option is
therefore being deprecated.
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
The existing calls to ieee802154_radio_send() and soft MAC ACK handling
were inconsistent and/or not properly integrated with more recent
radio driver capabilities as CSMA/CA and ACK in hardware.
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
The method ieee802154_radio_handle_ack() does not belong to the
PHY/radio layer but to the L2 layer. It is a callback called from the
radio layer into the L2 layer and to be implemented by all L2 stacks.
This is the same pattern as is used for ieee802154_init(). The
'_radio_' infix in this function is therefore confusing and
conceptually wrong.
This change fixes the naming inconsistency and extensively documents
its rationale.
It is assumed that the change can be made without prior deprecation of the
existing method as in the rare cases where users have implemented custom
radio drivers these will break in obvious ways and can easily be fixed.
Nevertheless such a rename would not be justified on its own if it were
not for an important conceptual reason:
The renamed function represents a generic "inversion-of-control" pattern
which will become important in the TSCH context: It allows for clean
separation of concerns between the PHY/radio driver layer and the
MAC/L2 layer even in situations where the radio driver needs to be
involved for performance or deterministic timing reasons. This
"inversion-of-control" pattern can be applied to negotiate timing
sensitive reception and transmission windows, it let's the L2 layer
deterministically timestamp information elements just-in-time with
internal radio timer counter values, etc.
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
The CSMA/CA algorithm had multiple issues:
- Timing of backoff periods depends on the PHY's symbol rate and other
PHY-specific settings. We introduce a preliminary solution that works
with current drivers. A fully standard-compliant long-term solution
has already been conceptualized but requires further pre-conditions,
see #50336 (issuecomment-1251122582).
- We enforce the condition defined in the standard that macMinBe must be
less than or equal macMaxBe.
- According to the standard a CSMA/CA failure should lead to immediate
abortion of the transmission attempt, no matter how many
retransmissions have been configured.
- The number of retransmissions was off by one. It is now used as
defined in the standard algorithm.
- Retransmissions are only allowed when acknowledgement is requested in
the packet.
- prepare_for_ack() has side effects and must be called before each
retransmission.
We also replace variables by constants where possible.
The function was renamed as it represents unslotted CSMA/CA and does not
support other CSMA/CA modes. These may be introduced in the future.
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
Over time, some non-standard concepts and extensions were introduced
into the stack (in KConfig, in drivers, in the internal API and into the
implementation) which makes introduction of additional standard-
compliant extensions like TSCH (and others) unnecessarily difficult.
To introduce extensions like TSCH it is required for the IEEE 802.15.4
stack to become more structurally aligned with the standard again which
will be the focus of some of the upcoming preparatory changes.
One way to check and prove standard compliance is to reference the
standard from within the source code. This change therefore introduces
inline references to the IEEE 802.15.4-2020 standard wherever possible.
Deviations from the standard are documented with TODO or deprecation
labels to be addressed in future changes.
In the future, new code introduced to the IEEE 802.15.4 stack should
be documented and reviewed for standard-compliance to avoid further
divergence. Most importantly:
* MAC/PHY configuration (via net mgmt, radio API, devicetree or
KConfig) should always be directly linked to well-defined MAC/PHY
PIB attributes if visible to the MAC API or the end user.
* Net management/shell/radio API commands should have a documented
reference to the corresponding MLME action from the standard.
Signed-off-by: Florian Grandel <fgrandel@code-for-humans.de>
Adding an Openthread radio API `otPlatRadioSetMacFrameCounterIfLarger`
implementation and the corresponding call to the IEEEE802154 driver.
Signed-off-by: Przemyslaw Bida <przemyslaw.bida@nordicsemi.no>
The IEEE 802.15.4 radio driver encodes attributes in:
* little endian for everything that is close to the protocol as
IEEE 802.15.4 frames are little endian encoded.
* mixed big and little endian in its configuration where extended
addresses are being represented. These inconsistencies are unfortunate
but cannot be easily fixed in a backwards compatible way so will be
left untouched in this change.
Endianness was almost nowhere documented which explains these
inconsistencies and led to several bugs where assignments of different
byte order are not converted (or sometimes converted, sometimes not).
This change documents intended endianness within the realm of the
IEEE 802.15.4 radio driver code. Conversion bugs are fixed in a separate
commit.
Signed-off-by: Florian Grandel <jerico.dev@gmail.com>
In order to bring consistency in-tree, migrate all includes within
include directory to the new prefix <zephyr/...>. Note that the
conversion has been scripted, refer to zephyrproject-rtos#45388 for more
details.
Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
Move include paths and add new target_include_directories to support
backwards compatibility:
* /include -> /include/zephyr
example: <irq.h> -> <zephyr/irq.h>
Issue #41543
Signed-off-by: Yuval Peress <peress@google.com>
2022-04-08 19:03:32 +02:00
Renamed from include/net/ieee802154_radio.h (Browse further)
