[nrf fromlist] openthread: Move OpenThread implementation from net to modules

Move OpenThread-related code from
zephyr/subsys/net/l2/openthread/openthread.c to
zephyr/modules/openthread/platform/openthread.c.

The primary goal of this refactor is to enable the use
of OpenThread as an independent module, without the necessity
of Zephyr's networking layer.

This change is particularly beneficial for simple applications
that have their own implementation of the IEEE802.15.4 driver
and do not require a networking layer. These applications can
now disable Zephyr's L2 and IEEE802.15.4 shim layers and
directly use the OpenThread module, saving valuable kilobytes
of memory.

In this approach if the CONFIG_NET_L2_OPENTHREAD
Kconfig option is set, Zephyr's L2 and IEEE802.15.4 layers
will be used, and everything will function as before.
The main difference is the Zephyr's L2 layer now uses
the OpenThread module, no longer implementing it.

While most of the functions in include/net/openthread.h
have been deprecated, they are still available for use to
maintain backwards compatibility.

Upstream PR #: 89090

Signed-off-by: Arkadiusz Balys <[email protected]>

Author: ArekBalysNordic

include/zephyr/net/openthread.h

@@ -5,26 +5,27 @@
  */
 
 /** @file
- * @brief OpenThread L2 stack public header
+ * @brief OpenThread stack public header
  */
 
 #ifndef ZEPHYR_INCLUDE_NET_OPENTHREAD_H_
 #define ZEPHYR_INCLUDE_NET_OPENTHREAD_H_
 
 /**
- * @brief OpenThread Layer 2 abstraction layer
- * @defgroup openthread OpenThread L2 abstraction layer
+ * @brief OpenThread stack public header
+ * @defgroup openthread OpenThread stack
  * @since 1.11
  * @version 0.8.0
  * @ingroup ieee802154
  * @{
  */
 
 #include <zephyr/kernel.h>
-
 #include <zephyr/net/net_if.h>
+#include <zephyr/kernel/thread.h>
 
 #include <openthread/instance.h>
