platform_net.h File Reference

Canonical C ABI for the nros platform networking surface. More...

#include <stdint.h>
#include <stddef.h>
#include "nros/platform.h"

Include dependency graph for platform_net.h:

Go to the source code of this file.

Macros
#define	NROS_PLATFORM_NET_SOCKET_ERROR   ((size_t) -1)

Functions
void	nros_platform_network_poll (void)
int8_t	nros_platform_socket_accept (const void *sock_in, void *sock_out)
void	nros_platform_socket_close (void *sock)
int8_t	nros_platform_socket_set_non_blocking (const void *sock)
int8_t	nros_platform_socket_wait_event (void *peers, void *mutex)
void	nros_platform_tcp_close (void *sock)
int8_t	nros_platform_tcp_create_endpoint (void *ep, const uint8_t *address, const uint8_t *port)
void	nros_platform_tcp_free_endpoint (void *ep)
int8_t	nros_platform_tcp_listen (void *sock, const void *endpoint)
int8_t	nros_platform_tcp_open (void *sock, const void *endpoint, uint32_t timeout_ms)
size_t	nros_platform_tcp_read (const void *sock, uint8_t *buf, size_t len)
size_t	nros_platform_tcp_read_exact (const void *sock, uint8_t *buf, size_t len)
size_t	nros_platform_tcp_send (const void *sock, const uint8_t *buf, size_t len)
int8_t	nros_platform_tcp_set_rx_notify (const void *sock, void(*notify)(void *ctx), void *ctx)
void	nros_platform_udp_close (void *sock)
int8_t	nros_platform_udp_create_endpoint (void *ep, const uint8_t *address, const uint8_t *port)
void	nros_platform_udp_free_endpoint (void *ep)
int8_t	nros_platform_udp_listen (void *sock, const void *endpoint, uint32_t timeout_ms)
void	nros_platform_udp_mcast_close (void *sockrecv, void *socksend, const void *rep, const void *lep)
int8_t	nros_platform_udp_mcast_listen (void *sock, const void *endpoint, uint32_t timeout_ms, const uint8_t *iface, const uint8_t *join)
int8_t	nros_platform_udp_mcast_open (void *sock, const void *endpoint, void *lep, uint32_t timeout_ms, const uint8_t *iface)
size_t	nros_platform_udp_mcast_read (const void *sock, uint8_t *buf, size_t len, const void *lep, void *addr)
size_t	nros_platform_udp_mcast_read_exact (const void *sock, uint8_t *buf, size_t len, const void *lep, void *addr)
size_t	nros_platform_udp_mcast_send (const void *sock, const uint8_t *buf, size_t len, const void *endpoint)
int8_t	nros_platform_udp_open (void *sock, const void *endpoint, uint32_t timeout_ms)
size_t	nros_platform_udp_read (const void *sock, uint8_t *buf, size_t len)
size_t	nros_platform_udp_read_exact (const void *sock, uint8_t *buf, size_t len)
int32_t	nros_platform_udp_readiness_handle (const void *sock)
size_t	nros_platform_udp_send (const void *sock, const uint8_t *buf, size_t len, const void *endpoint)
void	nros_platform_udp_set_recv_timeout (const void *sock, uint32_t timeout_ms)
int8_t	nros_platform_udp_set_rx_notify (const void *sock, void(*notify)(void *ctx), void *ctx)

Detailed Description

Canonical C ABI for the nros platform networking surface.

Companion to <nros/platform.h>; sits beside the core 39-symbol platform ABI as the network interface zenoh-pico and the XRCE-DDS transports use. Carved into a separate header because bare-metal targets without a network stack can omit it.

Sockets + endpoints

