docs: ASCII typography and style normalization across all repo text

Replace every em dash with real punctuation (rewrites, not hyphen swaps) in docs, code comments, scripts, configs, and the port records; convert en dashes, curly quotes, ellipsis glyphs, arrows, and section signs to ASCII; drop machine-writing tell phrases from living docs. ADR titles now use a colon. The M2 bring-up DTS model string carried an em dash into the patch series and its record echoes; fixed at both, and the full series re-verified to apply cleanly onto pristine 6.18.46. One comment in freshness.h deliberately names the em dash glyph the UI renders as the unknown mark; that is data, kept as prose naming it. Verified: cargo tests (sim, config-lint, rs485-bridge), shellcheck, both driver MC/DC harnesses, patches-apply.
2026-08-31 12:31:27 -06:00
parent 80d9a9539b
commit 42fb386f60
111 changed files with 1261 additions and 1261 deletions
@@ -11,16 +11,16 @@ QDIR="$(cd "$HERE/.." && pwd)"                           # qemu/

 ZIMAGE="${1:-}"
 if [ -z "$ZIMAGE" ] || [ ! -f "$ZIMAGE" ]; then
-  echo "FATAL: usage: $0 <zImage> [initramfs] — zImage missing or not a file: '${ZIMAGE:-}'" >&2
+  echo "FATAL: usage: $0 <zImage> [initramfs]: zImage missing or not a file: '${ZIMAGE:-}'" >&2
  exit 1
 fi
 INITRD="${2:-$QDIR/out/initramfs.cpio.gz}"
 [ -f "$INITRD" ] || {
-  echo "FATAL: initramfs not found at $INITRD — run qemu/mkinitramfs.sh first" >&2
+  echo "FATAL: initramfs not found at $INITRD: run qemu/mkinitramfs.sh first" >&2
  exit 1
 }
 command -v qemu-system-arm >/dev/null || {
-  echo "FATAL: qemu-system-arm not on PATH (apt-get install qemu-system-arm) — see qemu/README.md" >&2
+  echo "FATAL: qemu-system-arm not on PATH (apt-get install qemu-system-arm): see qemu/README.md" >&2
  exit 1
 }

@@ -29,7 +29,7 @@ trap 'rm -f "$LOG"' EXIT

 # Delegate the qemu invocation to run.sh (--no-disk) so the machine shape
 # (-M virt,highmem=off, cpu, memory, virtio topology) lives in exactly one
-# place — the two hand-copied invocations had already drifted once.
+# place: the two hand-copied invocations had already drifted once.
 # timeout -k: a wedged qemu that ignores SIGTERM gets SIGKILLed 10s later
 # instead of holding the job until the workflow-level timeout.
 timeout -k 10 180 bash "$QDIR/run.sh" \
@@ -2,7 +2,7 @@
 # Clock-sanity scenario (issue #3 regression guard): boot the VM, run the
 # musl-static clockprobe in the guest, and assert the vDSO monotonic RATE
 # matches the kernel's /proc/uptime within 1%. Under QEMU -M virt this passes
-# on the current kernel (measured 0.99963) — a regression here means the
+# on the current kernel (measured 0.99963): a regression here means the
 # generic vDSO path broke. The RV1106 *board* leg of issue #3 is a separate,
 # bench-only measurement; this scenario cannot see board-specific CNTFRQ or
 # CNTVOFF misprogramming.
@@ -21,7 +21,7 @@ if [ -z "$ZIMAGE" ] || [ ! -f "$ZIMAGE" ]; then
  exit 1
 fi
 command -v qemu-system-arm >/dev/null || {
-  echo "FATAL: qemu-system-arm not on PATH — see qemu/README.md" >&2
+  echo "FATAL: qemu-system-arm not on PATH: see qemu/README.md" >&2
  exit 1
 }
 command -v arm-linux-gnueabihf-gcc >/dev/null || {
@@ -58,7 +58,7 @@ for _attempt in 1 2 3; do
  sleep 3
  kill -0 "$QEMU_PID" 2>/dev/null && break
  if grep -aq 'Could not set up host forwarding' "$WORK/console.log"; then
-    echo "== hostfwd port collision on base $PORT — retrying"
+    echo "== hostfwd port collision on base $PORT, retrying"
    QEMU_PID=""
    continue
  fi
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# FULL OTA apply scenario — the loop the desk e2e stops short of: the real
+# FULL OTA apply scenario (the loop the desk e2e stops short of): the real
 # flared inside the VM downloads a real signed tier-1 .wfw whose payload is a
 # bootable rootfs, verifies it, and ACTUALLY WRITES rootfs_b (safe: it is a
 # region inside disk.img); the harness then reboots into slot _b and asserts
@@ -7,7 +7,7 @@
 #
 # Documented emulation gaps (ADR-0006): the BCB slot CHOICE and the physical
 # reset are performed by the harness (cmdline slot + a fresh qemu boot), not
-# by U-Boot/CRU — those stay bench territory.
+# by U-Boot/CRU. Those stay bench territory.
 #
 # FAILS CLOSED on missing prerequisites.
 #
@@ -22,7 +22,7 @@ PATH="$PATH:/usr/sbin:/sbin"

 ZIMAGE="${1:-}"
 if [ -z "$ZIMAGE" ] || [ ! -f "$ZIMAGE" ]; then
-  echo "FATAL: usage: $0 <zImage> — the virt.fragment kernel variant" >&2
+  echo "FATAL: usage: $0 <zImage>: the virt.fragment kernel variant" >&2
  exit 1
 fi
 if [ -z "${FLARE_EDGE:-}" ] || [ ! -f "$FLARE_EDGE/tools/mock-flare-portal.py" ]; then
@@ -34,7 +34,7 @@ fi
  exit 1
 }
 command -v qemu-system-arm >/dev/null || {
-  echo "FATAL: qemu-system-arm not on PATH — see qemu/README.md" >&2
+  echo "FATAL: qemu-system-arm not on PATH: see qemu/README.md" >&2
  exit 1
 }

