Skip to content

Commit 00620ec

Browse files
ldtsldts
committed
net: latmon: Add latency monitor service
Latmon service to interface with Xenomai's Latmus. Link: https://evlproject.org/core/benchmarks/#latmus-gpio-response-time Signed-off-by: Jorge Ramirez-Ortiz <[email protected]>
1 parent e0dbba5 commit 00620ec

File tree

8 files changed

+883
-0
lines changed

8 files changed

+883
-0
lines changed

‎doc/connectivity/networking/api/latmon.rst

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
.. _latmon:
2+
3+
Latmon Network Service
4+
######################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
Overview
11+
********
12+
13+
Provides the functionality required for network-based latency monitoring, including socket
14+
management, client-server communication, and data exchange with the Latmus service running
15+
on the System Under Test (SUT).
16+
17+
The Latmon network service is responsible for establishing and managing network
18+
communication between the Latmon application (running on a Zephyr-based board) and
19+
the Latmus service (running on the SUT).
20+
21+
It uses TCP sockets for reliable communication and UDP sockets for broadcasting
22+
the IP address of the Latmon device.
23+
24+
API Reference
25+
*************
26+
27+
.. doxygengroup:: latmon
28+
29+
Features
30+
********
31+
32+
- **Socket Management**: Creates and manages TCP and UDP sockets for communication.
33+
- **Client-Server Communication**: Handles incoming connections from the Latmus service.
34+
- **Data Exchange**: Sends latency metrics and histogram data to the Latmus service.
35+
- **IP Address Broadcasting**: Broadcasts the IP address of the Latmon device to facilitate
36+
discovery by the Latmus service.
37+
- **Thread-Safe Design**: Uses Zephyr's kernel primitives (e.g., message queues and semaphores) for
38+
synchronization.
39+
40+
Key Components
41+
**************
42+
43+
Socket Management
44+
=================
45+
46+
The service provides functions to create, bind, and listen on sockets.
47+
It also supports sending and receiving data over TCP and UDP.
48+
49+
Message Queue
50+
=============
51+
52+
A message queue (``latmon_msgq``) is used to pass messages between threads,
53+
ensuring thread-safe communication.
54+
55+
Synchronization
56+
===============
57+
58+
Semaphores (``latmon_done`` and ``monitor_done``) are used to synchronize the monitoring
59+
process and ensure proper cleanup.
60+
61+
Thread Management
62+
=================
63+
64+
The service uses Zephyr threads to handle incoming connections and manage the
65+
monitoring process.
66+
67+
Workflow
68+
********
69+
70+
Socket Creation
71+
===============
72+
73+
The :c:func:`net_latmon_get_socket()` function is called to create and configure a TCP socket to
74+
communicate with the Latmus service. A connection address can be specified as a paramenter to
75+
bind the socket to a specific interface and port.
76+
77+
Connection Handling
78+
===================
79+
80+
The :c:func:`net_latmon_connect()` function waits for a connection from the Latmus service.
81+
If no connection is received within the timeout period, the service broadcasts its IP address
82+
using UDP and returns ``-EAGAIN``.
83+
If the broadcast request cannot be sent, the function returns ``-1``, and the client should quit.
84+
85+
Monitoring Start
86+
================
87+
88+
Once a connection is established, the :c:func:`net_latmon_start()` function is called to
89+
start the monitoring process. This function uses a callback to calculate latency deltas
90+
and sends the data to the Latmus service.
91+
92+
Monitoring Status
93+
=================
94+
95+
The :c:func:`net_latmon_running()` function can be used to check if the monitoring process is active.
96+
97+
Thread Management
98+
=================
99+
100+
The service uses Zephyr threads to handle incoming connections and manage the monitoring
101+
process.
102+
103+
Enabling the Latmon Service
104+
***************************
105+
106+
The following configuration option must be enabled in the :file:`prj.conf` file.
107+
108+
- :kconfig:option:`CONFIG_NET_LATMON`
109+
110+
The following options may be configured to customize the Latmon service:
111+
112+
- :kconfig:option:`CONFIG_NET_LATMON_PORT` - Port number for the Latmon service.
113+
- :kconfig:option:`CONFIG_NET_LATMON_XFER_THREAD_STACK_SIZE`
114+
- :kconfig:option:`CONFIG_NET_LATMON_XFER_THREAD_PRIORITY`
115+
- :kconfig:option:`CONFIG_NET_LATMON_THREAD_STACK_SIZE`
116+
- :kconfig:option:`CONFIG_NET_LATMON_THREAD_PRIORITY`
117+
- :kconfig:option:`CONFIG_NET_LATMON_MONITOR_THREAD_STACK_SIZE`
118+
- :kconfig:option:`CONFIG_NET_LATMON_MONITOR_THREAD_PRIORITY`
119+
120+
Example Usage
121+
*************
122+
123+
.. code-block:: c
124+
125+
#include <zephyr/net/latmon.h>
126+
#include <zephyr/net/socket.h>
127+
128+
void main(void)
129+
{
130+
struct in_addr ip;
131+
int server_socket, client_socket;
132+
133+
/* Create and configure the server socket */
134+
server_socket = net_latmon_get_socket(NULL);
135+
136+
while (1) {
137+
/* Wait for a connection from the Latmus service */
138+
client_socket = net_latmon_connect(server_socket, &ip);
139+
if (client_socket < 0) {
140+
if (client_socket == -EAGAIN) {
141+
continue;
142+
}
143+
goto out;
144+
}
145+
146+
/* Start the latency monitoring process */
147+
net_latmon_start(client_socket, measure_latency_cycles);
148+
}
149+
out:
150+
close(server_socket);
151+
}

