Extracting and Validating Driver Facts from Hardware Manuals

Good to continue from the V1 review work list. You now know which reviewer concerns must be resolved; this lesson establishes what you may safely claim about the switch hardware while resolving them.

For a DSA driver, the hardware manual is evidence, not background reading. A register description, timing diagram, strap table, or port diagram only becomes useful when it is captured as a small, traceable fact with its exact location, conditions, and limits. If the manual does not establish a needed behavior, the agent must stop that part of the work and prepare a focused human question rather than fill the gap with a plausible implementation.

By the end of this lesson, you will have a manual-fact ledger in which every relevant statement has an exact page or section link and one operational status: CLEAR, UNCLEAR, INCOMPLETE, or CONFLICT.

---

Start with the DSA boundary, not a register search

Before extracting hardware facts, be clear about the boundary you are trying to describe. The switch is not merely a collection of PHYs and registers. In DSA, front-panel ports become Linux network interfaces, while the CPU-facing connection carries traffic between the host Ethernet controller and the switch.

The diagram is a useful model, but it is not proof of your device’s tag format or mode. Your manual must establish what the hardware actually does: which CPU port exists, how it is configured, whether tagging is inserted or stripped, how a port is identified, and which conditions select the behavior.

This gives you a disciplined way to translate a vague request such as “check the CPU port setup” into evidence questions:

• Which physical or logical port is the CPU port for this chip and package?
• Which MAC interface modes are supported on that port?
• Which registers, straps, or reset-time pins select the mode?
• Does the switch add metadata or a tag on packets sent to the CPU?
• Does it expect a tag or metadata on packets transmitted by the CPU?
• Is the tag present on the external cable, only on the CPU-facing link, or both?
• Which reset, clock, and power conditions must exist before registers are valid?

These questions keep the extraction process tied to the driver’s actual boundary without prematurely deciding how the driver should implement it.

---

Make a fact ledger with immutable citations

A manual fact is an atomic, normalized statement supported by a source excerpt. “Atomic” matters: do not combine three claims from different tables into one broad statement such as “port 5 is the RGMII CPU port and needs a delay after reset.” That sentence contains at least three independently checkable claims.

Store the original manual separately and identify the exact edition before extracting anything:

manual:
  id: "SWITCH-UM"
  vendor_document_number: "<document number>"
  revision: "<revision>"
  publication_date: "<date if stated>"
  file: "evidence/manual/SWITCH-UM-<revision>.pdf"
  sha256: "<file checksum>"
  silicon_scope: "<chip variants, package, and stepping if stated>"
  errata_checked: false

The checksum is useful because vendor manuals may be silently replaced at the same filename or portal location. A citation to “the switch manual” is not reproducible unless the manual revision is known.

For each fact, record both a human-readable locator and a direct local link. PDFs commonly have two page numbers: the PDF viewer index and the page number printed by the manual. Save both when they differ.

manual_facts:
  - id: "MF-CPU-PORT-001"
    trait: "CPU port topology"
    normalized_fact: >-
      The manual identifies logical port <N> as the CPU-facing port for
      the stated chip and package configuration.

    source:
      manual_id: "SWITCH-UM"
      link: "evidence/manual/SWITCH-UM-<revision>.pdf#page=<viewer-page>"
      printed_page: "<printed page>"
      pdf_page: "<PDF viewer page>"
      section: "<chapter > section > subsection>"
      object: "<figure, table, register, or bit-field name>"
      quote: >-
        <verbatim quotation sufficient to retain its conditions and meaning>
      context_note: >-
        Figure/table caption and any immediately applicable note, footnote,
        reset condition, or package qualification.

    applies_when:
      chip: "<chip or family>"
      revision: "<silicon stepping or manual revision>"
      package: "<if relevant>"
      port_mode: "<if relevant>"
      reset_or_boot_state: "<if relevant>"

    status: "CLEAR"
    status_rationale: >-
      The port is directly identified and the cited table applies to the
      target package. No unresolved qualifier changes this limited claim.

    v1_locator: "<file, function, property, or patch hunk if applicable>"
    dsa_relevance: >-
      Determines the Device Tree CPU-port node and the port that connects
      to the host Ethernet controller.
    allowed_use: >-
      May be used as hardware evidence for CPU-port identity; it does not
      establish interface mode, tagging, or initialization order.

