LCOV - code coverage report
Current view: top level - zephyr/net - conn_mgr_connectivity_impl.h Coverage Total Hit
Test: new.info Lines: 100.0 % 24 24
Test Date: 2025-09-05 22:20:39

            Line data    Source code
       1            1 : /*
       2              :  * Copyright (c) 2023 Nordic Semiconductor ASA
       3              :  *
       4              :  * SPDX-License-Identifier: Apache-2.0
       5              :  */
       6              : 
       7              : /**
       8              :  * @file
       9              :  * @brief API for defining conn_mgr connectivity implementations (allowing ifaces to be used with
      10              :  * conn_mgr_connectivity).
      11              :  */
      12              : 
      13              : #ifndef ZEPHYR_INCLUDE_CONN_MGR_CONNECTIVITY_IMPL_H_
      14              : #define ZEPHYR_INCLUDE_CONN_MGR_CONNECTIVITY_IMPL_H_
      15              : 
      16              : #include <zephyr/device.h>
      17              : #include <zephyr/net/net_if.h>
      18              : #include <zephyr/sys/iterable_sections.h>
      19              : #include <zephyr/net/net_mgmt.h>
      20              : #include <zephyr/net/conn_mgr_connectivity.h>
      21              : 
      22              : #ifdef __cplusplus
      23              : extern "C" {
      24              : #endif
      25              : 
      26              : /**
      27              :  * @brief Connection Manager Connectivity Implementation API
      28              :  * @defgroup conn_mgr_connectivity_impl Connection Manager Connectivity Implementation API
      29              :  * @since 3.4
      30              :  * @version 0.8.0
      31              :  * @ingroup conn_mgr_connectivity
      32              :  * @{
      33              :  */
      34              : 
      35              : /* Forward declaration */
      36              : struct conn_mgr_conn_binding;
      37              : 
      38              : /**
      39              :  * @brief Connectivity Manager Connectivity API structure
      40              :  *
      41              :  * Used to provide generic access to network association parameters and procedures
      42              :  */
      43            1 : struct conn_mgr_conn_api {
      44              :         /**
      45              :          * @brief When called, the connectivity implementation should start attempting to
      46              :          * establish connectivity (association with a network) for the bound iface pointed
      47              :          * to by if_conn->iface.
      48              :          *
      49              :          * Must be non-blocking.
      50              :          *
      51              :          * Called by @ref conn_mgr_if_connect.
      52              :          */
      53            1 :         int (*connect)(struct conn_mgr_conn_binding *const binding);
      54              : 
      55              :         /**
      56              :          * @brief When called, the connectivity implementation should disconnect (disassociate), or
      57              :          * stop any in-progress attempts to associate to a network, the bound iface pointed to by
      58              :          * if_conn->iface.
      59              :          *
      60              :          * Called by @ref conn_mgr_if_disconnect.
      61              :          */
      62            1 :         int (*disconnect)(struct conn_mgr_conn_binding *const binding);
      63              : 
      64              :         /**
      65              :          * @brief Called once for each iface that has been bound to a connectivity implementation
      66              :          * using this API.
      67              :          *
      68              :          * Connectivity implementations should use this callback to perform any required
      69              :          * per-bound-iface initialization.
      70              :          *
      71              :          * Implementations may choose to gracefully handle invalid buffer lengths with partial
      72              :          * writes, rather than raise errors, if deemed appropriate.
      73              :          */
      74            1 :         void (*init)(struct conn_mgr_conn_binding *const binding);
      75              : 
      76              :         /**
      77              :          * @brief Implementation callback for conn_mgr_if_set_opt.
      78              :          *
      79              :          * Used to set implementation-specific connectivity settings.
      80              :          *
      81              :          * Calls to conn_mgr_if_set_opt on an iface will result in calls to this callback with
      82              :          * the conn_mgr_conn_binding struct bound to that iface.
      83              :          *
      84              :          * It is up to the connectivity implementation to interpret optname. Options can be
      85              :          * specific to the bound iface (pointed to by if_conn->iface), or can apply to the whole
      86              :          * connectivity implementation.
      87              :          *
      88              :          * See the description of conn_mgr_if_set_opt for more details.
      89              :          * set_opt implementations should conform to that description.
      90              :          *
      91              :          * Implementations may choose to gracefully handle invalid buffer lengths with partial
      92              :          * reads, rather than raise errors, if deemed appropriate.
      93              :          */
      94            1 :         int (*set_opt)(struct conn_mgr_conn_binding *const binding,
      95              :                        int optname, const void *optval, size_t optlen);
      96              : 
      97              :         /**
      98              :          * @brief Implementation callback for conn_mgr_if_get_opt.
      99              :          *
     100              :          * Used to retrieve implementation-specific connectivity settings.
     101              :          *
     102              :          * Calls to conn_mgr_if_get_opt on an iface will result in calls to this callback with
     103              :          * the conn_mgr_conn_binding struct bound to that iface.
     104              :          *
     105              :          * It is up to the connectivity implementation to interpret optname. Options can be
     106              :          * specific to the bound iface (pointed to by if_conn->iface), or can apply to the whole
     107              :          * connectivity implementation.
     108              :          *
     109              :          * See the description of conn_mgr_if_get_opt for more details.
     110              :          * get_opt implementations should conform to that description.
     111              :          */
     112            1 :         int (*get_opt)(struct conn_mgr_conn_binding *const binding,
     113              :                        int optname, void *optval, size_t *optlen);
     114              : };
     115              : 
     116              : /** @cond INTERNAL_HIDDEN */
     117              : #define CONN_MGR_CONN_IMPL_GET_NAME(conn_id)            __conn_mgr_conn_##conn_id
     118              : #define CONN_MGR_CONN_IMPL_GET_CTX_TYPE(conn_id)        conn_id##_CTX_TYPE
     119              : /** @endcond */
     120              : 
     121              : /**
     122              :  * @brief Connectivity Implementation struct
     123              :  *
     124              :  * Declares a conn_mgr connectivity layer implementation with the provided API
     125              :  */
     126            1 : struct conn_mgr_conn_impl {
     127              :         /** The connectivity API used by the implementation */
     128            1 :         struct conn_mgr_conn_api *api;
     129              : };
     130              : 
     131              : /**
     132              :  * @brief Define a conn_mgr connectivity implementation that can be bound to network devices.
     133              :  *
     134              :  * @param conn_id The name of the new connectivity implementation
     135              :  * @param conn_api A pointer to a conn_mgr_conn_api struct
     136              :  */
     137            1 : #define CONN_MGR_CONN_DEFINE(conn_id, conn_api)                                         \
     138              :         const struct conn_mgr_conn_impl CONN_MGR_CONN_IMPL_GET_NAME(conn_id) = {        \
     139              :                 .api = conn_api,                                                        \
     140              :         };
     141              : 
     142              : /**
     143              :  * @brief Helper macro to make a conn_mgr connectivity implementation publicly available.
     144              :  */
     145            1 : #define CONN_MGR_CONN_DECLARE_PUBLIC(conn_id)                                           \
     146              :         extern const struct conn_mgr_conn_impl CONN_MGR_CONN_IMPL_GET_NAME(conn_id)
     147              : 
     148              : /** @cond INTERNAL_HIDDEN */
     149              : #define CONN_MGR_CONN_BINDING_GET_NAME(dev_id, sfx)     __conn_mgr_bndg_##dev_id##_##sfx
     150              : #define CONN_MGR_CONN_BINDING_GET_DATA(dev_id, sfx)     __conn_mgr_bndg_data_##dev_id##_##sfx
     151              : #define CONN_MGR_CONN_BINDING_GET_MUTEX(dev_id, sfx)    __conn_mgr_bndg_mutex_##dev_id##_##sfx
     152              : /** @endcond */
     153              : 
     154              : /**
     155              :  * @brief Connectivity Manager network interface binding structure
     156              :  *
     157              :  * Binds a conn_mgr connectivity implementation to an iface / network device.
     158              :  * Stores per-iface state for the connectivity implementation.
     159              :  */
     160            1 : struct conn_mgr_conn_binding {
     161              :         /** The network interface the connectivity implementation is bound to */
     162            1 :         struct net_if *iface;
     163              : 
     164              :         /** The connectivity implementation the network device is bound to */
     165            1 :         const struct conn_mgr_conn_impl *impl;
     166              : 
     167              :         /** Pointer to private, per-iface connectivity context */
     168            1 :         void *ctx;
     169              : 
     170              :         /**
     171              :          * @name Generic connectivity state
     172              :          * @{
     173              :          */
     174              : 
     175              :         /**
     176              :          * Connectivity flags
     177              :          *
     178              :          * Public boolean state and configuration values supported by all bindings.
     179              :          * See conn_mgr_if_flag for options.
     180              :          */
     181            1 :         uint32_t flags;
     182              : 
     183              :         /**
     184              :          * Timeout (seconds)
     185              :          *
     186              :          * Indicates to the connectivity implementation how long it should attempt to
     187              :          * establish connectivity for during a connection attempt before giving up.
     188              :          *
     189              :          * The connectivity implementation should give up on establishing connectivity after this
     190              :          * timeout, even if persistence is enabled.
     191              :          *
     192              :          * Set to @ref CONN_MGR_IF_NO_TIMEOUT to indicate that no timeout should be used.
     193              :          */
     194            1 :         int timeout;
     195              : 
     196              :         /** @} */
     197              : 
     198              : /** @cond INTERNAL_HIDDEN */
     199              :         /* Internal-use mutex for protecting access to the binding and API functions. */
     200              :         struct k_mutex *mutex;
     201              : /** @endcond */
     202              : };
     203              : 
     204              : /**
     205              :  * @brief Associate a connectivity implementation with an existing network device instance
     206              :  *
     207              :  * @param dev_id Network device id.
     208              :  * @param inst Network device instance.
     209              :  * @param conn_id Name of the connectivity implementation to associate.
     210              :  */
     211            1 : #define CONN_MGR_BIND_CONN_INST(dev_id, inst, conn_id)                                          \
     212              :         K_MUTEX_DEFINE(CONN_MGR_CONN_BINDING_GET_MUTEX(dev_id, inst));                          \
     213              :         static CONN_MGR_CONN_IMPL_GET_CTX_TYPE(conn_id)                                         \
     214              :                                         CONN_MGR_CONN_BINDING_GET_DATA(dev_id, inst);           \
     215              :         static STRUCT_SECTION_ITERABLE(conn_mgr_conn_binding,                                   \
     216              :                                         CONN_MGR_CONN_BINDING_GET_NAME(dev_id, inst)) = {       \
     217              :                 .iface = NET_IF_GET(dev_id, inst),                                              \
     218              :                 .impl = &(CONN_MGR_CONN_IMPL_GET_NAME(conn_id)),                            \
     219              :                 .ctx = &(CONN_MGR_CONN_BINDING_GET_DATA(dev_id, inst)),                             \
     220              :                 .mutex = &(CONN_MGR_CONN_BINDING_GET_MUTEX(dev_id, inst))                   \
     221              :         };
     222              : 
     223              : /**
     224              :  * @brief Associate a connectivity implementation with an existing network device
     225              :  *
     226              :  * @param dev_id Network device id.
     227              :  * @param conn_id Name of the connectivity implementation to associate.
     228              :  */
     229            1 : #define CONN_MGR_BIND_CONN(dev_id, conn_id)             \
     230              :         CONN_MGR_BIND_CONN_INST(dev_id, 0, conn_id)
     231              : 
     232              : /**
     233              :  * @brief Retrieves the conn_mgr binding struct for a provided iface if it exists.
     234              :  *
     235              :  * Bindings for connectivity implementations with missing API structs are ignored.
     236              :  *
     237              :  * For use only by connectivity implementations.
     238              :  *
     239              :  * @param iface - bound network interface to obtain the binding struct for.
     240              :  * @return struct conn_mgr_conn_binding* Pointer to the retrieved binding struct if it exists,
     241              :  *         NULL otherwise.
     242              :  */
     243            1 : static inline struct conn_mgr_conn_binding *conn_mgr_if_get_binding(struct net_if *iface)
     244              : {
     245              :         STRUCT_SECTION_FOREACH(conn_mgr_conn_binding, binding) {
     246              :                 if (iface == binding->iface) {
     247              :                         if (binding->impl->api) {
     248              :                                 return binding;
     249              :                         }
     250              :                         return NULL;
     251              :                 }
     252              :         }
     253              :         return NULL;
     254              : }
     255              : 
     256              : /**
     257              :  * @brief Lock the passed-in binding, making it safe to access.
     258              :  *
     259              :  * Call this whenever accessing binding data, unless inside a conn_mgr_conn_api callback, where it
     260              :  * is called automatically by conn_mgr.
     261              :  *
     262              :  * Reentrant.
     263              :  *
     264              :  * For use only by connectivity implementations.
     265              :  *
     266              :  * @param binding - Binding to lock
     267              :  */
     268            1 : static inline void conn_mgr_binding_lock(struct conn_mgr_conn_binding *binding)
     269              : {
     270              :         (void)k_mutex_lock(binding->mutex, K_FOREVER);
     271              : }
     272              : 
     273              : /**
     274              :  * @brief Unlocks the passed-in binding.
     275              :  *
     276              :  * Call this after any call to @ref conn_mgr_binding_lock once done accessing binding data.
     277              :  *
     278              :  * Reentrant.
     279              :  *
     280              :  * For use only by connectivity implementations.
     281              :  *
     282              :  * @param binding - Binding to unlock
     283              :  */
     284            1 : static inline void conn_mgr_binding_unlock(struct conn_mgr_conn_binding *binding)
     285              : {
     286              :         (void)k_mutex_unlock(binding->mutex);
     287              : }
     288              : 
     289              : /**
     290              :  * @brief Set the value of the specified connectivity flag for the provided binding
     291              :  *
     292              :  * Can be used from any thread or callback without calling @ref conn_mgr_binding_lock.
     293              :  *
     294              :  * For use only by connectivity implementations
     295              :  *
     296              :  * @param binding The binding to check
     297              :  * @param flag The flag to check
     298              :  * @param value New value for the specified flag
     299              :  */
     300            1 : static inline void conn_mgr_binding_set_flag(struct conn_mgr_conn_binding *binding,
     301              :                                              enum conn_mgr_if_flag flag, bool value)
     302              : {
     303              :         conn_mgr_binding_lock(binding);
     304              : 
     305              :         binding->flags &= ~BIT(flag);
     306              :         if (value) {
     307              :                 binding->flags |= BIT(flag);
     308              :         }
     309              : 
     310              :         conn_mgr_binding_unlock(binding);
     311              : }
     312              : 
     313              : /**
     314              :  * @brief Check the value of the specified connectivity flag for the provided binding
     315              :  *
     316              :  * Can be used from any thread or callback without calling @ref conn_mgr_binding_lock.
     317              :  *
     318              :  * For use only by connectivity implementations
     319              :  *
     320              :  * @param binding The binding to check
     321              :  * @param flag The flag to check
     322              :  * @return bool The value of the specified flag
     323              :  */
     324            1 : static inline bool conn_mgr_binding_get_flag(struct conn_mgr_conn_binding *binding,
     325              :                                              enum conn_mgr_if_flag flag)
     326              : {
     327              :         bool value = false;
     328              : 
     329              :         conn_mgr_binding_lock(binding);
     330              : 
     331              :         value = !!(binding->flags & BIT(flag));
     332              : 
     333              :         conn_mgr_binding_unlock(binding);
     334              : 
     335              :         return value;
     336              : }
     337              : 
     338              : /**
     339              :  * @}
     340              :  */
     341              : 
     342              : #ifdef __cplusplus
     343              : }
     344              : #endif
     345              : 
     346              : #endif /* ZEPHYR_INCLUDE_CONN_MGR_CONNECTIVITY_IMPL_H_ */
        

Generated by: LCOV version 2.0-1