The UDP wire protocol: what a received datagram looks like in the ring, and how one goes in and comes back out. More...

#include "endian/endian.h"
#include "memoria_anularis/memoria_anularis.h"
#include "octetus_introitus_exitus/octetus_introitus_exitus.h"
#include "shared/ip/ip.h"

Classes
struct	protocore_udp_dgram
	Who a queued datagram is from or to, and how long its payload is. More...

Macros
#define	PROTOCORE_UDP_DGRAM_HDR 21u
	Bytes a queued datagram spends on its header, ahead of the payload.

Functions
PROTOCORE_INLINE void	protocore_udp_dgram_encode (mmgr_span w, const protocore_udp_dgram d)
	Write the header of `d` into `w` at its cursor.

PROTOCORE_INLINE proto_bool	protocore_udp_dgram_decode (mmgr_cspan r, protocore_udp_dgram d)
	Read a header out of `r` at its cursor into `d`.

PROTOCORE_INLINE proto_bool	protocore_udp_dgram_take (mmgr_ring ring, uint8_t hdr, protocore_udp_dgram d, uint8_t stage, size_t stage_cap)
	Dequeue one datagram: `d` takes the header, `stage` takes the payload.

Detailed Description

The UDP wire protocol: what a received datagram looks like in the ring, and how one goes in and comes back out.

A datagram is a message, so a ring of them carries a fixed 21-byte header ahead of each payload rather than a byte stream:

offset  width  field
0       1      family   4 for IPv4, 6 for IPv6
1       2      port     big-endian
3       2      len      big-endian, payload bytes that follow the header
5       16     addr     network order, IPv4 in the first four
21      len    payload

Every field is written and read at a stated width in network byte order, so the bytes in the ring are the same bytes on every target. The header is built through an mmgr_span and read through an mmgr_cspan, which carry the bound and latch an overrun.

The layout is the contract, so it is published rather than opaque. Internal to transport/udp: no table, no exported symbol.

Author: Douglas Quigg (dstroy0)

Date: 2026

Definition in file common.h.

Macro Definition Documentation

◆ PROTOCORE_UDP_DGRAM_HDR

#define PROTOCORE_UDP_DGRAM_HDR 21u

Bytes a queued datagram spends on its header, ahead of the payload.

Definition at line 41 of file common.h.

Function Documentation

◆ protocore_udp_dgram_encode()

PROTOCORE_INLINE void protocore_udp_dgram_encode	(	mmgr_span *	w,
		const protocore_udp_dgram *	d
	)

Write the header of d into w at its cursor.

Definition at line 52 of file common.h.

References protocore_udp_dgram::addr, protocore_ip::bytes, protocore_ip::family, protocore_udp_dgram::len, and protocore_udp_dgram::port.

◆ protocore_udp_dgram_decode()

PROTOCORE_INLINE proto_bool protocore_udp_dgram_decode	(	mmgr_cspan *	r,
		protocore_udp_dgram *	d
	)

Read a header out of r at its cursor into d.

A family byte that is neither 4 nor 6 leaves the address empty, so a caller cannot route on a value the parser did not recognize.

Definition at line 71 of file common.h.

References protocore_udp_dgram::addr, protocore_ip::bytes, protocore_ip::family, protocore_udp_dgram::len, protocore_udp_dgram::port, PROTO_FALSE, PROTO_TRUE, PROTOCORE_IP_NONE, PROTOCORE_IP_V4, and PROTOCORE_IP_V6.

Referenced by protocore_udp_dgram_take().

◆ protocore_udp_dgram_take()

PROTOCORE_INLINE proto_bool protocore_udp_dgram_take	(	mmgr_ring *	ring,
		uint8_t *	hdr,
		protocore_udp_dgram *	d,
		uint8_t *	stage,
		size_t	stage_cap
	)

Dequeue one datagram: d takes the header, stage takes the payload.

hdr is caller-owned staging of at least PROTOCORE_UDP_DGRAM_HDR bytes, written only by the consumer. Peeks the header, consumes it, then reads exactly its payload length, so the tail always lands on the next entry boundary. Reports false when the ring holds no whole entry.

Definition at line 109 of file common.h.

References protocore_udp_dgram::len, PROTO_FALSE, PROTO_TRUE, protocore_udp_dgram_decode(), and PROTOCORE_UDP_DGRAM_HDR.

Classes

Macros