A few details prevent this ledger from becoming another informal note file:

1. Quote enough context.
   A bit definition without its register reset note, table heading, or “only in mode X” footnote may reverse the meaning. For a table, preserve its title, relevant row, column headings, and footnotes.

2. Record conditions explicitly.
   Conditions may include silicon revision, package, strap state, clock mode, interface mode, reset state, or whether a port is enabled. An unqualified statement is unsafe when the manual qualifies it.

3. Keep the fact separate from its DSA relevance.
   “The port exposes a certain mode” is a manual fact. “Therefore the DSA CPU-port node should use a particular property” is an engineering interpretation that still needs Device Tree and target-kernel evidence.

4. Link to V1 without treating V1 as evidence.
   The v1_locator tells you why the fact matters. It does not prove the existing V1 behavior is correct.

5. Use placeholders honestly.
   Do not write a fabricated port number, tag type, bit name, timing value, or register behavior simply to make the record look complete.

A useful directory layout is:

evidence/
  manual/
    SWITCH-UM-<revision>.pdf
    SWITCH-UM-<revision>.sha256
  manual-facts.yaml
  manual-conflicts.md
questions/
  hardware-questions.md

Keep the captured facts in version control if the manual’s distribution terms permit it. Otherwise, version-control the ledger and a checksum, while storing the manual in the approved private evidence location.

---

Extract by hardware trait, not by chapter order

Reading a hardware manual from page one to the last page is slow and tends to mix unrelated facts. Start from the V1 driver and reviewer work list, then make a short list of hardware traits that the driver must rely on.

For a typical DSA switch V1, the first pass usually covers these traits:

Trait	Manual evidence to extract	Do not infer from it
Chip identity and access	Device IDs, MDIO or other bus addressing, register-access rules	That all register reads are safe in every power state
Port map	Port count, CPU port, external ports, internal PHY ports, unused ports	A Device Tree numbering scheme not stated by the binding
CPU-port interface	Supported MAC modes, clocks, delays, straps, lane mapping	The board’s actual strap wiring unless board documentation establishes it
Packet tagging	Tag position, format, source/destination encoding, insertion and stripping conditions	Compatibility with an existing Linux tag protocol merely because both use tags
Reset and bootstrap	Reset sources, timing constraints, retained state, register reset values	A complete driver initialization order unless the manual gives it
Port forwarding and isolation	Port-matrix controls, default forwarding state, VLAN or isolation controls	Correct bridge and VLAN callback behavior in the target kernel
PHY and link management	Internal PHY arrangement, MDIO access, link-mode limits, MAC configuration	Whether phylink or a legacy path is correct in the target kernel
Interrupts and status	Interrupt source, masking, acknowledgement, read-clear behavior	IRQ ownership and teardown safety in the Linux driver
Counters and tables	Statistics width and clear behavior; FDB or VLAN table access rules	That an operation is safe concurrently with another operation
Time stamping, if V1 exposes it	Timestamp source, FIFO behavior, packet matching fields, availability timing	A Linux timestamping implementation without target-kernel interface evidence

Create a small “question card” before searching for each trait:

trait_question:
  id: "TQ-TAGGING-001"
  trait: "CPU-port packet tagging"
  question: >-
    For packets received by the CPU, what metadata identifies the source
    switch port, and for packets sent by the CPU, what field selects the
    destination port?
  v1_relevance:
    - "drivers/net/dsa/<driver>.c: <tag or setup location>"
    - "FB-V1-<id>: <reviewer concern>"
  required_evidence:
    - "Tag format or packet-layout description"
    - "Direction-specific insertion and removal behavior"
    - "Configuration or strap conditions"
    - "Maximum frame-size or CRC behavior if stated"

Then search the manual for terms that match the hardware vocabulary rather than only Linux vocabulary: “management port,” “host port,” “uplink,” “header,” “frame format,” “tail tag,” “proprietary header,” “port vector,” “forwarding matrix,” “bootstrap,” “soft reset,” and “read clear.”

