Zephyr OS Devicetree Bindings: Diagnose a Property That Exists but Has No Generated API

A property can be visible in a devicetree source file while application code still cannot obtain the generated information it expects. Diagnose the binding and generation path before inventing a replacement macro. The source text, its interpreted schema and the generated C interface are related artifacts with different jobs.

This guide uses Zephyr 4.4.0 tagged source. It focuses on custom or modified hardware descriptions whose properties are not reaching application or driver code as expected. The workflow is proposed engineering guidance, with no claim that a particular custom binding has been compiled or validated here.

Confirm that the property survives preprocessing

Start from the generated devicetree for the failing build. Verify the node path, property name and value. If the property is absent there, investigate source inclusion or overlay selection first; a binding change cannot recover an input that never reached this stage.

Keep the original diagnostic and generated files from the same revision. A later successful configuration can regenerate the header and erase the evidence needed to understand the earlier failure. Save a bounded diagnostic set before making speculative changes.

Also check whether the application references the intended node. A correct property on a neighboring peripheral does not satisfy a macro that selects another instance. Resolve aliases, labels or chosen entries to their actual node paths before comparing values.

Find the binding actually associated with the node

The version-pinned Zephyr EDT library interprets devicetree nodes using binding information. Its documented model includes compatible-based matching and child bindings inherited through a parent description.

Inspect the selected binding path rather than assuming that a similarly named YAML file was used. For a custom binding, confirm that its directory is available to the build and that its matching information describes the intended device and bus context.

A hypothetical custom sensor can have a valid-looking compatible string in DTS while the project has not made the corresponding binding available. Another node may acquire its property schema through a parent child-binding instead. Those situations need different corrections, even if both first appear as missing generated information.

Review the property's schema, not only its spelling

Check the property declaration in the applicable binding, including inherited definitions. Determine the expected type and whether the value belongs to a scalar, array or reference structure. The application's intended interpretation must agree with that schema.

For a reference with cells, examine how the provider's cell names define the meaning of the accompanying values. Treating all cells as interchangeable integers can hide a wrong index or wrong provider even when the DTS syntax is accepted.

Do not change a property's type merely to make one macro compile. A schema is an interface between the hardware description and its consumers. If the intended data model changes, review the driver and all relevant instances together, and document the compatibility impact.

Inspect generation at the right level

The Zephyr 4.4.0 header generator turns interpreted devicetree information into generated definitions. Use its release-matched behavior to investigate a genuine generation question rather than relying on a header copied from another project.

Prefer the supported devicetree access macros in application code. Inspecting generated definitions is useful for diagnosis, but hard-coding their internal spelling creates a dependency on implementation details that can change as the project evolves.

Ask whether the chosen access operation matches the property kind and cardinality. An application that expects one value may require a different access pattern when the binding defines multiple entries. A missing index or a mistaken property token can resemble a missing binding, so keep the exact compiler expansion in the evidence.

Avoid manufacturing default values too early

A fallback value can be appropriate when absence is part of the documented interface. It is dangerous when it merely hides an integration failure. Before adding a default, decide whether the property is genuinely optional and whether the device can operate safely without an explicit value.

For a hypothetical timing parameter, a convenient zero may mean something very different from an unspecified value. If the project requires a board-specific setting, an early build error can be more useful than a firmware image that silently uses an inappropriate assumption.

Document the intended absence behavior in the binding and consumer together. Test both a valid explicit value and the allowed missing-value case. Where the property is required, include a negative configuration test that demonstrates the expected rejection rather than claiming the schema is protective without checking it.

Validate one small instance before broad reuse

Reduce the custom binding to a representative node with the minimum relevant properties. Verify that the build recognizes the binding, interprets the value and supplies the information the consumer expects. Then add the remaining instances and inherited complexity deliberately.

This reduction is particularly useful when a common include file changes many boards at once. A small test can isolate schema interpretation, while the wider build matrix checks whether existing consumers still agree. The two activities answer different questions and should have separate results.

A passing build does not establish that the configured hardware value is electrically correct. After the description-to-code path is verified, perform the board-specific functional validation required by the product. Keep schema correctness and hardware correctness distinct in the acceptance record.

Preserve the interface decision

Record the node, selected binding, property type and consumer access pattern that resolved the issue. If the fix changes a shared binding, identify the affected instances and the checks performed for them. Avoid a maintenance note that says only that a macro name was changed.

The useful diagnostic chain is source property, selected schema, interpreted value, generated information and consumer use. Following that chain turns a confusing compiler symptom into a specific interface problem. It also makes future binding changes reviewable without depending on private knowledge of one generated header.