@@ -52,7 +52,7 @@ API_KEY="$(python3 -c 'import secrets; print(secrets.token_hex(24))')"
 PORT=$((20000 + RANDOM % 20000))

 # 0. The offer's payload is a REAL bootable rootfs: the same skeleton the
-#    disk uses, stamped with the NEW version — booting it is the proof.
+#    disk uses, stamped with the NEW version: booting it is the proof.
 QEMU_DIR="$QDIR"
 OUT="$QDIR/out"
 # shellcheck source=qemu/lib.sh disable=SC1091
@@ -105,7 +105,7 @@ for _attempt in 1 2 3; do
  sleep 3
  kill -0 "$QEMU_PID" 2>/dev/null && break
  if grep -aq 'Could not set up host forwarding' "$WORK/console.log"; then
-    echo "== hostfwd port collision on base $VMBASE — retrying"
+    echo "== hostfwd port collision on base $VMBASE, retrying"
    QEMU_PID=""
    continue
  fi
@@ -117,7 +117,7 @@ if [ -z "$QEMU_PID" ] || ! kill -0 "$QEMU_PID" 2>/dev/null; then
 fi

 # 4. wait for the apply to conclude. flared logs to its in-guest file, not
-#    the console — but the next check-in REPORTS the outcome to the portal:
+#    the console, but the next check-in REPORTS the outcome to the portal:
 #    detail "hard reset failed after slot flip" is the exact post-apply state
 #    under the gated reset (write done, AvbABData flipped, reboot refused).
 deadline=$((SECONDS + 420))
@@ -140,7 +140,7 @@ grep -aq "GET /api/v1/devices/$DEVICE_ID/firmware/assets/.* -> 200" "$WORK/mock.
  echo "FATAL: staged without a portal asset download?!" >&2
  exit 1
 }
-echo "== apply staged (asset downloaded, rootfs_b written, reset gated) — rebooting into _b"
+echo "== apply staged (asset downloaded, rootfs_b written, reset gated), rebooting into _b"
 kill "$QEMU_PID" 2>/dev/null || true
 wait "$QEMU_PID" 2>/dev/null || true
 QEMU_PID=""
@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
 # End-to-end device scenario: the REAL warden-flared, running inside the VM,
 # checks in to flare-edge's mock FLARE portal on the host and pulls its
-# firmware desired-state — the exact device-initiated HTTPS(-shaped) flow a
+# firmware desired-state: the exact device-initiated HTTPS(-shaped) flow a
 # panel performs, with zero flare-edge code changes (the portal URL is a state
 # file; 10.0.2.2 is slirp's host alias).
 #
-# FAILS CLOSED on every missing prerequisite — never a soft skip.
+# FAILS CLOSED on every missing prerequisite: never a soft skip.
 #
 # Usage: portal-scenario.sh <zImage-virt>
 # Env:   FLARE_EDGE  path to a flare-edge checkout (provides mock-flare-portal.py)
@@ -16,7 +16,7 @@ QDIR="$(cd "$HERE/.." && pwd)"                           # qemu/

 ZIMAGE="${1:-}"
 if [ -z "$ZIMAGE" ] || [ ! -f "$ZIMAGE" ]; then
-  echo "FATAL: usage: $0 <zImage> — the virt.fragment kernel variant" >&2
+  echo "FATAL: usage: $0 <zImage>: the virt.fragment kernel variant" >&2
  exit 1
 fi
 if [ -z "${FLARE_EDGE:-}" ] || [ ! -f "$FLARE_EDGE/tools/mock-flare-portal.py" ]; then
