Skip to content

Commit 8b1e4de

Browse files
ldtsldts
committed
net: latmon: 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 7823374 commit 8b1e4de

File tree

8 files changed

+731
-0
lines changed

8 files changed

+731
-0
lines changed

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

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

‎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: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
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_get_delta_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_get_delta_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.
42+
*
43+
* @param socket A valid socket descriptor for communication.
44+
* @param get_delta_func A callback function to execute the delta calculation.
45+
*/
46+
void net_latmon_start(int socket, net_latmon_get_delta_t get_delta_func);
47+
48+
/**
49+
* @brief Wait for a connection from a Latmus client.
50+
*
51+
* @details This function blocks until a Latmus client connects to the
52+
* specified socket. Once connected, the client's IP address is stored
53+
* in the provided `ip` structure.
54+
*
55+
* @param socket A valid socket descriptor for listening.
56+
* @param ip The client's IP address.
57+
* @return A valid client socket descriptor on success, negative errno code on failure.
58+
*/
59+
int net_latmon_connect(int socket, struct in_addr *ip);
60+
61+
/**
62+
* @brief Get a socket for the Latmus service.
63+
*
64+
* @details This function creates and returns a socket so that Latmon can
65+
* communicate to the Latmus service.
66+
*
67+
* @return A valid socket descriptor on success, negative errno code on failure.
68+
*/
69+
int net_latmon_get_socket(void);
70+
71+
/**
72+
* @brief Check if the latency monitor is running.
73+
*
74+
* @details This function checks whether the latency monitor is currently
75+
* active and running.
76+
*
77+
* @return True if the latency monitor is running, false otherwise.
78+
*/
79+
bool net_latmon_running(void);
80+
81+
/**
82+
* @}
83+
*/
84+
85+
#ifdef __cplusplus
86+
}
87+
#endif
88+
89+
#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: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
2+
config NET_LATMON
3+
bool "Enable latency monitoring"
4+
help
5+
This option enables the latency monitoring support for Zephyr
6+
select NET_IPV4
7+
select NET_ARP
8+
select NET_TCP
9+
select NET_UDP
10+
select NET_DHCPV4
11+
select NET_SOCKETS
12+
select NET_MGMT
13+
select NET_MGMT_EVENT
14+
select NET_LOG
15+
select POSIX_API
16+
select NET_SHELL
17+
select TEST_RANDOM_GENERATOR
18+
19+
20+
module = LATMON
21+
module-str = Latency monitoring Service
22+
module-help = This option enables the latency monitoring support for Zephyr
23+
source "subsys/net/Kconfig.template.log_config.net"

0 commit comments

Comments
 (0)