lwIP (Raw API)

Setup

Platform/LwipRaw/ wraps the Raw API of lwIP (lwIP documentation). Its .c files compile against your lwipopts.h, so the adapter inherits your stack's configuration.

Fills the Resolver, Datagram and Stream roles, plus the address handle they share. A TLS platform layers over the TCP stream; the platform × capability matrix shows which provide it.

What it ships

Header	What it is
SolidSyslogLwipRawAddress.h	An lwIP destination-address handle wrapping an ip_addr_t plus port.
SolidSyslogLwipRawAddressErrors.h	Source identity for the LwipRawAddress adapter; the detail codes it reports are the portable ones in SolidSyslogAddressErrors.h.
SolidSyslogLwipRawDatagram.h	UDP transport over the lwIP Raw API, for a UdpSender.
SolidSyslogLwipRawDatagramErrors.h	Source identity for the LwipRawDatagram adapter; the detail codes it reports are the portable ones in SolidSyslogDatagramErrors.h.
SolidSyslogLwipRawDnsResolver.h	The lwIP Raw resolver for a collector named by name, resolving names and numeric addresses alike.
SolidSyslogLwipRawDnsResolverErrors.h	Source identity for the LwipRawDnsResolver adapter; the detail codes it reports are the portable ones in SolidSyslogResolverErrors.h.
SolidSyslogLwipRawMarshal.h	The marshal seam that pins the library's lwIP Raw API calls to the core-owning thread.
SolidSyslogLwipRawResolver.h	The lwIP Raw resolver for a collector named by address: it resolves nothing, it parses the numeric literal you configured.
SolidSyslogLwipRawResolverErrors.h	Source identity for the LwipRawResolver adapter; the detail codes it reports are the portable ones in SolidSyslogResolverErrors.h.
SolidSyslogLwipRawTcpStream.h	A TCP stream over the lwIP Raw API, for a StreamSender or as the byte transport under a TLS stream.
SolidSyslogLwipRawTcpStreamErrors.h	Source identity for the LwipRawTcpStream adapter; the detail codes it reports are the portable ones in SolidSyslogTcpStreamErrors.h.

The marshal

Not a role: SolidSyslogLwipRaw_SetMarshal is a process-global seam, not a component you wire into the config. Every lwIP call the Datagram and TcpStream make is routed through one marshal hop.

• NO_SYS=1 - bare metal, one execution context. Do nothing; the default direct-call marshal is correct.
• NO_SYS=0 - an RTOS tcpip thread (lwIP multithreading documentation). Call SolidSyslogLwipRaw_SetMarshal(fn) once at boot, before creating any adapter, passing a function that runs its callback on the core-owning thread.

The marshal must invoke its callback synchronously - the adapter reads results the moment the hop returns. A LOCK_TCPIP_CORE / UNLOCK_TCPIP_CORE pair satisfies that directly. Posting to lwIP's mailbox does not, in any of its forms: tcpip_callback_with_block blocks until the message is accepted, not until the callback runs, so a mailbox marshal has to wait for completion itself.

Requirements

The source calls lwIP only - no direct OS calls. The TCP stream's synchronous Open and the DNS resolver's bounded wait both need a sleep, injected as a SolidSyslogSleepFunction. Create either without one, and it reports a bad configuration and hands back the shared Null object, so no record is delivered.

Your lwipopts.h must enable the features the adapter wraps:

Setting	For
LWIP_RAW=1	the Raw API
LWIP_UDP=1	the UDP datagram
LWIP_TCP=1	the TCP stream
LWIP_DNS=1	the DNS resolver only

Also set ARP_QUEUEING=1 (else the first datagram to an unresolved peer is dropped), and size PBUF_POOL_SIZE / MEMP_NUM_TCP_PCB / MEMP_NUM_UDP_PCB to your instance counts. LWIP_TCP_KEEPALIVE=1 is worth setting but not required - see dead-peer detection below. IP_FRAG decides what becomes of a record too large for the path - see what becomes of an over-large record below.

Security behaviour and obligations

The transport carries syslog in clear

Neither the datagram nor the TCP stream provides confidentiality, integrity or peer authentication. TLS is a separate role filled by a different platform - the platform × capability matrix shows which - layered over this stream rather than replacing it.

The marshal is a correctness requirement, not a tuning knob

On a build with an lwIP thread (NO_SYS=0), every call this adapter makes must reach the core-owning context, and it must do so synchronously because results are read the moment the hop returns. An asynchronous marshal, or none at all, corrupts lwIP's internal state rather than failing cleanly. Install it once at boot, before any adapter is created.

What becomes of an over-large record

The datagram cannot tell an over-large datagram from any other send failure, which the Datagram contract permits, and it reports the unknown-path payload from MaxPayload because the stack exposes no path MTU.

A record above that size is offered to lwIP whole, and what happens to that first attempt is IP_FRAG's decision rather than the adapter's. Only the outcome where lwIP tells us the send failed is recoverable: the sender then recognises a record that could not have fitted, trims it on a UTF-8 codepoint boundary and sends again.

• IP_FRAG=1, lwIP's default: lwIP attempts to fragment the datagram and submits the fragments to your interface. Submission is reported as success, so the record is not trimmed - this is the case RFC 5426 §3.2 warns about, where a lost fragment costs the whole record and some collectors and middleboxes drop fragments outright.
• IP_FRAG=0: lwIP compiles the length check out of its send path altogether and hands the over-length packet to your driver. A driver that drops it and answers ERR_OK loses the record while the store counts it delivered; a driver that answers an error fails the send, and the record is then trimmed and delivered short.

Setting IP_FRAG=0 is therefore the configuration that lets an over-large record be recovered, and it depends on your driver reporting the rejection rather than swallowing it.

No record reaches that size at the default SOLIDSYSLOG_MAX_MESSAGE_SIZE. These fates apply where the tunable has been raised past what the datagram reports - noting that the tunable is library-wide rather than per-transport, so a value chosen for this path applies to every transport the instance uses.

Dead-peer detection is yours to size

The stream sets the keepalive timings on its own connection, so the SOLIDSYSLOG_TCP_KEEPALIVE_* tunables govern it and no other connection in your system is affected.

How much of that the stack honours depends on one lwipopts.h setting. LWIP_TCP_KEEPALIVE=1 makes the probe interval and count per-connection fields, and all three tunables apply. Without it those two are compile-time constants the stack applies to every connection, so the idle period is still yours and the other two come from TCP_KEEPINTVL_DEFAULT and TCP_KEEPCNT_DEFAULT. Either way a silent peer is first probed when the idle tunable elapses.

This governs the idle case only. A connection actually carrying records notices a dead peer sooner: lwIP's send buffer fills, the write fails, and the stream closes itself so the sender reconnects.

Resolution is trusted as the stack returns it

The DNS resolver forwards what lwIP answers. A deployment that cannot trust its DNS should give the collector a numeric address, so that no resolution step exists to be poisoned.

Pool sizing is yours, and exhaustion is silent at the stack

PBUF_POOL_SIZE, MEMP_NUM_TCP_PCB and MEMP_NUM_UDP_PCB must cover the instances you create alongside everything else using the stack. lwIP reports nothing when it runs out; what you see is the send failing, which reaches you as a delivery failure through the error handler rather than as anything naming the pool that was exhausted.