@@ -24,11 +24,11 @@ if [ -z "${FLARE_EDGE:-}" ] || [ ! -f "$FLARE_EDGE/tools/mock-flare-portal.py" ]
  exit 1
 fi
 [ -x "$QDIR/payload/warden-flared" ] || {
-  echo "FATAL: no qemu/payload/warden-flared — build a static musl armv7 flared (see qemu/payload/README.md)" >&2
+  echo "FATAL: no qemu/payload/warden-flared: build a static musl armv7 flared (see qemu/payload/README.md)" >&2
  exit 1
 }
 command -v qemu-system-arm >/dev/null || {
-  echo "FATAL: qemu-system-arm not on PATH — see qemu/README.md" >&2
+  echo "FATAL: qemu-system-arm not on PATH: see qemu/README.md" >&2
  exit 1
 }

@@ -56,7 +56,7 @@ FW_SIGNING_KEY_FILE="$FLARE_EDGE/tools/testdata/fw-dev-key.seed" \
  WARDEN_UBOOT_VERSION=2017.09 \
  bash "$FLARE_EDGE/tools/mk-wfw.sh" "$WORK/rootfs-payload.img" 1 0.0.2 "$WORK/offer.wfw"

-# 1. mock portal on the host, our device pre-registered (no pairing needed —
+# 1. mock portal on the host, our device pre-registered (no pairing needed:
 #    the same credential-seeding shortcut fw-e2e-test.sh uses), offering the .wfw.
 python3 "$FLARE_EDGE/tools/mock-flare-portal.py" \
  --port "$PORT" --device "$DEVICE_ID:$API_KEY" \
@@ -79,7 +79,7 @@ echo "== mock portal on :$PORT, device $DEVICE_ID"

 # 2. image seeded with the portal URL + credentials.
 bash "$QDIR/mkinitramfs.sh"
-# All four enrolment keys — flare::enrolment() returns None (and the report
+# All four enrolment keys: flare::enrolment() returns None (and the report
 # loop parks forever) unless flare.site is present too.
 bash "$QDIR/mkimage.sh" \
  --portal-url "http://10.0.2.2:$PORT" \
@@ -88,7 +88,7 @@ bash "$QDIR/mkimage.sh" \
  --state "flare.site=qemu-devsim"

 # 3. boot the VM headless (daemons run; console log to file). Random hostfwd
-#    ports can collide with another process — detect the early qemu bind
+#    ports can collide with another process. Detect the early qemu bind
 #    failure and retry with a fresh base rather than failing spuriously.
 QEMU_PID=""
 for _attempt in 1 2 3; do
@@ -103,7 +103,7 @@ for _attempt in 1 2 3; do
    break
  fi
  if grep -aq 'Could not set up host forwarding' "$WORK/console.log"; then
-    echo "== hostfwd port collision on base $VMBASE — retrying"
+    echo "== hostfwd port collision on base $VMBASE, retrying"
    QEMU_PID=""
    continue
  fi
@@ -116,7 +116,7 @@ if [ -z "$QEMU_PID" ] || ! kill -0 "$QEMU_PID" 2>/dev/null; then
  exit 1
 fi

-# 4. assert: rootfs up, and the portal saw — from OUR device id — an
+# 4. assert: rootfs up, and the portal saw (from OUR device id) an
 #    authenticated check-in, the firmware desired-state pull, and the signed
 #    .wfw asset download (i.e. flared accepted the offer and fetched it; the
 #    verify+stage+APPLYING that follow are a dry run without
@@ -8,7 +8,7 @@
 # RV1106-only init steps degrade on virt (backlight, goodix, npu, the 5.10
 # /oem modules fail vermagic), and binaries older than the flare-edge #106
 # fix reproduce that crash faithfully. Interactive login uses the image's own
-# credentials — deliberately not recorded here.
+# credentials: deliberately not recorded here.
 #
 # FAILS CLOSED on missing prerequisites.
 #
@@ -21,12 +21,12 @@ QDIR="$(cd "$HERE/.." && pwd)"                           # qemu/
 ZIMAGE="${1:-}"; ROOTFS="${2:-}"; OEM="${3:-}"
 for f in "$ZIMAGE" "$ROOTFS" "$OEM"; do
  if [ -z "$f" ] || [ ! -f "$f" ]; then
-    echo "FATAL: usage: $0 <zImage> <rootfs.img> <oem.img> — '$f' missing" >&2
+    echo "FATAL: usage: $0 <zImage> <rootfs.img> <oem.img>: '$f' missing" >&2
    exit 1
  fi
 done
 command -v qemu-system-arm >/dev/null || {
-  echo "FATAL: qemu-system-arm not on PATH — see qemu/README.md" >&2
+  echo "FATAL: qemu-system-arm not on PATH: see qemu/README.md" >&2
  exit 1
 }

