Re: [PATCH v3 3/4] doc: dts-format: Describe later definitions and deletes

[David Gibson <david@gibson.dropbear.id.au>]

[-- Attachment #1: Type: text/plain, Size: 4100 bytes --]

On Thu, Oct 29, 2026 at 03:30:56AM -0600, Simon Glass wrote:
> dts-format.txt does not say that a node can be defined more than once,
> nor describe /delete-property/ and /delete-node/, so anyone wanting to
> use them has to learn from examples or the parser.
> 
> Add a section on how later definitions are merged, how to delete a
> property or node, and that an overlay cannot delete anything from the
> tree it is applied to.

This is good information to add, but I think it can be expressed
better than this draft.

> 
> Assisted-by: Claude:claude-opus-5-5
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
> 
> Changes in v3:
> - Describe only the general rules, leaving out the edge cases
> 
> Changes in v2:
> - Add new patch to document deletes
> 
>  Documentation/dts-format.txt | 35 +++++++++++++++++++++++++++++++++++
>  1 file changed, 35 insertions(+)
> 
> diff --git a/Documentation/dts-format.txt b/Documentation/dts-format.txt
> index 41741df..da0783b 100644
> --- a/Documentation/dts-format.txt
> +++ b/Documentation/dts-format.txt
> @@ -87,6 +87,41 @@ elements, as NUL-terminated strings, as bytestrings or a combination of these.
>  	e.g. prop = [ab cd ef byte4: 00 ff fe];
>  	e.g. str = start: "string value" end: ;
>  
> +Later definitions and deletes
> +-----------------------------
> +
> +A node may be defined more than once, for example in an included file
> +and again in the file which includes it.

This is true, but kind of misleading.  Being able to "double define"
isn't really inherent to include files.  The problem here is that this
document never describes source-level overlays / fragments.  The "File
layout" section should be updated to cover that, rather than amending
the description there in a later section.

I think we want to be explicit about how those fragments overlay /
overwrite each other as a way to describing why and when a second node
definition makes sense.  As noted in my comments on the semantic
changes for merges, I think it would be preferable to _only_ allow
those overwrites on fragment merges, not allow them within a single
fragment (though of course either would be better than doing it
inconsistently as we do now).

Describing that source level fragment syntax would also then lead
naturally into extending this document to cover the /plugin/
directive and source for dtbo files.

It might be safer to leave updating this file until we've finalised
the cleanup of the actual semantics of merge, to make sure it remains
accurate.  This document has been wrong (or at least, incomplete) for
a decade, it can wait a little longer.

(Also, btw, converting the doc to Markdown might be a nice idea).


> +A later definition refers to
> +the node by '&' followed by its label or full path in braces, or
> +repeats the path from the root. The definitions are merged in source
> +order: a property which is defined again takes the new value, and new
> +properties and child nodes are added.
> +
> +	e.g. / {
> +		serial: serial@1000 {
> +			status = "disabled";
> +			clock-frequency = <100000000>;
> +		};
> +	     };
> +
> +	     &serial {
> +		status = "okay";
> +		/delete-property/ clock-frequency;
> +	     };
> +
> +Within a node definition, a property or child node can be removed with:
> +	/delete-property/ property-name;
> +	/delete-node/ node-name;
> +and outside any node, a node can be removed with:
> +	/delete-node/ &label;
> +
> +A delete in a later definition removes the property or node from the
> +earlier ones. Like child nodes, /delete-node/ must come after any
> +properties in a node definition.
> +
> +An overlay (a file with /plugin/) cannot delete anything from the tree
> +it is applied to, since the overlay format has no way to express this.
> +
>  
>  File layout
>  -----------
> -- 
> 2.43.0
> 
> 

-- 
David Gibson (he or they)	| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you, not the other way
				| around.
http://www.ozlabs.org/~dgibson

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]