This is particularly helpful when the manual never uses the term “DSA.” The job is not to force the manual’s terminology into Linux terminology; it is to document the mapping and its limits.

---

Classify evidence by what it permits you to do

The status applies to the usable normalized fact, not to the apparent confidence of the person reading it. A polished paragraph with a missing condition is still incomplete.

Status	Meaning	Typical response
CLEAR	The manual directly establishes one bounded claim, including conditions needed for that claim.	Use it as hardware evidence, while still checking DSA and target-kernel rules separately.
UNCLEAR	The relevant wording, diagram, bit semantics, or terminology has more than one reasonable meaning.	Preserve the ambiguity, do not choose an interpretation, and ask a focused question if it blocks work.
INCOMPLETE	The manual establishes part of a needed claim but omits a necessary parameter, condition, sequence, unit, or failure behavior.	Use only the supported portion; block the dependent behavior until the missing fact is supplied.
CONFLICT	Two applicable passages in the same evidence scope cannot both be true for the same hardware state.	Record both citations, do not select a winner, and seek clarification or an erratum.

CLEAR: clear is scoped, not universal

Suppose a register table explicitly identifies a port and its field meaning, and its table heading limits the claim to the target chip package. You may record the limited port-identity fact as CLEAR.

That does not make these broader claims clear:

• that the board connects this port to the host MAC;
• that the selected interface mode matches the board straps;
• that the port should be enabled at a particular point in probe;
• that the current V1 sequence is valid after a warm reset.

Every added claim needs its own evidence.

UNCLEAR: preserve competing readings

Mark a fact UNCLEAR when you cannot unambiguously parse the source. Common examples include:

• a diagram labels a “host port” but does not say whether the label is logical or physical;
• a bit says “enable header mode,” but does not define whether the header is inserted on transmit, receive, or both;
• a timing diagram has signal names but no defined active polarity;
• an acronym appears in a table without a glossary or a cross-reference that explains it.

Record plausible readings only as alternatives, not as a hidden conclusion:

status: "UNCLEAR"
status_rationale: >-
  The figure labels a management interface, but does not state whether its
  port number uses the logical numbering of the register map or the physical
  pad numbering shown elsewhere.
possible_readings:
  - "The label refers to logical port <N>."
  - "The label refers to an external physical interface, not a port number."
blocked_decision: "CPU-port index used by the driver and Device Tree"

Do not resolve this from V1 code, an analogous driver, or what “usually” happens for this vendor. Those sources can generate hypotheses for later investigation, but they cannot make ambiguous manual text clear.

INCOMPLETE: separate the known part from the missing part

A common trap is to treat a partial statement as sufficient evidence for initialization.

For example, a manual may clearly say that a reset bit exists and that it resets the forwarding engine. If it never states whether the bit is self-clearing, how long reset takes, whether link logic is reset too, or which registers must be reprogrammed afterward, the claim “the driver can issue this reset in setup and proceed immediately” is INCOMPLETE.

Capture the supported fragment and the missing element:

normalized_fact: >-
  The documented reset control affects the forwarding engine.
status: "INCOMPLETE"
status_rationale: >-
  The manual does not establish completion detection, maximum reset time,
  retained register state, or whether the CPU-port interface is reset.
missing_information:
  - "How reset completion is detected"
  - "Required delay or status bit"
  - "Post-reset configuration requirements"
allowed_use: >-
  The reset control exists; no reset sequence or timeout may be derived from
  this source alone.

This avoids a false binary choice. You need not discard the entire passage; you simply cannot use it to justify the missing behavior.

CONFLICT: check scope before declaring a contradiction

A conflict is not merely two facts that look different. First check whether both passages apply to the same:

• chip model and silicon stepping;
• package;
• operating or interface mode;
• boot or reset state;
• register-bank selection;
• manual revision.

A statement in revision A and a changed statement in revision B is usually a version difference, not an internal conflict. Record both and identify which edition covers the target silicon. If you cannot establish that, the resulting target-silicon fact is INCOMPLETE or UNCLEAR.

Use CONFLICT when two passages are both applicable and incompatible. For example, if one applicable port table identifies the CPU connection as one logical port while another applicable configuration table assigns that same exclusive role to a different port, do not “average” the result. Create a conflict group:

