Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2017 Nordic Semiconductor ASA
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : /** @file
       8             :  * @brief OpenThread L2 stack public header
       9             :  */
      10             : 
      11             : #ifndef ZEPHYR_INCLUDE_NET_OPENTHREAD_H_
      12             : #define ZEPHYR_INCLUDE_NET_OPENTHREAD_H_
      13             : 
      14             : /**
      15             :  * @brief OpenThread Layer 2 abstraction layer
      16             :  * @defgroup openthread OpenThread L2 abstraction layer
      17             :  * @since 1.11
      18             :  * @version 0.8.0
      19             :  * @ingroup ieee802154
      20             :  * @{
      21             :  */
      22             : 
      23             : #include <zephyr/kernel.h>
      24             : 
      25             : #include <zephyr/net/net_if.h>
      26             : 
      27             : #include <openthread/instance.h>
      28             : 
      29             : #ifdef __cplusplus
      30             : extern "C" {
      31             : #endif
      32             : 
      33             : /**
      34             :  * @cond INTERNAL_HIDDEN
      35             :  */
      36             : /**
      37             :  * @brief Type of pkt_list
      38             :  */
      39             : struct pkt_list_elem {
      40             :         struct net_pkt *pkt;
      41             : };
      42             : 
      43             : /**
      44             :  * @brief OpenThread l2 private data.
      45             :  */
      46             : struct openthread_context {
      47             :         /** Pointer to OpenThread stack instance */
      48             :         otInstance *instance;
      49             : 
      50             :         /** Pointer to OpenThread network interface */
      51             :         struct net_if *iface;
      52             : 
      53             :         /** Index indicates the head of pkt_list ring buffer */
      54             :         uint16_t pkt_list_in_idx;
      55             : 
      56             :         /** Index indicates the tail of pkt_list ring buffer */
      57             :         uint16_t pkt_list_out_idx;
      58             : 
      59             :         /** Flag indicates that pkt_list is full */
      60             :         uint8_t pkt_list_full;
      61             : 
      62             :         /** Array for storing net_pkt for OpenThread internal usage */
      63             :         struct pkt_list_elem pkt_list[CONFIG_OPENTHREAD_PKT_LIST_SIZE];
      64             : 
      65             :         /** A mutex to protect API calls from being preempted. */
      66             :         struct k_mutex api_lock;
      67             : 
      68             :         /** A work queue for all OpenThread activity */
      69             :         struct k_work_q work_q;
      70             : 
      71             :         /** Work object for OpenThread internal usage */
      72             :         struct k_work api_work;
      73             : 
      74             :         /** A list for state change callbacks */
      75             :         sys_slist_t state_change_cbs;
      76             : };
      77             : /**
      78             :  * INTERNAL_HIDDEN @endcond
      79             :  */
      80             : 
      81             : /** OpenThread state change callback  */
      82             : 
      83             : /**
      84             :  * @brief OpenThread state change callback structure
      85             :  *
      86             :  * Used to register a callback in the callback list. As many
      87             :  * callbacks as needed can be added as long as each of them
      88             :  * are unique pointers of struct openthread_state_changed_cb.
      89             :  * Beware such structure should not be allocated on stack.
      90             :  */
      91           1 : struct openthread_state_changed_cb {
      92             :         /**
      93             :          * @brief Callback for notifying configuration or state changes.
      94             :          *
      95             :          * @param flags as per OpenThread otStateChangedCallback() aFlags parameter.
      96             :          *        See https://openthread.io/reference/group/api-instance#otstatechangedcallback
      97             :          * @param ot_context the OpenThread context the callback is registered with.
      98             :          * @param user_data Data to pass to the callback.
      99             :          */
     100           1 :         void (*state_changed_cb)(otChangedFlags flags, struct openthread_context *ot_context,
     101             :                                  void *user_data);
     102             : 
     103             :         /** User data if required */
     104           1 :         void *user_data;
     105             : 
     106             :         /**
     107             :          * Internally used field for list handling
     108             :          *  - user must not directly modify
     109             :          */
     110           1 :         sys_snode_t node;
     111             : };
     112             : 
     113             : /**
     114             :  * @brief Registers callbacks which will be called when certain configuration
     115             :  * or state changes occur within OpenThread.
     116             :  *
     117             :  * @param ot_context the OpenThread context to register the callback with.
     118             :  * @param cb callback struct to register.
     119             :  */
     120           1 : int openthread_state_changed_cb_register(struct openthread_context *ot_context,
     121             :                                          struct openthread_state_changed_cb *cb);
     122             : 
     123             : /**
     124             :  * @brief Unregisters OpenThread configuration or state changed callbacks.
     125             :  *
     126             :  * @param ot_context the OpenThread context to unregister the callback from.
     127             :  * @param cb callback struct to unregister.
     128             :  */
     129           1 : int openthread_state_changed_cb_unregister(struct openthread_context *ot_context,
     130             :                                            struct openthread_state_changed_cb *cb);
     131             : 
     132             : /**
     133             :  * @brief Get OpenThread thread identification.
     134             :  */
     135           1 : k_tid_t openthread_thread_id_get(void);
     136             : 
     137             : /**
     138             :  * @brief Get pointer to default OpenThread context.
     139             :  *
     140             :  * @retval !NULL On success.
     141             :  * @retval NULL  On failure.
     142             :  */
     143           1 : struct openthread_context *openthread_get_default_context(void);
     144             : 
     145             : /**
     146             :  * @brief Get pointer to default OpenThread instance.
     147             :  *
     148             :  * @retval !NULL On success.
     149             :  * @retval NULL  On failure.
     150             :  */
     151           1 : struct otInstance *openthread_get_default_instance(void);
     152             : 
     153             : /**
     154             :  * @brief Starts the OpenThread network.
     155             :  *
     156             :  * @details Depends on active settings: it uses stored network configuration,
     157             :  * start joining procedure or uses default network configuration. Additionally
     158             :  * when the device is MTD, it sets the SED mode to properly attach the network.
     159             :  *
     160             :  * @param ot_context
     161             :  */
     162           1 : int openthread_start(struct openthread_context *ot_context);
     163             : 
     164             : /**
     165             :  * @brief Lock internal mutex before accessing OT API.
     166             :  *
     167             :  * @details OpenThread API is not thread-safe, therefore before accessing any
     168             :  * API function, it's needed to lock the internal mutex, to prevent the
     169             :  * OpenThread thread from preempting the API call.
     170             :  *
     171             :  * @param ot_context Context to lock.
     172             :  */
     173           1 : void openthread_api_mutex_lock(struct openthread_context *ot_context);
     174             : 
     175             : /**
     176             :  * @brief Try to lock internal mutex before accessing OT API.
     177             :  *
     178             :  * @details This function behaves like openthread_api_mutex_lock() provided that
     179             :  * the internal mutex is unlocked. Otherwise, it exists immediately and returns
     180             :  * a negative value.
     181             :  *
     182             :  * @param ot_context Context to lock.
     183             :  * @retval 0  On success.
     184             :  * @retval <0 On failure.
     185             :  */
     186           1 : int openthread_api_mutex_try_lock(struct openthread_context *ot_context);
     187             : 
     188             : /**
     189             :  * @brief Unlock internal mutex after accessing OT API.
     190             :  *
     191             :  * @param ot_context Context to unlock.
     192             :  */
     193           1 : void openthread_api_mutex_unlock(struct openthread_context *ot_context);
     194             : 
     195             : /** @cond INTERNAL_HIDDEN */
     196             : 
     197             : #define OPENTHREAD_L2_CTX_TYPE struct openthread_context
     198             : 
     199             : /** @endcond */
     200             : 
     201             : #ifdef __cplusplus
     202             : }
     203             : #endif
     204             : 
     205             : /**
     206             :  * @}
     207             :  */
     208             : 
     209             : #endif /* ZEPHYR_INCLUDE_NET_OPENTHREAD_H_ */