net: latmon: latency monitor service and sample

doc/connectivity/networking/api/latmon.rst

@@ -0,0 +1,151 @@
+.. _latmon:
+
+Latmon Network Service
+######################
+
+.. contents::
+    :local:
+    :depth: 2
+
+Overview
+********
+
+Provides the functionality required for network-based latency monitoring, including socket
+management, client-server communication, and data exchange with the Latmus service running
+on the System Under Test (SUT).
+
+The Latmon network service is responsible for establishing and managing network
+communication between the Latmon application (running on a Zephyr-based board) and
+the Latmus service (running on the SUT).
+
+It uses TCP sockets for reliable communication and UDP sockets for broadcasting
+the IP address of the Latmon device.
+
+API Reference
+*************
+
+.. doxygengroup:: latmon
+
+Features
+********
+
+- **Socket Management**: Creates and manages TCP and UDP sockets for communication.
+- **Client-Server Communication**: Handles incoming connections from the Latmus service.
+- **Data Exchange**: Sends latency metrics and histogram data to the Latmus service.
+- **IP Address Broadcasting**: Broadcasts the IP address of the Latmon device to facilitate
+  discovery by the Latmus service.
+- **Thread-Safe Design**: Uses Zephyr's kernel primitives (e.g., message queues and semaphores) for
+  synchronization.
+
+Key Components
+**************
+
+Socket Management
+=================
+
+The service provides functions to create, bind, and listen on sockets.
+It also supports sending and receiving data over TCP and UDP.
+
+Message Queue
+=============
+
+A message queue (``latmon_msgq``) is used to pass messages between threads,
+ensuring thread-safe communication.
+
+Synchronization
+===============
+
+Semaphores (``latmon_done`` and ``monitor_done``) are used to synchronize the monitoring
+process and ensure proper cleanup.
+
+Thread Management
+=================
+
+The service uses Zephyr threads to handle incoming connections and manage the
+monitoring process.
+
+Workflow
+********
+
+Socket Creation
+===============
+
+The ``net_latmon_get_socket()`` function is called to create and configure a TCP socket to
+communicate with the Latmus service. A connection address can be specified as a paramenter to
+bind the socket to a specific interface and port.
+
+Connection Handling
+===================
+
+The ``net_latmon_connect()`` function waits for a connection from the Latmus service.
+If no connection is received within the timeout period, the service broadcasts its IP address
+using UDP and returns ``-EAGAIN``.
+If the broadcast request cannot be sent, the function returns ``-1``, and the client should quit.
+
+Monitoring Start
+================
+
+Once a connection is established, the ``net_latmon_start()`` function is called to
+start the monitoring process. This function uses a callback to calculate latency deltas
+and sends the data to the Latmus service.
+
+Monitoring Status
+=================
+
+The ``net_latmon_running()`` function can be used to check if the monitoring process is active.
+
+Thread Management
+=================
+
+The service uses Zephyr threads to handle incoming connections and manage the monitoring
+process.
+
+Enabling the Latmon Service
+***************************
+
+The following configuration option must be enabled in the :file:`prj.conf` file.
+
+- :kconfig:option:`CONFIG_NET_LATMON`
+
+The following options may be configured to customize the Latmon service:
+
+- :kconfig:option:`CONFIG_NET_LATMON_PORT` - Port number for the Latmon service.
+- :kconfig:option:`CONFIG_NET_LATMON_XFER_THREAD_STACK_SIZE`
+- :kconfig:option:`CONFIG_NET_LATMON_XFER_THREAD_PRIORITY`
+- :kconfig:option:`CONFIG_NET_LATMON_THREAD_STACK_SIZE`
+- :kconfig:option:`CONFIG_NET_LATMON_THREAD_PRIORITY`
+- :kconfig:option:`CONFIG_NET_LATMON_MONITOR_THREAD_STACK_SIZE`
+- :kconfig:option:`CONFIG_NET_LATMON_MONITOR_THREAD_PRIORITY`
+
+Example Usage
+*************
+
+.. code-block:: c
+
+    #include <zephyr/net/latmon.h>
+    #include <zephyr/net/socket.h>
+
+    void main(void)
+    {
+        struct in_addr ip;
+        int server_socket, client_socket;
+
+        /* Create and configure the server socket */
+        server_socket = net_latmon_get_socket();
+
+        while (1) {
+            /* Wait for a connection from the Latmus service */
+            client_socket = net_latmon_connect(server_socket, &ip);
+            if (client_socket < 0) {
+                if (client_socket == -EAGAIN) {
+                    continue;
+                }
+                goto out;
+            }
+
+            /* Start the latency monitoring process */
+            net_latmon_start(client_socket, measure_latency_cycles);
+        }
+    out:
+        close(socket);
+    }

