feat: send the first record — passthrough buffer over UDP

The smallest wiring that delivers anything: a UDP sender over lwIP's raw API,
with a passthrough buffer in front of it. Passthrough means Log sends inline on
the calling task — no queue, no background drain, nothing to service — so this is
the cheapest thing that can be called working.

  Flash  +4,716 B
  RAM      +372 B
  Log stack  +16 B

What the collector received:

  <134>1 - - - - BOOT - device started

Timestamp, hostname, app-name and procid are all NILVALUE. RFC 5424 defines one
for each, so the record is valid and syslog-ng parses it — filling them in is a
later stage with a cost of its own, and separating the two is what lets the cost
of each be seen.

The three bad-config reports from the previous stage are gone, which is the other
half of that stage's point.

Two details worth knowing. Every lwIP raw call has to happen on the thread that
owns the lwIP core; lwipopts.h sets LWIP_TCPIP_CORE_LOCKING, so taking the core
lock in the caller's own task is simpler than posting to the tcpip mailbox and is
unconditionally synchronous, which the marshal contract requires. And the
collector address is a numeric literal, which keeps the resolver numeric-only —
no DNS, so no LWIP_DNS and no resolver component compiled in.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: DavidCozens

README.md

@@ -10,15 +10,16 @@ It builds on a baseline that simulates the sort of device you might be adding th
 measures itself: see [docs/baseline.md](docs/baseline.md) for what the baseline is, how the
 figures are made, and how to run it.
 
-## This stage — Logger created
+## This stage — First record
 
-The logger exists, with nothing wired into it. Both collaborators that decide where a record goes
-are absent, so the handler from the previous stage reports them and the run report carries the
-faults — which is the point of creating it empty first.
+A UDP sender over lwIP, with a passthrough buffer in front of it: `Log` sends inline on the calling
+task, so there is no queue and nothing to drain. The collector receives a valid RFC 5424 record
+with timestamp, hostname, app-name and procid all left as `-`, which the RFC allows and a
+collector accepts.
 
 <!-- STAGE-COST:START (generated by scripts/gen-cost-table.py — do not edit by hand) -->
 
-**Cost above baseline: Flash +1,036 B, RAM +180 B.**
+**Cost above baseline: Flash +4,716 B, RAM +372 B.**
 
 <!-- STAGE-COST:END -->
 
@@ -35,6 +36,7 @@ committed as [`run-report.md`](run-report.md), and rewritten by every stage.
 | Linked | the core library and lwIP raw-mode networking, linked but not yet called | +0 | +0 |
 | Error handler | a fault inside the logger reaches the console instead of being silent | +404 | +8 |
 | Logger created | the logger object, reporting exactly what is still missing from it | +1,036 | +180 |
+| First record | a valid RFC 5424 record on the wire, over UDP | +4,716 | +372 |
 
 *Deltas are bytes above the baseline, which is itself Flash 350,308 B, RAM 111,192 B.*
 

app/main.c

@@ -66,9 +66,14 @@ static void HarnessTask(void* parameters)
     bool logIdle = LogTask_WaitIdle(2000U);
     bool serviceIdle = ServiceTask_WaitIdle(2000U);
 
+    /* Emitted before the figures are taken: the record goes out inline on the
+     * log task's stack, so its stack figure only means anything afterwards. */
+    bool logged = LogTask_EmitOnce(5000U);
+    (void) printf("[device]   first record logged: %s\n", logged ? "yes" : "FAILED");
+
     (void) Measure_Report();
 
-    bool ready = simReady && logIdle && serviceIdle;
+    bool ready = simReady && logIdle && serviceIdle && logged;
     (void) printf("[device] %s\n", ready ? "ready" : "FAILED");
     SemihostingExit(ready ? 0 : 1);
 }
@@ -98,8 +103,6 @@ int main(void)
     /* Before the first _Create — see SyslogErrorHandler.h for why that matters. */
     SyslogErrorHandler_Install();
 
