MIPI camera device tree overlay not applied: verify what UEFI loaded

You added the FDT and OVERLAYS lines for your MIPI camera to the boot configuration, the board boots cleanly, and the sensor still never probes. Nothing in dmesg blames the overlay, because the decision happened one stage earlier: whether the bootloader loaded and merged your files at all. This page gives the check order for the bench: confirm which boot entry ran, prove the named files exist and match that base DTB, re-run the merge on the build host, then read the merged tree under /sys/firmware/devicetree/base. When you finish, you will know whether the overlay stage is fixed or cleared, and whether the search belongs to the camera or driver side.

Why is my MIPI camera overlay not taking effect?

Four causes explain nearly every case: the boot entry with your FDT and OVERLAYS lines never ran, a named path is missing, the overlay's targets do not resolve against the base DTB, or it applied and the fault sits downstream of the device tree.

The symptom is always the same shape. Boot completes, the I2C bus is up, but the sensor node you expect never appears and the camera driver has nothing to bind to. dmesg shows no overlay error, because a loader that never merged your files has nothing to report.

Rank the causes and test them in this order:

1. Wrong entry ran. Your label exists in the boot config, but the DEFAULT field points elsewhere. This is the most common failure by a wide margin; the next section is the two-minute test.
2. Path or file missing. An update renamed the base DTB, or the .dtbo sits where the loader does not look. Some loaders skip a missing overlay silently.
3. Targets do not resolve. The fragments point at labels or paths the base DTB does not carry, so nodes drop out without an error you will ever see.
4. It applied; you searched the wrong place. Behind an I2C multiplexer the node lives deeper than the path you checked.

A loud probe failure with an error message is a different situation: start from the guide on two camera overlays fighting over one CSI port when configs conflict. For a sensor that never even registers on the bus, the companion page is MIPI camera not detected: I2C bus and device tree checks.

Which boot entry did the bootloader actually select?

The entry that runs is the one named by the DEFAULT field, not the one you edited, so read that field first; a TIMEOUT of 30 waits in units of 0.1 s, just 3 s, and then boots the default entry.

Show the config on the target and read its top:

TIMEOUT 30
DEFAULT camera-test

LABEL primary
    LINUX /boot/Image
    INITRD /boot/initrd
    APPEND root=/dev/mmcblk0p1 rw rootwait

LABEL camera-test
    LINUX /boot/Image
    FDT /boot/dtb/base-carrier.dtb
    OVERLAYS /boot/dtbo/camera-sensor.dtbo

The file names are examples; the fields are the generic extlinux ones. The loader waits TIMEOUT × 0.1 s — here 30 × 0.1 s = 3 s — and then boots DEFAULT unattended, which is why a bench board keeps booting the wrong label when you only added a new one.

Two checks settle it in minutes. Attach the debug serial console at 115200 baud, the usual rate, and read the label it reports at reset. Then confirm DEFAULT names the label that carries your FDT and OVERLAYS lines; if it does not, edit DEFAULT or select the entry by hand inside the timeout window. After every BSP update, diff this file against the copy in your repo, because update flows can rewrite it.

Do the FDT and OVERLAYS files exist and match this base DTB?

Every path in FDT and OVERLAYS is read from storage exactly as written, so run ls against each one on the target; the FDT must be the DTB built for your carrier and SoC package, and each .dtbo must target nodes or labels that exist in that same DTB.

Three checks, each seconds long. List and checksum what is deployed, so a week later you can still answer which DTB this board runs:

ls -l /boot/dtb/base-carrier.dtb /boot/dtbo/camera-sensor.dtbo
sha256sum /boot/dtb/base-carrier.dtb

Then check the targets. A fragment that references a label, such as target = <&cam_i2c>, resolves through the symbols block, which the device tree compiler adds only when the DTB is built with -@. A base DTB built without it leaves those fragments with nothing to attach to. Decompile and search:

dtc -I dtb -O dts /boot/dtb/base-carrier.dtb | grep -A3 cam_i2c

Pick the fix by where the fault sits: rebuild the base DTB with -@ to emit symbols, or rewrite the fragments to target-path with a literal path such as /soc/i2c@1. Prefer target-path where you can, because literal paths survive base-tree rebuilds better than labels. Where the file itself is the story — renamed, rebuilt or simply absent — continue with the guide on diagnosing a camera driver and device tree mismatch from missing DTBs. To see how far one small fragment reaches, the walkthrough on setting an SD card's maximum frequency in a device tree overlay is a compact, camera-free example of a single property change.

How do I read the merged device tree after boot?

After boot, the kernel mirrors the tree it was handed at /sys/firmware/devicetree/base, with /proc/device-tree as the usual symlink, so what you see there is exactly what the bootloader merged; your change is either in that directory or it never happened.

Search for the node name before the full path — sysfs stores one property per file, and node directories carry the unit address:

find /sys/firmware/devicetree/base -name '*camera*'
find /sys/firmware/devicetree/base -name status -exec cat {} \;

