Datagram PLPMTUD API

Data Structures
struct	net_dplpmtud_path
	Transport-owned DPLPMTUD path handle. More...

Macros
#define	NET_DPLPMTUD_BASE_PLPMTU   1200U
	Default base PLPMTU from RFC 8899/RFC 9000 for UDP-based transports.

Enumerations
enum	net_dplpmtud_state { NET_DPLPMTUD_STATE_BASE = 0 , NET_DPLPMTUD_STATE_SEARCHING , NET_DPLPMTUD_STATE_SEARCH_COMPLETE , NET_DPLPMTUD_STATE_ERROR }
	DPLPMTUD search state. More...

Functions
int	net_dplpmtud_init_path (struct net_dplpmtud_path *path, const struct net_sockaddr *dst, uint16_t max_plpmtu)
	Initialize a DPLPMTUD path handle for a remote destination.
void	net_dplpmtud_set_path_max_plpmtu (struct net_dplpmtud_path *path, uint16_t max_plpmtu)
	Update the transport-local maximum PLPMTU for a path.
int	net_dplpmtud_get_path_mtu (struct net_dplpmtud_path *path)
	Get the currently validated PLPMTU for a path.
int	net_dplpmtud_get_path_probe_size (struct net_dplpmtud_path *path)
	Get the next probe size a transport may transmit for a path.
bool	net_dplpmtud_path_probe_in_flight (struct net_dplpmtud_path *path)
	Check whether a probe is currently in flight for a path.
int	net_dplpmtud_on_path_probe_sent (struct net_dplpmtud_path *path, uint16_t probe_size)
	Report that a probe has been sent for a path.
int	net_dplpmtud_on_path_probe_acked (struct net_dplpmtud_path *path, uint16_t probe_size)
	Report that a probe was acknowledged for a path.
int	net_dplpmtud_on_path_probe_lost (struct net_dplpmtud_path *path, uint16_t probe_size)
	Report that a probe was lost for a path.
void	net_dplpmtud_note_path_blackhole (struct net_dplpmtud_path *path)
	Report black-hole fallback for a path.

Detailed Description

Since

4.5

Version

0.1.0

Generic Datagram Packetization Layer Path MTU Discovery (:rfc:8899) for UDP transports. The stack owns per-destination search state (validated PLPMTU, probe size, retry counters). Each transport owns probe packet construction, send with don't fragment, and confirmation through its loss-recovery path.

Typical integration:

1. Call net_dplpmtud_init_path() when a connection is established.
2. Use net_dplpmtud_get_path_mtu() to size outgoing datagrams.
3. When net_dplpmtud_get_path_probe_size() returns a value greater than zero and net_dplpmtud_path_probe_in_flight() is false, send a probe datagram at that size with IP_DONTFRAG / IPV6_DONTFRAG enabled.
4. Call net_dplpmtud_on_path_probe_sent() before sending the probe, then net_dplpmtud_on_path_probe_acked() or net_dplpmtud_on_path_probe_lost().

ICMP Packet Too Big (PTB) updates through the PMTU destination cache are applied automatically. Validated probe results are written back into that cache for other stack users.

QUIC uses this API internally; see :ref:quic_dplpmtud.

Macro Definition Documentation

NET_DPLPMTUD_BASE_PLPMTU

#define NET_DPLPMTUD_BASE_PLPMTU   1200U

#include <zephyr/net/dplpmtud.h>

Default base PLPMTU from RFC 8899/RFC 9000 for UDP-based transports.

Enumeration Type Documentation

net_dplpmtud_state

enum net_dplpmtud_state

#include <zephyr/net/dplpmtud.h>

DPLPMTUD search state.

Enumerator
NET_DPLPMTUD_STATE_BASE	Path is using the base PLPMTU.
NET_DPLPMTUD_STATE_SEARCHING	Path is actively probing for a larger PLPMTU.
NET_DPLPMTUD_STATE_SEARCH_COMPLETE	Path has no larger probe candidate.
NET_DPLPMTUD_STATE_ERROR	Path fell back after black-hole detection.

Function Documentation

net_dplpmtud_get_path_mtu()

