Line data Source code
1 1 : /*
2 : * Copyright (c) 2023 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file icmp.h
9 : * @brief Header file for ICMP protocol support.
10 : * @ingroup icmp
11 : *
12 : * @defgroup icmp ICMP
13 : * @brief Send and receive IPv4 or IPv6 ICMP (Internet Control Message Protocol)
14 : * Echo Request messages.
15 : * @since 3.5
16 : * @version 0.8.0
17 : * @ingroup networking
18 : * @{
19 : */
20 :
21 : #ifndef ZEPHYR_INCLUDE_NET_ICMP_H_
22 : #define ZEPHYR_INCLUDE_NET_ICMP_H_
23 :
24 : #include <stddef.h>
25 :
26 : #include <zephyr/kernel.h>
27 : #include <zephyr/types.h>
28 : #include <zephyr/net/net_ip.h>
29 : #include <zephyr/net/net_if.h>
30 : #include <zephyr/net/net_pkt.h>
31 :
32 : #ifdef __cplusplus
33 : extern "C" {
34 : #endif
35 :
36 1 : #define NET_ICMPV4_ECHO_REQUEST 8 /**< ICMPv4 Echo-Request */
37 1 : #define NET_ICMPV4_ECHO_REPLY 0 /**< ICMPv4 Echo-Reply */
38 1 : #define NET_ICMPV6_ECHO_REQUEST 128 /**< ICMPv6 Echo-Request */
39 1 : #define NET_ICMPV6_ECHO_REPLY 129 /**< ICMPv6 Echo-Reply */
40 :
41 : struct net_icmp_ctx;
42 : struct net_icmp_ip_hdr;
43 : struct net_icmp_ping_params;
44 :
45 : /**
46 : * @typedef net_icmp_handler_t
47 : * @brief Handler function that is called when ICMP response is received.
48 : *
49 : * @param ctx ICMP context to use.
50 : * @param pkt Received ICMP response network packet.
51 : * @param ip_hdr IP header of the packet.
52 : * @param icmp_hdr ICMP header of the packet.
53 : * @param user_data A valid pointer to user data or NULL
54 : */
55 1 : typedef int (*net_icmp_handler_t)(struct net_icmp_ctx *ctx,
56 : struct net_pkt *pkt,
57 : struct net_icmp_ip_hdr *ip_hdr,
58 : struct net_icmp_hdr *icmp_hdr,
59 : void *user_data);
60 :
61 : /**
62 : * @typedef net_icmp_offload_ping_handler_t
63 : * @brief Handler function that is called when an Echo-Request is sent
64 : * to offloaded device. This handler is typically setup by the
65 : * device driver so that it can catch the ping request and send
66 : * it to the offloaded device.
67 : *
68 : * @param ctx ICMP context used in this request.
69 : * @param iface Network interface, can be set to NULL in which case the
70 : * interface is selected according to destination address.
71 : * @param dst IP address of the target host.
72 : * @param params Echo-Request specific parameters. May be NULL in which case
73 : * suitable default parameters are used.
74 : * @param user_data User supplied opaque data passed to the handler. May be NULL.
75 : *
76 : */
77 1 : typedef int (*net_icmp_offload_ping_handler_t)(struct net_icmp_ctx *ctx,
78 : struct net_if *iface,
79 : struct sockaddr *dst,
80 : struct net_icmp_ping_params *params,
81 : void *user_data);
82 :
83 : /**
84 : * @brief ICMP context structure.
85 : */
86 1 : struct net_icmp_ctx {
87 : /** List node */
88 1 : sys_snode_t node;
89 :
90 : /** ICMP response handler */
91 1 : net_icmp_handler_t handler;
92 :
93 : /** Network interface where the ICMP request was sent */
94 1 : struct net_if *iface;
95 :
96 : /** Opaque user supplied data */
97 1 : void *user_data;
98 :
99 : /** ICMP type of the response we are waiting */
100 1 : uint8_t type;
101 :
102 : /** ICMP code of the response type we are waiting */
103 1 : uint8_t code;
104 : };
105 :
106 : /**
107 : * @brief Struct presents either IPv4 or IPv6 header in ICMP response message.
108 : */
109 1 : struct net_icmp_ip_hdr {
110 : union {
111 : /** IPv4 header in response message. */
112 1 : struct net_ipv4_hdr *ipv4;
113 :
114 : /** IPv6 header in response message. */
115 1 : struct net_ipv6_hdr *ipv6;
116 0 : };
117 :
118 : /** Is the header IPv4 or IPv6 one. Value of either AF_INET or AF_INET6 */
119 1 : sa_family_t family;
120 : };
121 :
122 : /**
123 : * @brief Struct presents parameters that are needed when sending
124 : * Echo-Request (ping) messages.
125 : */
126 1 : struct net_icmp_ping_params {
127 : /** An identifier to aid in matching Echo Replies to this Echo Request.
128 : * May be zero.
129 : */
130 1 : uint16_t identifier;
131 :
132 : /** A sequence number to aid in matching Echo Replies to this
133 : * Echo Request. May be zero.
134 : */
135 1 : uint16_t sequence;
136 :
137 : /** Can be either IPv4 Type-of-service field value, or IPv6 Traffic
138 : * Class field value. Represents combined DSCP and ECN values.
139 : */
140 1 : uint8_t tc_tos;
141 :
142 : /** Network packet priority. */
143 1 : int priority;
144 :
145 : /** Arbitrary payload data that will be included in the Echo Reply
146 : * verbatim. May be NULL.
147 : */
148 1 : const void *data;
149 :
150 : /** Size of the Payload Data in bytes. May be zero. In case data
151 : * pointer is NULL, the function will generate the payload up to
152 : * the requested size.
153 : */
154 1 : size_t data_size;
155 : };
156 :
157 : /**
158 : * @brief Initialize the ICMP context structure. Must be called before
159 : * ICMP messages can be sent. This will register handler to the
160 : * system.
161 : *
162 : * @param ctx ICMP context used in this request.
163 : * @param type Type of ICMP message we are handling.
164 : * @param code Code of ICMP message we are handling.
165 : * @param handler Callback function that is called when a response is received.
166 : */
167 1 : int net_icmp_init_ctx(struct net_icmp_ctx *ctx, uint8_t type, uint8_t code,
168 : net_icmp_handler_t handler);
169 :
170 : /**
171 : * @brief Cleanup the ICMP context structure. This will unregister the ICMP handler
172 : * from the system.
173 : *
174 : * @param ctx ICMP context used in this request.
175 : */
176 1 : int net_icmp_cleanup_ctx(struct net_icmp_ctx *ctx);
177 :
178 : /**
179 : * @brief Send ICMP echo request message.
180 : *
181 : * @param ctx ICMP context used in this request.
182 : * @param iface Network interface, can be set to NULL in which case the
183 : * interface is selected according to destination address.
184 : * @param dst IP address of the target host.
185 : * @param params Echo-Request specific parameters. May be NULL in which case
186 : * suitable default parameters are used.
187 : * @param user_data User supplied opaque data passed to the handler. May be NULL.
188 : *
189 : * @return Return 0 if the sending succeed, <0 otherwise.
190 : */
191 1 : int net_icmp_send_echo_request(struct net_icmp_ctx *ctx,
192 : struct net_if *iface,
193 : struct sockaddr *dst,
194 : struct net_icmp_ping_params *params,
195 : void *user_data);
196 :
197 : /**
198 : * @brief Send ICMP echo request message without waiting during send.
199 : *
200 : * @details This function can be used to send ICMP Echo-Request from a system
201 : * workqueue handler which should not have any sleeps or waits.
202 : * This variant will do the net_buf allocations with K_NO_WAIT.
203 : * This will avoid a warning message in the log about the timeout.
204 : *
205 : * @param ctx ICMP context used in this request.
206 : * @param iface Network interface, can be set to NULL in which case the
207 : * interface is selected according to destination address.
208 : * @param dst IP address of the target host.
209 : * @param params Echo-Request specific parameters. May be NULL in which case
210 : * suitable default parameters are used.
211 : * @param user_data User supplied opaque data passed to the handler. May be NULL.
212 : *
213 : * @return Return 0 if the sending succeed, <0 otherwise.
214 : */
215 1 : int net_icmp_send_echo_request_no_wait(struct net_icmp_ctx *ctx,
216 : struct net_if *iface,
217 : struct sockaddr *dst,
218 : struct net_icmp_ping_params *params,
219 : void *user_data);
220 :
221 : /**
222 : * @brief ICMP offload context structure.
223 : */
224 1 : struct net_icmp_offload {
225 : /** List node */
226 1 : sys_snode_t node;
227 :
228 : /**
229 : * ICMP response handler. Currently there is only one handler.
230 : * This means that one offloaded ping request/response can be going
231 : * on at the same time.
232 : */
233 1 : net_icmp_handler_t handler;
234 :
235 : /** ICMP offloaded ping handler */
236 1 : net_icmp_offload_ping_handler_t ping_handler;
237 :
238 : /** Offloaded network interface */
239 1 : struct net_if *iface;
240 : };
241 :
242 : /**
243 : * @brief Register a handler function that is called when an Echo-Request
244 : * is sent to the offloaded device. This function is typically
245 : * called by a device driver so that it can do the actual offloaded
246 : * ping call.
247 : *
248 : * @param ctx ICMP offload context used for this interface.
249 : * @param iface Network interface of the offloaded device.
250 : * @param ping_handler Function to be called when offloaded ping request is done.
251 : *
252 : * @return Return 0 if the register succeed, <0 otherwise.
253 : */
254 1 : int net_icmp_register_offload_ping(struct net_icmp_offload *ctx,
255 : struct net_if *iface,
256 : net_icmp_offload_ping_handler_t ping_handler);
257 :
258 : /**
259 : * @brief Unregister the offload handler.
260 : *
261 : * @param ctx ICMP offload context used for this interface.
262 : *
263 : * @return Return 0 if the call succeed, <0 otherwise.
264 : */
265 1 : int net_icmp_unregister_offload_ping(struct net_icmp_offload *ctx);
266 :
267 : /**
268 : * @brief Get a ICMP response handler function for an offloaded device.
269 : * When a ping response is received by the driver, it should call
270 : * the handler function with proper parameters so that the ICMP response
271 : * is received by the net stack.
272 : *
273 : * @param ctx ICMP offload context used in this request.
274 : * @param resp_handler Function to be called when offloaded ping response
275 : * is received by the offloaded driver. The ICMP response handler
276 : * function is returned and the caller should call it when appropriate.
277 : *
278 : * @return Return 0 if the call succeed, <0 otherwise.
279 : */
280 1 : int net_icmp_get_offload_rsp_handler(struct net_icmp_offload *ctx,
281 : net_icmp_handler_t *resp_handler);
282 :
283 : #ifdef __cplusplus
284 : }
285 : #endif
286 :
287 : #endif /* ZEPHYR_INCLUDE_NET_ICMP_H */
288 :
289 : /**@} */
|
