LCOV - code coverage report
Current view: top level - zephyr/net - socket_service.h Hit Total Coverage
Test: new.info Lines: 18 18 100.0 %
Date: 2025-01-09 21:13:38

          Line data    Source code
       1           1 : /**
       2             :  * @file
       3             :  * @brief BSD Socket service API
       4             :  *
       5             :  * API can be used to install a k_work that is called
       6             :  * if there is data received to a socket.
       7             :  */
       8             : 
       9             : /*
      10             :  * Copyright (c) 2023 Nordic Semiconductor ASA
      11             :  *
      12             :  * SPDX-License-Identifier: Apache-2.0
      13             :  */
      14             : 
      15             : #ifndef ZEPHYR_INCLUDE_NET_SOCKET_SERVICE_H_
      16             : #define ZEPHYR_INCLUDE_NET_SOCKET_SERVICE_H_
      17             : 
      18             : /**
      19             :  * @brief BSD socket service API
      20             :  * @defgroup bsd_socket_service BSD socket service API
      21             :  * @since 3.6
      22             :  * @version 0.2.0
      23             :  * @ingroup networking
      24             :  * @{
      25             :  */
      26             : 
      27             : #include <sys/types.h>
      28             : #include <zephyr/types.h>
      29             : #include <zephyr/net/socket.h>
      30             : 
      31             : #ifdef __cplusplus
      32             : extern "C" {
      33             : #endif
      34             : 
      35             : struct net_socket_service_event;
      36             : 
      37             : /** @brief The signature for a net socket service handler function.
      38             :  *
      39             :  * The function will be invoked by the socket service.
      40             :  *
      41             :  * @param pev the socket service event that provided the handler.
      42             :  */
      43           1 : typedef void (*net_socket_service_handler_t)(struct net_socket_service_event *pev);
      44             : 
      45             : /**
      46             :  * This struct contains information which socket triggered
      47             :  * calls to the callback function.
      48             :  */
      49           1 : struct net_socket_service_event {
      50             :         /** Callback to be called for desired socket activity */
      51           1 :         net_socket_service_handler_t callback;
      52             :         /** Socket information that triggered this event. */
      53           1 :         struct zsock_pollfd event;
      54             :         /** User data */
      55           1 :         void *user_data;
      56             :         /** Service back pointer */
      57           1 :         struct net_socket_service_desc *svc;
      58             : };
      59             : 
      60             : /**
      61             :  * Main structure holding socket service configuration information.
      62             :  * The k_work item is created so that when there is data coming
      63             :  * to those fds, the k_work callback is then called.
      64             :  * The workqueue can be set NULL in which case system workqueue is used.
      65             :  * The service descriptor should be created at built time, and then used
      66             :  * as a parameter to register the sockets to be monitored.
      67             :  * User should create needed sockets and then setup the poll struct and
      68             :  * then register the sockets to be monitored at runtime.
      69             :  */
      70           1 : struct net_socket_service_desc {
      71             : #if CONFIG_NET_SOCKETS_LOG_LEVEL >= LOG_LEVEL_DBG
      72             :         /**
      73             :          * Owner name. This can be used in debugging to see who has
      74             :          * registered this service.
      75             :          */
      76           1 :         const char *owner;
      77             : #endif
      78             :         /** Pointer to the list of services that we are listening */
      79           1 :         struct net_socket_service_event *pev;
      80             :         /** Length of the pollable socket array for this service. */
      81           1 :         int pev_len;
      82             :         /** Where are my pollfd entries in the global list */
      83           1 :         int *idx;
      84             : };
      85             : 
      86             : /** @cond INTERNAL_HIDDEN */
      87             : 
      88             : #define __z_net_socket_svc_get_name(_svc_id) __z_net_socket_service_##_svc_id
      89             : #define __z_net_socket_svc_get_idx(_svc_id) __z_net_socket_service_idx_##_svc_id
      90             : #define __z_net_socket_svc_get_owner __FILE__ ":" STRINGIFY(__LINE__)
      91             : 
      92             : #if CONFIG_NET_SOCKETS_LOG_LEVEL >= LOG_LEVEL_DBG
      93             : #define NET_SOCKET_SERVICE_OWNER .owner = __z_net_socket_svc_get_owner,
      94             : #else
      95             : #define NET_SOCKET_SERVICE_OWNER
      96             : #endif
      97             : 
      98             : #define __z_net_socket_service_define(_name, _cb, _count, ...) \
      99             :         static int __z_net_socket_svc_get_idx(_name);                   \
     100             :         static struct net_socket_service_event                          \
     101             :                         __z_net_socket_svc_get_name(_name)[_count] = {  \
     102             :                 [0 ... ((_count) - 1)] = {                              \
     103             :                         .event.fd = -1, /* Invalid socket */            \
     104             :                         .callback = _cb,                                \
     105             :                 }                                                       \
     106             :         };                                                              \
     107             :         COND_CODE_0(NUM_VA_ARGS_LESS_1(__VA_ARGS__), (), __VA_ARGS__)   \
     108             :         const STRUCT_SECTION_ITERABLE(net_socket_service_desc, _name) = { \
     109             :                 NET_SOCKET_SERVICE_OWNER                                \
     110             :                 .pev = __z_net_socket_svc_get_name(_name),              \
     111             :                 .pev_len = (_count),                                    \
     112             :                 .idx = &__z_net_socket_svc_get_idx(_name),          \
     113             :         }
     114             : 
     115             : /** @endcond */
     116             : 
     117             : /**
     118             :  * @brief Statically define a network socket service.
     119             :  *        The user callback is called synchronously for this service meaning that
     120             :  *        the service API will wait until the user callback returns before continuing
     121             :  *        with next socket service.
     122             :  *
     123             :  * The socket service can be accessed outside the module where it is defined using:
     124             :  *
     125             :  * @code extern struct net_socket_service_desc <name>; @endcode
     126             :  *
     127             :  * @note This macro cannot be used together with a static keyword.
     128             :  *       If such a use-case is desired, use NET_SOCKET_SERVICE_SYNC_DEFINE_STATIC
     129             :  *       instead.
     130             :  *
     131             :  * @param name Name of the service.
     132             :  * @param cb Callback function that is called for socket activity.
     133             :  * @param count How many pollable sockets is needed for this service.
     134             :  */
     135           1 : #define NET_SOCKET_SERVICE_SYNC_DEFINE(name, cb, count) \
     136             :         __z_net_socket_service_define(name, cb, count)
     137             : 
     138             : /**
     139             :  * @brief Statically define a network socket service in a private (static) scope.
     140             :  *        The user callback is called synchronously for this service meaning that
     141             :  *        the service API will wait until the user callback returns before continuing
     142             :  *        with next socket service.
     143             :  *
     144             :  * @param name Name of the service.
     145             :  * @param cb Callback function that is called for socket activity.
     146             :  * @param count How many pollable sockets is needed for this service.
     147             :  */
     148           1 : #define NET_SOCKET_SERVICE_SYNC_DEFINE_STATIC(name, cb, count)  \
     149             :         __z_net_socket_service_define(name, cb, count, static)
     150             : 
     151             : /**
     152             :  * @brief Register pollable sockets.
     153             :  *
     154             :  * @param service Pointer to a service description.
     155             :  * @param fds Socket array to poll.
     156             :  * @param len Length of the socket array.
     157             :  * @param user_data User specific data.
     158             :  *
     159             :  * @retval 0 No error
     160             :  * @retval -ENOENT Service is not found.
     161             :  * @retval -ENINVAL Invalid parameter.
     162             :  */
     163           1 : __syscall int net_socket_service_register(const struct net_socket_service_desc *service,
     164             :                                           struct zsock_pollfd *fds, int len, void *user_data);
     165             : 
     166             : /**
     167             :  * @brief Unregister pollable sockets.
     168             :  *
     169             :  * @param service Pointer to a service description.
     170             :  *
     171             :  * @retval 0 No error
     172             :  * @retval -ENOENT Service is not found.
     173             :  * @retval -ENINVAL Invalid parameter.
     174             :  */
     175           1 : static inline int net_socket_service_unregister(const struct net_socket_service_desc *service)
     176             : {
     177             :         return net_socket_service_register(service, NULL, 0, NULL);
     178             : }
     179             : 
     180             : /**
     181             :  * @typedef net_socket_service_cb_t
     182             :  * @brief Callback used while iterating over socket services.
     183             :  *
     184             :  * @param svc Pointer to current socket service.
     185             :  * @param user_data A valid pointer to user data or NULL
     186             :  */
     187           1 : typedef void (*net_socket_service_cb_t)(const struct net_socket_service_desc *svc,
     188             :                                         void *user_data);
     189             : 
     190             : /**
     191             :  * @brief Go through all the socket services and call callback for each service.
     192             :  *
     193             :  * @param cb User-supplied callback function to call
     194             :  * @param user_data User specified data
     195             :  */
     196           1 : void net_socket_service_foreach(net_socket_service_cb_t cb, void *user_data);
     197             : 
     198             : #ifdef __cplusplus
     199             : }
     200             : #endif
     201             : 
     202             : #include <zephyr/syscalls/socket_service.h>
     203             : 
     204             : /**
     205             :  * @}
     206             :  */
     207             : 
     208             : #endif /* ZEPHYR_INCLUDE_NET_SOCKET_SERVICE_H_ */

Generated by: LCOV version 1.14