mirror of
https://github.com/morluto/rea.git
synced 2026-11-20 05:32:44 +00:00
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:
1 parent
a44ff73676
commit
370602cfbb
7 files changed
+156
-20
No files matched your search
@@ -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
@@ -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
|
||||
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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 };
|
||||
};
|
||||
@@ -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));
|
||||
|
||||
@@ -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 }) => {
|
||||
|
||||
Reference in new issue
Block a user