+#include <openthread/message.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -44,8 +45,10 @@ struct pkt_list_elem {
  * @brief OpenThread l2 private data.
  */
 struct openthread_context {
-	/** Pointer to OpenThread stack instance */
-	otInstance *instance;
+	/** @deprecated Pointer to OpenThread stack instance. This is deprecated and will be removed
+	 * in a future release. This field must not be used anymore.
+	 */
+	__deprecated otInstance *instance;
 
 	/** Pointer to OpenThread network interface */
 	struct net_if *iface;
@@ -62,25 +65,74 @@ struct openthread_context {
 	/** Array for storing net_pkt for OpenThread internal usage */
 	struct pkt_list_elem pkt_list[CONFIG_OPENTHREAD_PKT_LIST_SIZE];
 
-	/** A mutex to protect API calls from being preempted. */
-	struct k_mutex api_lock;
+	/** @deprecated A mutex to protect API calls from being preempted. This is deprecated and
+	 * will be removed in a future release. This field must not be used anymore.
+	 */
+	__deprecated struct k_mutex api_lock;
 
-	/** A work queue for all OpenThread activity */
-	struct k_work_q work_q;
+	/** @deprecated A work queue for all OpenThread activity. This is deprecated and will be
+	 * removed in a future release. This field must not be used anymore.
+	 */
+	__deprecated struct k_work_q work_q;
 
-	/** Work object for OpenThread internal usage */
-	struct k_work api_work;
+	/** @deprecated Work object for OpenThread internal usage. This is deprecated and will be
+	 * removed in a future release. This field must not be used anymore.
+	 */
+	__deprecated struct k_work api_work;
 
-	/** A list for state change callbacks */
+	/** @deprecated A list for state change callbacks. This is deprecated and will be removed in
+	 * a future release.
+	 */
 	sys_slist_t state_change_cbs;
 };
 /**
  * INTERNAL_HIDDEN @endcond
  */
 
+/**
+ * @brief The common callback type for receiving IPv4 (translated by NAT64) and IPv6 datagrams.
+ *
+ * This callback is called when a datagram is received.
+ *
+ * @param message The message to receive.
+ * @param context The context to pass to the callback.
+ */
+typedef void (*openthread_receive_cb)(otMessage *message, void *context);
+
 /** OpenThread state change callback  */
 
 /**
+ * @brief OpenThread state change callback structure
+ *
+ * Used to register a callback in the callback list. As many
+ * callbacks as needed can be added as long as each of them
+ * are unique pointers of struct openthread_state_changed_cb.
+ *
+ * @note You may destroy the object only after it is unregistered from the callback list.
+ */
+struct openthread_state_changed_callback {
+	/**
+	 * @brief Callback for notifying configuration or state changes.
+	 *
+	 * @param otCallback OpenThread callback to register.
+	 * See https://openthread.io/reference/group/api-instance#otstatechangedcallback for
+	 * details.
+	 */
+	otStateChangedCallback otCallback;
+
+	/** User data if required */
+	void *user_data;
+
+	/**
+	 * Internally used field for list handling
+	 *  - user must not directly modify
+	 */
+	sys_snode_t node;
+};
+
+/**
+ * @deprecated use @ref openthread_state_changed_callback instead.
+ *
  * @brief OpenThread state change callback structure
  *
  * Used to register a callback in the callback list. As many
@@ -111,23 +163,42 @@ struct openthread_state_changed_cb {
 };
 
 /**
+ * @brief Register callbacks that will be called when a certain configuration
+ * or state changes occur within OpenThread.
+ *
+ * @param cb Callback struct to register.
+ */
+int openthread_state_changed_callback_register(struct openthread_state_changed_callback *cb);
+
+/**
+ * @brief Unregister OpenThread configuration or state changed callbacks.
+ *
+ * @param cb Callback struct to unregister.
+ */
+int openthread_state_changed_callback_unregister(struct openthread_state_changed_callback *cb);
+
+/**
+ * @deprecated use @ref openthread_state_changed_callback_register instead.
+ *
  * @brief Registers callbacks which will be called when certain configuration
  * or state changes occur within OpenThread.
  *
  * @param ot_context the OpenThread context to register the callback with.
  * @param cb callback struct to register.
  */
-int openthread_state_changed_cb_register(struct openthread_context *ot_context,
-					 struct openthread_state_changed_cb *cb);
+__deprecated int openthread_state_changed_cb_register(struct openthread_context *ot_context,
+						      struct openthread_state_changed_cb *cb);
 
 /**
+ * @deprecated use @ref openthread_state_changed_callback_unregister instead.
+ *
  * @brief Unregisters OpenThread configuration or state changed callbacks.
  *
  * @param ot_context the OpenThread context to unregister the callback from.
  * @param cb callback struct to unregister.
  */
-int openthread_state_changed_cb_unregister(struct openthread_context *ot_context,
-					   struct openthread_state_changed_cb *cb);
+__deprecated int openthread_state_changed_cb_unregister(struct openthread_context *ot_context,
+							struct openthread_state_changed_cb *cb);
 
 /**
  * @brief Get OpenThread thread identification.
@@ -151,6 +222,44 @@ struct openthread_context *openthread_get_default_context(void);
 struct otInstance *openthread_get_default_instance(void);
 
 /**
+ * @brief Initialize the OpenThread module.
+ *
+ * This function:
+ * - Initializes the OpenThread module.
+ * - Creates an OpenThread single instance.
+ * - Starts the shell.
+ * - Enables the UART and NCP HDLC for coprocessor purposes.
+ * - Initializes the NAT64 translator.
+ * - Creates a work queue for the OpenThread module.
+ *
+ * @note This function is automatically called by Zephyr's networking layer.
+ * If you want to initialize the OpenThread independently, call this function
+ * in your application init code.
+ *
+ * @retval 0 On success.
+ * @retval -EIO On failure.
+ */
+int openthread_init(void);
+
+/**
+ * @brief Run the OpenThread network.
+ *
+ * @details Prepares the OpenThread network and enables it.
+ * Depends on active settings: it uses the stored network configuration,
+ * starts the joining procedure or uses the default network configuration.
+ * Additionally, when the device is MTD, it sets the SED mode to properly
+ * attach the network.
+ */
+int openthread_run(void);
+
+/**
+ * @brief Disable the OpenThread network.
+ */
+int openthread_stop(void);
+
+/**
+ * @deprecated use @ref openthread_run instead.
+ *
  * @brief Starts the OpenThread network.
  *
  * @details Depends on active settings: it uses stored network configuration,
@@ -159,9 +268,46 @@ struct otInstance *openthread_get_default_instance(void);
  *
  * @param ot_context
  */
-int openthread_start(struct openthread_context *ot_context);
+__deprecated int openthread_start(struct openthread_context *ot_context);
 
 /**
+ * @brief Set the additional callback for receiving packets.
+ *
+ * @details This callback is called once a packet is received and can be
+ * used to inject packets into the Zephyr networking stack.
+ * Setting this callback is optional.
+ *
+ * @param cb Callback to set.
+ * @param context Context to pass to the callback.
+ */
+void openthread_set_receive_cb(openthread_receive_cb cb, void *context);
+
+/**
+ * @brief Lock internal mutex before accessing OpenThread API.
+ *
+ * @details OpenThread API is not thread-safe. Therefore, before accessing any
+ * API function, you need to lock the internal mutex, to prevent the
+ * OpenThread thread from pre-empting the API call.
+ */
+void openthread_mutex_lock(void);
+
+/**
+ * @brief Try to lock internal mutex before accessing OpenThread API.
+ *
+ * @details This function behaves like openthread_mutex_lock(), provided that
+ * the internal mutex is unlocked. Otherwise, it returns a negative value without
+ * waiting.
+ */
+int openthread_mutex_try_lock(void);
+
+/**
+ * @brief Unlock internal mutex after accessing OpenThread API.
+ */
+void openthread_mutex_unlock(void);
+
+/**
+ * @deprecated use @ref openthread_mutex_lock.
+ *
  * @brief Lock internal mutex before accessing OT API.
  *
  * @details OpenThread API is not thread-safe, therefore before accessing any
@@ -170,9 +316,11 @@ int openthread_start(struct openthread_context *ot_context);
  *
  * @param ot_context Context to lock.
  */
-void openthread_api_mutex_lock(struct openthread_context *ot_context);
+__deprecated void openthread_api_mutex_lock(struct openthread_context *ot_context);
 
 /**
+ * @deprecated use @ref openthread_mutex_try_lock instead.
+ *
  * @brief Try to lock internal mutex before accessing OT API.
  *
  * @details This function behaves like openthread_api_mutex_lock() provided that
@@ -183,14 +331,16 @@ void openthread_api_mutex_lock(struct openthread_context *ot_context);
  * @retval 0  On success.
  * @retval <0 On failure.
  */
-int openthread_api_mutex_try_lock(struct openthread_context *ot_context);
+__deprecated int openthread_api_mutex_try_lock(struct openthread_context *ot_context);
 
 /**
+ * @deprecated use @ref openthread_mutex_unlock instead.
+ *
  * @brief Unlock internal mutex after accessing OT API.
  *
  * @param ot_context Context to unlock.
  */
-void openthread_api_mutex_unlock(struct openthread_context *ot_context);
+__deprecated void openthread_api_mutex_unlock(struct openthread_context *ot_context);
 
 /** @cond INTERNAL_HIDDEN */
 

modules/openthread/CMakeLists.txt

@@ -273,6 +273,13 @@ zephyr_link_libraries(${ot_libs})
 
 endif()
 
+# Create a library for the OpenThread Zephyr utils
+zephyr_library_named(openthread_utils)
+zephyr_library_sources(
+  openthread.c
+)
+zephyr_library_sources_ifdef(CONFIG_OPENTHREAD_SHELL shell.c)
+
 add_subdirectory(platform)
 
 endif()