The book: a long-form tutorial on the ASRC, complete#29
Merged
Conversation
book/: mdBook project with the full 22-chapter outline (placeholders build), the introduction, and the first complete chapter - the SPSC ring concurrency deep-dive, written as the tone benchmark: algorithm + memory-model argument + rejected alternatives + the wraparound proof + what tests can and cannot certify, ending in verify-it-yourself commands. Code excerpts are included live from the headers via mdBook anchors (ANCHOR comments added to spsc_ring.hpp; comment-only, format-clean). New CI job builds the book with a pinned mdbook binary (v0.4.40, sha256-verified) and treats warnings as errors, so a refactor that orphans an excerpt fails CI - the same freshness contract as the generated README tables. https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
Two Part I chapters: the Kaiser prototype design walk (Bessel series, beta fit, harris length estimate, runtime-vs-constexpr decision) and the polyphase bank (extra row L, tap-reversed rows, coefficient blending). Adds comment-only kai_*/bank_* ANCHOR markers to kaiser.hpp and polyphase_filter.hpp for the live excerpts. https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
Part I chapters for pi_servo.hpp (plant equation, PLL-matched gains, three-stage machine, both tuning war stories) and the FractionalResampler (Q0.64 phase, slip logic, dispatch, history management). Adds comment-only sv_*/rs_* ANCHOR markers; rs_slip deliberately co-brackets the p0_phase_step region since both chapters excerpt the same loop. https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
Part III told as it happened: C1-C2 profile-first and the restrict audit, C3's Q0.64 phase with the M55 float regression accepted, C4's bounded win, C5's implemented-then-reverted vrmpyh with disassembly evidence, and C6's channel axis with both recorded traps. Adds comment-only opt_* ANCHOR markers to polyphase_filter.hpp (opt_dot_rows co-brackets the rs_ region). https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
The traits/concept mechanism interleaved with a fixed-point course (Q-format headroom, recomputed accumulation bounds, the blend-margin audit correction) and the C-ABI shim chapter (opaque handles, C-linkage overload workaround, null-guard audit history, no-unwind caveat). Adds comment-only st_*/abi_* ANCHOR markers. https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
Part V chapters (real-clock bridges and firmware; the channels/rates/ blocks scaling rules with their measured evidence) plus the glossary (~55 entries) and the annotated bibliography. No new anchors; snippets are short hand-copies per the style contract. https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
Hexagon as the one-file cross+emulator port with its four lessons (soft-double phase, restrict deltas, the C5 revert, no-unwind exceptions) and the two Cortex-M bare-metal ports (startup anatomy, memory maps, one-shot ctest protocol, Helium and SMLALD discoveries). Adds comment-only pt_* ANCHOR markers to the startup file, both linker scripts, and the M55 toolchain file; the .ld C-style anchor comments resolve in mdBook. https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
Part II: tests-as-specifications (virtual-time simulator, sine-fit metrology, bare-metal one-shot protocol), deterministic instruction counting (plugin walk, two-sided ratchet, instructions-vs-cycles), and notebooks as calibrated instruments with their five measurement traps. Adds comment-only pf_* ANCHOR markers to two_clock_sim.hpp and insn_count.c. Also fixes the demo notebook's summary cell to the measured 126.4 dB — the docs truth sweep claimed this fix but never applied it — and an adjacent 'dB dB' typo. https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
tap
changed the title
Six SVG figures wired into the chapters, all produced by scripts/book_figures.py from the sources the text cites: the Kaiser window and prototype responses re-run kaiser.hpp's math formula-for- formula; the servo lock/dropout/re-lock trace and both feasibility panels are measured by compiling scripts/book_figures_trace.cpp against the real headers (the before panel against the pre-fix commit's tree via git archive); the Q0.64 slip figure runs the actual mod-2^64 arithmetic; the architecture diagram is drawn and labeled as such. The introduction gains a third mechanical commitment describing this, and the book CI job now verifies every image reference resolves (regeneration is not gated: matplotlib SVG output is not byte-stable across versions). https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
The book is now 'SampleRateTap: The Story of an Asynchronous Sample Rate Converter'. Each of the 24 pages opens with a quote matched to its theme (Heraclitus for the two crystals, Maxwell's On Governors for the servo, Kronecker for Q0.64, Dijkstra for the tests, the full Knuth quote for C1-C2, Postel for the C ABI, ...). Uncertain attributions are marked 'attributed to'. https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
Notebooks gets 'lies, damned lies, and statistics' (its five traps are that quote, measured); sample_traits gets the Heart Sutra (the primary template is deliberately empty, the specializations are its form); hardware trades the theory/practice aphorism for the Zen woodcutter. Also resolves the double-Feynman. https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
New book-pages workflow: builds with the pinned mdBook and deploys book/book to GitHub Pages (public site, deliberate) on pushes to main that touch the book or any excerpt source, plus workflow_dispatch. book.toml gains site-url for the /SampleRateTap/ path; README links the published site. https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this is
The complete book — an mdBook long-form tutorial that teaches C++, DSP, real-time
concurrency, and measurement discipline with this ASRC at the center. Every chapter
in
book/src/SUMMARY.mdis written: an introduction, 21 chapters across Parts 0–V,and 3 appendices (~65,000 words), staged as one commit per authoring unit on this PR.
Contents
Mechanisms
{{#include ...:anchor}}against comment-only// ANCHOR:markers added to the headers, platform files, and test support — excerpts can never drift from the code. All anchor edits are comment-only;clang-format --dry-run --Werrorclean; full host suite passes under-Werror(64/64).scripts/book_figures.pyfrom the sources the text cites — the filter curves re-run kaiser.hpp's math formula-for-formula, and the servo and feasibility traces are measured by compilingscripts/book_figures_trace.cppagainst the real headers (the feasibility "before" panel builds against the last pre-fix commit's tree viagit archive, so both panels of the centerpiece bug figure are measurements, not models).bookjob builds with pinned mdBook v0.4.40 (sha256-verified), fails on any warning (an orphaned anchor breaks the build), and verifies every image reference resolves.One repo fix riding along
The proof-system chapter found that the docs truth sweep's claimed fix to the demo
notebook's summary cell was never actually applied — the "> 130 dB" overstatement was
still live. This PR applies it: the cell now reads the measured 126.4 dB (plus an
adjacent "dB dB" typo).
Build it
mdbook build book && open book/book/index.html🤖 Generated with Claude Code
https://claude.ai/code/session_01HuAFfoeD5a5Xe5aGNA16M9