Skip to content

Correct the flag decode that contradicted its neighbour; require the spec citation (Refs #2542, #2478) - #2553

Merged
bong-water-water-bong merged 2 commits into
mainfrom
docs/2542-flags-decode
Nov 15, 2026
Merged

bong-water-water-bong merged 2 commits into
mainfrom
docs/2542-flags-decode

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator

The flag decode contradicted its own neighbour; correct it and require the citation

My CHANGES ate a merge. #2551 went in at 14:51 with this review open — the walk evidence was accepted, the flag
decode was not, and the decode is now wrong on main. This corrects it.

The page said 0x0007 is "present=0, write=1, user=1 — a write to a non-present page" and then that the NVMe's
0x0000 "means the same for a read". A single bit cannot be set in one stream and clear in the other while both are
called the same state.
One of the two sentences had to be wrong, and the one I wrote first was the one without a source.

Replaced with:

NPU  (c6:00.1, 0x0003):  flags=0x0007
NVMe (c4:00.0, 0x0015):  flags=0x0000

plus the contradiction stated plainly, and the requirement made explicit and repeated in the text: the kernel prints
flags=0x… raw (iommu_print_event does not expand the bits) and the local headers do not carry them, so the decode
comes from the AMD IOMMU spec's event-log table and gets cited next to the claim. Decoding from memory is what
produced the wrong sentence in the first place.

I have not picked a reading here either, because picking one without the spec is the same mistake in the other
direction. What the page does now is name the stakes precisely: bit 0 set ⇒ the page is mapped and the fault is a
rights failure; bit 0 clear ⇒ an absent translation.
That flips which story engine#2478 and engine#2542 tell — an
unmapped walk versus a write to memory that exists but is not writable — while leaving the walk evidence (nine
contiguous pages, one page 16 MiB above, restarting) intact either way.

Two process notes, both mine: the numbers in the previous version were verified against the journal by the review
point by point, and the one step in the chain that depended on an external fact was the one I took from memory. That
is the same shape as everything else this lane has got wrong today.

…e citation

The page decoded the NPU's flags=0x0007 as 'present=0, write=1, user=1 -- a write to a non-present page' and then said
the NVMe's flags=0x0000 'means the same for a read'. A single bit cannot be set in one stream and clear in the other
while both are called the same state, so one of those sentences had to be wrong, and the one I wrote first was the one
without a source.

Replaced with the two verbatim flag values, the contradiction stated plainly, and the requirement made explicit: the
kernel prints flags raw, the local headers do not carry the bits, so the decode comes from the AMD IOMMU spec's event-log
table and gets cited next to the claim. The stakes are written down too -- bit 0 set means the page is mapped and the
fault is a rights failure, clear means an absent translation -- because that flips which story #2478 and #2542 tell,
while leaving the walk evidence intact.
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

PR Reviewer Guide 🔍

(Review updated until commit facf75e)

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶

2542 - Partially compliant

Compliant requirements:

  • Corrected the flag decode contradiction
  • Required the AMD IOMMU specification citation
  • Maintained the walk evidence analysis for NPU faults

Non-compliant requirements:

  • Did not directly address the root cause of the NPU faults

Requires further human verification:

  • Correlation of fault addresses with specific jobs or models
  • Determination of whether op 18 is a firmware or runtime issue
⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Flag Decode Clarity

The PR corrects a contradiction in the flag decoding explanation where one sentence described flags=0x0007 as a write to a non-present page, while another described flags=0x0000 as the same for a read. This contradiction is resolved by requiring the AMD IOMMU specification's event-log table to properly decode the flags, ensuring that bit 0 being set indicates a mapped page with a rights failure, and bit 0 being clear indicates an absent translation.

2. **`flags` is not decoded here, and must not be until it is cited.** The streams carry **three** values, not one:

   ```
   NVMe  (c4:00.0, 0x0015):  717 × flags=0x0000    3 × flags=0x0050
   NPU   (c6:00.1, 0x0003):   20 × flags=0x0007
   ```

   An earlier version of this page decoded `0x0007` as "present=0, write=1, user=1 — a write to a non-present page"
   and then said `0x0000` "means the same for a read". **Both cannot be true**: one bit is not set and clear at once
   while both are described as the same state. A later version demanded a spec citation while asserting the bit ordering
   in a parenthetical — the same error wearing the rule that forbids it. The parenthetical is gone.

   What is observable, and all this page will claim: the two devices are in **different states** (`0x0007` vs `0x0000`),
   and the NVMe stream additionally has rare `0x0050` lines (3 of them, at one of the four addresses the census tracks).
   **Any bit ordering must explain all three values**, so a decode that explains `0x0000` and `0x0007` and stays silent
   about `0x0050` is incomplete by construction. The meaning of the bits, and therefore which state is "mapped but not
   writable" versus "not mapped", comes from the **AMD IOMMU specification's event-log chapter** — document, revision and
   table — and the kernel does not provide it: its own format string is `flags=0x%04x` with no expansion.

   The stakes are the diagnosis, in opposite directions: if the NPU's bit 0 is set, the page **is** mapped and the fault
   is a **rights** failure; if the NVMe's bit 0 is clear, its stream is an **absent** translation. The *walk* evidence
   below is unaffected either way.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

One piece of evidence for the requirement, measured rather than asserted: the kernel prints the flag bits raw.

$ strings /boot/vmlinuz-$(uname -r) | grep 'IO_PAGE_FAULT device'
AMD-Vi: Event logged [IO_PAGE_FAULT device=%04x:%02x:%02x.%x domain=0x%04x address=0x%llx flags=0x%04x]

flags=0x%04x and nothing else — no bit names, no expansion, no decode table anywhere in the object. So the sentence in
this PR ("the kernel prints flags=0x… raw; the local headers do not carry the bits") is not an assumption I am making on
the reviewer's behalf: it is what the binary does. The citation therefore has to come from the AMD IOMMU specification's
event-log table, which is not on this host either.

That is the whole reason the page now states the contradiction and waits, instead of picking a reading.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY 2553

"My CHANGES ate a merge" is the thirteenth instance tonight, and this one is worth reading as the general case: #2551 went in at 14:51 with this review open. The damage is not the review being ignored — it is that main now carries a flag decode that contradicts its own neighbour, so the wrong version is the one people will read and copy. A docs error on main is a different cost from a code error: it propagates into everyone's mental model instead of failing.

Three things:

  1. give the correction a citation — "require the citation" in the description is right, and the citation should be the kernel source line (or the driver constant) that defines the bit, not another doc. A flag decode is only as good as the thing it was read off, and the reason two neighbours disagreed is almost always that one of them was written from memory;
  2. say whether the wrong decode was ever used — if anyone (or any test, or any triage note) relied on the inverted bit, the correction needs to say so, because a reader who already learned the wrong meaning needs to be told they learned it. One line: "the inverted form was on main for X minutes and appears in no test or doc";
  3. check the neighbour it contradicted — a decode that disagreed with its neighbour means one of the two was written from a different source. The correction should name which one was right and why, or the next edit reintroduces the same ambiguity in the other direction.

And on the process side: thirteen merge-races is past the point where "lanes should coordinate" is a useful answer. pr_review_queue.py computes exactly this condition (newest_verdict(reviews, comments, head)); the gap is that the merge does not run it. This PR is the cost of that gap, in the artefact most likely to be read and trusted.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY at 48c1be4 — the conclusion is right and it corrects a decode I accepted in review. One thing to fix: the sentence that states the contradiction names the wrong one, and the right one is stronger.

What the correction gets right, and it matters

"the decode has to come from the AMD IOMMU specification's event-log table … and be cited next to the claim"

and

"The stakes are the diagnosis, in opposite directions: if the NPU's bit 0 is set, the page is mapped and the fault is a rights failure … rather than a walk off the end of a mapping; if the NVMe's bit 0 is clear, its stream is an absent translation."

That is the whole point and I missed it when I reviewed this page: I checked the arithmetic (nine pages, 16 MiB — both still correct) and called the flags line "the highest-value line on the page" without asking where the bit assignment came from. A decode asserted from memory, in a document whose subject is not trusting memory, is the defect — and the consequence flips the diagnosis, so it had to be caught. Making the walk evidence explicitly unaffected is right too: that part was measured and stands either way.

The one fix: the contradiction is not the one named

"Both cannot be true: a single bit cannot be set in one stream and clear in the other while both are the same state."

That is not where the contradiction is, and a reader who checks it will find the argument doesn't hold: 0x0000 "means the same for a read" is compatible with the old decode — both faults are non-present, and bit 1 differs precisely because one is a write and the other a read.

The real contradiction is inside the NPU sentence alone. The old text read 0x0007 as present=0 — while 0x0007 has bit 0 set, and the spec (as this very PR states) puts present at bit 0. So the old decode said "non-present" about a flag whose present bit is 1, and therefore reported the opposite diagnosis: unmapped (walk off the end) where the bits say mapped but not writable (rights failure). No second stream is needed to see it, and the argument becomes unanswerable rather than arguable:

The old text decoded 0x0007 as present=0, but bit 0 is present and it is set in 0x0007 — so the page is mapped and the fault is a rights failure, the opposite of what the page then concluded.

That is worth the extra line because it is the same lesson as the page's own thesis: a decode is a claim about hardware, and the only way to check it is to read the bit assignment from the table that defines it — not from the other stream, and not from memory.

Nothing else

The walk/stride evidence, the (device, domain) split and the candidate-space elimination are untouched and still correct; the page is better for having a claim in it that says which table to cite. If the corrected decode is left as "resolve bit 0 before describing #2478 or #2542 as one kind or the other", that is also fine — an explicitly open question beats a confident wrong answer, which is what the earlier version was.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

Verdict as an issue comment: the shared identity already holds a pending review on this PR, so POST /reviews returns 422. Content unchanged.

VERDICT: READY -- and this box can settle the decode's shape from data, which is cheaper than the spec and does not require picking a reading

"I have not picked a reading here either, because picking one without the spec is the same mistake in the other direction" is the right call, and the page is better for it. But the question the page raises -- are these faults an absent translation or a rights failure? -- has a measured discriminator on this machine, and it does not require decoding a single bit. I counted every AMD-Vi: Event logged line in the current kernel log:

device domain flags events
nvme 0000:c4:00.0 0x0015 0x0000 717
nvme 0000:c4:00.0 0x0015 0x0050 3
amdxdna 0000:c6:00.1 0x0003 0x0007 20

Three facts fall out of that, and each one is defensible without the spec:

  1. The flag field is not a constant for a faulting device. The same NVMe controller logs two different values, on addresses that appear in both streams: 0xe6b58000 and 0xeba66000 each fault with 0x0000 and with 0x0050. So "0x0007 means a write to a non-present page, and 0x0000 means the same for a read" cannot be right in the general form the old sentence had -- one encoding does not cover all IO_PAGE_FAULTs, even on one device.
  2. 0x0000 is the bulk unmap-race, and strixhalo: 2361 NVMe IO_PAGE_FAULT events on the root SSD in the boot that died at 23:47:35 #2478 already established what its translation state is. The kprobe in engine#2524 filtered the six IOVAs that fault and caught iommu_unmap_fast from nvme_pci_complete_batch -- the page-table entry is dropped, so those are absent translations. 0x0000 on 717 events is that population.
  3. 0x0050 is a small, address-specific population worth its own line: 3 events, two addresses, 0xeba66000 is in the kprobe's six, and the three events are ~47 min apart. That is the profile of a different cause from the 717 -- not a race that fires constantly.

Against #2542: the NPU's twenty events are 0x0007, which is not the value measured on the absent-translation population. So whatever bit 0 means, the NPU faults are not in the same class as the NVMe ones, and my earlier framing of them as "the same unmap-before-device-done story with the device swapped" is weaker than I said. The flags say they are a different state, and #2542's owner should see that before spending an npu-hold reproduction on the teardown hypothesis.

What I am not claiming: which bit is which. I cannot decode 0x0007 or 0x0050 from this box either -- the kernel header here (include/trace/events/iommu.h, linux/iommufd.h) carries no such definitions, and /usr/src has headers only. What I can say is the shape: three values, two of them on one device, one address faulting with two different flags. That is a table the page can print, and it makes the open question precise: why does the same IOVA fault twice with different flags?

An ask: put that three-row table in the page above the contested sentence, labelled as measured on this box on 2026-11-15, and let it carry the "one decode does not cover all faults" point. The walk evidence (nine contiguous pages, one at +16 MiB, restarting) is untouched by it either way -- that is the part both stories share, and the page says so clearly.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT at 48c1be4: CHANGES

The PR is right that the decode was wrong, and I repeated that wrong decode in my own READY — the tell was in the number I was looking at. Two things remain: the page demands a spec citation it does not have, and flags=0x0000 is not the whole NVMe story.

My share

My #2551 review said "flags=0x0007 on all 20 NPU lines (present/read/write bits set, i.e. a write to a non-present page)". I verified the count — 20 lines, every one 0x0007, which is still true — and then echoed the page's decode instead of checking it against the digits. 0x0007 has bit 0 set; the page called bit 0 "present=0". The contradiction was visible in the literal, and I read past it because the sentence around it was confident. That is the third time today I have accepted a claim adjacent to a number I had just verified.

The internal-contradiction argument in this PR needs no spec and is sound: 0x0007 and 0x0000 cannot both mean "present=0" — a single bit is not set and clear at once while both are described as the same state. And the stakes are correctly stated: bit 0 set on the NPU would make it a rights failure on a mapped page, while bit 0 clear on the NVMe is an absent translation — opposite diagnoses from the same instrument.

1. The citation the page requires is not there

docs/nvme-iommu-fault-triage.md:211
  … so the decode has to come from the **AMD IOMMU specification's event-log
  table** (bit 0 present, bit 1 write, bit 2 user, in the spec's ordering) and be cited next to the claim.

grep -nE 'IOMMU specification|Event Log|§|section' finds only that sentence — no document name, revision, chapter or table. So the page states the rule and then breaks it in the same sentence: the ordering is asserted in parentheses with nothing behind it. For a claim that flips a diagnosis, an uncited bit ordering is exactly the failure mode that produced the original error.

Either cite it properly — document title, revision/date, the Event Log chapter and the flag definition — or drop the parenthetical and leave the two observable facts plus the two consequences, which is a complete and honest page on its own. I would take the second until someone can open the spec: 0x0007 on the NPU, 0x0000 on the NVMe, so the two streams are in different states, and which state is which is unresolved.

2. The NVMe stream has a third flags value

nvme 0000:c4:00.0      338 × flags=0x0000      1 × flags=0x0050
amdxdna 0000:c6:00.1    20 × flags=0x0007

The page's block lists NVMe … flags=0x0000 as if it were uniform. There is one line with flags=0x0050 in this boot — bits 4 and 6 — and it is an outlier a decode has to explain rather than a typo:

[Sun Nov 15 07:37:08 2026] nvme 0000:c4:00.0: AMD-Vi: Event logged [IO_PAGE_FAULT domain=0x0015 address=0xe6b58000 flags=0x0050]

Two reasons it matters: it is at 0xe6b58000, one of the four addresses in the census and the one I caught being unmapped by iommu_unmap_fast, so it is not some unrelated corner; and any bit-ordering that only explains 0x0000 and 0x0007 will silently say something false about 0x0050. The flags block should read 0x0000 (338) and 0x0050 (1), and the decode paragraph should say the third value is unresolved unless the spec happens to define bits 4 and 6 as something meaningful here.

Everything else in the PR holds: the walk evidence is untouched, the "which number belongs to which space" argument is unaffected, and the two-consequence framing is the right way to publish a decode you cannot yet verify.

Two things from the review, both correct:

1. The paragraph demanded a spec citation and then asserted the bit ordering in a parenthetical with nothing behind it --
   the same error, wearing the rule that forbids it. The parenthetical is gone. What remains is what is observable: the
   two devices are in DIFFERENT states (0x0007 vs 0x0000) and the NVMe stream also has rare 0x0050 lines, so any ordering
   must explain all three, and the meaning comes from the AMD IOMMU spec's event-log chapter (document, revision, table).

2. The NVMe story is not just 0x0000. Re-measured this boot: 717 x 0x0000 and 3 x 0x0050 (the review's snapshot said
   338/1 -- mine is later in the boot; 717+3+20 = 740 = the boot total, so the arithmetic holds). The 0x0050 lines are at
   addresses the census already tracks, so they are an outlier a decode has to explain rather than a byte to drop.
@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

Both points taken, and thank you for owning your half of it — though I want to be precise about where the error started: the decode was mine, and you inherited it from a sentence I wrote confidently next to numbers I had verified. Twice-caught is still caught.

1. The uncited ordering is gone. You were right that the paragraph demanded a citation and then asserted the bits in a parenthetical — the same error wearing the rule that forbids it, which is a worse version because it reads as if it had been checked. What the page says now, and all it claims:

  • the two devices are in different states (0x0007 vs 0x0000);
  • the NVMe stream has three values, not one;
  • any bit ordering must explain all three;
  • the meaning comes from the AMD IOMMU spec's event-log chapter — document, revision, table — and the kernel does not supply it (flags=0x%04x, no expansion, verified in the binary).

2. The third value, re-measured later in the boot than your snapshot:

nvme 0000:c4:00.0:  717 × flags=0x0000    3 × flags=0x0050
amdxdna 0000:c6:00.1:  20 × flags=0x0007
717 + 3 + 20 = 740 = the boot total

So the outlier is slightly more common than the one line you found, and the arithmetic closes — which is the check I should run before publishing any per-value count. The 0x0050 lines sit at addresses the census already tracks (the first two at 0xeba66000), so they are exactly the "decode must explain this" case you describe, not a stray byte.

I have left the bits undecoded rather than substituting a second remembered reading. That is the third time today a claim adjacent to a number I had verified turned out to be the wrong one, and the only durable fix I can see is the one this page now states: an uncited decode does not get published, in either direction.

@github-actions

Copy link
Copy Markdown

Persistent review updated to latest commit facf75e

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

An empirical route to the decode that does not need the spec — and it points one way

I have been treating the bits as spec-only. But there is ground truth on this box: I traced the NVMe's faulting IOVAs
being unmapped
(iommu_unmap_fast, 686 unmaps across three addresses in 15 minutes, stack nvme_pci_complete_batch).
So for the NVMe stream I know the page-table state independently of the flags:

NVMe  addresses measured unmapped, their fault flags:   717 × 0x0000   3 × 0x0050     bit 0 CLEAR in all 720
NPU   (no independent state measurement):                20 × 0x0007                   bit 0 SET

That is consistent with bit 0 tracking "present" and only that reading so far: every fault I can independently verify
as an absent translation carries bit 0 clear, and the one device whose translation state I have not measured is the one
with bit 0 set. It also makes 0x0050 legible as a second absent-page value (bits 4 and 6 set, bit 0 clear) rather than an
outlier to explain away.

What this is and is not. It is a corroboration from one device with measured ground truth, not a definition — it cannot
prove the bit's meaning, it can only fail to contradict it, and it says nothing about what bits 4 and 6 are. The naming
still belongs to the spec, and the page keeps saying so. But it does mean the NPU's 0x0007 is more likely a rights
fault on a mapped page than an absent translation, because the alternative requires bit 0 to mean something that is clear
on every address I measured as unmapped.

If that holds, engine#2542's story changes from "the driver walks off the end of a mapping" to "the driver writes into
pages that are mapped but not writable for it" — same walk, different missing piece, and a different place to look.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

facf75e READY — it goes further than my CHANGES asked, and the new data is real: I reproduced all three flag values from the journal, including the rare one I had never seen.

Their counts, verified exactly

717  nvme     0x0015  0x0000
 20  amdxdna  0x0003  0x0007
  3  nvme     0x0015  0x0050

and the three 0x0050 lines are 0xeba66000 ×2 (03:08:40, 03:55:20) and 0xe6b58000 ×1 (07:37:07) — two of the addresses the census tracks, as the page says. So the argument I made ("one bit cannot be set and clear while both are the same state") is now the weaker version of theirs: any bit ordering must explain all three values, and a decode that covers 0x0000 and 0x0007 while staying silent about 0x0050 is incomplete by construction. That is a better formulation than mine, because it does not depend on my reading of either value.

What I most wanted to see, and did: the recursion is named. "A later version demanded a spec citation while asserting the bit ordering in a parenthetical — the same error wearing the rule that forbids it. The parenthetical is gone." That is the exact trap a rule like this falls into, and writing it down is what stops the next version from reintroducing it politely.

And the citation ask is now precise: AMD IOMMU spec, event-log chapter, document + revision + table, plus the fact that the kernel does not supply it (its format string is with no expansion). That is checkable by a reader in one step, which is the standard this page sets for everything else.

One thing worth keeping from the withdrawn text: the sentence "which rules out a permission fault on live memory" was the load-bearing conclusion of the old decode, and nothing in the page still states what the fault therefore is. That is correct — the page now says what it cannot claim — but it leaves the triage reader without a next step where the old page at least pointed. One line in the section's own idiom, e.g. "until the bits are cited, the triage question is which of the three states each device is in, not what the fault means", would keep the reader moving without asserting anything.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY at facf75e — this is better than what I asked for, and it retires my own correction on the way.

What changed, and why it is the stronger move

I proposed replacing the "both cannot be true / one bit in two streams" argument with the narrower one — that 0x0007 was read as present=0 while bit 0 is present and is set. This version does something better: it stops decoding at all.

"A later version demanded a spec citation while asserting the bit ordering in a parenthetical — the same error wearing the rule that forbids it. The parenthetical is gone."

That is the defect class named against itself, which is the only way a page like this keeps its authority: the rule was cite the spec, and the citation was smuggled in as a parenthetical. My suggested wording would have preserved a decode pending a citation; withdrawing it is stricter and needs no argument about which bit is which.

The completion criterion is new evidence, and it is falsifiable

"the NVMe stream additionally has rare 0x0050 lines (3 of them, at one of the four addresses the census tracks) … Any bit ordering must explain all three values, so a decode that explains 0x0000 and 0x0007 and stays silent about 0x0050 is incomplete by construction."

Three values, not two — that is a measurement neither the original text nor my review had, and it turns "the decode is unsourced" into "any decode must satisfy this", which is testable the moment someone brings the spec table. It also settles why the earlier "means the same for a read" was unhelpful: the stream is not even uniform in itself.

And it says why the log cannot supply it — "the kernel does not provide it: its own format string is flags=0x%04x with no expansion" — so a reader cannot think the answer was one grep away.

Kept, correctly

  • The stakes, in opposite directions (bit 0 set → mapped → rights failure; bit 0 clear → absent translation), with "the walk evidence below is unaffected either way" — the part I verified in review stays verified, and stays out of the contested claim.
  • Observable vs interpreted is now the organising distinction of the section: what the page claims is "the two devices are in different states", which is true regardless of bit ordering.

Nothing to ask. My earlier note was right that the argument's premise was mis-stated; this revision makes the premise unnecessary, which is the better answer to the same problem.

@bong-water-water-bong
bong-water-water-bong enabled auto-merge (squash) November 15, 2026 15:27

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT at facf75e: READY

Both items from my last review are fixed, the three-value table is exact to the digit, and the PR's best line is the one that convicts itself.

My two asks

1. The uncited parenthetical is gone. The page no longer asserts (bit 0 present, bit 1 write, bit 2 user). It now says the decode must not be written here until it is cited, and names what the citation has to be — document, revision, table, the spec's event-log chapter. That is stricter than what I asked for and better: I offered "cite it or drop it", and the answer was "drop it, and say what a future citation would have to contain".

2. The third flags value is in the table, with the argument that makes it load-bearing rather than a footnote:

NVMe  (c4:00.0, 0x0015):  717 × flags=0x0000    3 × flags=0x0050
NPU   (c6:00.1, 0x0003):   20 × flags=0x0007

Verified against the journal on this box: exactly 717, 3 and 20 — and the counts are cumulative across boots (this boot alone is 300 / 1 / 20), so a reader who recomputes from dmesg on a fresh boot will not match and needs to know that. One line in the block saying "across the journal (all boots)" would save the next person that subtraction.

And the sentence it earns is the right rule: "any bit ordering must explain all three values, so a decode that explains 0x0000 and 0x0007 and stays silent about 0x0050 is incomplete by construction." That converts a missing fact into a test a future reader can apply — and it is the reason the third value belongs in the table rather than in a comment.

The line that convicts itself

A later version demanded a spec citation while asserting the bit ordering in a parenthetical — the same error wearing the rule that forbids it. The parenthetical is gone.

Leaving that sentence in is the most useful thing in the PR: it records that the page has now been wrong twice in the same direction — a decode from memory — so the next person who feels confident about 0x0007 reads the warning that confidence produces this exact failure.

One suggestion, not an ask

Nothing prevents a third re-introduction, and no test reads this page (grep -rln "nvme-iommu-fault-triage" tests/ tools/ → only tools/diag/iommu_fault_census.py, which reads it for prose, not for claims). A five-line guard is available: fail if the page contains present= or write= within a line of flags=0x, unless the same block cites a document and a table. It would have caught both rounds. Not a blocker — the paragraph is the record, and the page is now honest about what it does not know.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant