[RFC] net: ieee802154: (re-)enforce vendor and protocol neutrality of the driver API

[fgrandel]

Introduction

Transforming the IEEE 802.15.4 driver API (back) into being vendor- and protocol-neutral, see detailed rationale including practical examples of problems and solutions. I'm arguing here that a more standard conforming API would considerably lower the hurdle to entry for other vendors into the Thread/IEEE 802.15.4 space.

Problem description

Some recent additions to the IEEE 802.15.4 driver API broke encapsulation: They are either closely coupled to one specific upper layer stack (OT) or a specific vendor's choice of hardware offloading.

This created some technical debt for L2 and community driver maintainers when different offloading choices or different upper layer stacks are to be implemented (e.g. to support [parts of] the Thread protocol or other IEEE 802.15.4 sub-protocols). This technical debt is currently experienced by the TSCH protocol and CC13/26xx driver developments. See e.g. #60946, openthread/openthread#9322, #60401, #59133, #58434, #51266 for a non-exhaustive list of PRs that fix the kind of technical debt specified in this RFC.

NB: By my personal estimate, the linked PRs cover about 5-10% of the actual technical debt in the current API as established by this RFC.

Proposed change

The following IEEE 802.15.4 driver API review policies are proposed for all future changes and as guidelines for "repair work":

• All future additions to the public IEEE 802.15.4 driver API SHALL either prove (by letting the API docs point to appropriate sections of current/future standard versions) that they are vendor and upper-layer agnostic or they SHALL be encapsulated in separate files selected via Kconfig/Devicetree if (and only if) the specific vendor/upper-layer stack is active. An appropriate architectural pattern has already been established and exemplified ("vendor extensions", "protocol extensions").
• MAC or PHY features that are covered by the IEEE 802.15.4 standard (MLME, data structures, PHY/MAC PIB attributes, etc.), SHALL be divided up into primitives as defined by the standard (again to be proven by pointers to the standard).
• The driver architecture SHALL continue to support all kinds of non-mandatory/non-standard hardware-offloading measures for vendors to differentiate themselves ("hard MAC" extensions).
• We promote a "soft MAC first" approach such that driver maintainers have to implement strictly only what is required by the standard no matter what the individual offloading requirements of one vendor, i.e. driver maintainers MAY decide to not do hardware offloading and such a choice SHALL have first-class architecture support even if the soft-MAC solution is not implemented right away.
• Zephyr L2 code SHALL NOT call directly or indirectly into soft-MAC solutions that are exclusively provided by one vendor's driver. Such soft-MAC features SHALL be ported to vendor-agnostic (possibly but not necessarily protocol-agnostic) soft-MAC code re-usable by all drivers before being accepted into mainline. Zephyr SHALL only call into vendor-specific driver code that provably does hardware offloading for performance reasons. (Prominent examples: IE parser and certain security-related features in the nRF5 driver that at least optionally run on the CPU within Zephyr threads/ISRs and could be implemented in a vendor-agnostic way w/o loss of performance, see the driver's mac_features folder. Similar examples exist to a lesser extent in other drivers.)

As an architectural measure, it is proposed, to divide the IEEE 802.15.4 driver API up into two separate sections:

• PHY/L1
• Hard MAC/L2

Implementing the PHY/L1 part SHALL be sufficient for basic soft MAC support of all Zephyr protocol stacks, i.e. the hard MAC/L2 layer SHALL be architecturally optional even if the standard itself requires de-facto hardware offloading on some hardware (e.g. specialized peripherals in the absence of a fast-enough CPU). The decision whether some MAC feature needs to be offloaded SHALL be left to the individual driver maintainers as the standard itself has no requirements concerning implementation on CPUs vs. specialized peripherals or dedicated radio cores.

For historical reasons documentation and code calls L1 and L2 driver API parts jointly "IEEE 802.15.4 radio API" which is misleading for the L2 portion. As future documentation policy it is therefore proposed to introduce the following nomenclature:

