A period, an edge, and jitter
You will learn
What a clock carries besides frequency, what jitter does to an edge, and what a tool-card spec is for.
A clock is a period with an edge in it, and the edge is not perfectly placed: cycle to cycle it wanders by the jitter. The spec of the tri clocks tool card is not a test suite, and the recording shows its native report saying exactly that: 0 tests, because it is constants a tool page reads. Every constant on that card names the tool output it came from. Jitter eats the margin a setup calculation leaves: the clock-tree spec of the next module carries 50 ps of PLL jitter as one of its constants.
Try it
In the recording, find the line that says why the report counts 0 tests; then in the spec frame read the constants and find where each names the tool output it came from.
t27c 0.4.0 on a laptop (macOS): the tri clocks tool-card spec reports 0 tests -- it is constants for a tool page, not a test suite; the first lines show what it carries.
specs/tools/trios/tri/clocks.t27
// SPDX-License-Identifier: Apache-2.0
; specs/tools/trios/tri/clocks.t27 -- tool gHashTag/BrowserOS:tri/clocks, the `tri clocks` command of the trios loop CLI
; Generated by apps/website/scripts/tools-from-trios-tri.mjs from gHashTag/BrowserOS:trios/bin/tri at 7366096248df; do not edit.
; The CLI the loop timers run (`tri drift` holds ~/.local/bin/tri to the tracked copy). It is another program than
; the Rust tri of gHashTag/t27 and the Zig tri of gHashTag/trinity, so the ID is repository-qualified.
; A card is data and carries no test block. ASCII only (L3). phi^2 + 1/phi^2 = 3 | TRINITY
module tool_trios_tri_clocks;
pub const KIND : str = "tool";
pub const FAMILY : str = "tri-cli";
pub const ID : str = "gHashTag/BrowserOS:tri/clocks";
pub const REPO : str = "gHashTag/BrowserOS";
pub const QUALIFIED_ID : str = "gHashTag/BrowserOS:tri/clocks";
pub const SCHEMA : u32 = 2;
pub const COMMAND : str = "tri clocks";
; The case arm of the dispatcher and the first line of it that does the work.
pub const VARIANT : str = "case arm `clocks)`, line 353";
pub const SOURCE : str = "trios/bin/tri";
pub const ENTRY : str = "trios/bin/tri";
pub const SOURCE_COMMIT : str = "7366096248dfb09893e9a7d1a0f1c56ced13d16e";
pub const ROUTED : bool = true;
pub const DISPATCH : str = "node ~/BrowserOS/trios/.trinity/loop/clocks.mjs";
pub const DOCUMENTED : bool = true;
pub const HELP_LINE : str = "tri clocks -- which fields decisions hang on, and whether someone rewrites them";
pub const CATEGORY : str = "continuous loop (trios)";
pub const ABOUT : str = "which fields decisions hang on, and whether someone rewrites them";
pub const ABOUT_SOURCE : str = "`tri help` (the heredoc under the help arm of trios/bin/tri)";
pub const ACTIONS : [0]str = [];
pub const ACTIONS_ABOUT : [0]str = [];
pub const ARGS : [0]str = [];
pub const AGENTS : [0]str = [];
pub const AGENTS_NOTE : str = "No source binds an agent letter to this command: the trios CLI is not named by docs/agents/AGENTS_ALPHABET.md or .claude/agents/*.md of gHashTag/t27.";
pub const WHEN_TO_USE : str = "which fields decisions hang on, and whether someone rewrites them";
pub const WITNESS : str = "source-parse";
pub const WITNESS_SOURCE : str = "gHashTag/BrowserOS:trios/bin/tri at 7366096248dfb09893e9a7d1a0f1c56ced13d16e, read as text (the help heredoc and the top-level case arms); the CLI was not run";
pub const ENABLED : bool = true;
All lessons
Module 1 · What a clock is
One edge, one world: what shares a clock edge shares a world, the period and the jitter of a real edge, and where the clock enters a board.
Module 2 · Clock trees
Skew and insertion delay, the global buffer network, and the trap of gating a clock with logic.
Module 3 · PLL and MMCM
Multiply and divide one clock into another, move its phase in steps of the VCO, and which clocks the analyzer treats as related.
Module 4 · Resets
Assert asynchronously, release synchronously: the three reset kinds, the release pipe, and the tree a reset grows.
Module 5 · Metastability
The setup-hold window, the mean time between failures in integer arithmetic, and the two flops that fix it.
Module 6 · Crossing many bits
Why a binary bus tears, why Gray code does not, and the handshake that moves a pulse between worlds.
Module 7 · The asynchronous FIFO
Pointers, flags and depth: the buffer that moves a stream between two clocks.
Module 8 · Constraints
The lines that tell the analyzer what a clock is, which paths not to check, and what the pins must meet.
Module 9 · On the board
A CDC report, one crossing captured at the flip-flops, and the bitstream diff that closes the course.