Re: [PATCH v4] doc: dts-format: Describe later definitions and deletes

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

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

On Sun, Nov 01, 2026 at 09:46:11AM -0700, 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.
> 
> Assisted-by: Claude:claude-opus-5-5
> Signed-off-by: Simon Glass <sjg@chromium.org>
> Reviewed-by: Herve Codina <herve.codina@bootlin.com>
> ---
> The other patches from v3 are dropped: David is applying the /dts-v1/
> fix himself, and he would rather extend dtc-fatal.sh than remove it, so
> the test changes need a different approach.
> 
> Changes in v4:
> - Send this patch on its own
> 
> 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. 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.

Sorry, I meant to say this earlier, but I think it got lost with the
other shuffles.

I don't think this wording is very clear - I think we want to
explicitly describe the "fragment" structure of the dts, and how those
are combined together.  The specifics of the /delete/ logic will make
more sense given that context.


> +	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
>  -----------
> ---
> base-commit: c22868416b8db8354ce5db29d3494dda688a2ae3
> branch: delete-markers4
> 
> -- 
> 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 --]