‎doc/connectivity/networking/api/protocols.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,4 @@ Protocols
1717
mqtt_sn
1818
ptp
1919
tftp
20+
latmon

‎include/zephyr/net/latmon.h

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
/** @file
2+
* @brief Latency Monitor API
3+
*/
4+
5+
/*
6+
* Copyright (c) 2025 Jorge A. Ramirez Ortiz <[email protected]>
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+
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+
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+
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+
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+
bool net_latmon_running(void);
88+
89+
/**
90+
* @}
91+
*/
92+
93+
#ifdef __cplusplus
94+
}
95+
#endif
96+
97+
#endif /* ZEPHYR_INCLUDE_NET_LATMON_H_ */

‎subsys/net/lib/CMakeLists.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ add_subdirectory_ifdef(CONFIG_SNTP sntp)
88
add_subdirectory_ifdef(CONFIG_MQTT_LIB mqtt)
99
add_subdirectory_ifdef(CONFIG_MQTT_SN_LIB mqtt_sn)
1010
add_subdirectory_ifdef(CONFIG_PTP ptp)
11+
add_subdirectory_ifdef(CONFIG_NET_LATMON latmon)
1112
add_subdirectory_ifdef(CONFIG_TFTP_LIB tftp)
1213
add_subdirectory_ifdef(CONFIG_NET_CONFIG_SETTINGS config)
1314
add_subdirectory_ifdef(CONFIG_NET_SOCKETS sockets)

‎subsys/net/lib/Kconfig

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ source "subsys/net/lib/coap/Kconfig"
77

88
source "subsys/net/lib/dns/Kconfig"
99

10+
source "subsys/net/lib/latmon/Kconfig"
11+
1012
source "subsys/net/lib/mqtt/Kconfig"
1113

1214
source "subsys/net/lib/mqtt_sn/Kconfig"

‎subsys/net/lib/latmon/CMakeLists.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
zephyr_library()
2+
3+
zephyr_library_sources(
4+
latmon.c
5+
)

‎subsys/net/lib/latmon/Kconfig

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Copyright (c) 2025 Jorge A. Ramirez-Ortiz <[email protected]>
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
config NET_LATMON
5+
bool "Latency monitoring support"
6+
select EXPERIMENTAL
7+
select NET_SOCKETS
8+
depends on NET_TCP
9+
help
10+
This option enables the latency monitoring support for Zephyr
11+
12+
config NET_LATMON_PORT
13+
int "Latmon - Latmus communication port"
14+
default 2306
15+
help
16+
Specify the port number used for Latmon - Latmus communication.
17+
18+
config NET_LATMON_XFER_THREAD_STACK_SIZE
19+
int "Stack size for the network transfer thread"
20+
default 8192
21+
help
22+
Specify the stack size for the network transfer thread used in latency monitoring.
23+
24+
config NET_LATMON_XFER_THREAD_PRIORITY
25+
int "Priority for the network transfer thread"
26+
default 14
27+
help
28+
Specify the priority for the network transfer thread used in latency monitoring.
29+
30+
config NET_LATMON_THREAD_STACK_SIZE
31+
int "Stack size for the Latmon thread"
32+
default 8192
33+
help
34+
Specify the stack size for the Latmon thread used in latency monitoring.
35+
36+
config NET_LATMON_THREAD_PRIORITY
37+
int "Priority for the Latmon thread"
38+
default 14
39+
help
40+
Specify the priority for the Latmon thread used in latency monitoring.
41+
42+
config NET_LATMON_MONITOR_THREAD_STACK_SIZE
43+
int "Stack size for the monitor thread"
44+
default 8192
45+
help
46+
Specify the stack size for the monitor thread used in latency monitoring.
47+
48+
config NET_LATMON_MONITOR_THREAD_PRIORITY
49+
int "Priority for the monitor thread"
50+
default -16
51+
help
52+
Specify the priority for the monitor thread used in latency monitoring.
53+
54+
module = LATMON
55+
module-dep = NET_LOG
56+
module-str = Latency monitoring Service
57+
module-help = This option enables the latency monitoring support for Zephyr
58+
source "subsys/net/Kconfig.template.log_config.net"

0 commit comments

Comments
 (0)