Sockets and endpoints are opaque storage pointers. The application allocates the bytes (size known to the implementor; matches zenoh-pico's _z_sys_net_socket_t / _z_sys_net_endpoint_t). The implementation writes its handle into the supplied storage. read_* and send return (size_t) -1 on error, otherwise the number of bytes transferred (zero is a valid short-read result).

Timeout semantics

Read functions inherit the socket's recv timeout (set via set_recv_timeout). 0 ms means block indefinitely; non-zero is an upper bound on per-call duration.

Optional capabilities

nros_platform_udp_listen and udp_multicast_* are optional. A platform that doesn't implement them supplies a stub that returns -1 (or (size_t) -1 on the read/send variants); higher layers detect the failure and fall back. network_poll exists for platforms with a non-OS network stack (smoltcp on bare-metal) — POSIX / Zephyr / NuttX / FreeRTOS+lwIP / ThreadX+NetXDuo provide a no-op stub.

Macro Definition Documentation

NROS_PLATFORM_NET_SOCKET_ERROR

#define NROS_PLATFORM_NET_SOCKET_ERROR   ((size_t) -1)

Function Documentation

nros_platform_network_poll()

void nros_platform_network_poll

(

void

)

Pump the underlying network stack to process pending I/O. No-op on platforms with a kernel-driven socket layer (POSIX, Zephyr, lwIP, NetX Duo). Bare-metal smoltcp targets advance the stack from this entry point.

nros_platform_socket_accept()

int8_t nros_platform_socket_accept	(	const void *	sock_in,
		void *	sock_out )

Accept a pending connection from sock_in into sock_out.

nros_platform_socket_close()

void nros_platform_socket_close

(

void *

sock

)

Socket-layer shutdown + close. Distinct from nros_platform_tcp_close because zenoh-pico's helper layer exposes both.

nros_platform_socket_set_non_blocking()

int8_t nros_platform_socket_set_non_blocking

(

const void *

sock

)

Switch a socket to non-blocking mode.

nros_platform_socket_wait_event()

int8_t nros_platform_socket_wait_event	(	void *	peers,
		void *	mutex )

Wait for socket events on a multi-peer set. Optional on platforms without a poll/select primitive.

nros_platform_tcp_close()

void nros_platform_tcp_close

(

void *

sock

)

Close a TCP socket.

nros_platform_tcp_create_endpoint()

int8_t nros_platform_tcp_create_endpoint	(	void *	ep,
		const uint8_t *	address,
		const uint8_t *	port )

Resolve (address, port) strings into the caller-allocated endpoint storage at ep. Both strings are NUL-terminated.

nros_platform_tcp_free_endpoint()

void nros_platform_tcp_free_endpoint

(

void *

ep

)

Release any resources held by the endpoint at ep.

nros_platform_tcp_listen()

int8_t nros_platform_tcp_listen	(	void *	sock,
		const void *	endpoint )

Open a listening TCP socket bound to endpoint.

nros_platform_tcp_open()

int8_t nros_platform_tcp_open	(	void *	sock,
		const void *	endpoint,
		uint32_t	timeout_ms )

Open a TCP client connection to endpoint.

nros_platform_tcp_read()

size_t nros_platform_tcp_read	(	const void *	sock,
		uint8_t *	buf,
		size_t	len )

Read up to len bytes. Returns bytes received, or NROS_PLATFORM_NET_SOCKET_ERROR on error.

nros_platform_tcp_read_exact()

size_t nros_platform_tcp_read_exact	(	const void *	sock,
		uint8_t *	buf,
		size_t	len )

Read exactly len bytes. Returns len on success, or NROS_PLATFORM_NET_SOCKET_ERROR on error.

nros_platform_tcp_send()

size_t nros_platform_tcp_send	(	const void *	sock,
		const uint8_t *	buf,
		size_t	len )

Send len bytes. Returns bytes sent, or NROS_PLATFORM_NET_SOCKET_ERROR on error.

nros_platform_tcp_set_rx_notify()

int8_t nros_platform_tcp_set_rx_notify	(	const void *	sock,
		void(*	notify )(void *ctx),
		void *	ctx )

phase-521 W6 (RFC-0113 D4) — install (notify != NULL) or remove the receive notification on a connected TCP socket: the stack calls notify(ctx) each time data is queued on it, from the stack's own context (NetX's IP thread), so notify must only signal. Data already queued at install calls it once before this returns; once a removal returns, the previous notify is never called again. A zenoh session in CALLER mode over sock reports this as NROS_RMW_READINESS_NOTIFY.

Returns 0 when installed (or removed), -1 where the stack offers no such hook (every stack whose zenoh sessions read the link on their own thread needs none).

