Skip to content
FreeBSDDeep Dive Published Updated 6 min readViews unavailable

FreeBSD ACPI Table Forensics with acpidump and iasl: A Read-Only Workflow

Capture and interpret FreeBSD ACPI tables without changing firmware, loader configuration, or boot behavior during read-only evidence collection.

When a FreeBSD host reports an ACPI problem, the first useful artifact is often a reproducible snapshot of the firmware tables (not a boot-time override). FreeBSD’s acpidump(8) can dump ACPI tables and ASL, while ACPICA’s iasl can decode or disassemble that material for inspection. This provides evidence about what the firmware exposed to the operating system. It does not prove that every table is correct, that FreeBSD consumed every table in the way you expect, or that editing a table is safe.

This workflow is deliberately read-only with respect to the installed system and firmware. It does not cover table replacement, loader settings, kernel tunables, BIOS changes, suspend/resume testing, or repair by applying a modified AML file. Keep those operational domains separate from evidence collection.

Capture a baseline before interpreting a symptom

Begin by recording the exact FreeBSD release, kernel build, architecture, hardware model, boot time, and symptom timestamp. Include whether the issue occurs on a cold boot, after a warm reboot, or only after a runtime event. Do not infer the release-specific manual behavior from a different FreeBSD branch: consult the installed man 8 acpidump and the manual for the precise release, then use the corresponding source tag if the installed manual is ambiguous.

On FreeBSD 15.1-RELEASE, the official manual describes acpidump(8) as a utility to dump ACPI tables and ASL. The upstream main manual is useful for current development, but it is not a substitute for the installed 15.1 manual when documenting a 15.1 host. This distinction matters because command-line options and tool behavior may evolve.

Create a case directory in a normal writable location, not /boot, /etc, or a firmware utility directory. Check available space and access policy. A simple inventory step is:

freebsd-version -kru
uname -a
sysctl -n hw.model
man 8 acpidump
man 8 iasl

In minimal or custom installations, iasl(8) may not be installed. If organizational policy permits installing a package on a dedicated analysis machine, record its exact version; otherwise transfer the captured text to a separate workstation with ACPICA tools. Do not install or upgrade tools on a production host just to inspect a table.

Dump, preserve, and label the evidence

The FreeBSD manual documents acpidump options for selecting table output and disassembly output. The installed manual is the authority for exact flags on the target release. A commonly documented pattern in FreeBSD manuals is to direct the dump and decoded output to files in a case directory, for example:

case_dir="$HOME/acpi-case-$(date +%Y%m%d)"
mkdir -p "$case_dir"
cd "$case_dir"
acpidump -t -d -o firmware.dsdt > firmware.asl

Before using this pattern, confirm the flags and output-file semantics in the local 15.1 manual; do not paste a command copied from a different release without checking. The > redirection captures standard output in firmware.asl; -o firmware.dsdt writes the extracted DSDT separately, and -d sends its ASL disassembly to standard output. The tool invocation reads platform-exposed ACPI information, but the output can contain machine-specific identifiers and configuration data. Treat it as sensitive diagnostic material: restrict access, avoid posting it publicly without review, and remove serial-like or organization-specific data if it is not needed for a report.

Record command lines, exit status, stderr, and hashes alongside the output. If the dump fails, preserve the failure details instead of repeatedly running increasingly privileged commands. A permissions error is not evidence that a firmware table is corrupt. Use only the privilege level explicitly required by the manual and the host’s policy; do not turn a one-time capture into a broad privilege change.

What the disassembly can and cannot tell you

ASL is a source representation of AML bytecode and ACPI objects. A successful disassembly makes a table more searchable; it does not recover the firmware author’s intent or prove runtime evaluation order. Record the table signature, OEM identifiers, revision, and checksum information available in the dump, then compare only like-for-like systems and firmware releases. A changed table can reflect a firmware update, machine model, configuration option, or a legitimate platform revision.

Use iasl in decode/disassemble mode on the captured file and save a separate output file. Do not compile a modified ASL file, produce a replacement AML image, or feed generated tables into the boot process as part of a forensic capture. Even when a disassembler emits warnings, that does not establish that FreeBSD is experiencing the symptom because of that warning. Correlate the table with kernel messages and a minimal reproduction before drawing a causal conclusion.

Avoid treating a visually suspicious method name or an unfamiliar device object as a defect. ACPI namespaces are vendor-defined in many places. A useful report identifies the object path, table and offset or source line, the observed FreeBSD diagnostic, and why the two are plausibly related. It should also state what the artifact cannot establish, for example, whether a method was evaluated on the failing path.

Build a comparison that can be repeated

For an intermittent problem, capture one baseline from a known-good state and one from the failing state, using the same release, hardware, and tool versions where possible. Compare table signatures and checksums first, then inspect the relevant ASL object rather than diffing the entire disassembly without context. If the two dumps differ, determine whether the difference comes from firmware configuration or from the capture/toolchain before calling it a regression.

Use a compact evidence table:

Evidence Record
Operating system freebsd-version, kernel build, architecture
Platform model, firmware version, relevant settings as observed (do not change them)
Capture tool acpidump and iasl versions, manual section/release
Artifact file names, timestamps, hashes, exit status
Symptom exact time, trigger, kernel message, repeatability
Comparison table signature and narrowly scoped object differences

This turns “ACPI looks wrong” into a reviewable claim. Preserve originals as immutable files and analyze copies. If a table is malformed or a decode is incomplete, report the limitation and the specific parser output; do not silently repair the source material to make a clean diff.

Keep the incident response non-invasive

Do not test a hypothesis by replacing a table, adding an ACPI override, changing loader.conf, changing a kernel tunable, altering firmware setup, or rebooting a customer machine unless a separately approved change plan calls for it. Those are state-changing experiments with distinct rollback, availability, and support risks. A data-capture article cannot establish that any such intervention is safe for a given system.

For a suspend/resume symptom, use a controlled test plan and recovery precautions from the separate suspend/resume operations guide. Do not conflate collecting DSDT evidence with exercising sleep states. If an upstream bug report is warranted, attach only sanitized and permission-approved evidence, specify exact release and firmware revisions, and explain the reproduction steps. If private identifiers remain, share through the vendor or project’s approved private channel rather than a public issue.

The stopping condition for this workflow is a reproducible, read-only evidence package: versioned manuals, tool versions, original dumps, checksums, narrowly scoped analysis, and the system logs that align with the symptom. If that package does not support a causal finding, the right result is “not established,” followed by a separately reviewed experiment (not an undocumented boot override).

Related:

Sources:

Comments