• Only the PHY part SHALL be called "IEEE 802.15.4 PHY/Radio API" (for the API) or "IEEE 802.15.4 PHY/Radio" (for the subsystem architecture block) from now on.
• The MAC offloading part SHALL be called "IEEE 802.15.4 MAC/L2 Offloading API" (for the API) or "IEEE 802.15.4 Hard MAC" (for the subsystem architecture block).
• Both parts together SHALL constitute the "IEEE 802.15.4 Driver API" (for the API) or "IEEE 802.15.4 Driver(s)" for the architecture block.

Detailed RFC

See the detailed discussion in a pull request that first introduced parts of the new architecture approach

Proposed change (Detailed)

Practical relevance and feasibility of these architectural patterns and policies was proven and exemplified by two recent PRs (1, 2) - among several others.

See the detailed discussion in a pull request that first introduced parts of the new architecture approach

Dependencies

I'm not aware of any dependencies other than [Open]Thread development and the IEEE 802.15.4 drivers and native L2 stack.

The change has, however, considerable positive impact on the general implementation effort and feasibility of future additions to the IEEE 802.15.4 subsystem.

Impact that can be proven rather objectively:

• The current API stands in the way of re-using existing standard primitives in non-CSL IEEE 802.15.4 protocols that require IEs (which are ALL recent IEEE 802.15.4 protocols). This can be fixed such that future additions will be roughly an order of magnitude less effort for IE-based protocols.
• The current API stands in the way of re-using existing standard security primitives in a vendor agnostic way (i.e. secure IEs, device-specific security, etc.). This can be fixed so that implementing such security features in additional drivers will be roughly an order of magnitude less effort.
• The current API makes sharing of some [Open]Thread features (like CSL or support of advanced security) across drivers unnecessarily hard because re-usable code is hidden inside the driver. This can be fixed such that providing support for these features by additional drivers is roughly an order of magnitude less effort.

Impact that represents my personal opinions:

• Lack of cross-vendor wireless protocol support (BLE and Thread) is a major hudle to entry into Zephyr for several users I've been talking to as a consultant. Implementing a much larger part of L2 in a cross-vendor "soft MAC" would considerably reduce the barrier to entry (see the strong cross-vendor adoption of the native stack as compared to OpenThread).
• The current situation creates an unnecessary incentive to circumvent a proper Zephyr OSS solution by plugging in proprietary binary blobs or source code. This is a poor replacement to a proper OSS architecture IMO. OpenThread is a specialized monolithic block of code that cannot serve as an example for proper OSS development in a protocol-neutral framework like Zephyr.
• I'm not proposing this RFC as a general "wireless APIs RFC" as I don't know enough about other wireless communication stacks in Zephyr but I suspect that BLE in Zepyhr is suffering from similar hurdles to entry.

Concerns and Unresolved Questions

• The effort to fix the technical debt specified/established in this RFC must not hinder ongoing Thread protocol development, otherwise we throw out the child with the bathwater. Zephyr is a "testbed" for the newest Thread standard which is great. I think we need an approach that causes marginal extra effort to ongoing development work. The easiest way to do this is to live with "alternative" approaches for some time (example: leave the monolithic CSL implementation as it is and build up an alternative IE and standards primitive API in parallel for future protocol extensions).
• Who is going to ensure mandatory reviews of the IEEE 802.15.4 driver API according to the above policies? The current IEEE 802.15.4 maintainer seems to be MIA. The network maintainer does his best to fill in the gap, but he has acknowledged conflict of interest on several occasions and according to his own assessment lacks sufficient knowledge of the IEEE 802.15.4 standard to properly enforce conformance with standard primitives.

Alternatives

I personally have none - please feel free to add in case I'm missing something.

[fgrandel]

@rlubos @jciupis @hubertmis We've been discussing the topic of this RFC on several occasions and I had promised to summarize my proposals and our discussion in one RFC. Here it is.

[fgrandel]

@carlescufi @rlubos I think it makes sense that you review and comment on this RFC before we discuss it in the architecture WG. It is probably too specialized to discuss it in detail with 20 people in the call. I had asked @nashif to postpone it in the arch wg until when you have a chance to participate. I think your wholehearted approval is vital - otherwise it doesn't make sense.

[rlubos]

