feat: install the SolidSyslog error handler

Nothing in the library fails loudly. A _Create that cannot succeed substitutes a
Null object and reports it rather than returning NULL, so a logger that has
silently stopped looks exactly like one with nothing to say. The handler is what
tells them apart, and it goes in before the first _Create rather than after
something looks wrong.

  Flash  +412 B
  RAM      +8 B

The handler prints to the same console as everything else, so a fault lands in
the run report next to the rest of what the device did. It names the four
lifecycle categories a misconfigured integration raises and prints the rest
numerically — a device reacting to those would switch on the category, not the
text.

It is more than an integration aid. The handler is the seam into the device's own
error and health reporting, and later stages use it at run time: an edge-triggered
warning when the collector becomes unreachable, a notice when delivery recovers.

The build gains one source file and its include directory. Nothing about how
SolidSyslog enters the build changes.

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

Author: DavidCozens

Makefile

@@ -50,7 +50,8 @@ APP_SRCS := \
 	$(APP_DIR)/platform/SemihostingIo.c \
 	$(APP_DIR)/net/EthernetIf.c \
 	$(APP_DIR)/storage/diskio.c \
-	$(APP_DIR)/storage/SemihostingDisk.c
+	$(APP_DIR)/storage/SemihostingDisk.c \
+	$(APP_DIR)/syslog/SyslogErrorHandler.c
 
 UPSTREAM_SRCS := \
 	$(FREERTOS_SRCS) \
@@ -71,6 +72,7 @@ APP_INCLUDES := \
 	-I$(APP_DIR)/net/smsc9220 \
 	-I$(APP_DIR)/platform \
 	-I$(APP_DIR)/storage \
+	-I$(APP_DIR)/syslog \
 	$(FREERTOS_INCLUDES) $(LWIP_INCLUDES) $(FATFS_INCLUDES) $(MBEDTLS_INCLUDES) \
 	$(SOLIDSYSLOG_INCLUDES)
 

README.md

@@ -10,28 +10,35 @@ 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 — Linked
+## This stage — Error handler
 
-SolidSyslog is linked into the application without any of it being called. The stage is broken out
-for clarity: it separates getting the build to accept the library from getting the device to use
-it, so anything that goes wrong here is a build problem and nothing else.
+Install the handler before any other call into SolidSyslog.
 
-The library ships `solidsyslog.mk`, so `make/solidsyslog.mk` names the platforms and includes it,
-and gets the source lists and include sets back. `SOLIDSYSLOG_PLATFORMS` names the platforms rather
-than letting the library infer them from the environment — lwIP alone, because nothing at this
-stage reaches any other pack. What is left is this build's own architecture: Core compiles against
-the library's own headers into an archive, and the platform sources compile with this device's
-flags and config headers.
+```c
+SolidSyslog_SetErrorHandler(OnSyslogError, NULL);
+```
 
-`--gc-sections` discards what nothing calls, so a platform pack that is linked but unused does not
-reach the image.
+Nothing in the library fails loudly. A `_Create` that cannot succeed substitutes a Null object and
+reports it rather than returning `NULL`, so a logger that has silently stopped looks exactly like
+one with nothing to say. The handler is what tells the two apart, which is why it goes in before
+the first `_Create` and not after something looks wrong. It reports many misconfiguration errors,
+and can save significant time while integrating.
 
-For now you need only the core and a network platform. The library has no release tag yet, so the
-pin is a commit.
+This is not only an integration aid. The handler is the seam into the device's own error and health
+reporting, and it stays valuable at run time: later stages raise an edge-triggered warning when the
+collector becomes unreachable and a notice when delivery recovers. Route it wherever the device
+already routes faults — here, the same console as everything else, so a fault lands in the run
+report next to the rest of what the device did.
+
+The handler names the four lifecycle categories a misconfigured integration raises and prints the
+rest numerically. A device reacting to a fault would switch on the category rather than the text.
+
+**When you need it.** Every device, and first. It is the only thing standing between a
+misconfigured logger and a silent one.
 
 <!-- STAGE-COST:START (generated by scripts/gen-cost-table.py — do not edit by hand) -->
 
-**Cost above baseline: Flash +0 B, RAM +0 B.**
+**Cost above baseline: Flash +412 B, RAM +8 B.**
 
 <!-- STAGE-COST:END -->
 
