fix(devicetree): report nonzero structure padding (#12361)

Keep DTB and FIT observations when an admitted alignment gap contains
nonzero bytes. Retain one parser-owned diagnostic with the count and
first file offset.

Refs #10179.

Co-authored-by: Nianze Wu <wunianze666@gmail.com>
This commit is contained in:
morlutoandNianze Wu authored and GitHub committed 2026-11-19 13:47:46 +00:00
1 parent a44ff73676
commit 370602cfbb
7 files changed
+156 -20

No files matched your search

+7
View File
@@ -6,6 +6,13 @@ other versions return `unsupported_target`. Corrupt recognized blobs return
`invalid_request`, and exhausted budgets return `resource_constraint` without
partial success.
[DTSpec §5.4.1](https://devicetree-specification.readthedocs.io/en/stable/flattened-format.html#lexical-structure)
requires zero padding after structure node names and property values. For
example, [libfdt's node rename](https://github.com/dgibson/dtc/blob/c954f9dd835764ec69d3d9afb467c4541b47b66d/libfdt/fdt_rw.c#L253-L273)
can leave bytes from the old name after the new terminator. REA reports the
count and first file offset of nonzero padding while retaining the tree's
observations when all fields fit.
```bash
rea inspect-devicetree /artifacts/board.dtb --json
rea inspect-devicetree /artifacts/board.dtb --detail summary --evidence_output /artifacts/board-evidence.json --json
+3 -1
View File
@@ -30,7 +30,9 @@ that contains `/images` is treated as a FIT. The container format is `fit`.
Recognition is a probe. The complete devicetree parse decides, so a file whose
prefix declares `/images` but whose structure is malformed fails as a
malformed FIT rather than falling back to plain classification.
malformed FIT rather than falling back to plain classification. FIT inventory
reports nonzero structure alignment padding using the shared
[devicetree rules](devicetree.md).
## Images and metadata
+3 -3
View File
@@ -557,7 +557,7 @@ const fitConfigurations = (
return { default_configuration: defaultConfiguration, configurations };
};
const parseFit = (fdt: Buffer, path: string): Devicetree => {
const parseFit = (fdt: Buffer, path: string) => {
try {
// The artifact field is only echoed back; the reader binds the carrier hash.
return parseDevicetree(
@@ -595,7 +595,7 @@ export const readFitStructure = (
path: string,
fileSize: number,
): FitStructure => {
const tree = parseFit(fdt, path);
const { report: tree, structureLimitations } = parseFit(fdt, path);
const byPath = new Map(tree.nodes.map((node) => [node.path, node]));
const children = new Map<string, FitNode[]>();
for (const node of tree.nodes) {
@@ -627,7 +627,7 @@ export const readFitStructure = (
`FIT images declare ${String(declared)} bytes, exceeding this file's ${String(budget)}-byte expansion budget`,
{ boundary: "memory" },
);
const facts: FitFacts = { fdt, limitations: [] };
const facts: FitFacts = { fdt, limitations: [...structureLimitations] };
return {
images,
limitations: facts.limitations,
+1 -1
View File
@@ -24,7 +24,7 @@ const parse = (b: Buffer, limits = {}) =>
sha256: createHash("sha256").update(b).digest("hex"),
},
inspectDevicetreeInputSchema.parse({ path: "/board.dtb", ...limits }),
);
).report;
describe("flattened devicetree", () => {
it.each([16, 17])(
"decodes v%s with derived facts and unresolved references",
+28 -5
View File
@@ -35,7 +35,7 @@ export const parseDevicetree = (
bytes: Buffer,
artifact: Devicetree["artifact"],
input: InspectDevicetreeInput,
): Devicetree => {
): { report: Devicetree; structureLimitations: readonly string[] } => {
if (bytes.length > input.max_file_bytes)
throw devicetreeLimitFailure("max_file_bytes", input.max_file_bytes);
const {
@@ -98,6 +98,16 @@ export const parseDevicetree = (
if (cursor > structEnd - n)
malformed("Truncated FDT structure token or property");
};
let nonzeroPaddingBytes = 0;
let firstNonzeroPadding: number | undefined;
const observePadding = (start: number, end: number) => {
// Callers admit the aligned extent before observing its padding.
for (let offset = start; offset < end; offset++) {
if (bytes[offset] === 0) continue;
nonzeroPaddingBytes += 1;
firstNonzeroPadding ??= offset;
}
};
while (cursor < structEnd) {
need(4);
const offset = cursor,
@@ -109,8 +119,10 @@ export const parseDevicetree = (
if (nodes.length >= input.max_nodes)
throw devicetreeLimitFailure("max_nodes", input.max_nodes);
const name = text(cursor, structEnd);
cursor = align(name.next);
need(0);
const next = align(name.next);
need(next - cursor);
observePadding(name.next, next);
cursor = next;
const parent = stack.at(-1);
if (
name.value.includes("/") ||
@@ -144,9 +156,11 @@ export const parseDevicetree = (
const length = u32(cursor),
nameoff = u32(cursor + 4);
cursor += 8;
const next = align(cursor + length);
const end = cursor + length;
const next = align(end);
// Every open node needs an END_NODE token, followed by FDT_END.
need(next - cursor + (stack.length + 1) * 4);
observePadding(end, next);
if (++properties > input.max_properties)
throw devicetreeLimitFailure("max_properties", input.max_properties);
if (nameoff >= header.size_dt_strings)
@@ -232,7 +246,15 @@ export const parseDevicetree = (
return s?.length === 1 ? (s[0] ?? null) : null;
};
const handles = new Map<number, string | null>();
// An editor can leave nonzero padding without changing the parsed fields.
const structureLimitations =
firstNonzeroPadding === undefined
? []
: [
`FDT structure padding contains ${String(nonzeroPaddingBytes)} nonzero ${nonzeroPaddingBytes === 1 ? "byte" : "bytes"}. The first is at file offset ${String(firstNonzeroPadding)}.`,
];
const limitations = [
...structureLimitations,
"Raw property previews are limited to 256 bytes; offsets and lengths identify complete values in the hashed artifact.",
"Phandle references cover only single-cell interrupt-parent, remote-endpoint and msi-parent; binding-specific arrays and overlays are not resolved.",
];
@@ -337,7 +359,7 @@ export const parseDevicetree = (
});
}
}
return {
const report: Devicetree = {
artifact,
header,
reservations,
@@ -361,4 +383,5 @@ export const parseDevicetree = (
},
limitations,
};
return { report, structureLimitations };
};
+9 -10
View File
@@ -61,17 +61,16 @@ export class DevicetreeProvider implements DevicetreePort {
undefined,
this.#resources,
);
return ok(
parseDevicetree(
snapshot.bytes,
{
path: input.path,
sha256: snapshot.sha256,
bytes: snapshot.bytes.length,
},
input,
),
const { report } = parseDevicetree(
snapshot.bytes,
{
path: input.path,
sha256: snapshot.sha256,
bytes: snapshot.bytes.length,
},
input,
);
return ok(report);
});
} catch (cause) {
return err(devicetreeFailure(cause, input, snapshot));
+105
View File
@@ -2,6 +2,7 @@ import { readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { expect } from "vitest";
import { z } from "zod";
import { fitFixture } from "../../src/artifacts/fit/FitImage.fixture.js";
import { toolContract } from "../../src/contracts/toolContracts.js";
import { createEvidence } from "../../src/domain/evidence.js";
import {
@@ -13,6 +14,110 @@ import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";
import { connectLocalToolsMcp } from "../fixtures/localToolsMcp.js";
import { cliTest } from "../support/cli/cliFixture.js";
const paddingDiagnostic = /FDT structure padding contains/iu;
cliTest(
"retains DTB facts and reports both nonzero padding placements",
async ({ cli }) => {
const root = await createTestTempDirectory("rea-dtb-padding-");
const path = join(root, "board.dtb");
const zeroPadded = devicetreeFixture({
name: "",
properties: { model: Buffer.from([0x78, 0]) },
children: [{ name: "a" }],
});
const nonzeroPadded = Buffer.from(zeroPadded);
const start = nonzeroPadded.readUInt32BE(8);
// Two-byte model value rounded up to four, then a child named "a".
const propertyPadding = start + 22;
nonzeroPadded[propertyPadding] = 1;
// libfdt's in-place rename from "abc" to "a" leaves the former 'c'.
nonzeroPadded[start + 30] = 0x63;
const inspect = async (bytes: Buffer) => {
await writeFile(path, bytes);
const result = await cli.run({
arguments: ["inspect-devicetree", path, "--json"],
});
expect(result.exitCode, result.stderr).toBe(0);
return toolContract("inspect_devicetree").outputSchema.parse(result.json);
};
const control = await inspect(zeroPadded);
expect(control.limitations).not.toEqual(
expect.arrayContaining([expect.stringMatching(paddingDiagnostic)]),
);
const observed = await inspect(nonzeroPadded);
const diagnostic = `FDT structure padding contains 2 nonzero bytes. The first is at file offset ${String(propertyPadding)}.`;
expect(observed.limitations).toContain(diagnostic);
expect(observed.normalized_result).toMatchObject({
summary: { model: "x" },
nodes: expect.arrayContaining([expect.objectContaining({ path: "/a" })]),
coverage: {
status: "complete",
examined_nodes: 2,
examined_properties: 1,
},
limitations: expect.arrayContaining([diagnostic]),
});
const { call } = await connectLocalToolsMcp();
const reply = await call("inspect_devicetree", { path });
expect(reply.isError).not.toBe(true);
const mcp = toolContract("inspect_devicetree").outputSchema.parse(
reply.structuredContent,
);
expect(mcp.limitations).toContain(diagnostic);
expect(mcp.normalized_result).toEqual(observed.normalized_result);
expect((await readFile(path)).equals(nonzeroPadded)).toBe(true);
},
);
cliTest(
"reports FIT structure padding without losing image inventory",
async ({ cli }) => {
const root = await createTestTempDirectory("rea-fit-padding-");
const path = join(root, "boot.itb");
const bytes = fitFixture({
images: [{ name: "kernel", data: Buffer.from([1, 2, 3, 4]) }],
});
const inspect = () =>
cli.run({ arguments: ["inspect-artifact", path, "--json"] });
await writeFile(path, bytes);
const control = await inspect();
expect(control.exitCode, control.stderr).toBe(0);
expect(control.json).not.toMatchObject({
limitations: expect.arrayContaining([
expect.stringMatching(paddingDiagnostic),
]),
});
const rootNamePadding = bytes.readUInt32BE(8) + 5;
bytes[rootNamePadding] = 1;
await writeFile(path, bytes);
const observed = await inspect();
expect(observed.exitCode, observed.stderr).toBe(0);
expect(observed.json).toMatchObject({
limitations: expect.arrayContaining([
`FDT structure padding contains 1 nonzero byte. The first is at file offset ${String(rootNamePadding)}.`,
]),
normalized_result: {
coverage: { status: "complete-within-substeps" },
observations: expect.arrayContaining([
expect.objectContaining({
kind: "root-manifest",
value: expect.objectContaining({
root_format: "fit",
occurrence_count: 2,
}),
}),
]),
},
});
expect((await readFile(path)).equals(bytes)).toBe(true);
},
);
cliTest(
"rejects ambiguous Devicetree node paths in correctly hashed Evidence",
async ({ cli }) => {