Worked example. Say the overlay renames the sensor node camera_a@36 to camera_b@36 and you search for the new name. The unit address 36 is hexadecimal: 3 × 16 + 6 = 54, so the sensor answers at address 0x36, which is 54 decimal, on its I2C bus. After a clean merge, find returns a path shaped like /sys/firmware/devicetree/base/soc/i2c@1/mux@77/i2c@0/camera_b@36, with your board's controller and multiplexer names in the middle. Then read the bus with i2cdetect -y 2 and decide from this table:

UU is i2cdetect's mark for an address a kernel driver occupies, so UU at 36 is the strongest single signal on this page: tree and driver both good. A bare 36 means the chip answers but no driver claimed it; the guide on a camera loading the wrong sensor driver takes the dmesg read from there, and the sensor ID mismatch diagnosis covers the wrong-address case.

Can I test the overlay merge before I reboot the target again?

Yes, and it is the fastest way to clear or convict the overlay: on the build host, run fdtoverlay with your base DTB and .dtbo, decompile the output and confirm your property; if the change is missing there, no boot configuration will ever apply it.

dtc -@ -I dts -O dtb -o camera-sensor.dtbo camera-sensor-overlay.dts
fdtoverlay -i base-carrier.dtb -o merged-test.dtb camera-sensor.dtbo
dtc -I dtb -O dts merged-test.dtb > merged-test.dts
grep -A5 camera_b@36 merged-test.dts

Substitute your file names; the three tools are the standard device tree utilities in every build environment. Read the result with a hard rule. Your marker node or property must appear in merged-test.dts. If it does not, the fragment targets something the base DTB lacks, and you are back to the symbols-versus-target-path decision from the previous section; no amount of boot config editing fixes that. If it does appear, the merge logic is clean and any remaining failure is delivery: the entry, the paths, or the base DTB that actually ships.

For the same loop worked end to end on real hardware, the walkthrough on enabling a board's Ethernet port through a device tree overlay follows the identical edit, compile, merge and check sequence, camera or no camera.

How do I get the bootloader to log the overlays it loaded?

Enable the bootloader's debug output and watch the serial console: many UEFI-based loaders print one line per processed overlay, naming that overlay's overlay-name property, in the final moments before the kernel banner.

If the log stays silent, work three steps:

1. Confirm you are on the loader's debug port. Some carriers route firmware messages to a dedicated debug UART rather than the console the kernel prints on.
2. Raise the firmware debug level. Open-source UEFI builds guard the overlay-processing message behind a debug flag, so the build that prints each overlay's name prints nothing while the flag is off.
3. Rebuild the firmware with debug enabled through your board vendor's documented build and flash flow, on a bench unit, with a recovery flash path you have already exercised.

When the log names your overlay, the loader merged it, and the remaining suspect is content rather than delivery: an overlay can merge cleanly and still drop nodes whose targets never resolved. That is why the sysfs read in the earlier section stays the final judge. The log tells you what was loaded; sysfs tells you what survived.

Why does the same overlay work on one board and fail on another?

Because the overlay merges into whichever base DTB the failing board boots: a different carrier or board revision ships a different DTB with different node names, and some platforms apply their own per-camera overrides when they detect a camera board at boot.

Test it directly. Decompile the DTB named in the failing board's FDT line, search for the node your fragment targets, and compare against the board where it works. The first differing node name shows where the target moved. Two durable fixes follow:

• Maintain one overlay per base DTB and name them as a pair, such as base-carrier-r2.dtb with camera-sensor-r2.dtbo, so a rebuild can never pair the wrong two.
• Write fragments against stable target-path strings rather than labels wherever the platform's node layout allows it, because paths move less between variants than symbols do.

Two platform realities sit behind many board-to-board failures. A camera behind an I2C multiplexer has a parent path that includes the mux node, so the target path is longer than it looks; the guide on wiring several MIPI cameras through an I2C multiplexer in the device tree shows that structure. And where the firmware applies its own overrides to detected camera boards before your list is merged, the base tree your fragments land on is not the file on disk. The platform's release notes state that behavior, and it changes what you should expect to find in sysfs.

How do I keep overlays applying correctly after every update?

Treat the base DTB, the .dtbo files and the boot entry as one versioned set: record the DTB name and each overlay checksum in the build output, re-run the host-side merge check on every rebuild, and make the sysfs check part of the bring-up smoke test.

Make the checks permanent rather than heroic:

• Version the boot config with the board: the DEFAULT field, the FDT name and the OVERLAYS list live in your repo and get diffed after every update.
• Add the merge to CI: compile the overlay, run fdtoverlay against the shipping base DTB, and fail the build when the marker property does not appear in the output.
• End the smoke test with the sysfs check: the node directory must exist and read back okay before the camera stage runs.

Then hold the line between stages. If the node exists, the driver bound — UU at the sensor address — and the image is still wrong, the fault is downstream: start from the guide on probing a blank image acquisition pipeline stage by stage. If the node exists but nothing binds, work through the sensor-side checks in the MIPI streaming article on power, clocks and device tree, or step back to the embedded camera bring-up sequence that isolates which stage fails first.

When the overlay is innocent and the fault turns out to be hardware — the sensor, the carrier, or the host that drives them — pick the camera from the board-level cameras category with the camera finder, and the host from the vision controllers category, or start at the camera configurator. The systems topic page collects the rest of the bring-up guides.