conflict_groups:
  - id: "MCG-CPU-PORT-001"
    question: "Which logical port is the CPU-facing port in the target mode?"
    fact_ids:
      - "MF-CPU-PORT-001"
      - "MF-CPU-PORT-014"
    citations:
      - "SWITCH-UM revision <rev>, section <section>, printed page <page>"
      - "SWITCH-UM revision <rev>, section <section>, printed page <page>"
    applicability_checked:
      chip: "<target chip>"
      package: "<target package>"
      mode: "<target mode>"
    status: "CONFLICT"
    safe_action: >-
      Do not alter CPU-port selection, CPU-port Device Tree description, or
      dependent register programming based on either passage alone.

A manual conflict is a request for clarification, not an invitation for the agent to select the behavior that best matches V1.

---

Treat diagrams, tables, and register descriptions as evidence with different risks

Driver-relevant facts are often spread across formats. The extraction method must preserve the format-specific context.

Figures and packet diagrams

For a CPU-port or packet-tag diagram, capture:

• figure number and caption;
• direction of travel;
• which endpoint is the CPU or management side;
• byte order and bit numbering;
• whether the figure describes ingress, egress, or both;
• any statement about FCS, frame length, VLAN headers, or checksum interaction;
• configuration mode that activates the layout.

The DSA control and data flow diagram in this lesson is useful for framing those questions. It cannot answer them for a specific switch. In particular, never infer that an apparent tag layout matches a tagger already present in the Linux tree without comparing each field and behavior later.

Register and bit-field tables

For each relevant bit, record:

• register name and address;
• bit range and bit numbering convention;
• access type, such as read-only, read-write, write-one-to-clear, or self-clearing;
• reset value;
• preconditions and side effects;
• related status or completion register;
• whether the register is global, per-port, per-VLAN, or banked.

The bit-field prose may be clear while the driver-relevant sequence remains incomplete. “Write one to clear” does not state whether an interrupt is level-triggered, whether another status read is needed, or whether masking must precede acknowledgement. Those are separate facts.

Timing and reset material

For reset, clocks, and bootstrap straps, the minimum evidence set is often distributed across a pin chapter, reset chapter, electrical timing chapter, and initialization example. Keep citations to all contributing parts, but do not combine them into a full sequence until every ordering relation is documented.

If an initialization example is labelled “typical,” “recommended,” or “reference only,” quote that qualification. It may be good evidence of a vendor-supported sequence, but it may not establish that the sequence is mandatory or complete for every configuration.

---

Use an agent for extraction, but reserve the safety decision for review

This is a good place for an AI agent to reduce clerical work. It can search a large manual, collect candidate passages, identify references between a register and a timing diagram, and populate a draft ledger. It must not decide that a behavior is safe merely because it found a plausible sentence.

Give the agent narrow, tool-neutral instructions such as:

Read the approved local hardware manual and the existing V1 work list.
Do not edit kernel source, Device Tree files, or patch messages.

For each requested hardware trait:
1. Find candidate manual passages, figures, tables, registers, and footnotes.
2. Copy a sufficient verbatim quote or structured table excerpt.
3. Record document number, revision, chapter and subsection, printed page,
   PDF viewer page, object name, and local page link.
4. State the exact normalized claim and every stated condition.
5. Propose one status: CLEAR, UNCLEAR, INCOMPLETE, or CONFLICT.
6. For UNCLEAR and INCOMPLETE, state what exact fact is missing.
7. For CONFLICT, cite every conflicting passage and compare their scope.
8. Keep manual fact, V1 behavior, DSA interpretation, and assumptions in
   separate fields.

Never:
- infer behavior from existing driver code, a similar driver, or common
  vendor practice;
- invent a timing value, reset sequence, port number, tag field, or
  register side effect;
- mark a fact CLEAR when qualifiers, direction, or applicability are absent;
- resolve contradictory text by choosing the result that best fits V1;
- modify code to test an unproven hardware interpretation.

Review the output in two passes:

1. Citation pass: Open every page link. Check that the quoted text, page number, table heading, footnotes, and manual revision actually support the normalized claim.
2. Scope pass: Check whether the claim applies to the target chip, package, board mode, and reset state. This is where many apparently clear facts become incomplete.

