Separating Facts, Behaviors, Rules, Patterns, Guesses, and Questions for Safe Hardware Work

Welcome. This module is the evidence-control part of the driver loop: it prevents an agent from turning plausible assumptions into kernel patches. Your V1 driver, reviewer comments, the hardware manual, DSA documentation, and similar upstream drivers all provide useful information—but they do not prove the same things.

The goal of this lesson is to create one working table that separates those sources cleanly. You will use it to decide whether a task is safe to implement now, needs more kernel research, or must stop for a focused hardware question. Treat the table as a living engineering record, not as prose written after the fact.

---

The central rule: evidence has a scope

A common agent failure looks like this:

“A similar switch driver configures register X during setup, so this switch should too.”

That is a pattern, not evidence about your hardware. It may be a useful lead, but it cannot establish register semantics, reset behavior, port numbering, tag format, or electrical wiring.

The same separation applies in the other direction:

• A hardware manual can establish what the chip can do, provided its wording is clear and applies to the exact variant and revision.
• V1 code establishes what the current driver does, not whether it is correct.
• DSA rules establish what the kernel framework expects from a driver on the target kernel version.
• An upstream analogue establishes a design pattern under that other device’s constraints.
• A guess is a possible explanation or proposed implementation. It is not allowed to silently become a fact.
• An open question is an explicit blocker with an owner and a precise answer needed.

This distinction matters especially for a DSA driver. A switch may appear to pass basic traffic while still violating the DSA lifecycle, standalone isolation, bridge offload, VLAN, tagging, or Device Tree rules that upstream review will inspect.

---

Read the framework rules before filling the DSA column

Use the supplied DSA architecture documentation as the baseline for interpreting the DSA-specific entries in your table. For the actual patch, always reconcile it with the documentation and source in the target kernel tree: DSA APIs and expectations can change across kernel versions.

Two DSA details are especially valuable when reviewing V1:

1. Driver lifecycle is a framework contract. DSA registration requires valid device, port-count, operations, and private-data members. The driver must also arrange correct shutdown handling, without allowing shutdown and remove paths to tear down the switch twice.

2. A successful setup() has a high bar. It is not merely “registers were written without error.” By the time it returns, the switch should be configured to isolate interfaces appropriately, unused ports should be disabled, and the driver should be ready for later DSA requests. Whether your hardware can achieve that must come from the manual; the DSA requirement itself belongs in the DSA column.

---

Build an evidence matrix, not a notes document

Create one tracked file, for example:

docs/evidence-matrix.md

Use one row for each hardware trait or review decision. A trait is smaller than “DSA support”; it is something concrete such as:

• software-reset effects;
• CPU-port identification;
• tag insertion and maximum tag length;
• user-port isolation at initial setup;
• PHY access method;
• interrupt status and acknowledgement;
• VLAN membership representation;
• FDB database scope;
• a binding property such as interrupts, phy-mode, or dsa,member.

Each cell must state its source and location. A statement without a locator is a lead, not evidence.

Recommended matrix

Trait or decision	Hardware facts	V1 behavior	DSA rules, target kernel	Upstream pattern	Guess or proposed change	Open question	Status and next permitted action
Atomic, testable subject	Exact manual claim, revision, page or section; mark clear, unclear, incomplete, or conflicting	Exact file, function, line range, and observed behavior	Target-tree document/source location and the condition under which it applies	Driver, commit or version, and the relevant hardware similarity and difference	Explicitly labelled inference; no “is” or “must” language	Exact missing fact or conflict	Ready, research, blocked, or rejected; state the next safe action

A few conventions keep this useful under repeated agent runs:

• Give every row an ID such as HW-RESET-01, DSA-SETUP-03, or DT-IRQ-02.
• Link each row to the review-task ID it helps resolve, such as RVW-07.
• Use stable source labels:
  • M: for manual
  • V1: for current driver code
  • K: for target kernel rules or source
  • P: for an analogous upstream pattern
  • Q: for a human question