-    Syslog_Start();
-
     /* lwIP tcpip thread + core-lock mutex + mbox. Pre-scheduler safe. */
     tcpip_init(NULL, NULL);
 
@@ -111,6 +114,11 @@ int main(void)
         SemihostingExit(1);
     }
 
+    /* After tcpip_init, not before: the marshal Syslog_Start installs takes the
+     * lwIP core lock, and tcpip_init is what creates it. Nothing is sent here —
+     * the sender resolves and opens lazily on its first record. */
+    Syslog_Start();
+
     if (!LogTask_Create() || !ServiceTask_Create())
     {
         (void) printf("[device] FATAL: application task create failed\n");

app/syslog/Syslog.c

@@ -1,26 +1,86 @@
-/* See Syslog.h. Created with nothing wired into it, on purpose: a missing
- * collaborator is substituted with its Null object and reported, and the run
- * report is where that shows. */
+/* See Syslog.h.
+ *
+ * The smallest wiring that delivers: a UDP sender over lwIP, with a passthrough
+ * buffer in front of it. Passthrough means Log sends inline on the calling task
+ * — no queue, no background drain, nothing to service.
+ *
+ * Timestamp, hostname, app-name and procid are left unset. RFC 5424 defines a
+ * NILVALUE for each, so a record carrying "-" for them is valid and a collector
+ * accepts it. */
 
 #include "Syslog.h"
 
 #include "SolidSyslogConfig.h"
+#include "SolidSyslogEndpoint.h"
+#include "SolidSyslogEndpointHost.h"
+#include "SolidSyslogLwipRawAddress.h"
+#include "SolidSyslogLwipRawDatagram.h"
+#include "SolidSyslogLwipRawMarshal.h"
+#include "SolidSyslogLwipRawResolver.h"
+#include "SolidSyslogNullStore.h"
+#include "SolidSyslogPassthroughBuffer.h"
+#include "SolidSyslogUdpSender.h"
+
+#include "lwip/tcpip.h"
 
 #include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+/* The collector, reached through QEMU's slirp gateway. A numeric literal keeps
+ * the resolver numeric-only — no DNS, so no LWIP_DNS and no DNS resolver
+ * component to compile. */
+#define SYSLOG_COLLECTOR_HOST "10.0.2.2"
+#define SYSLOG_COLLECTOR_PORT ((uint16_t) 5514U)
 
 static struct SolidSyslog* s_logger = NULL;
 
+/* Every lwIP Raw call the datagram makes has to happen on the thread that owns
+ * the lwIP core. lwipopts.h sets LWIP_TCPIP_CORE_LOCKING, so taking the core
+ * lock in the caller's own task is simpler and cheaper than posting to the tcpip
+ * mailbox — and unconditionally synchronous, which the marshal contract
+ * requires. The lock is recursive and these callbacks never re-marshal, so it
+ * cannot deadlock against itself. */
+static void LwipCoreLockMarshal(SolidSyslogLwipRawCallback callback, void* context)
+{
+    LOCK_TCPIP_CORE();
+    callback(context);
+    UNLOCK_TCPIP_CORE();
+}
+
+/* Pulled by the sender when it connects, not on every send. Host is a bounded
+ * sink rather than a raw buffer, so a destination cannot overrun the field. */
+static void CollectorEndpoint(struct SolidSyslogEndpoint* endpoint, void* context)
+{
+    (void) context;
+
+    SolidSyslogEndpointHost_String(endpoint->Host, SYSLOG_COLLECTOR_HOST, strlen(SYSLOG_COLLECTOR_HOST));
+    endpoint->Port = SYSLOG_COLLECTOR_PORT;
+}
+
 void Syslog_Start(void)
 {
-    /* Buffer and Sender decide where a record goes. NULL is "not supplied" and
-     * is reported; a collaborator deliberately done without is passed as its
-     * Null object instead, which is how the library tells the two apart. */
+    SolidSyslogLwipRaw_SetMarshal(LwipCoreLockMarshal);
+
+    /* A numeric resolver to parse the literal, a datagram for the socket, and an
+     * address slot for the resolver to write into. No EndpointVersion — this
+     * collector never moves, so the sender resolves once and pins it. */
+    struct SolidSyslogUdpSenderConfig senderConfig = {
+        .Resolver = SolidSyslogLwipRawResolver_Create(),
+        .Datagram = SolidSyslogLwipRawDatagram_Create(),
+        .Address = SolidSyslogLwipRawAddress_Create(),
+        .Endpoint = CollectorEndpoint,
+    };
+    struct SolidSyslogSender* sender = SolidSyslogUdpSender_Create(&senderConfig);
+
     struct SolidSyslogConfig config = {
-        .Buffer = NULL,
-        .Sender = NULL,
+        .Buffer = SolidSyslogPassthroughBuffer_Create(sender),
+        .Sender = sender,
+        /* No store-and-forward here. The Null object rather than NULL is how
+         * that is said out loud — NULL is reported as a fault. */
+        .Store = SolidSyslogNullStore_Get(),
     };
 
-    /* No null check — Create returns a shared null instance rather than NULL. */
     s_logger = SolidSyslog_Create(&config);
 }
 

app/tasks/LogTask.c

@@ -2,6 +2,11 @@
 
 #include "LogTask.h"
 
+#include "Syslog.h"
+
+#include "SolidSyslog.h"
+#include "SolidSyslogPrival.h"
+
 #include "AppConfig.h"
 
 #include "semphr.h"
@@ -26,7 +31,16 @@ static void LogTask_Entry(void* parameters)
     {
         if (xSemaphoreTake(s_emitRequested, portMAX_DELAY) == pdTRUE)
         {
-            /* Nothing to say: this device has no logger. */
+            const struct SolidSyslogMessage message = {
+                .Facility = SOLIDSYSLOG_FACILITY_LOCAL0,
+                .Severity = SOLIDSYSLOG_SEVERITY_INFORMATIONAL,
+                .MessageId = "BOOT",
+                .Msg = "device started",
+            };
+
+            /* Sends inline on this stack and returns once it is done. */
+            SolidSyslog_Log(Syslog_Handle(), &message);
+
             (void) xSemaphoreGive(s_emitDone);
         }
     }

app/tasks/LogTask.h

@@ -22,11 +22,12 @@ extern "C"
      * high-water mark reflects something real. */
     bool LogTask_WaitIdle(uint32_t timeoutMs);
 
-    /* Emit one record and wait for it to finish. Nothing to emit yet. */
+    /* Emit one record and wait for it to finish. */
     bool LogTask_EmitOnce(uint32_t timeoutMs);
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* APP_TASKS_LOG_TASK_H */
+

measurements/stages.tsv

@@ -13,3 +13,4 @@ Baseline	Baseline	a device that already networks, stores, and holds an mTLS sess
 linked	Linked	the core library and lwIP raw-mode networking, linked but not yet called
 error-handler	Error handler	a fault inside the logger reaches the console instead of being silent
 logger	Logger created	the logger object, reporting exactly what is still missing from it
+udp	First record	a valid RFC 5424 record on the wire, over UDP

measurements/udp.csv

@@ -0,0 +1,13 @@
+# udp figures (bytes) — captured by scripts/run.sh (CAPTURE=1).
+# The device reads measurements/Baseline.csv as its frozen baseline and reports current-minus-Baseline.
+flash_text,354576
+flash_data,448
+static_bss,111116
+heap_used,4440
+mbedtls_peak,21292
+mbedtls_free,11476
+lwip_mem_free,7576
+lwip_pbufs_free,13
+stack_log,136
+stack_service,52
+stack_harness,2848

run-report.md

@@ -1,28 +1,26 @@
-# solid-syslog-example — run (logger)
+# solid-syslog-example — run (udp)
 
 ## Device (self-measured)
 
 ```text
 [device] solid-syslog-example (FreeRTOS + lwIP + mbedTLS + FatFs)
-[syslog] CRITICAL SolidSyslog bad-config (detail 1)
-[syslog] CRITICAL SolidSyslog bad-config (detail 2)
-[syslog] CRITICAL SolidSyslog bad-config (detail 3)
 [device] starting simulated existing application...
 [sim] broker session to 10.0.2.2:8883: TLSv1.3, TLS1-3-CHACHA20-POLY1305-SHA256
 [device]   sim app (lwIP up, FatFs mounted, broker session held over mTLS): ready
+[device]   first record logged: yes
 [report] --- SolidSyslog cost above baseline (simulated existing application) ---
 [report] key,current,baseline,used_above_baseline
-[report] flash_text,350960,349992,968
-[report] flash_data,384,316,68
-[report] static_bss,110988,110876,112
+[report] flash_text,354576,349992,4584
+[report] flash_data,448,316,132
+[report] static_bss,111116,110876,240
 [report] heap_used,4440,4440,0
-[report] mbedtls_peak,21228,21332,-104
-[report] mbedtls_free,11540,11436,104
+[report] mbedtls_peak,21336,21332,4
+[report] mbedtls_free,11432,11436,-4
 [report] lwip_mem_free,7576,7576,0
-[report] lwip_pbufs_free,13,14,-1
-[report] stack_log,120,120,0
+[report] lwip_pbufs_free,14,14,0
+[report] stack_log,136,120,16
 [report] stack_service,52,52,0
-[report] stack_harness,2840,2840,0
+[report] stack_harness,2848,2840,8
 [report] --- end ---
 [device] ready
 ```
@@ -31,7 +29,7 @@
 
 ```text
    text	   data	    bss	    dec	    hex	filename
- 350952	    392	 110988	 462332	  70dfc	/w/build/baseline-cross/baseline.elf
+ 354568	    456	 111116	 466140	  71cdc	/w/build/baseline-cross/baseline.elf
 ```
 
 ## Listeners (proved before the device ran)
@@ -49,23 +47,24 @@
 ## Collector (syslog-ng) received
 
 ```text
-(nothing — this device sends no records yet)
+wire   <134>1 - - - - BOOT - device started
+parsed PRIORITY=134 TIMESTAMP=2026-07-29T07:13:03+00:00 HOSTNAME=localhost APP_NAME= PROCID= MSGID=BOOT STRUCTURED_DATA= MSG=device started
 ```
 
-## Self-check (vs measurements/logger.csv)
+## Self-check (vs measurements/udp.csv)
 
 ```text
-  OK    flash_text: 350960 (expected 350960, Δ0)
-  OK    flash_data: 384 (expected 384, Δ0)
-  OK    static_bss: 110988 (expected 110988, Δ0)
+  OK    flash_text: 354576 (expected 354576, Δ0)
+  OK    flash_data: 448 (expected 448, Δ0)
+  OK    static_bss: 111116 (expected 111116, Δ0)
   OK    heap_used: 4440 (expected 4440, Δ0)
-  OK    mbedtls_peak: 21228 (expected 21192, Δ36)
-  OK    mbedtls_free: 11540 (expected 11576, Δ36)
+  OK    mbedtls_peak: 21336 (expected 21292, Δ44)
+  OK    mbedtls_free: 11432 (expected 11476, Δ44)
   OK    lwip_mem_free: 7576 (expected 7576, Δ0)
-  OK    lwip_pbufs_free: 13 (expected 13, Δ0)
-  OK    stack_log: 120 (expected 120, Δ0)
+  OK    lwip_pbufs_free: 14 (expected 13, Δ1)
+  OK    stack_log: 136 (expected 136, Δ0)
   OK    stack_service: 52 (expected 52, Δ0)
-  OK    stack_harness: 2840 (expected 2840, Δ0)
+  OK    stack_harness: 2848 (expected 2848, Δ0)
 ```
 
 **RESULT: PASS**