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 layer
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.

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

Author: ArekBalysNordic

include/zephyr/net/openthread.h

@@ -21,10 +21,11 @@
  */
 
 #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 outside anymore.
+	 */
+	__deprecated otInstance *instance;
 
 	/** Pointer to OpenThread network interface */
 	struct net_if *iface;
@@ -62,22 +65,40 @@ 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 outside 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 outside 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 outside 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 IPv4 (translated by NAT64) and IPv6 datagrams.
+ *
+ * This callback is called when a datagram is received.
+ *
+ * @param aMessage The message to receive.
+ * @param aContext The context to pass to the callback.
+ */
+typedef void (*openthread_receive_cb)(otMessage *aMessage, void *aContext);
+
 /** OpenThread state change callback  */
 
 /**
@@ -88,6 +109,38 @@ struct openthread_context {
  * are unique pointers of struct openthread_state_changed_cb.
  * Beware such structure should not be allocated on stack.
  */
+struct openthread_state_changed_callback {
+	/**
+	 * @brief Callback for notifying configuration or state changes.
+	 *
+	 * @param flags as per OpenThread otStateChangedCallback() aFlags parameter.
+	 *        See https://openthread.io/reference/group/api-instance#otstatechangedcallback
+	 * @param instance the OpenThread instance the callback is registered with.
+	 * @param user_data Data to pass to the callback.
+	 */
+	void (*openthread_state_changed_cb)(otChangedFlags flags, struct otInstance *instance,
+					    void *user_data);
+
+	/** 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
+ * callbacks as needed can be added as long as each of them
+ * are unique pointers of struct openthread_state_changed_cb.
+ * Beware such structure should not be allocated on stack.
+ */
 struct openthread_state_changed_cb {
 	/**
 	 * @brief Callback for notifying configuration or state changes.
@@ -111,23 +164,44 @@ struct openthread_state_changed_cb {
 };
 
 /**
+ * @brief Registers callbacks which will be called when certain configuration
+ * or state changes occur within OpenThread.
+ *
+ * @param cb callback struct to register.
+ */
+int openthread_state_change_callback_register(struct openthread_state_changed_callback *cb);
+
+/**
+ * @brief Unregisters OpenThread configuration or state changed callbacks.
+ *
+ * @param cb callback struct to unregister.
+ */
+int openthread_state_change_callback_unregister(struct openthread_state_changed_callback *cb);
+
+/**
+ * @deprecated use @ref openthread_platform_state_changed_cb_register from modules/openthread
+ * 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_platform_state_changed_cb_unregister from modules/openthread
+ * 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 +225,46 @@ 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.
+ * - Initializes the state change callback list.
+ *
+ * @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 and then call openthread_run() to prepare and run
+ * the OpenThread network.
+ *
+ * @param rx_handler The receive callback for the OpenThread module.
+ * @param context The context to pass to the callback.
+ * @return true if initialization succeeded, false otherwise.
+ */
+bool openthread_init(openthread_receive_cb rx_handler, void *context);
+
+/**
+ * @brief Runs the OpenThread network.
+ *
+ * @details Prepares the OpenThread network and enables it.
+ * Depends on active settings: it uses stored network configuration,
+ * start joining procedure or uses default network configuration. Additionally
+ * when the device is MTD, it sets the SED mode to properly attach the network.
+ */
+int openthread_run(void);
+
+/**
+ * @brief Disables 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,7 +273,7 @@ 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 Lock internal mutex before accessing OT API.
@@ -170,9 +284,40 @@ int openthread_start(struct openthread_context *ot_context);
  *
  * @param ot_context Context to lock.
  */
-void openthread_api_mutex_lock(struct openthread_context *ot_context);
+void openthread_mutex_lock(void);
 
 /**
+ * @brief Try to lock internal mutex before accessing OT API.
+ *
+ * @details This function behaves like openthread_mutex_lock() provided that
+ * the internal mutex is unlocked. Otherwise, it exists immediately and returns
+ * a negative value.
+ */
+int openthread_mutex_try_lock(void);
+
+/**
+ * @brief Unlock internal mutex after accessing OT API.
+ *
+ * @param ot_context Context to unlock.
+ */
+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
+ * API function, it's needed to lock the internal mutex, to prevent the
+ * OpenThread thread from preempting the API call.
+ *
+ * @param ot_context Context to lock.
+ */
+__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 +328,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/platform/CMakeLists.txt

@@ -6,6 +6,7 @@ zephyr_library_sources(
   entropy.c
   misc.c
   platform.c
+  openthread.c
   )
 
 zephyr_library_sources_ifndef(CONFIG_HDLC_RCP_IF