• Quote only the minimum source text needed to preserve the claim. Keep longer excerpts or screenshots in a separate evidence directory if necessary.
• Record the manual revision and chip variant. A claim from a family manual may be wrong for a specific part.
• Record the kernel commit or release base for K: entries. Do not let an online document silently substitute for the target branch.

For example, a compact cell may read:

M: Switch Manual Rev 1.4, §8.3, p. 211:
“[exact short quotation]”. Clear for port 5 only.

That wording records both the source and its scope. It avoids the dangerous compression:

The switch supports tagging.

The latter loses which port, which tag form, which direction, and whether optional modes or errata apply.

---

Keep Device Tree claims in the right columns

Bindings describe the hardware interface and its ABI. They should not be shaped around the temporary limitations of V1.

Put these claims in separate cells:

Claim	Correct category
“This chip has an interrupt output.”	Hardware fact, subject to the exact chip manual
“This board wires that interrupt to SoC interrupt line 42.”	Hardware or board fact, established by schematics, board documentation, or an authoritative existing DTS
“V1 has no interrupt handler and polls link state.”	V1 behavior
“The binding should describe a hardware interrupt even if V1 currently polls.”	Binding rule
“Another switch binding exposes an interrupts property.”	Upstream pattern
“Adding an interrupt property will work without a driver change.”	Guess until wiring and driver handling are established

This prevents a frequent mistake: adding a property solely to quiet a schema or reviewer comment, despite no proof that the described resource exists or is wired on the relevant board.

---

A worked template: three rows, with no invented facts

The following is a template, not a conclusion about your device. Its placeholders show the expected level of precision and, more importantly, how a row remains honest when the answer is incomplete.

ID / trait	Hardware facts	V1 behavior	DSA rules, target kernel	Upstream pattern	Guess or proposed change	Open question	Status and next permitted action
HW-RESET-01 — reset effects before DSA setup	M: [manual rev], [reset section], [page]. Software reset control exists. Effects on VLAN/FDB state are unclear because the reset table omits those blocks.	V1: [path:function]. Calls reset, waits for completion, then programs only CPU-port state.	K: DSA driver-development documentation, setup. Setup is expected to establish isolation and should not rely on bootloader state.	P: [driver/commit]. Performs reset before setting port isolation; its reset register map differs.	Reset may clear forwarding and VLAN state, making V1’s later configuration sufficient.	Does software reset clear port membership, VLAN state, FDB state, and tag mode on this exact part?	Blocked: hardware. Do not remove or add post-reset configuration based only on the analogue. Safe work: trace and document V1’s actual writes.
DSA-TAG-02 — CPU tag format and buffer space	M: [manual rev], [CPU interface section]. CPU ingress tag is documented as [n] bytes in normal mode; extended mode wording is incomplete.	V1: [path:function]. Returns [protocol] and selects [tagger]; no evidence yet that its maximum head/tailroom covers extended frames.	K: target tagger source and DSA documentation. A tagger declares worst-case headroom or tailroom and transforms frames on transmit and receive.	P: [tag driver]. Declares maximum tag size because timestamps extend the tag on that hardware.	V1 may need maximum rather than normal-mode tag size.	Can this chip emit or accept extended tags in any enabled mode, including timestamp or management frames?	Blocked: hardware. Safe work: compare tagger declarations with every documented V1-supported tag mode.
DT-IRQ-03 — switch interrupt resource	M: [manual rev], [interrupt chapter]. Chip provides an interrupt output. Board connection is unknown.	V1: [path]. Uses polling; binding lacks interrupts.	K: binding-writing guidance. Bindings describe hardware rather than current driver support; properties require defined constraints.	P: [similar binding]. Uses interrupts and interrupt-names; its line is wired to a parent interrupt controller.	The V1 binding should gain interrupts.	Is the interrupt output routed on each supported board, and if so, what polarity and parent interrupt specifier apply?	Blocked: board fact. Safe work: inspect current board DTS files and schematics; do not invent an interrupt specifier.