@@ -46,6 +53,7 @@ committed as [`run-report.md`](run-report.md), and rewritten by every stage.
 |---|---|---|---|
 | Baseline | a device that already networks, stores, and holds an mTLS session — before any syslog | — | — |
 | 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 | +412 | +8 |
 
 *Deltas are bytes above the baseline, which is itself Flash 350,124 B, RAM 111,192 B.*
 

app/main.c

@@ -9,6 +9,7 @@
 #include "SemihostingExit.h"
 #include "ServiceTask.h"
 #include "SimulatedExistingApp.h"
+#include "SyslogErrorHandler.h"
 
 #include "lwip/tcpip.h"
 
@@ -93,6 +94,9 @@ int main(void)
     CmsdkUart_Init(&UART_ACCESS, DEVICE_UART0_BASE);
     (void) printf("[device] solid-syslog-example (FreeRTOS + lwIP + mbedTLS + FatFs)\n");
 
+    /* Before the first _Create — see SyslogErrorHandler.h for why that matters. */
+    SyslogErrorHandler_Install();
+
     /* lwIP tcpip thread + core-lock mutex + mbox. Pre-scheduler safe. */
     tcpip_init(NULL, NULL);
 

app/syslog/SyslogErrorHandler.c

@@ -0,0 +1,89 @@
+/* See SyslogErrorHandler.h. Prints to the same console as the rest of the
+ * device, so a fault shows up in the run report next to everything else. */
+
+#include "SyslogErrorHandler.h"
+
+#include "SolidSyslogError.h"
+#include "SolidSyslogErrorCategory.h"
+#include "SolidSyslogPrival.h"
+
+#include <stdint.h>
+#include <stdio.h>
+
+static const char* SeverityName(enum SolidSyslogSeverity severity)
+{
+    switch (severity)
+    {
+        case SOLIDSYSLOG_SEVERITY_EMERGENCY:
+            return "EMERGENCY";
+        case SOLIDSYSLOG_SEVERITY_ALERT:
+            return "ALERT";
+        case SOLIDSYSLOG_SEVERITY_CRITICAL:
+            return "CRITICAL";
+        case SOLIDSYSLOG_SEVERITY_ERROR:
+            return "ERROR";
+        case SOLIDSYSLOG_SEVERITY_WARNING:
+            return "WARNING";
+        case SOLIDSYSLOG_SEVERITY_NOTICE:
+            return "NOTICE";
+        case SOLIDSYSLOG_SEVERITY_INFORMATIONAL:
+            return "INFO";
+        case SOLIDSYSLOG_SEVERITY_DEBUG:
+            return "DEBUG";
+    }
+    return "?";
+}
+
+/* The four a misconfigured integration raises. Role-specific categories sit in
+ * ranges above 0x0100 and print numerically. */
+static const char* CategoryName(uint16_t category)
+{
+    switch (category)
+    {
+        case SOLIDSYSLOG_CAT_BAD_CONFIG:
+            return "bad-config";
+        case SOLIDSYSLOG_CAT_BAD_ARGUMENT:
+            return "bad-argument";
+        case SOLIDSYSLOG_CAT_POOL_EXHAUSTED:
+            return "pool-exhausted";
+        case SOLIDSYSLOG_CAT_UNKNOWN_DESTROY:
+            return "unknown-destroy";
+        default:
+            return NULL;
+    }
+}
+
+static void OnSyslogError(void* context, const struct SolidSyslogErrorEvent* event)
+{
+    (void) context;
+
+    if (event == NULL)
+    {
+        return;
+    }
+
+    /* Sources are matched by pointer identity — Name is only ever a label, which
+     * is all it is used for here. */
+    const char* source = ((event->Source != NULL) && (event->Source->Name != NULL)) ? event->Source->Name : "?";
+    const char* category = CategoryName(event->Category);
+
+    if (category != NULL)
+    {
+        (void) printf("[syslog] %s %s %s (detail %ld)\n", SeverityName(event->Severity), source, category, (long) event->Detail);
+    }
+    else
+    {
+        (void) printf(
+            "[syslog] %s %s category 0x%04X (detail %ld)\n",
+            SeverityName(event->Severity),
+            source,
+            (unsigned int) event->Category,
+            (long) event->Detail
+        );
+    }
+}
+
+void SyslogErrorHandler_Install(void)
+{
+    SolidSyslog_SetErrorHandler(OnSyslogError, NULL);
+}

