doc: openthread: integrate ot/ieee802154 docs

Integrates and cross-references OpenThread and native IEEE 802.15.4 docs
as they share a common driver layer.

While OpenThread is of course not an IEEE 802.15.4 subsystem API it is
still included in the ieee802154 documentation group, purely for
convenience to the documentation readers.

For organizational purposes OT is considered a separate area of
maintenance and therefore keeps its dedicated documentation page - but
the two subsystems now cross-reference each other for convenience.

Signed-off-by: Florian Grandel <[email protected]>

Author: fg-cfh

doc/connectivity/networking/api/ieee802154.rst

@@ -32,10 +32,10 @@ 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).
+Zephyr supports both, native IEEE 802.15.4 and Thread, with 6LoWPAN. Zephyr's
+:ref:`thread_protocol_interface` implementation is based on `OpenThread
+<https://openthread.io/>`_. The IPv6 header compression in 6LoWPAN is shared
+among native IEEE 802.15.4 and the Bluetooth IPSP (IP support profile).
 
 API Reference
 *************
@@ -85,3 +85,13 @@ 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
+
+OpenThread L2 Adaptation Layer API
+==================================
+
+Zephyr's OpenThread L2 platform adaptation layer glues the external OpenThread
+stack together with Zephyr's IEEE 802.15.4 protocol agnostic driver API. This
+API is of interest to OpenThread L2 **subsystem contributors** only.
+
+The OpenThread API is part of the :ref:`thread_protocol_interface` subsystem and
+documented there.

doc/connectivity/networking/api/thread.rst

@@ -40,3 +40,25 @@ which provide out-of-the-box configuration for OpenThread. To enable OpenThread
 support in these samples, build them with ``overlay-ot.conf`` overlay config file.
 See :zephyr:code-sample:`sockets-echo-server` and :zephyr:code-sample:`sockets-echo-client`
 samples for details.
+
+Thread related APIs
+*******************
+
+OpenThread Driver API
+========================
+
+OpenThread L2 uses Zephyr's protocol agnostic IEEE 802.15.4 driver API
+internally. This API is of interest to **driver developers** that want to
+support OpenThread.
+
+The driver API is part of the :ref:`ieee802154_driver_api` subsystem and
+documented there.
+
+OpenThread L2 Adaptation Layer API
+==================================
+
+Zephyr's OpenThread L2 platform adaptation layer glues the external OpenThread
+stack together with Zephyr's IEEE 802.15.4 protocol agnostic driver API. This
+API is of interest to OpenThread L2 **subsystem contributors** only.
+
+.. doxygengroup:: openthread

include/zephyr/net/ieee802154.h

@@ -23,19 +23,24 @@ extern "C" {
 #endif
 
 /**
- * @defgroup ieee802154 IEEE 802.15.4 APIs
+ * @defgroup ieee802154 IEEE 802.15.4 and Thread APIs
  * @ingroup connectivity
  *
- * @brief IEEE 802.15.4 L2, configuration and driver APIs
+ * @brief IEEE 802.15.4 native and OpenThread L2, configuration, management 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.).
+ * @details The IEEE 802.15.4 and Thread subsystems comprise the OpenThread L2
+ * subsystem, 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:
+ * The **OpenThread subsystem API** integrates the external <a
+ * href="https://openthread.io">OpenThread</a> stack into Zephyr. It builds upon
+ * Zephyr's native IEEE 802.15.4 driver API.
+ *
+ * The **native 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):
@@ -51,18 +56,20 @@ extern "C" {
  *    - 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),
+ *
+ *  - OpenThread and native IEEE 802.15.4 share a common **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
  */
 
 /**

include/zephyr/net/openthread.h

@@ -5,7 +5,7 @@
  */
 
 /** @file
- * @brief OpenThread l2 stack public header
+ * @brief OpenThread L2 stack public header
  */
 
 #ifndef ZEPHYR_INCLUDE_NET_OPENTHREAD_H_
@@ -14,7 +14,7 @@
 /**
  * @brief OpenThread Layer 2 abstraction layer
  * @defgroup openthread OpenThread L2 abstraction layer
- * @ingroup networking
+ * @ingroup ieee802154
  * @{
  */