Notice what this table does not do:

• It does not turn a likely reset behavior into a fact.
• It does not treat current V1 behavior as proof of correct DSA integration.
• It does not assume that matching code in another vendor driver establishes matching hardware.
• It does not use a binding change to hide a missing hardware answer.
• It still permits useful work: code tracing, source collection, target-kernel API checks, and tests that do not depend on the unresolved assumption.

---

Make the entries auditable

A good row can survive an upstream review thread six weeks later. To achieve that, write claims at the right strength.

Hardware fact language

Use direct, bounded language:

• “Manual Rev 1.4, §9.2 states that bit 3 enables CPU-port tagging.”
• “The manual is clear that register A applies to ports 0 through 4; applicability to port 5 is not stated.”
• “Tables 9-4 and 9-7 conflict about the reset value of this field.”

Avoid:

• “The manual implies this is probably default.”
• “The register looks like other switches.”
• “V1 has worked with this setting.”

V1 behavior language

Describe observations, including error paths:

• “probe() allocates private state with managed allocation.”
• “After dsa_register_switch() fails, this branch returns without disabling the interrupt.”
• “port_bridge_join() returns success but does not update the port membership table.”
• “The binding example supplies property X, but the driver never reads it.”

Do not label any of those correct or incorrect until the row contains the applicable hardware and DSA evidence.

DSA-rule language

Rules should be conditional and versioned:

• “On the target kernel, a driver calling DSA registration must provide these switch fields.”
• “If the driver reports successful bridge offload, DSA expects the hardware forwarding behavior associated with that callback.”
• “If a port remains standalone because bridge offload is unsupported, the forwarding configuration has different expectations.”

That prevents over-implementing optional features merely because the framework documents them.

Pattern language

A pattern must include both similarity and difference:

P: driver X, target-kernel commit Y.
Similarity: managed through MDIO; has internal PHYs.
Difference: X uses a six-byte CPU header, while our manual describes a four-byte header.
Use: leads to inspect its error unwinding only; does not justify copying its tag handling.

This small discipline sharply reduces copy-paste “cargo-cult” patches.

---

Decide what work is safe

Every row ends in an explicit disposition. Use four states:

Status	Meaning	Agent may do now
Ready	The relevant hardware fact is clear, V1 behavior is known, target-kernel rule is known, and the planned change does not rely on an unresolved assumption.	Implement a narrow change, then run the normal build, DT, static-review, and Sashiko gates.
Research needed	No hardware ambiguity blocks the change, but target-kernel API semantics, V1 control flow, or a reviewer’s concern needs more source inspection.	Inspect target-tree code, history, and relevant analogues. Do not make speculative edits.
Blocked: hardware	A change depends on ambiguous, incomplete, or conflicting manual or board information.	Preserve the evidence, ask a focused human question, and avoid the affected change.
Rejected	The proposed change conflicts with known hardware facts, target-kernel rules, or the binding ABI.	Record why it is rejected and close that proposal; do not retry it under different wording.

A row is not Ready merely because an agent can compile the patch. Compilation can establish syntax and some API compatibility. It cannot establish that a register field has the presumed meaning or that an interrupt is wired.

The safe-change gate

Before permitting an edit, verify all of the following:

1. The change’s required hardware claims are clear.
   A register write, port classification, tag size, PHY mode, or interrupt setup must have a direct source appropriate to the claim.

2. The change has a target-kernel DSA rationale.
   Identify the operation, callback, lifetime rule, or binding constraint it satisfies. If the kernel source differs from an online document, the target tree governs the patch.

3. V1’s current behavior is traced through success and failure paths.
   For lifecycle changes, include probe, registration, setup, teardown, remove, and shutdown. For port features, include the transition into and out of the state.

4. The diff can be kept narrow.
   A one-purpose patch is easier to validate and easier to connect to a reviewer comment. Split unrelated cleanup from functional repair.

