Re: [RFC PATCH 29/77] Add support for FDT_EXPORT_SYM_REF dtb tag

David Gibson <[email protected]> Thu, 15 Jan 2026 17:25:58 +1100
Newsgroups	org.kernel.vger.devicetree-spec,org.kernel.vger.devicetree-compiler,org.kernel.vger.linux-devicetree,org.kernel.vger.linux-kernel
Message-ID	<aWiIdpH0oG7H4fMZ@zatzit>
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 <[email protected]>
> ---
>  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
signature.asc (application/pgp-signature, 833 B)