Line data    Source code

       1            1 : /** @file
       2              :  *  @brief Latency Monitor API
       3              :  */
       4              : 
       5              : /*
       6              :  * Copyright (c) 2025 Jorge A. Ramirez Ortiz <jorge.ramirez@oss.qualcomm.com>
       7              :  *
       8              :  * SPDX-License-Identifier: Apache-2.0
       9              :  */
      10              : 
      11              : #ifndef ZEPHYR_INCLUDE_NET_LATMON_H_
      12              : #define ZEPHYR_INCLUDE_NET_LATMON_H_
      13              : 
      14              : #include <zephyr/kernel.h>
      15              : #include <zephyr/net/net_ip.h>
      16              : 
      17              : #ifdef __cplusplus
      18              : extern "C" {
      19              : #endif
      20              : 
      21              : /**
      22              :  * @brief Latency Monitor
      23              :  * @defgroup latmon Latency Monitor
      24              :  * @ingroup networking
      25              :  * @{
      26              :  */
      27              : 
      28              : /**
      29              :  * @typedef net_latmon_measure_t
      30              :  * @brief Callback function type for retrieving latency deltas.
      31              :  *
      32              :  * @param delta Pointer to store the calculated latency delta in cycles.
      33              :  * @return 0 on success, negative errno code on failure.
      34              :  */
      35            1 : typedef int (*net_latmon_measure_t)(uint32_t *delta);
      36              : 
      37              : /**
      38              :  * @brief Start the latency monitor.
      39              :  *
      40              :  * @details This function starts the latency monitor, which measures
      41              :  * latency using the provided callback function to calculate deltas. Samples
      42              :  * are sent to the connected Latmus client.
      43              :  *
      44              :  * @param latmus A valid socket descriptor connected to latmus
      45              :  * @param measure_func A callback function to execute the delta calculation.
      46              :  */
      47            1 : void net_latmon_start(int latmus, net_latmon_measure_t measure_func);
      48              : 
      49              : /**
      50              :  * @brief Wait for a connection from a Latmus client.
      51              :  *
      52              :  * @details This function blocks until a Latmus client connects to the
      53              :  * specified socket. Once connected, the client's IP address is stored
      54              :  * in the provided `ip` structure.
      55              :  *
      56              :  * @param socket A valid socket descriptor for listening.
      57              :  * @param ip The client's IP address.
      58              :  * @return A valid client socket descriptor connected to latmus on success,
      59              :  * negative errno code on failure.
      60              :  *
      61              :  */
      62            1 : int net_latmon_connect(int socket, struct in_addr *ip);
      63              : 
      64              : /**
      65              :  * @brief Get a socket for the Latmus service.
      66              :  *
      67              :  * @details This function creates and returns a socket to wait for Latmus
      68              :  * connections
      69              :  *
      70              :  * @param bind_addr The address to bind the socket to. If NULL, the socket
      71              :  * will be bound to the first available address using the build time configured
      72              :  * latmus port.
      73              :  *
      74              :  * @return A valid socket descriptor on success, negative errno code on failure.
      75              :  */
      76            1 : int net_latmon_get_socket(struct sockaddr *bind_addr);
      77              : 
      78              : /**
      79              :  * @brief Check if the latency monitor is running.
      80              :  *
      81              :  * @details This function checks whether the latency monitor is currently
      82              :  * active and running.
      83              :  *
      84              :  * @return True if the latency monitor is running, false if it is waiting for a
      85              :  * Latmus connection
      86              :  */
      87            1 : bool net_latmon_running(void);
      88              : 
      89              : /**
      90              :  * @}
      91              :  */
      92              : 
      93              : #ifdef __cplusplus
      94              : }
      95              : #endif
      96              : 
      97              : #endif /* ZEPHYR_INCLUDE_NET_LATMON_H_ */