Hi Andre, On Mon, 12 Oct 2020 at 10:39, Andre Przywara <andre.przywara@xxxxxxx> wrote: > > When generating a flattened devicetree on the fly, we employ some clever > techniques to avoid excessive copying and adjustments of offset values. > > To avoid people scratching their heads over all those negative string > offsets and weird magic values, let's document the nifty tricks we > pull here. Great stuff! Some suggestions below. > > Signed-off-by: Andre Przywara <andre.przywara@xxxxxxx> > --- > Hi, > > this is at least my understanding of how it works, by reading the code. > Please correct me (and the comment), should I have got something wrong. > > Cheers, > Andre > > libfdt/fdt_sw.c | 26 ++++++++++++++++++++++++++ > 1 file changed, 26 insertions(+) > > diff --git a/libfdt/fdt_sw.c b/libfdt/fdt_sw.c > index 68b543c..1f08a92 100644 > --- a/libfdt/fdt_sw.c > +++ b/libfdt/fdt_sw.c > @@ -3,6 +3,32 @@ > * libfdt - Flat Device Tree manipulation > * Copyright (C) 2006 David Gibson, IBM Corporation. > */ > +/** > + * DOC: libfdt sequential write support > + * > + * When creating a flattened device tree on the fly, the fixed structure > + * of a DTB would require constant adjustment of memory offsets, also copying > + * of whole regions like the string table. > + * To avoid this, we use an intermediate representation of a flattened tree, > + * which needs to be finalised explicitly to create a spec-conformant DTB. > + * > + * This is achieved by the following means: > + * - The magic in the header differs (FDT_SW_MAGIC), to identify such an The magic number in the header > + * unfinished tree and to avoid it to be mistaken for a proper DTB, should > + * the fdt_finish() call have been missed. > + * - The string table is located at the end of the allocated buffer, and > + * is growing *downwards*, as new strings are *prepended*. > + * - The string offsets in the dt_struct are expressed as negative offsets, > + * measured from the *end* of the string table. This allows offsets to > + * stay fixed, even when new strings are added (before the old ones). > + * - The dt_struct is located at its usual place, but leaves room behind it, s/behind/after/ > + * to grow *upwards* towards the string table. > + * - Upon finalising the DTB, all negative string offsets in dt_struct will > + * be adjusted, by adding the offset of the new end of the string table. s/will be/are/ > + * - Eventually the final offset of all structures is written into the s/Eventually/To finish the tree,/ > + * header, and the magic will be changed to be the spec defined one. s/will be/is/ > + */ > + > #include "libfdt_env.h" > > #include <fdt.h> > -- > 2.17.5 > Regards, Simon