app/syslog/SyslogErrorHandler.h

@@ -0,0 +1,15 @@
+/* The device's reaction to a SolidSyslog internal fault.
+ *
+ * Nothing in the library fails loudly — a _Create that cannot succeed returns a
+ * Null object instead — so a logger that has silently stopped looks exactly like
+ * one with nothing to say. This is the only thing that tells them apart, which
+ * is why it goes in before the first _Create and not after something looks
+ * wrong. */
+#ifndef SYSLOG_ERROR_HANDLER_H
+#define SYSLOG_ERROR_HANDLER_H
+
+/** Install the handler on the library's single global slot. Call once, at
+ *  startup, before any SolidSyslog object is created. */
+void SyslogErrorHandler_Install(void);
+
+#endif /* SYSLOG_ERROR_HANDLER_H */

measurements/error-handler.csv

@@ -0,0 +1,13 @@
+# error-handler 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,350216
+flash_data,320
+static_bss,110880
+heap_used,4440
+mbedtls_peak,21304
+mbedtls_free,11464
+lwip_mem_free,7576
+lwip_pbufs_free,13
+stack_log,120
+stack_service,52
+stack_harness,2840

measurements/stages.tsv

@@ -11,3 +11,4 @@
 # after it.
 Baseline	Baseline	a device that already networks, stores, and holds an mTLS session — before any syslog
 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

run-report.md

@@ -1,4 +1,4 @@
-# solid-syslog-example — run (linked)
+# solid-syslog-example — run (error-handler)
 
 ## Device (self-measured)
 
@@ -9,14 +9,14 @@
 [device]   sim app (lwIP up, FatFs mounted, broker session held over mTLS): ready
 [report] --- SolidSyslog cost above baseline (simulated existing application) ---
 [report] key,current,baseline,used_above_baseline
-[report] flash_text,349808,349808,0
-[report] flash_data,316,316,0
-[report] static_bss,110876,110876,0
+[report] flash_text,350216,349808,408
+[report] flash_data,320,316,4
+[report] static_bss,110880,110876,4
 [report] heap_used,4440,4440,0
-[report] mbedtls_peak,21244,21328,-84
-[report] mbedtls_free,11524,11440,84
+[report] mbedtls_peak,21220,21328,-108
+[report] mbedtls_free,11548,11440,108
 [report] lwip_mem_free,7576,7576,0
-[report] lwip_pbufs_free,13,13,0
+[report] lwip_pbufs_free,14,13,1
 [report] stack_log,120,120,0
 [report] stack_service,52,52,0
 [report] stack_harness,2840,2840,0
@@ -28,7 +28,7 @@
 
 ```text
    text	   data	    bss	    dec	    hex	filename
- 349800	    324	 110876	 461000	  708c8	/w/build/baseline.elf
+ 350208	    328	 110880	 461416	  70a68	/w/build/baseline.elf
 ```
 
 ## Listeners (proved before the device ran)
@@ -49,17 +49,17 @@
 (nothing — this device sends no records yet)
 ```
 
-## Self-check (vs measurements/linked.csv)
+## Self-check (vs measurements/error-handler.csv)
 
 ```text
-  OK    flash_text: 349808 (expected 349808, Δ0)
-  OK    flash_data: 316 (expected 316, Δ0)
-  OK    static_bss: 110876 (expected 110876, Δ0)
+  OK    flash_text: 350216 (expected 350216, Δ0)
+  OK    flash_data: 320 (expected 320, Δ0)
+  OK    static_bss: 110880 (expected 110880, Δ0)
   OK    heap_used: 4440 (expected 4440, Δ0)
-  OK    mbedtls_peak: 21244 (expected 21284, Δ40)
-  OK    mbedtls_free: 11524 (expected 11484, Δ40)
+  OK    mbedtls_peak: 21220 (expected 21304, Δ84)
+  OK    mbedtls_free: 11548 (expected 11464, Δ84)
   OK    lwip_mem_free: 7576 (expected 7576, Δ0)
-  OK    lwip_pbufs_free: 13 (expected 13, Δ0)
+  OK    lwip_pbufs_free: 14 (expected 13, Δ1)
   OK    stack_log: 120 (expected 120, Δ0)
   OK    stack_service: 52 (expected 52, Δ0)
   OK    stack_harness: 2840 (expected 2840, Δ0)