Thanks @fgrandel for the comprehensive description of the idea.

As a high level feedback, I'm ok with separating concepts of PHY/offloaded MAC features into separate components of the 15.4 radio driver API. I think it could even be considered to move certain APIs/configurations introduced specifically for OpenThread into recently introduced OT extension header, so that they do not stand in a way of other 15.4 based protocols (although this should be discussed with OT contributors).

There are however a few items that in my ignorance, require some clarification.

Zephyr L2 code SHALL NOT call directly or indirectly into soft-MAC solutions that are exclusively provided by one vendor's driver. Such soft-MAC features SHALL be ported to vendor-agnostic (possibly but not necessarily protocol-agnostic) soft-MAC code re-usable by all drivers before being accepted into mainline. Zephyr SHALL only call into vendor-specific driver code that provably does hardware offloading for performance reasons. (Prominent examples: IE parser and certain security-related features in the nRF5 driver that run on the CPU and could be implemented in a vendor-agnostic way w/o loss of performance.)

Ok, but I'm not sure if nRF5 is a proper example here. The driver is intended (on newer SoCs) to run on a separate NET core, not the CPU where L2/soft-MAC implementation would be executed. Therefore, for me, I'm not convinced that the driver contents should be considered as a soft-MAC solution that could be implemented in a "vendor-agnostic way w/o loss of performance".

The current API stands fundamentally in the way of all non-CSL IEEE 802.15.4 protocols that require IEs (which are ALL recent IEEE 802.15.4 protocols). This can be fixed such that future additions will be roughly an order of magnitude less effort for IE-based protocols.

The current API stands fundamentally in the way of implementing an upper-layer agnostic version of recent standard security features (i.e. secure IEs, device-specific security, etc.). This can be fixed so that implementing such security features in additional drivers will be roughly an order of magnitude less effort.

By "stands fundamentally in the way" I understand there are some major blockers preventing other L2 implementations. I think it'd make sense to list the blockers, and decide one by one on how to proceed (either fix, in a way we don't break OT support, or make a particular config/api introduced for the sake of OT, OT specific).

The current API makes support of [Open]Thread by other drivers unnecessarily hard. This can be fixed such that providing basic Thread protocol support by additional drivers is roughly an order of magnitude less effort.

Is "basic Thread protocol support" really that hard to achieve? I think we should settle on what "basic" means, but all of the advanced MAC features (CSL, IE support for Link Metrics , TX security) are either optional (need to be explicitly enabled) or have a soft-MAC variant in OT itself (like TX security).

[fgrandel]

@rlubos Thanks for your review! :-)

Ok, but I'm not sure if nRF5 is a proper example here. The driver is intended (on newer SoCs) to run on a separate NET core, not the CPU where L2/soft-MAC implementation would be executed.

Code that is always running on a dedicated (non-Zephyr) NET core is by definition offloaded code. Such code is not covered by this clause and most of the time cannot be ported anyway. CC13/26xx's radio core for example only accepts proprietary "blobs".

If, however, code may optionally run as part of Zepyhr-scheduled threads or ISRs, then it can be pulled into a shared "Soft MAC" w/o any loss of performance: Calls into the proprietary driver can be replaced by equivalent "inversion of control" calls into a shared L2 - no matter on which core it runs. Whether this is "fast enough" on a single core is not an L2 architecture choice but a decision to be taken by individual driver maintainers.

AFAICS the nRF5 driver contains code that (at least optionally) runs in Zephyr-scheduled threads or ISRs. The driver has a dedicated "mac_features" folder mostly implementing standard L2 primitives plus implements further standard L1/L2 primitives sprinkled throughout the rest of the code. Such code would be covered by this RFC.

This doesn't mean that I'm proposing to migrate existing code (see "Concerns and Unresolved Questions"). I'm just proposing that future PRs SHALL NOT introduce further such code and that existing code MAY be ported into shared L2 by whoever finds it worth the time.

By "stands fundamentally in the way" I understand there are some major blockers preventing other L2 implementations. I think it'd make sense to list the blockers

