On Mon, Jan 12, 2026 at 03:19:19PM +0100, Herve Codina wrote:
> The FDT_EXPORT_SYM_REF dtb tag is similar to the FDT_EXPORT_SYM tag
> except that it identifies a reference to an external phandle. The node
> referenced by the phandle is not present in the device-tree blob.
>
> The FDT_EXPORT_SYM_REF dtb tag is a meta-data tag defining an exported
> symbol. It can be present in a node bloc meaning that a symbol is
> exported at this node level. The node pointed to by this symbol is not a
> local node (i.e. the node is not present in the device-tree blob.). This
> tag can be available only in overlay or addon device-tree blobs. The
> symbol has to be resolved when the device-tree blob is applied on top of
> a base device-tree.
>
> It is followed by three values and a possible alignment padding:
> - name (string including \0)
> The export symbol name. I.e. the name used to reference this
> exported symbol.
> - padding:
> Padding (0x00) added to have the next value aligned on 32bit.
> - phandle (32bit)
> A placeholder for a phandle value.
> This placeholder can be used during some dtb manipulation to store
> a temporary phandle value.
Yuck.
> In terms of FDT_EXPORT_SYM_REF definition, it has no meaningful
> signification and will be probably set to 0xffffffff, the
> unresolved phandle value.
> - label (string including \0):
> The label to use to resolve this symbol. This label is the
> reference to the external phandle.
> - padding:
> Padding (0x00) added to have the next value aligned on 32bit.
>
> Example:
> FDT_EXPORT_SYM_REF 'foo1' 0x00 0x00 0x00 0xffffffff 'foo_a' 0x00 0x00
>
> This means that 'foo1' is an exported symbol and the node referenced
> by this symbol is external to the dtb (unresolved symbol). This
> external node is referenced by the "foo_a" label.
>
> This is what is encoded in the dtb when the related dts has the
> following exported symbol defined:
> /export/ foo1: &foo_a;
> with 'foo_a' a reference to a non local node.
>
> If several non local symbols are exported at a given node level, several
> FDT_EXPORT_SYM_REF are present. Each of them defining one symbol.
>
> For instance, exporting 'foo1' pointing the node referenced by 'foo_a'
> and exporting 'bar1' pointing to the node referenced by 'bar_b' leads to
> the following sequence:
> FDT_EXPORT_SYM_REF 'foo1' 0x00 0x00 0x00 'foo_a' 0x00 0x00
> FDT_EXPORT_SYM_REF 'bar1' 0x00 0x00 0x00 'bar_b' 0x00 0x00
>
> Add support for this new dtb tag.
>
> Signed-off-by: Herve Codina <herve.codina@bootlin.com>
> ---
> fdtdump.c | 12 ++++++++++++
> flattree.c | 40 ++++++++++++++++++++++++++++++++++++++++
> libfdt/fdt.c | 24 ++++++++++++++++++++++++
> libfdt/fdt.h | 2 ++
> 4 files changed, 78 insertions(+)
>
> diff --git a/fdtdump.c b/fdtdump.c
> index d1af5b6..8baadc4 100644
> --- a/fdtdump.c
> +++ b/fdtdump.c
> @@ -186,6 +186,18 @@ static void dump_blob(void *blob, bool debug)
> continue;
> }
>
> + if (tag == FDT_EXPORT_SYM_REF) {
> + s = p;
> + p = PALIGN(p + strlen(s) + 1, 4);
> + val32 = fdt32_to_cpu(GET_CELL(p));
> + t = p;
> + p = PALIGN(p + strlen(t) + 1, 4);
> +
> + printf("%*s// [FDT_EXPORT_SYM_REF] '%s' -> '%s'\n", depth * shift, "",
> + s, t);
> + continue;
> + }
> +
> fprintf(stderr, "%*s ** Unknown tag 0x%08"PRIx32"\n", depth * shift, "", tag);
> break;
> }
> diff --git a/flattree.c b/flattree.c
> index bd52e81..d970259 100644
> --- a/flattree.c
> +++ b/flattree.c
> @@ -49,6 +49,7 @@ struct emitter {
> void (*ref_local)(void *);
> void (*ref_phandle)(void *);
> void (*export_sym)(void *);
> + void (*export_sym_ref)(void *);
> };
>
> static void bin_emit_cell(void *e, cell_t val)
> @@ -113,6 +114,11 @@ static void bin_emit_export_sym(void *e)
> bin_emit_cell(e, FDT_EXPORT_SYM);
> }
>
> +static void bin_emit_export_sym_ref(void *e)
> +{
> + bin_emit_cell(e, FDT_EXPORT_SYM_REF);
> +}
> +
> static struct emitter bin_emitter = {
> .cell = bin_emit_cell,
> .string = bin_emit_string,
> @@ -124,6 +130,7 @@ static struct emitter bin_emitter = {
> .ref_local = bin_emit_ref_local,
> .ref_phandle = bin_emit_ref_phandle,
> .export_sym = bin_emit_export_sym,
> + .export_sym_ref = bin_emit_export_sym_ref,
> };
>
> static void emit_label(FILE *f, const char *prefix, const char *label)
> @@ -259,6 +266,14 @@ static void asm_emit_export_sym(void *e)
> asm_emit_cell(e, FDT_EXPORT_SYM);
> }
>
> +static void asm_emit_export_sym_ref(void *e)
> +{
> + FILE *f = e;
> +
> + fprintf(f, "\t/* FDT_EXPORT_SYM_REF */\n");
> + asm_emit_cell(e, FDT_EXPORT_SYM_REF);
> +}
> +
> static struct emitter asm_emitter = {
> .cell = asm_emit_cell,
> .string = asm_emit_string,
> @@ -270,6 +285,7 @@ static struct emitter asm_emitter = {
> .ref_local = asm_emit_ref_local,
> .ref_phandle = asm_emit_ref_phandle,
> .export_sym = asm_emit_export_sym,
> + .export_sym = asm_emit_export_sym_ref,
> };
>
> static int stringtable_insert(struct data *d, const char *str)
> @@ -369,6 +385,18 @@ static void flatten_tree(struct node *tree, struct emitter *emit,
> emit->cell(etarget, exportsym->phandle);
> continue;
> }
> +
> + if (exportsym->ref[0] == '/')
> + die("Export symbol uses a non local reference by path (%s)\n",
> + m->ref);
> +
> + emit->export_sym_ref(etarget);
> + emit->string(etarget, exportsym->name, 0);
> + emit->align(etarget, sizeof(cell_t));
> + /* Placeholder for the phandle */
> + emit->cell(etarget, exportsym->phandle);
> + emit->string(etarget, exportsym->ref, 0);
> + emit->align(etarget, sizeof(cell_t));
> }
> }
>
> @@ -838,6 +866,7 @@ static struct node *unflatten_tree(struct inbuf *dtbuf,
> uint32_t val;
> uint32_t offset;
> const char *str;
> + const char *str2;
>
> node = build_node(NULL, NULL, NULL, NULL);
>
> @@ -919,6 +948,17 @@ static struct node *unflatten_tree(struct inbuf *dtbuf,
> add_symbol(&node->exportsymlist, exportsym);
> break;
>
> + case FDT_EXPORT_SYM_REF:
> + if (!(flags & FTF_EXPORT_IMPORT_SYM))
> + die("FDT_EXPORT_SYM_REF tag found in flat tree"
> + " version <18\n");
> + str = flat_read_string(dtbuf); /* Name */
> + phandle = flat_read_word(dtbuf); /* Phandle */
> + str2 = flat_read_string(dtbuf); /* Ref */
> + exportsym = build_exportsym(str, str2, phandle, NULL);
> + add_symbol(&node->exportsymlist, exportsym);
> + break;
> +
> default:
> die("Invalid opcode word %08x in device tree blob\n",
> val);
> diff --git a/libfdt/fdt.c b/libfdt/fdt.c
> index 44d7399..febfa71 100644
> --- a/libfdt/fdt.c
> +++ b/libfdt/fdt.c
> @@ -248,6 +248,29 @@ uint32_t fdt_next_tag_full(const void *fdt, int startoffset, int *nextoffset)
> offset += sizeof(fdt32_t);
> break;
>
> + case FDT_EXPORT_SYM_REF:
> + /* Skip name */
> + do {
> + p = fdt_offset_ptr(fdt, offset++, 1);
> + } while (p && (*p != '\0'));
> + if (!can_assume(VALID_DTB) && !p)
> + return FDT_END; /* premature end */
> + offset = FDT_CELLALIGN(offset);
> +
> + /* Skip phandle */
> + tmp32p = fdt_offset_ptr(fdt, offset, sizeof(*tmp32p));
> + if (!can_assume(VALID_DTB) && !tmp32p)
> + return FDT_END; /* premature end */
> + offset += sizeof(fdt32_t);
> +
> + /* Skip external name */
> + do {
> + p = fdt_offset_ptr(fdt, offset++, 1);
> + } while (p && (*p != '\0'));
> + if (!can_assume(VALID_DTB) && !p)
> + return FDT_END; /* premature end */
> + break;
> +
> default:
> return FDT_END;
> }
> @@ -290,6 +313,7 @@ uint32_t fdt_next_tag(const void *fdt, int startoffset, int *nextoffset)
> case FDT_REF_LOCAL:
> case FDT_REF_PHANDLE:
> case FDT_EXPORT_SYM:
> + case FDT_EXPORT_SYM_REF:
> /*
> * Next tag is a meta-data tag present in the middle
> * of the structure -> Skip it and look at next one
> diff --git a/libfdt/fdt.h b/libfdt/fdt.h
> index e85bc07..c23723b 100644
> --- a/libfdt/fdt.h
> +++ b/libfdt/fdt.h
> @@ -65,6 +65,8 @@ struct fdt_property {
> external label */
> #define FDT_END 0x9
> #define FDT_EXPORT_SYM 0xa /* export symbol: name, phandle value */
> +#define FDT_EXPORT_SYM_REF 0xb /* export symbol: name, phandle value (maybe
> + unresolved), external label */
>
> #define FDT_V1_SIZE (7*sizeof(fdt32_t))
> #define FDT_V2_SIZE (FDT_V1_SIZE + sizeof(fdt32_t))
> --
> 2.52.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