int net_dplpmtud_get_path_mtu

(

struct net_dplpmtud_path *

path

)

#include <zephyr/net/dplpmtud.h>

Get the currently validated PLPMTU for a path.

The path must have been initialized with net_dplpmtud_init_path(). This call does not create per-destination DPLPMTUD state.

Parameters

path	Initialized path handle

Returns

Validated PLPMTU on success, negative errno otherwise

net_dplpmtud_get_path_probe_size()

int net_dplpmtud_get_path_probe_size

(

struct net_dplpmtud_path *

path

)

#include <zephyr/net/dplpmtud.h>

Get the next probe size a transport may transmit for a path.

The path must have been initialized with net_dplpmtud_init_path(). This call does not create per-destination DPLPMTUD state.

Parameters

path	Initialized path handle

Returns

Next probe size, 0 if no probe is currently needed, negative errno on error

net_dplpmtud_init_path()

int net_dplpmtud_init_path	(	struct net_dplpmtud_path *	path,
		const struct net_sockaddr *	dst,
		uint16_t	max_plpmtu )

#include <zephyr/net/dplpmtud.h>

Initialize a DPLPMTUD path handle for a remote destination.

Parameters

path	Path handle to initialize
dst	Remote destination address
max_plpmtu	Transport-local maximum PLPMTU, or 0 if uncapped

Return values

0	on success
-EINVAL	if an argument is invalid
-ENOMEM	if no DPLPMTUD state entry can be created

net_dplpmtud_note_path_blackhole()

void net_dplpmtud_note_path_blackhole

(

struct net_dplpmtud_path *

path

)

#include <zephyr/net/dplpmtud.h>

Report black-hole fallback for a path.

Resets the validated PLPMTU toward the base size, stops probing, and records the path in the error state. Transports may also call this when they detect a black hole without an ICMP PTB.

Parameters

path	Initialized path handle

net_dplpmtud_on_path_probe_acked()

int net_dplpmtud_on_path_probe_acked	(	struct net_dplpmtud_path *	path,
		uint16_t	probe_size )

#include <zephyr/net/dplpmtud.h>

Report that a probe was acknowledged for a path.

Parameters

path	Initialized path handle
probe_size	Probe size acknowledged by the transport

Return values

0	on success
negative	errno otherwise

net_dplpmtud_on_path_probe_lost()

int net_dplpmtud_on_path_probe_lost	(	struct net_dplpmtud_path *	path,
		uint16_t	probe_size )

#include <zephyr/net/dplpmtud.h>

Report that a probe was lost for a path.

Parameters

path	Initialized path handle
probe_size	Probe size declared lost by the transport

Return values

0	on success
negative	errno otherwise

net_dplpmtud_on_path_probe_sent()

int net_dplpmtud_on_path_probe_sent	(	struct net_dplpmtud_path *	path,
		uint16_t	probe_size )

#include <zephyr/net/dplpmtud.h>

Report that a probe has been sent for a path.

Parameters

path	Initialized path handle
probe_size	Probe size sent by the transport

Return values

0	on success
-EINVAL	if an argument is invalid
-EMSGSIZE	if the probe exceeds the transport-local path limit
negative	errno from the DPLPMTUD core otherwise

net_dplpmtud_path_probe_in_flight()

bool net_dplpmtud_path_probe_in_flight

(

struct net_dplpmtud_path *

path

)

#include <zephyr/net/dplpmtud.h>

Check whether a probe is currently in flight for a path.

The path must have been initialized with net_dplpmtud_init_path(). This call does not create per-destination DPLPMTUD state.

Parameters

path	Initialized path handle

Returns

true if a probe is in flight, false otherwise

net_dplpmtud_set_path_max_plpmtu()

void net_dplpmtud_set_path_max_plpmtu	(	struct net_dplpmtud_path *	path,
		uint16_t	max_plpmtu )

#include <zephyr/net/dplpmtud.h>

Update the transport-local maximum PLPMTU for a path.

Parameters

path	Initialized path handle
max_plpmtu	Transport-local maximum PLPMTU, or 0 if uncapped