For a scanned or OCR-derived manual, add an explicit OCR-risk note whenever a field name, bit number, unit, polarity, or diagram label cannot be read reliably. Treat such a record as UNCLEAR until checked against the original image.

---

Create focused human questions from blocked facts

A good hardware question is answerable by someone with board knowledge, vendor access, or an authoritative erratum. It names the exact decision that is blocked and shows the evidence already checked.

Avoid this:

How should reset work?

Use this form:

Decision blocked:
Whether the driver may poll a reset-complete status bit before programming
the CPU-port mode.

Evidence checked:
- Switch User Manual, revision <rev>, section <section>, printed page <page>:
  reset control definition.
- Switch User Manual, revision <rev>, section <section>, printed page <page>:
  status register definition.

What is clear:
The reset control exists and affects <documented block>.

What is missing:
The manual does not say whether <status bit> indicates completion of this
reset operation, nor the required wait condition before CPU-port programming.

Question:
For chip <model>, stepping <step>, and board mode <mode>, what supported
completion condition and post-reset delay or ordering should software use?

This format makes it difficult for an agent or a human to answer vaguely. It also makes the eventual response easy to convert into a cited decision record.

While a hardware question is open, independent work may continue. For example, you may repair a YAML spelling error or a managed-resource lifetime bug if that work makes no claim about the missing reset behavior. The blocked scope must remain explicit:

blocked_scopes:
  - "CPU-port reset ordering"
  - "Delay value after reset"
allowed_parallel_work:
  - "Binding schema syntax and example consistency"
  - "Target-kernel API investigation unrelated to reset ordering"

---

A 40-minute first pass for the current V1

Use this first pass now rather than waiting until all reviewer comments are understood perfectly.

1. Freeze the manual identity.
   Save its document number, revision, date, file checksum, and target silicon scope.

2. Select five high-risk trait questions.
   Begin with the traits that influence V1 behavior or reviewer concerns. For most DSA drivers these are CPU-port identity, CPU-port interface mode, packet tagging, reset and bootstrap, and port isolation or forwarding defaults.

3. Create candidate fact records.
   Extract only directly supported statements. Aim for small records rather than a polished hardware summary.

4. Classify each record immediately.
   Give every record one of the four statuses and write the reason. Do not leave “probably clear” as an implicit fifth state.

5. Create conflict groups and human questions.
   Do this as soon as you encounter conflicting or insufficient material. Do not wait for the agent to begin implementation.

6. Link each fact to a V1 concern.
   Add the relevant function, binding property, or feedback task. A fact without a use case may be retained, but it should not distract from the review-driven work list.

Finish with this audit:

Audit question	Required answer
Can another engineer open the exact source location?	Manual edition, section, printed page, viewer page, object, and link are present.
Does the quote retain the needed condition?	Table headings, notes, qualifiers, and direction are captured.
Is the normalized claim smaller than the evidence?	The record makes no broader claim than the source states.
Has V1 been kept separate from hardware truth?	V1 is only a locator or observed behavior, never proof.
Are ambiguous facts blocked?	Every UNCLEAR, INCOMPLETE, or CONFLICT record names the decision it prevents.
Can a human answer the question efficiently?	The question identifies target hardware, citations, known facts, missing facts, and the requested decision.

---

Key takeaways

A DSA driver manual is useful only when its claims are reproducible and bounded.

• Preserve the precise manual edition, checksum, pages, sections, figures, tables, and conditions behind every extracted fact.
• Keep four layers separate: manual fact, V1 behavior, DSA interpretation, and implementation decision.
• Mark a fact CLEAR only for the limited behavior the source directly establishes.
• Mark missing qualifiers or sequencing information INCOMPLETE; mark genuinely ambiguous wording UNCLEAR; and preserve incompatible applicable passages as CONFLICT.
• Neither a successful build, current V1 behavior, nor a similar upstream driver can fill a manual gap.
• Convert blocked work into focused human questions and permit only independent work to proceed.

Next, you will break the switch into hardware traits more systematically and use analogous upstream drivers, kernel changes, and mailing-list discussions as comparative evidence—without treating another device’s behavior as proof for this one.