@@ -51,7 +51,7 @@ for _attempt in 1 2 3; do
  sleep 3
  kill -0 "$QEMU_PID" 2>/dev/null && break
  if grep -aq 'Could not set up host forwarding' "$WORK/console.log"; then
-    echo "== hostfwd port collision on base $PORT — retrying"
+    echo "== hostfwd port collision on base $PORT, retrying"
    QEMU_PID=""
    continue
  fi
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Display + touch scenario: boot the VM headless with virtio-gpu, wait for the
 # LVGL UI (fbdev build) to render a real frame, then inject an absolute touch
-# tap on the Metrics tab (virtio-tablet) and ASSERT the frame changed — the
+# tap on the Metrics tab (virtio-tablet) and ASSERT the frame changed: the
 # device-level analogue of flare-edge's Xvfb/xdotool sim-test.sh. Readiness is
 # polled from screendumps on bounded deadlines, never guessed with fixed
 # sleeps: TCG renders CPU-bound and a loaded host can be arbitrarily slow.
@@ -17,15 +17,15 @@ QDIR="$(cd "$HERE/.." && pwd)"                           # qemu/
 ZIMAGE="${1:-}"
 OUTDIR="${2:-$QDIR/out}"
 if [ -z "$ZIMAGE" ] || [ ! -f "$ZIMAGE" ]; then
-  echo "FATAL: usage: $0 <zImage> [out-dir] — the virt.fragment kernel variant" >&2
+  echo "FATAL: usage: $0 <zImage> [out-dir]: the virt.fragment kernel variant" >&2
  exit 1
 fi
 [ -x "$QDIR/payload/warden-ui" ] || {
-  echo "FATAL: no qemu/payload/warden-ui — build it with flare-edge tools/build-ui-vm.sh" >&2
+  echo "FATAL: no qemu/payload/warden-ui: build it with flare-edge tools/build-ui-vm.sh" >&2
  exit 1
 }
 command -v qemu-system-arm >/dev/null || {
-  echo "FATAL: qemu-system-arm not on PATH — see qemu/README.md" >&2
+  echo "FATAL: qemu-system-arm not on PATH: see qemu/README.md" >&2
  exit 1
 }

@@ -41,7 +41,7 @@ trap cleanup EXIT
 bash "$QDIR/mkinitramfs.sh"
 bash "$QDIR/mkimage.sh"

-# Random hostfwd ports can collide — detect qemu's early bind failure and
+# Random hostfwd ports can collide. Detect qemu's early bind failure and
 # retry with a fresh base rather than failing spuriously.
 for _attempt in 1 2 3; do
  PORT=$((21000 + RANDOM % 20000))
@@ -53,7 +53,7 @@ for _attempt in 1 2 3; do
  sleep 3
  kill -0 "$QEMU_PID" 2>/dev/null && break
  if grep -aq 'Could not set up host forwarding' "$WORK/console.log"; then
-    echo "== hostfwd port collision on base $PORT — retrying"
+    echo "== hostfwd port collision on base $PORT, retrying"
    QEMU_PID=""
    continue
  fi
@@ -96,7 +96,7 @@ EOF

 # The VM can die mid-poll (OOM, crash): check liveness before every QMP
 # call so the failure is OUR message + console evidence, not a python
-# traceback — and preserve the console log before the trap removes $WORK.
+# traceback, and preserve the console log before the trap removes $WORK.
 vm_alive_or_die() {
  kill -0 "$QEMU_PID" 2>/dev/null && return 0
  echo "FATAL: VM exited during the screendump poll" >&2
@@ -121,7 +121,7 @@ done
 }

 # Tap the "Metrics" tab: pixel (373,40) of 720x720 scaled to the QMP absolute
-# range 0..32767 — switching tabs must repaint the content area. Poll for the
+# range 0..32767. Switching tabs must repaint the content area. Poll for the
 # repaint rather than guessing a delay.
 vm_alive_or_die
 qmp tap 16975 1820
@@ -142,7 +142,7 @@ cp "$WORK/shot1.ppm" "$OUTDIR/ui-shot1.ppm"
 cp "$WORK/shot2.ppm" "$OUTDIR/ui-shot2.ppm" 2>/dev/null || true

 [ "$changed" = 1 ] || {
-  echo "FATAL: tapping the Metrics tab did not change the frame within 90s — touch is not reaching the UI" >&2
+  echo "FATAL: tapping the Metrics tab did not change the frame within 90s: touch is not reaching the UI" >&2
  cp "$WORK/console.log" "$OUTDIR/ui-shot-console.log" || true
  exit 1
 }