doc/connectivity/networking/api/protocols.rst

@@ -17,3 +17,4 @@ Protocols
    mqtt_sn
    ptp
    tftp
+   latmon

include/zephyr/net/latmon.h

@@ -0,0 +1,97 @@
+/** @file
+ *  @brief Latency Monitor API
+ */
+
+/*
+ * Copyright (c) 2025 Jorge A. Ramirez Ortiz <jorge.ramirez@oss.qualcomm.com>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_NET_LATMON_H_
+#define ZEPHYR_INCLUDE_NET_LATMON_H_
+
+#include <zephyr/kernel.h>
+#include <zephyr/net/net_ip.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Latency Monitor
+ * @defgroup latmon Latency Monitor
+ * @ingroup networking
+ * @{
+ */
+
+/**
+ * @typedef net_latmon_measure_t
+ * @brief Callback function type for retrieving latency deltas.
+ *
+ * @param delta Pointer to store the calculated latency delta in cycles.
+ * @return 0 on success, negative errno code on failure.
+ */
+typedef int (*net_latmon_measure_t)(uint32_t *delta);
+
+/**
+ * @brief Start the latency monitor.
+ *
+ * @details This function starts the latency monitor, which measures
+ * latency using the provided callback function to calculate deltas. Samples
+ * are sent to the connected Latmus client.
+ *
+ * @param latmus A valid socket descriptor connected to latmus
+ * @param measure_func A callback function to execute the delta calculation.
+ */
+void net_latmon_start(int latmus, net_latmon_measure_t measure_func);
+
+/**
+ * @brief Wait for a connection from a Latmus client.
+ *
+ * @details This function blocks until a Latmus client connects to the
+ * specified socket. Once connected, the client's IP address is stored
+ * in the provided `ip` structure.
+ *
+ * @param socket A valid socket descriptor for listening.
+ * @param ip The client's IP address.
+ * @return A valid client socket descriptor connected to latmus on success,
+ * negative errno code on failure.
+ *
+ */
+int net_latmon_connect(int socket, struct in_addr *ip);
+
+/**
+ * @brief Get a socket for the Latmus service.
+ *
+ * @details This function creates and returns a socket to wait for Latmus
+ * connections
+ *
+ * @param ip The IP address to bind the socket to. If NULL, the socket
+ * will be bound to the first available address using the build time configured
+ * latmus port.
+ *
+ * @return A valid socket descriptor on success, negative errno code on failure.
+ */
+int net_latmon_get_socket(struct sockaddr *ip);
+
+/**
+ * @brief Check if the latency monitor is running.
+ *
+ * @details This function checks whether the latency monitor is currently
+ * active and running.
+ *
+ * @return True if the latency monitor is running, false if it is waiting for a
+ * Latmus connection
+ */
+bool net_latmon_running(void);
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ZEPHYR_INCLUDE_NET_LATMON_H_ */

samples/net/latmon/CMakeLists.txt

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(latmon)
+
+target_sources(app PRIVATE src/main.c)

samples/net/latmon/Kconfig

@@ -0,0 +1,13 @@
+# Private config options for Latmon Sample app
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 Jorge Ramirez-Ortiz <jorge.ramirez@oss.qualcomm.com>
+
+mainmenu "Latmon Sample application"
+
+config LATMON_LOOPBACK_CALIBRATION
+	bool "Run the sample code in calibration mode"
+	default n
+	help
+	  Run Latmon in calibration mode.
+
+source "Kconfig.zephyr"