E08: FreeRTOS example

[DavidCozens]

Demonstrate SolidSyslog running on a representative embedded RTOS, with the
existing Behave BDD suite providing acceptance. The demo serves both as proof
of portability for the library and as a public reference for readers of the
"Crafted with AI" blog series and prospective clients evaluating SolidSyslog
for CRA-class products.

Scope decision — FreeRTOS over Zephyr

This epic was originally framed as "FreeRTOS and Zephyr are candidates, not
commitments". The decision is now FreeRTOS, run under QEMU. Zephyr remains a
plausible follow-on but is not in scope here.

Suggested technical direction

These are design suggestions to be confirmed or revised during story-level
work; record decisions as ADRs as they are taken.

• Target: QEMU mps2-an385, Cortex-M3, with the LAN9118 NIC the model
  emulates.
• Kernel + networking: FreeRTOS kernel with FreeRTOS-Plus-TCP for UDP
  and TCP, and FreeRTOS-Plus-FAT introduced when store-and-forward needs
  persistence.
• Build container: extends the existing davidcozens/cpputest image
  with the ARM toolchain, QEMU, and GDB; SHA-pinned.
• Oracle: custom SHA-pinned syslog-ng image with a file destination,
  used both in CI and locally.
• CI: GitHub Actions Linux runner using a job container plus the oracle
  as a service container; all actions and images SHA-pinned.
• Local dev: VSCode Dev Containers on WSL2 + Docker Desktop, sharing
  the same images as CI, with the oracle present by default and QEMU
  launchable in a GDB-attachable mode.
• BDD harness: existing scenarios run against QEMU through the same
  stdin contract used by the Linux examples (Example/SingleTask,
  Example/Threaded), with target selection parameterised in the harness.
• Determinism is a hard requirement: a flaky scenario is a failing
  scenario; investigate and fix rather than retry. -icount in QEMU is a
  likely default for CI.

Story decomposition

Each story is a vertical slice of demo capability; acceptance for each is
that the relevant existing BDD scenarios pass against QEMU,
deterministically. Stories are filed as separate issues — see the
Stories section at the bottom for the live list.

1. Hello world running and debuggable in QEMU on a developer machine.
   Bring-up only — no BDD coverage at this point; acceptance is a
   developer-run smoke test plus working GDB attach.
2. Hello world running in QEMU on CI. Plumbing only — acceptance is a
   green CI job that runs the smoke binary in QEMU. No BDD scenarios yet.
3. UDP syslog from FreeRTOS reaches the oracle. This is where the
   majority of existing UDP-side BDD becomes acceptance, executed against
   the QEMU target rather than the Linux examples:
   • syslog.feature — walking skeleton end-to-end.
   • header_fields.feature, message_fields.feature, timestamp.feature,
     prival.feature — RFC 5424 field-level coverage.
   • structured_data.feature, origin.feature, time_quality.feature —
     standard structured data elements.
4. Concurrent task emission is safe and lossless. Reuses the existing
   portable SolidSyslogCircularBuffer (S04.05) with a new
   SolidSyslogFreeRtosMutex injected — mirrors the
   SolidSyslogPosixMutex / SolidSyslogWindowsMutex pattern. A
   FreeRTOS-queue–backed buffer is not the chosen approach.
   Cross-cuts E04: Buffering #6 E04: Buffering.
   • buffered.feature — single and multiple buffered messages.
   • structured_data.feature — sequence ID monotonicity is the
     loss-detector under concurrency.
5. Messages survive an oracle outage via store-and-forward. Introduces
   a FreeRTOS-Plus-FAT–backed SolidSyslogFile so the existing
   SolidSyslogFileBlockDevice / SolidSyslogBlockStore ecosystem runs
   unchanged. Cross-cuts E05: Store and Forward #7 E05: Store and Forward.
   • store_and_forward.feature — messages delivered after sender outage.
   • power_cycle_replay.feature — stored messages replayed after restart.
   • store_capacity.feature — overflow / discard / halt policies.
6. TCP transport works end-to-end. TCP itself already exists on POSIX
   (E15 closed); this story is about the FreeRTOS-Plus-TCP port.
   • tcp_transport.feature — happy path delivery.
   • tcp_reconnect.feature — recovery after server outage.
   • switching_transport.feature (UDP→TCP mid-run scenario) — useful
     once both transports are running on the target.
7. TLS on FreeRTOS via mbedTLS. mbedTLS is chosen over OpenSSL because
   OpenSSL is too large for Cortex-M3; mbedTLS has first-class FreeRTOS
   integration. ECC P-256 server certs by default — RSA handshakes are too
   slow on M3. TLS 1.3 enforced by the syslog-ng oracle (already in place
   from S03.14). Existing TLS BDD scenarios are reused, parameterised
   against the QEMU target.

Scope notes

• In scope: the seven capabilities above (UDP, concurrency, store-and-
  forward, TCP, TLS via mbedTLS), the build and dev container plumbing they
  require, the CI workflow, and the local dev environment.
• Out of scope for this epic: multi-RTOS abstraction, MISRA gating of
  the demo, unit tests on the simulator, mutual TLS on FreeRTOS, and
  hardware crypto acceleration.
• Repo layout: library code lives under Core/, tests under Tests/,
  examples under Example/, and platform integration under Platform/ —
  RTOS demo work should respect that structure.

Cross-epic touchpoints

• E11: Static-Allocation Variant #29 E11: Static-Allocation Variant — RTOS targets typically can't use
  heap; the static-allocation work and this epic will inform each other.
• E04: Buffering #6 E04: Buffering — story 4 reuses the existing portable
  SolidSyslogCircularBuffer and adds a SolidSyslogFreeRtosMutex.
• E05: Store and Forward #7 E05: Store and Forward — story 5 likely needs FreeRTOS-Plus-FAT
  alongside the existing POSIX file backend.
• E13: Cross-Platform CI and Windows #40 E13: Cross-Platform CI and Windows — the QEMU-in-CI plumbing is a
  natural neighbour to the existing cross-platform CI work.

Stories

#	Story
S08.01	#266 — FreeRTOS hello-world bring-up — QEMU mps2-an385 + GDB attach
S08.02	#267 — Hello-world running under QEMU on CI
S08.03	#268 — UDP syslog from FreeRTOS reaches the oracle
S08.04	#269 — FreeRTOS mutex — CircularBuffer for concurrent task emission
S08.05	#270 — Store-and-forward on FreeRTOS-Plus-FAT
S08.06	#271 — TCP transport on FreeRTOS-Plus-TCP
S08.07	#272 — TLS via mbedTLS on FreeRTOS
S08.08	#288 — SolidSyslogFreeRtosResolver — DNS resolution on FreeRTOS-Plus-TCP