Known faults

A boot log says what failed — Unable to connect to phy, error -110. Someone who has repaired a few hundred boards also knows why it usually fails and what to measure first. Known faults put that knowledge next to the message.

How matching works

• Only new lines are checked: lines of the board under test that are not in the golden log. A message your healthy boards print as well is not a fault of this board.
• Patterns are Python regular expressions, matched case-insensitively anywhere in the line.
• A line counts for the first rule that matches. Your own rules are checked before the built-in ones.
• Each fault is listed once, with all its lines, in the order the faults first show up in the log.

Built-in faults

id	title	severity
ddr-training	DDR training or calibration failed	error
mmc-timeout	eMMC/SD card does not respond (timeout)	error
mmc-crc	eMMC/SD signal errors (CRC)	error
mmc-io-error	Block device I/O errors	error
eth-phy	Ethernet PHY not found	error
eth-no-link	Ethernet link does not come up	warning
usb-enumeration	USB device does not enumerate	error
usb-overcurrent	USB over-current	error
i2c-nack	I2C device does not answer	error
spi-flash	SPI/NOR flash not detected	error
nand	NAND/UBI error	error
pcie-link	PCIe link does not come up	error
rootfs-mount	Root file system cannot be mounted	error
fs-corruption	File system errors	error
env-default	Bootloader environment is invalid	warning
bad-image	Bootloader rejects the kernel or device tree image	error
kernel-panic	Kernel panic or oops	error
watchdog-reset	Reset by watchdog	error
power	Supply or regulator problem	error
thermal	Over-temperature	error
memory-ecc	Memory ECC errors	error
firmware-missing	Firmware file not found	warning
rcu-stall	CPU stall	error

The patterns and full diagnosis texts are in faults.toml; boot-log-diff --help lists the ids. Built-in diagnoses are general: they name the usual causes for any board. For your own boards you can do better.

Your own faults

Write them in a TOML file, one [[fault]] table each:

# our-boards.toml
[[fault]]
id = "eth-phy"                  # same id as a built-in fault: replaces it
title = "Ethernet PHY not found"
pattern = 'unable to connect to phy'
diagnosis = "EPC-8M rev C: check R212 (PHY reset pull-up, 0402) for cracks first; then the 25 MHz crystal Y3."

[[fault]]
id = "sd-slot"
title = "SD card slot dead"
pattern = 'mmc1: error -110'
diagnosis = "No card inserted is the usual cause at the test station. Otherwise replace the SD connector J12."

$ boot-log-diff golden.log faulty.log --rules our-boards.toml

What happened here:

• The own eth-phy rule replaced the built-in one: same id, own diagnosis.
• The own sd-slot rule took line 63 (error -110), because own rules are checked first. Line 62 (Timeout waiting for hardware interrupt) did not match it and went to the built-in mmc-timeout.

Fields

Field	Required	Meaning
id	yes	short name; the same id as a built-in fault replaces it
title	yes	one line, shown first
pattern	yes	regular expression, case-insensitive; use TOML single quotes so backslashes stay as they are
diagnosis	yes	what causes it and what to check; may span lines ("""), line breaks are joined
severity	no	error (default) or warning

Unknown fields, a missing field or a bad regex stop with exit status 2 and the name of the file and the rule.

Good diagnoses

From repair practice, the ones that save the most time:

• name the part — reference designator, package, where it sits;
• give the order — the most likely cause first, the expensive one last;
• say what is normal at the station — "no card inserted" is not a board fault;
• give the measurement — "VCCQ at C118 must be 1.8 V".

Switching faults off

• --no-builtin-rules uses only your own files.
• To silence one built-in fault, override its id with a pattern for the messages you do care about, or add the harmless line to the golden log.

In Python

from boot_log_diff import BUILTIN_RULES, compare, load_rules

rules = load_rules("our-boards.toml") + list(BUILTIN_RULES)
result = compare(golden_text, dut_text, rules=rules)
for fault in result.faults:
    print(fault.rule.id, [line.number for line in fault.lines])