5. The normal loop can test the claim.
   At minimum, prepare the compilation, warning, kernel-check, binding-schema, DTB, and Sashiko evidence that applies. Hardware testing remains optional and comes only after those gates pass.

If any relevant row is blocked, the agent can continue with independent Ready rows but must not “work around” the block by assuming the desired answer.

---

Ask hardware questions that can actually be answered

A vague question produces a vague reply and leaves the agent guessing. Every blocked row should produce a short, self-contained question with the exact decision at stake.

Use this format:

Question ID: Q-HW-RESET-01

Decision blocked:
Whether setup must explicitly clear VLAN and forwarding state after
software reset.

Evidence:
Manual Rev [X], §[Y], p. [Z] documents the reset control but does not
state the post-reset values for [register group].
Table [A] appears to conflict with Table [B].

Current V1 behavior:
[Function and brief observed behavior.]

Why this matters:
DSA setup must establish initial port isolation rather than depend on
bootloader state.

Answer needed:
For chip variant [part/revision], does software reset reset [specific
register group]? If not, what values are required for an isolated
initial configuration?

Safe interim position:
No functional reset-related change will be made. The patch can retain
the existing reset call while independent code and binding tasks proceed.

The question identifies:

• the exact chip and manual revision;
• the competing readings or missing detail;
• the code decision that depends on the answer;
• the smallest answer needed to unblock work;
• the conservative behavior while waiting.

Do not ask a human to “confirm the driver is correct.” Ask them to resolve one observable hardware or board fact.

---

A tool-neutral agent instruction for this stage

Whether you use Cursor or Claude Code, give the agent an explicit evidence boundary before it edits:

For each proposed DSA-driver or binding change, update the evidence matrix.

Keep these categories separate:
1. hardware facts with manual revision and page or section,
2. observed V1 behavior with file and function,
3. target-kernel DSA or binding rules,
4. analogous upstream patterns with material differences,
5. guesses or proposed changes,
6. open human questions.

Do not treat V1 behavior, successful compilation, a similar driver, or
an undocumented register value as proof of hardware behavior.

If a change depends on an unclear, incomplete, or conflicting manual or
board fact, mark the row Blocked: hardware. Prepare a focused question
and do not edit the affected behavior.

Only edit rows marked Ready. After any edit, return the change to the
project's standard checks and review loop.

Have the agent first produce a proposed matrix diff for review. This is faster than undoing an attractive but assumption-driven patch series later.

---

A practical first pass

Start with the reviewer comments that challenge correctness rather than style: DSA lifecycle, port role classification, tagger choice, bridge/VLAN behavior, DT properties, and error handling.

For each one:

1. Create a task ID and one or more trait rows.
2. Extract raw evidence without proposing code.
3. Fill the V1 and target-kernel columns.
4. Search analogues only after you know the trait being compared.
5. Mark every inference as a guess.
6. Assign a disposition before allowing the agent to modify files.

At the end of this pass, the best result may be a short list of Ready fixes and several high-quality hardware questions. That is progress: the table has prevented the agent from converting uncertainty into an upstream-visible bug.

---

Key takeaways

A reliable driver-development loop needs an evidence matrix because different sources answer different questions:

• The manual and board evidence establish hardware facts.
• V1 establishes current behavior, including omissions and error paths.
• Target-kernel DSA and binding rules establish framework obligations.
• Other upstream drivers provide bounded patterns, never direct proof.
• Guesses stay visibly quarantined.
• Open questions stop only the affected work and give humans a precise way to unblock it.

A row becomes Ready only when the proposed change is supported at the required scope. If hardware facts are unclear or conflicting, preserve the uncertainty, ask a focused question, and keep that behavior out of the patch.

The next lesson moves from this evidence record into the V1 driver itself: inventorying its switch features and DSA operations, then checking each callback against the target kernel’s calling, locking, sleeping, return-value, and helper-function rules.