doc: ieee802154: improved API documentation structure

fg-cfh · carlescufi · commit 80fc3508497f · 2023-09-28T15:13:12.000+02:00
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 &lt;fgrandel@code-for-humans.de&gt;
diff --git a/doc/connectivity/networking/api/ieee802154.rst b/doc/connectivity/networking/api/ieee802154.rst
@@ -7,30 +7,81 @@ IEEE 802.15.4
     :local:
     :depth: 2
 
-Overview
-********
+Introduction
+************
+
 IEEE 802.15.4 is a technical standard which defines the operation of low-rate
-wireless personal area networks (LR-WPANs). For more detailed overview of this
-standard, see this
-`IEEE 802.15.4 Wikipedia article <https://en.wikipedia.org/wiki/IEEE_802.15.4>`_.
-Also, see `IEEE GET Program
-<https://ieeexplore.ieee.org/browse/standards/get-program/page/series?id=68>`_
-for creating an IEEE account and downloading the specification.
-
-Zephyr supports IEEE 802.15.4 with Thread and 6LoWPAN. The Thread implementation
-is based on `OpenThread <https://openthread.io/>`_.
-The IPv6 header compression in 6LoWPAN is shared with
-the Bluetooth IPSP (IP support profile).
+wireless personal area networks (LR-WPANs). For a more detailed overview of this
+standard, see the `IEEE 802.15.4 Wikipedia article
+<https://en.wikipedia.org/wiki/IEEE_802.15.4>`_.
+
+The most recent version of the standard is accessible through the `IEEE GET
+Program
+<https://ieeexplore.ieee.org/browse/standards/get-program/page/series?id=68>`_.
+You need to create a free IEEE account and can then downloading it.
+
+We're currently following the IEEE 802.15.4-2020 specification. This version is
+backwards compatible with IEEE 802.15.4-2015, parts of which are contained in
+the Thread protocol stack. The 2020 version also includes prior extensions that
+were accepted into the standard, namely IEEE 802.15.4g (SUN FSK) and IEEE
+802.15.4e (TSCH) which are of relevance to industrial IoT and automation. For
+recent developments in UWB ranging technology, see IEEE 802.15.4z which is not
+yet integrated into the standard's mainline.
+
+Whenever sections from the standard are cited in the documentation, they refer
+to IEEE 802.15.4-2020 section, table and figure numbering - unless otherwise
+specified.
+
+Zephyr supports bot native IEEE 802.15.4 and Thread with 6LoWPAN. The Thread
+implementation is based on `OpenThread <https://openthread.io/>`_. The IPv6
+header compression in 6LoWPAN is shared among native IEEE 802.15.4, OpenThread
+and the Bluetooth IPSP (IP support profile).
 
 API Reference
 *************
 
-IEEE 802.15.4
-=============
+IEEE 802.15.4 API Overview
+==========================
+
+Gives an introduction and overview over the whole IEEE 802.15.4 subsystem and
+all of its APIs, configuration and user interfaces for all audiences.
 
 .. doxygengroup:: ieee802154
 
-IEEE 802.15.4 Management
-========================
+
+.. _ieee802154_mgmt_api:
+
+IEEE 802.15.4 Management API
+============================
+
+This is the main subsystem-specific API of interest to IEEE 802.15.4
+**application developers** as it allows to configure the IEEE 802.15.4 subsystem
+at runtime.  Other relevant interfaces for application developers are the
+typical shell, socket, Kconfig and devicetree APIs that can be accessed through
+Zephyr's generic subsystem-independent documentation. Look out for
+IEEE802154/ieee802154 prefixes there.
 
 .. doxygengroup:: ieee802154_mgmt
+
+
+.. _ieee802154_driver_api:
+
+IEEE 802.15.4 Driver API
+========================
+
+This is the main API of interest to IEEE 802.15.4 **driver developers**.
+
+.. doxygengroup:: ieee802154_driver
+
+
+.. _ieee802154_l2_api:
+
+IEEE 802.15.4 L2 / Native Stack API
+===================================
+
+This documents the IEEE 802.15.4 L2 native stack, which neither applications nor
+drivers will ever access directly. It is called internally by Zephyr's upper
+network layers (L3+), its socket and network context abstractions. This API is
+therefore of interest to IEEE 802.15.4 **subsystem contributors** only.
+
+.. doxygengroup:: ieee802154_l2
diff --git a/doc/develop/api/overview.rst b/doc/develop/api/overview.rst
@@ -169,6 +169,18 @@ between major releases are available in the :ref:`zephyr_release_notes`.
      - Experimental
      - 3.2
 
+   * - :ref:`ieee802154_driver_api`
+     - Unstable
+     - 1.0
+
+   * - :ref:`ieee802154_l2_api`
+     - Unstable
+     - 1.0
+
+   * - :ref:`ieee802154_mgmt_api`
+     - Unstable
+     - 1.0
+
    * - :ref:`input`
      - Experimental
      - 3.4
