Re: [PATCH v2 6/6] doc: dts-format: Describe later definitions and deletes

[Herve Codina <herve.codina@bootlin.com>]

On Wed, 28 Oct 2026 03:36:13 -0600
Simon Glass <sjg@chromium.org> wrote:

> dts-format.txt does not say that a node can be defined more than once,
> nor describe /delete-property/ and /delete-node/, so the rules for
> deletes in the earlier patches are not written down anywhere.
> 
> Add a section on how later definitions are merged and how deletes
> behave: within a definition, before a node or property is defined
> again, and in an overlay.
> 
> Assisted-by: Claude:claude-opus-5-5
> Signed-off-by: Simon Glass <sjg@chromium.org>
> ---
> 
> Changes in v2:
> - Add new patch to document deletes
> 
>  Documentation/dts-format.txt | 44 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 44 insertions(+)
> 
> diff --git a/Documentation/dts-format.txt b/Documentation/dts-format.txt
> index 41741df..d594822 100644
> --- a/Documentation/dts-format.txt
> +++ b/Documentation/dts-format.txt
> @@ -116,6 +116,50 @@ Version 1 DTS files have the overall layout:
>  * C style (/* ... */) and C++ style (// ...) comments are supported.
>  
>  
> +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.
> +
> +	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 removes the property or node as defined so far, including
> +  earlier in the same node definition, but not one defined after it.
> +  Outside an overlay, a delete within a node definition with nothing to
> +  remove is ignored.
> +
> +* A property or node which is deleted and then defined again comes
> +  after the existing ones, like any new property or node. A node defined
> +  again has only the properties and child nodes of its new definition.
> +
> +* In an overlay (a file with /plugin/), a delete can only remove
> +  something defined earlier in the same fragment, i.e. the same
> +  &label { ... } or &{/path} { ... }. An overlay cannot delete anything
> +  from the tree it is applied to, so dtc reports an error for a delete
> +  with nothing to remove in its fragment.
> +
> +

Not so sure:
--- 8< ---
/plugin/

&target1 {
	node: node1 {
		...
	};
};

/delete-node/ &node;  <--- It is not defined in the *same* fragment
--- 8< ---

Agree that an overlay cannot delete something in the tree it is applied to.
But /delete-node/ can be outside any fragments and delete something in a
fragment.

Best regards,
Hervé