Openthread separate L2 configs

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()

modules/openthread/Kconfig

@@ -17,6 +17,22 @@ config OPENTHREAD
 
 if OPENTHREAD
 
+config OPENTHREAD_SYS_INIT
+	bool "Initialize OpenThread stack during system initialization"
+	default y
+	depends on !NET_L2_OPENTHREAD
+	help
+	  This option initializes the OpenThread automatically by calling the openthread_init()
+	  function during system initialization.
+
+config OPENTHREAD_SYS_INIT_PRIORITY
+	int "OpenThread system initialization priority"
+	default 40
+	depends on OPENTHREAD_SYS_INIT
+	help
+	  This option sets the priority of the OpenThread system initialization.
+
+
 choice OPENTHREAD_IMPLEMENTATION
 	prompt "OpenThread origin selection"
 	help