diff --git a/include/zephyr/net/ieee802154.h b/include/zephyr/net/ieee802154.h
@@ -23,9 +23,64 @@ extern "C" {
 #endif
 
 /**
- * @brief IEEE 802.15.4 library
- * @defgroup ieee802154 IEEE 802.15.4 Library
- * @ingroup networking
+ * @defgroup ieee802154 IEEE 802.15.4 APIs
+ * @ingroup connectivity
+ *
+ * @brief IEEE 802.15.4 L2, configuration and driver APIs
+ *
+ * @details The IEEE 802.15.4 subsystem API comprises the native IEEE 802.15.4
+ * L2 subsystem ("Soft" MAC), a mostly vendor and protocol agnostic driver API
+ * shared between the OpenThread and native L2 stacks ("Hard" MAC and PHY) as
+ * well as several APIs to configure the subsystem (shell, net management,
+ * Kconfig, devicetree, etc.).
+ *
+ * The IEEE 802.15.4 subsystem APIs are exposed at different levels and address
+ * several audiences:
+ *  - shell (end users, application developers):
+ *    - a set of IEEE 802.15.4 shell commands (see `shell> ieee802154 help`)
+ *  - application API (application developers):
+ *    - IPv6, DGRAM and RAW sockets for actual peer-to-peer, multicast and
+ *      broadcast data exchange between nodes including connection specific
+ *      configuration (sample coming soon, see
+ *      https://github.com/linux-wpan/wpan-tools/tree/master/examples for now
+ *      which inspired our API and therefore has a similar socket API),
+ *    - Kconfig and devicetree configuration options (net config library
+ *      extension, subsystem-wide MAC and PHY Kconfig/DT options, driver/vendor
+ *      specific Kconfig/DT options, watch out for options prefixed with
+ *      IEEE802154/ieee802154),
+ *    - Network Management: runtime configuration of the IEEE 802.15.4
+ *      protocols stack at the MAC (L2) and PHY (L1) levels
+ *      (see @ref ieee802154_mgmt),
+ *  - driver API (driver maintainers/contributors):
+ *    - see @ref ieee802154_driver
+ *    - a basic, mostly PHY-level driver API to be implemented by all drivers,
+ *    - several "hard MAC" (hardware/firmware offloading) extension points for
+ *      performance critical or timing sensitive aspects of the protocol
+ *  - L2 integration (subsystem contributors):
+ *    - see @ref ieee802154_l2
+ *    - implementation of Zephyr's internal L2-level socket and network context
+ *      abstractions (context/socket operations, see @ref net_l2),
+ *    - protocol-specific extension to the interface structure (see @ref net_if)
+ *    - protocol-specific extensions to the network packet structure
+ *      (see @ref net_pkt),
+ */
+
+/**
+ * @defgroup ieee802154_l2 IEEE 802.15.4 L2
+ * @ingroup ieee802154
+ *
+ * @brief IEEE 802.15.4 L2 APIs
+ *
+ * @details This API provides integration with Zephyr's sockets and network
+ * contexts. **Application and driver developers should never interface directly
+ * with this API.** It is of interest to subsystem maintainers only.
+ *
+ * The API implements and extends the following structures:
+ *    - implements Zephyr's internal L2-level socket and network context
+ *      abstractions (context/socket operations, see @ref net_l2),
+ *    - protocol-specific extension to the interface structure (see @ref net_if)
+ *    - protocol-specific extensions to the network packet structure
+ *      (see @ref net_pkt),
  * @{
  */
 
diff --git a/include/zephyr/net/ieee802154_mgmt.h b/include/zephyr/net/ieee802154_mgmt.h
@@ -22,9 +22,17 @@ extern "C" {
 #endif
 
 /**
+ * @defgroup ieee802154_mgmt IEEE 802.15.4 Net Management
+ * @ingroup ieee802154
+ *
  * @brief IEEE 802.15.4 net management library
- * @defgroup ieee802154_mgmt IEEE 802.15.4 Net Management Library
- * @ingroup networking
+ *
+ * @details The IEEE 802.15.4 net management library provides runtime
+ * configuration features that applications can interface with directly.
+ *
+ * Most of these commands are also accessible via shell commands. See the
+ * shell's help feature (`shell> ieee802154 help`).
+ *
  * @{
  */
 
diff --git a/include/zephyr/net/ieee802154_radio.h b/include/zephyr/net/ieee802154_radio.h
@@ -27,7 +27,33 @@ extern "C" {
 #endif
 
 /**
- * @addtogroup ieee802154
+ * @defgroup ieee802154_driver IEEE 802.15.4 Drivers
+ * @ingroup ieee802154
+ *
+ * @brief IEEE 802.15.4 driver API
+ *
+ * @details This API provides a common representation of vendor-specific
+ * hardware and firmware to the native IEEE 802.15.4 L2 and OpenThread stacks.
+ * **Application developers should never interface directly with this API.** It
+ * is of interest to driver maintainers only.
+ *
+ * The IEEE 802.15.4 driver API consists of two separate parts:
+ *    - a basic, mostly PHY-level driver API to be implemented by all drivers,
+ *    - several optional MAC-level extension points to offload performance
+ *      critical or timing sensitive aspects at MAC level to the driver hardware
+ *      or firmware ("hard" MAC).
+ *
+ * Implementing the basic driver API will ensure integration with the native L2
+ * stack as well as basic support for OpenThread. Depending on the hardware,
+ * offloading to vendor-specific hardware or firmware features may be required
+ * to achieve full compliance with the Thread protocol or IEEE 802.15.4
+ * subprotocols (e.g. fast enough ACK packages, precise timing of timed TX/RX in
+ * the TSCH or CSL subprotocols).
+ *
+ * Whether or not MAC-level offloading extension points need to be implemented
+ * is to be decided by individual driver maintainers. Upper layers SHOULD
+ * provide a "soft" MAC fallback whenever possible.
+ *
  * @{
  */
 
