Re: [RFC PATCH 05/15] libfdt: Introduce fdt_first_node()

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

Hi Luca, David,

On Wed, 01 Apr 2026 17:11:15 +0200
"Luca Ceresoli" <luca.ceresoli@bootlin.com> wrote:

> Hi Hervé, David,
> 
> I'm trying to review the patches that have no feedback so far.
> 
> Being new to the dtc codebase I'm mostly pointing out things that are not
> clear from a newcomer point of view. I hope this helps anyway.
> 
> On Tue Feb 10, 2026 at 6:33 PM CET, Herve Codina wrote:
> > In several places, libfdt assumes that a FDT_BEGIN_NODE tag is present
> > at the offset 0 of the structure block.
> >
> > This assumption is not correct. Indeed, a FDT_NOP can be present at the
> > offset 0 and this is a legit case.  
> 
> I wonder whether this can be proven by showing an example, or the specs, or
> whatever use case that makes sense.

I can point the device-tree specification and add the following:
--- 8< ---
Indeed, the FDT_NOP definition according to the device-tree specification [0]
is the following:
   The FDT_NOP token will be ignored by any program parsing the device
   tree. This token has no extra data; so it is followed immediately by
   the next token, which can be any valid token. A property or node
   definition in the tree can be overwritten with FDT_NOP tokens to
   remove it from the tree without needing to move other sections of
   the tree’s representation in the devicetree blob.

Nothing refers to any location for this tag and it has to be simply ignored.
Having this tag at offset 0 doesn't make an exception, the tag has to be
ignored.

[0] https://github.com/devicetree-org/devicetree-specification/blob/main/source/chapter5-flattened-format.rst?plain=1#L317
--- 8< ---

> 
> > Introduce fdt_first_node() in order to get the offset of the first node
> > (first FDT_BEGIN_NODE tag) available in a fdt blob.
> >
> > Signed-off-by: Herve Codina <herve.codina@bootlin.com>
> > ---
> >  libfdt/fdt.c             | 25 +++++++++++++++++++++++++
> >  libfdt/libfdt_internal.h |  1 +
> >  2 files changed, 26 insertions(+)
> >
> > diff --git a/libfdt/fdt.c b/libfdt/fdt.c
> > index 56d4dcb..676c7d7 100644
> > --- a/libfdt/fdt.c
> > +++ b/libfdt/fdt.c
> > @@ -252,6 +252,31 @@ int fdt_check_prop_offset_(const void *fdt, int offset)
> >  	return offset;
> >  }
> >  
> 
> Even though this seems to be quite uncommon in this repository, I think
> documenting new functions would be helpful, especially preconditions,
> postconditions and parameter values when not obvious.
> 
> What about:
> 
>   Find the initial node with content (FDT_BEGIN_NODE) in a fdt, skipping
>   FDT_NOP [and <other tags> is applicable].
> 
>   *return: pointer to the first node into the fdt or e negative error value

As you already said, documentation is quite uncommon here.

I would prefer to keep the code consistent and avoid adding documentation for
some functions and not others.

On the other side, adding some documentation could be beneficial.

David, what do you prefer?

Should I document new functions I introduce?

Best regards,
Hervé