nros_platform_udp_close()

void nros_platform_udp_close

(

void *

sock

)

nros_platform_udp_create_endpoint()

int8_t nros_platform_udp_create_endpoint	(	void *	ep,
		const uint8_t *	address,
		const uint8_t *	port )

nros_platform_udp_free_endpoint()

void nros_platform_udp_free_endpoint

(

void *

ep

)

nros_platform_udp_listen()

int8_t nros_platform_udp_listen	(	void *	sock,
		const void *	endpoint,
		uint32_t	timeout_ms )

Bind a UDP socket in listen / server mode. Optional — return -1 on platforms that don't expose a UDP-server primitive.

nros_platform_udp_mcast_close()

void nros_platform_udp_mcast_close	(	void *	sockrecv,
		void *	socksend,
		const void *	rep,
		const void *	lep )

nros_platform_udp_mcast_listen()

int8_t nros_platform_udp_mcast_listen	(	void *	sock,
		const void *	endpoint,
		uint32_t	timeout_ms,
		const uint8_t *	iface,
		const uint8_t *	join )

nros_platform_udp_mcast_open()

int8_t nros_platform_udp_mcast_open	(	void *	sock,
		const void *	endpoint,
		void *	lep,
		uint32_t	timeout_ms,
		const uint8_t *	iface )

nros_platform_udp_mcast_read()

size_t nros_platform_udp_mcast_read	(	const void *	sock,
		uint8_t *	buf,
		size_t	len,
		const void *	lep,
		void *	addr )

nros_platform_udp_mcast_read_exact()

size_t nros_platform_udp_mcast_read_exact	(	const void *	sock,
		uint8_t *	buf,
		size_t	len,
		const void *	lep,
		void *	addr )

nros_platform_udp_mcast_send()

size_t nros_platform_udp_mcast_send	(	const void *	sock,
		const uint8_t *	buf,
		size_t	len,
		const void *	endpoint )

nros_platform_udp_open()

int8_t nros_platform_udp_open	(	void *	sock,
		const void *	endpoint,
		uint32_t	timeout_ms )

nros_platform_udp_read()

size_t nros_platform_udp_read	(	const void *	sock,
		uint8_t *	buf,
		size_t	len )

nros_platform_udp_read_exact()

size_t nros_platform_udp_read_exact	(	const void *	sock,
		uint8_t *	buf,
		size_t	len )

nros_platform_udp_readiness_handle()

int32_t nros_platform_udp_readiness_handle

(

const void *

sock

)

phase-521 W4 (RFC-0113 D4) — the OS handle that becomes readable when a datagram arrives on sock: its file descriptor on POSIX and NuttX. An RMW session reports it as NROS_RMW_READINESS_WAITABLE, and the executor parks on it (nros_platform_wake_park_handles_us) instead of blocking in read. Returns -1 where the stack has no such handle (lwIP, NetX, a bare-metal stack); those report readiness as a Notify instead.

nros_platform_udp_send()

size_t nros_platform_udp_send	(	const void *	sock,
		const uint8_t *	buf,
		size_t	len,
		const void *	endpoint )

Send len bytes to endpoint.

nros_platform_udp_set_recv_timeout()

void nros_platform_udp_set_recv_timeout	(	const void *	sock,
		uint32_t	timeout_ms )

Set the recv timeout in milliseconds; 0 means block indefinitely.

nros_platform_udp_set_rx_notify()

int8_t nros_platform_udp_set_rx_notify	(	const void *	sock,
		void(*	notify )(void *ctx),
		void *	ctx )

phase-521 W4 (RFC-0113 D4) — install (notify != NULL) or remove the receive notification on sock: the stack calls notify(ctx) each time a datagram is queued on it, from the stack's own context (lwIP's tcpip thread, NetX's IP thread), so notify must only signal. Data already queued at install calls it once before this returns; once a removal returns, the previous notify is never called again. An RMW session over sock reports this as NROS_RMW_READINESS_NOTIFY.

Returns 0 when installed (or removed), -1 where the stack offers no such hook — POSIX/NuttX, which have nros_platform_udp_readiness_handle instead, and stacks not yet given one.