Contact Us

Device Not Showing Up in Linux? Decoding Device Tree and Probe Failures from Kernel Error Codes

One of the most common situations during board bring-up is "the hardware looks right, but the device does not show up in Linux." The device file for an I2C (a two-wire serial bus for controlling chips) sensor never appears, an Ethernet PHY (physical layer chip) does not get a link, or a device that worked fine disappears after a kernel update. Sometimes it works on some boots and not on others.

Embedded Linux reads the device tree (a data structure that describes the board's hardware to the kernel), registers the devices it describes, and runs the matching driver's probe (the step where a driver finds and initializes its device). This note splits the problem into three states based on where things stop, then narrows down the cause using the error codes left in the kernel log. The log formats and values in the tables are typical examples; the actual wording varies by kernel version and driver.

Device tree and driver probe failures: three states and error codes

First: which of the three states are you in?

StateHow to check (concept)Common causes
① The device is not registered at allThe device is missing from the bus device list in sysfs (the kernel's system information file system)Missing node, status property not "okay", parent bus (I2C or SPI controller) disabled, overlay not applied, booted with a different DTB (device tree blob, the compiled device tree)
② The device exists but no driver is boundThe device is listed, but no driver is attached to itcompatible (the string that identifies the device type) mismatch, driver not enabled in the kernel configuration, module not loaded
③ Probe ran but failedThe kernel log shows the driver name and a negative error code (e.g., a "probe … failed with error -110" style message). Note that -19 and -6 are not logged by default and can look like state ②See the error code table below

States ① and ② are mostly device tree and kernel configuration issues, while state ③ often requires looking at the circuit, power, and timing as well. Identifying the state first tells you whether to look at the hardware or the source.

Narrowing down the cause with error codes

Linux drivers report why they failed with negative error codes. The same code can be used in slightly different situations by different drivers, so treat the table below as a starting point for deciding where to look first.

Code in the logNameCommon meaningWhere to look first
-517EPROBE_DEFERA required resource is not ready yet, so probe will be retried laterWhether the drivers that provide clocks, regulators (power supplies), GPIOs (general-purpose I/O pins), or resets have loaded, and whether the device stays in the deferred list in debugfs (the kernel debug file system) (devices_deferred)
-19ENODEVNo device, or its identification does not matchChip ID register value, part change or revision, whether power is applied
-22EINVALInvalid settingMissing device tree properties, wrong format (cell count, units), or out-of-range values; a pin conflict can also produce this code
-110ETIMEDOUTTimed out waiting for a responseClock supply, reset release, power stabilization time
-121 / -6EREMOTEIO / ENXIOThe I2C device did not acknowledge (ACK) (the code depends on the adapter driver)Address notation (7-bit vs. 8-bit confusion, e.g., 0x36 vs. 0x6C), pull-up resistors, power
-2ENOENTFile or resource not foundFirmware file name and path, whether it is included in the root file system
-16EBUSYResource already in useWhether another node or driver has already claimed the memory region or interrupt

-517 is not an error in itself; it means "try again later." The problem is when a device is still deferred after boot has finished. Recent kernels may log a "deferred probe pending" style message for such devices, so use that message and the deferred list to see what the device is waiting for. If the device works when you load the module by hand later, the cause is most likely a dependency ordering problem. Conversely, when probe returns -19 (ENODEV) or -6 (ENXIO), the kernel treats it as "this driver does not handle this device" and does not log a failure at the default log level. Unless the driver prints its own error message, nothing appears in the log and the device looks like state ② (no driver bound). In that case, enable the driver core's debug messages (for example, with dynamic debug) or check where the driver source returns that error.

Resource connections: compare the schematic and the device tree line by line

  • Reset and power GPIO polarity: if the reset is active-low in the circuit but described the other way in the device tree, the driver asserts reset when it means to release it. Communication then fails with a timeout (-110) or no response.
  • Clocks: if the frequency of an external input clock (e.g., a 24 MHz sensor input clock) differs from the device tree value, or the clock is never enabled, the chip will not respond.
  • Regulators (power supplies): if a supply name does not match the name the driver looks for, the kernel may substitute a dummy regulator with a "using dummy regulator" style message, and the real supply may never be turned on.
  • Interrupts: if the interrupt number or trigger type (rising edge, active-low level, etc.) does not match the circuit, probe can succeed while no data ever arrives.
  • Pin function selection (pinctrl): if two nodes use the same pin, the log shows an "already requested" style conflict message.
  • Timing requirements: if the wait time the datasheet requires after power-up or reset release (often in the millisecond range) is too short, you get intermittent failures that vary from boot to boot.

A surprisingly common cause: the fixed device tree is not the one actually used

If you fixed the device tree source and nothing changed, check the tree the kernel actually received at boot. On a running system, the contents under /proc/device-tree (or /sys/firmware/devicetree/base) show the tree the kernel received. The bootloader may be loading a DTB with a different name, an overlay may have failed to apply, or the bootloader may be modifying some nodes. With Yocto or PetaLinux builds, also confirm that your modified file made it into the DTB in the final image.

What to record when asking for help or handing over the issue

  • Kernel version, board revision, and bootloader version
  • The full kernel boot log (around the driver name in question)
  • The actual contents of the relevant node in the running device tree
  • Whether the bus (I2C, SPI, etc.) signals were measured, and the results
  • How often it reproduces (e.g., 3 failures in 20 boots)

Summary: start with "where did it stop?"

Separate the three stages first (not registered, no driver bound, probe failed), and if probe failed, use the error code to pick the suspect area. That quickly tells you whether to fix the circuit, the device tree, or the build.

THEFINE provides embedded Linux contract development, including Linux bring-up on new boards and device tree and driver development.

If your device will not come up, send us the SoC (system on chip) and component part numbers, kernel version, kernel log, and the contents of the relevant node. We will review them and get back to you.

Related notes

Related services: Embedded Linux Development · SoC / FPGA Development

Contact us / Request a quote | ☎ +82-31-498-3130

Contact