From 60bcf1cde1a806fb17dd4c892aff9089f12a8165 Mon Sep 17 00:00:00 2001 From: Rasmus Villemoes Date: Wed, 12 Apr 2023 17:31:53 +0200 Subject: improve documentation for fdt_path_offset() The current documentation doesn't mention the possibility of passing a non-absolute path and having that treated as an alias. Add that information, along with an example (which will further be expanded in a subsequent patch), and clarify when -FDT_ERR_BADPATH can be returned. Signed-off-by: Rasmus Villemoes Signed-off-by: David Gibson --- libfdt/libfdt.h | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/libfdt/libfdt.h b/libfdt/libfdt.h index 67fcafb..34c4d55 100644 --- a/libfdt/libfdt.h +++ b/libfdt/libfdt.h @@ -524,10 +524,35 @@ int fdt_path_offset_namelen(const void *fdt, const char *path, int namelen); * level matching the given component, differentiated only by unit * address). * + * If the path is not absolute (i.e. does not begin with '/'), the + * first component is treated as an alias. That is, the property by + * that name is looked up in the /aliases node, and the value of that + * property used in place of that first component. + * + * For example, for this small fragment + * + * / { + * aliases { + * i2c2 = &foo; // RHS compiles to "/soc@0/i2c@30a40000/eeprom@52" + * }; + * soc@0 { + * foo: i2c@30a40000 { + * bar: eeprom@52 { + * }; + * }; + * }; + * }; + * + * these would be equivalent: + * + * /soc@0/i2c@30a40000/eeprom@52 + * i2c2/eeprom@52 + * * returns: * structure block offset of the node with the requested path (>=0), on * success - * -FDT_ERR_BADPATH, given path does not begin with '/' or is invalid + * -FDT_ERR_BADPATH, given path does not begin with '/' and the first + * component is not a valid alias * -FDT_ERR_NOTFOUND, if the requested node does not exist * -FDT_ERR_BADMAGIC, * -FDT_ERR_BADVERSION, -- cgit v1.2.1