feat: buffer records and drain them on the service task

[DavidCozens]

Pull request

What this stage adds

A circular buffer in front of the sender, and the service seam finally doing
something: Log enqueues and returns, the service task drains and sends. The
logging task stops waiting on the network. A FreeRTOS mutex makes the two sides
safe on different tasks, which is what brings the FreeRtos platform into the
build.

Flash +6,788 B (+756)
RAM +5,676 B (+3,720)
Log stack +448 B (-232)
Service +728 B (+728)

The RAM is the ring plus a stack that moved. Sending left the log task — its
high-water fell from 800 to 568 — and arrived on the service task, which had been
idle at the FreeRTOS minimum and overflowed on the first run:

[device] FATAL: stack overflow in task service

Measured at 780 bytes, so the service seam grows to 2 KiB by the same two-fold
rule. That is the model working: the stage that deepens a seam pays for it, and
the baseline holds no spare capacity on its behalf.

Both overflows this evening were loud and immediate. That is worth more than it
sounds — a seam sized by guesswork rather than by measurement fails silently, and
on a logger a silent failure is indistinguishable from nothing to say.

Files

 CMakeLists.txt            |  4 ++--
 README.md                 | 16 +++++++++-------
 app/AppConfig.h           |  7 +++----
 app/main.c                |  5 +++--
 app/syslog/Syslog.c       | 16 +++++++++++-----
 app/tasks/LogTask.h       |  6 +++---
 app/tasks/ServiceTask.c   | 11 ++++++++++-
 measurements/buffered.csv | 13 +++++++++++++
 measurements/stages.tsv   |  1 +
 run-report.md             | 38 +++++++++++++++++++-------------------
 10 files changed, 74 insertions(+), 43 deletions(-)

Checklist

• The diff touches build infra (1 file(s)) — see Files above; deliberate for this stage.
• measurements/buffered.csv committed.
• Row added to measurements/stages.tsv.
• README regenerated: python3 scripts/gen-cost-table.py.
• ./run.sh green (build + QEMU + baseline self-check) — run-report.md committed.

---

Context for review: 8 of 21 sequential single-commit PRs replaying the integration on top of the Baseline root. Each lands green and reviewed before the next is built on it, because a change to an early commit would force every commit above it to be re-run and re-measured.

Summary by CodeRabbit

• New Features

  • Added buffered logging with a circular buffer, enabling log records to be queued before transmission.
  • Added a dedicated service task that periodically sends queued logs.
  • Enabled FreeRTOS platform support in the build configuration.

• Improvements

  • Increased the service task stack allocation for improved reliability.
  • Updated documentation and runtime reports to reflect buffered logging behavior and measurements.

[coderabbitai]

📝 Walkthrough

Walkthrough

The example now uses a bounded, mutex-protected circular buffer for syslog records. A FreeRTOS service task periodically drains the buffer to the lwIP UDP sender, with updated task sizing, harness timing, build linkage, documentation, and measurement reports.

Changes

Buffered syslog pipeline

Layer / File(s)	Summary
Enable FreeRTOS buffering support CMakeLists.txt	Adds the FreeRtos SolidSyslog platform pack and links it to baseline.
Construct and drain the circular buffer app/syslog/Syslog.c, app/tasks/ServiceTask.c, app/AppConfig.h, app/main.c, app/tasks/LogTask.h	Replaces passthrough buffering with static circular storage and an RTOS mutex, periodically calls SolidSyslog_Service, increases the service-task stack, and delays the harness before measurement.
Document buffered measurements README.md, run-report.md	Updates buffered-stage descriptions, cost figures, resource measurements, baseline values, and self-check expectations.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant LogTask
  participant CircularBuffer
  participant ServiceTask
  participant UDP_Sender
  LogTask->>CircularBuffer: enqueue log record
  ServiceTask->>CircularBuffer: poll and drain
  CircularBuffer->>UDP_Sender: provide queued record
  ServiceTask->>UDP_Sender: transmit record

Loading

Possibly related PRs

• cososo-ltd/solid-syslog-example#13: Implements the same circular-buffer and service-task delivery path.
• cososo-ltd/solid-syslog-example#31: Builds on the passthrough UDP path that this change replaces.
• cososo-ltd/solid-syslog-example#28: Updates the CMake SolidSyslog platform configuration and target linkage.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately captures the main change: buffering log records and draining them on the service task.
Description check	✅ Passed	The description includes the required stage summary and checklist sections with the key implementation, measurements, README, and run-report details.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch stage/buffered

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@app/main.c`:
- Around line 69-73: Replace the fixed vTaskDelay after LogTask_EmitOnce with a
bounded wait for an explicit acknowledgement from SolidSyslog_Service or the
collector indicating the record was transmitted and received. Keep the existing
enqueue result logging, and ensure Measure_Report() runs only after
acknowledgement or the defined timeout so readiness cannot be inferred from
elapsed time alone.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ae15093b-0fdc-4b0b-87d6-3f6af05ba64b

📥 Commits

Reviewing files that changed from the base of the PR and between c31b54c and b7c4a90.

⛔ Files ignored due to path filters (2)

• measurements/buffered.csv is excluded by !**/*.csv
• measurements/stages.tsv is excluded by !**/*.tsv

📒 Files selected for processing (8)

• CMakeLists.txt
• README.md
• app/AppConfig.h
• app/main.c
• app/syslog/Syslog.c
• app/tasks/LogTask.h
• app/tasks/ServiceTask.c
• run-report.md