No, nothing blocks alternative L2 implementations and you're right that the way I wrote it was ambivalent (hopefully fixed). Alternative implementations are just unnecessarily hard as the Zephyr-runnable code I mention above has not been pulled into granular re-usable primitives as prescribed by the standard.

By "fixing this situation" I mean that alternative re-usable implementations of these standard primitives should be provided rather than trying to migrate existing code, see "Concerns and Unresolved Questions". I would only "repair" existing code when it's actually less effort. Once such an alternative exists, existing drivers may or may not choose to migrate to the community-maintained re-usable version.

I think it'd make sense to list the blockers

The individual features that cannot be re-used have been listed in the linked discussion thread.

make a particular config/api introduced for the sake of OT, OT specific

Which OT-specific features are you speaking about?

IMO the latest OT stack is exclusively based on plain IEEE 802.15.4 with some additional refinements inside the limits of the standard. The only non-standard OT feature I'm aware of is multi-CCA which we already pulled into its own namespace. All features required to support Thread 1.3.1 (not only OT) fall into the categories covered by this RFC. By the rules of this RFC it would therefore be wrong to place anything of this in an OT-specific API.

Is "basic Thread protocol support" really that hard to achieve? I think we should settle on what "basic" means, but all of the advanced MAC features (CSL, IE support for Link Metrics , TX security) are either optional (need to be explicitly enabled) or have a soft-MAC variant in OT itself (like TX security).

By "basic" I mean: "The most recent version of the standard with restrictions only in precise timing of ACKs" (but not CSL which can easily be scheduled in advance). I've updated the RFC text accordingly to be more precise.

Prior versions of the standard may be even easier to support, as you say. Could you or the OT team easily name the parts of the API to be implemented for the different Thread versions?

[rlubos]

Which OT-specific features are you speaking about?

I was referring to the configs that were introduced to address OT radio API requirements:

• IEEE802154_CONFIG_MAC_KEYS
• IEEE802154_CONFIG_FRAME_COUNTER
• IEEE802154_CONFIG_FRAME_COUNTER_IF_LARGER
• IEEE802154_CONFIG_RX_SLOT
• IEEE802154_CONFIG_CSL_PERIOD
• IEEE802154_CONFIG_CSL_RX_TIME
• IEEE802154_CONFIG_ENH_ACK_HEADER_IE

I understand they cover standard 802.15.4 features, although from the RFC I also understood that in their current form they're difficult to reuse in other upper-layer implementations. Therefore, as part of the "alternative" solutions approach you suggested:

The easiest way to do this is to live with "alternative" approaches for some time (example: leave the monolithic CSL implementation as it is and build up an alternative IE and standards primitive API in parallel for future protocol extensions).

they could be moved to OT namespace and possibly deprecated in the future if possible.

Could you or the OT team easily name the parts of the API to be implemented for the different Thread versions?

I can think of improving documentation in this area.

[fgrandel]

I was referring to the configs that were introduced to address OT radio API requirements:

@rlubos Yeah, we have the same features in mind, except for RX slots. RX slots are already re-usable and do not need any further refactoring beyond what we've already done.

We agree that these are all standard features. The fact that we've been thinking of them as "Thread requirements" is the problem I'm trying to address. IMO we should stop relating anything in L1/L2 specifically to [Open]Thread or a vendor's offloading choices unless it is really specific to that protocol stack or SoC.

This has nothing to do with offloading as such. It just means that both, soft MAC and offloading APIs that implement standard features, SHALL NOT be tied in any way to upper layers or to a specific vendor's SoC.

they could be moved to OT namespace and possibly deprecated in the future if possible.

I'm not in favor of moving standard-based features into an underspecified OT architecture block where they conceptually do not belong. This would just cement and "legitimize" the current status quo and provide an unwanted "safe haven" for it. IMO our limited resources should go into eliminating the problem rather than moving it. Therefore I'd deprecate non-reusable APIs in place if we cannot fix them.

Could you or the OT team easily name the parts of the API to be implemented for the different Thread versions?

I can think of improving documentation in this area.

Wow, that would be great. :-)

[fgrandel]

Closed as "accepted" by the Arch WG with no objections. As no further immediate action is implied by this RFC it can be considered "done".