Add a basic assortment of functions to access the live device tree. These come from Linux v4.9 and are modified for U-Boot to the minimum extent possible. While these functions are now very stable in Linux, it will be possible to merge in fixes if needed.
Signed-off-by: Simon Glass sjg@chromium.org ---
Changes in v3: None Changes in v2: None
drivers/core/Makefile | 1 + drivers/core/of_access.c | 735 +++++++++++++++++++++++++++++++++++++++++++++++ include/dm/of_access.h | 347 ++++++++++++++++++++++ 3 files changed, 1083 insertions(+) create mode 100644 drivers/core/of_access.c create mode 100644 include/dm/of_access.h
diff --git a/drivers/core/Makefile b/drivers/core/Makefile index 8261f14f45..4211fd1e22 100644 --- a/drivers/core/Makefile +++ b/drivers/core/Makefile @@ -11,3 +11,4 @@ obj-$(CONFIG_$(SPL_)SIMPLE_BUS) += simple-bus.o obj-$(CONFIG_DM) += dump.o obj-$(CONFIG_$(SPL_)REGMAP) += regmap.o obj-$(CONFIG_$(SPL_)SYSCON) += syscon-uclass.o +obj-$(CONFIG_OF_LIVE) += of_access.o diff --git a/drivers/core/of_access.c b/drivers/core/of_access.c new file mode 100644 index 0000000000..94ef3cc251 --- /dev/null +++ b/drivers/core/of_access.c @@ -0,0 +1,735 @@ +/* + * Originally from Linux v4.9 + * Paul Mackerras August 1996. + * Copyright (C) 1996-2005 Paul Mackerras. + * + * Adapted for 64bit PowerPC by Dave Engebretsen and Peter Bergner. + * {engebret|bergner}@us.ibm.com + * + * Adapted for sparc and sparc64 by David S. Miller davem@davemloft.net + * + * Reconsolidated from arch/x/kernel/prom.c by Stephen Rothwell and + * Grant Likely. + * + * Modified for U-Boot + * Copyright (c) 2017 Google, Inc + * + * This file follows drivers/of/base.c with functions in the same order as the + * Linux version. + * + * SPDX-License-Identifier: GPL-2.0+ + */ + +#include <common.h> +#include <libfdt.h> +#include <dm/of_access.h> +#include <linux/ctype.h> +#include <linux/err.h> +#include <linux/ioport.h> + +DECLARE_GLOBAL_DATA_PTR; + +/* list of struct alias_prop aliases */ +LIST_HEAD(aliases_lookup); + +/* "/aliaes" node */ +static struct device_node *of_aliases; + +/* "/chosen" node */ +static struct device_node *of_chosen; + +/* node pointed to by the stdout-path alias */ +static struct device_node *of_stdout; + +/* pointer to options given after the alias (separated by :) or NULL if none */ +static const char *of_stdout_options; + +/** + * struct alias_prop - Alias property in 'aliases' node + * + * The structure represents one alias property of 'aliases' node as + * an entry in aliases_lookup list. + * + * @link: List node to link the structure in aliases_lookup list + * @alias: Alias property name + * @np: Pointer to device_node that the alias stands for + * @id: Index value from end of alias name + * @stem: Alias string without the index + */ +struct alias_prop { + struct list_head link; + const char *alias; + struct device_node *np; + int id; + char stem[0]; +}; + +int of_n_addr_cells(const struct device_node *np) +{ + const __be32 *ip; + + do { + if (np->parent) + np = np->parent; + ip = of_get_property(np, "#address-cells", NULL); + if (ip) + return be32_to_cpup(ip); + } while (np->parent); + + /* No #address-cells property for the root node */ + return OF_ROOT_NODE_ADDR_CELLS_DEFAULT; +} + +int of_n_size_cells(const struct device_node *np) +{ + const __be32 *ip; + + do { + if (np->parent) + np = np->parent; + ip = of_get_property(np, "#size-cells", NULL); + if (ip) + return be32_to_cpup(ip); + } while (np->parent); + + /* No #size-cells property for the root node */ + return OF_ROOT_NODE_SIZE_CELLS_DEFAULT; +} + +struct property *of_find_property(const struct device_node *np, + const char *name, int *lenp) +{ + struct property *pp; + + if (!np) + return NULL; + + for (pp = np->properties; pp; pp = pp->next) { + if (strcmp(pp->name, name) == 0) { + if (lenp) + *lenp = pp->length; + break; + } + } + if (!pp && lenp) + *lenp = -FDT_ERR_NOTFOUND; + + return pp; +} + +struct device_node *of_find_all_nodes(struct device_node *prev) +{ + struct device_node *np; + + if (!prev) { + np = gd->of_root; + } else if (prev->child) { + np = prev->child; + } else { + /* + * Walk back up looking for a sibling, or the end of the + * structure + */ + np = prev; + while (np->parent && !np->sibling) + np = np->parent; + np = np->sibling; /* Might be null at the end of the tree */ + } + + return np; +} + +const void *of_get_property(const struct device_node *np, const char *name, + int *lenp) +{ + struct property *pp = of_find_property(np, name, lenp); + + return pp ? pp->value : NULL; +} + +static const char *of_prop_next_string(struct property *prop, const char *cur) +{ + const void *curv = cur; + + if (!prop) + return NULL; + + if (!cur) + return prop->value; + + curv += strlen(cur) + 1; + if (curv >= prop->value + prop->length) + return NULL; + + return curv; +} + +int of_device_is_compatible(const struct device_node *device, + const char *compat, const char *type, + const char *name) +{ + struct property *prop; + const char *cp; + int index = 0, score = 0; + + /* Compatible match has highest priority */ + if (compat && compat[0]) { + prop = of_find_property(device, "compatible", NULL); + for (cp = of_prop_next_string(prop, NULL); cp; + cp = of_prop_next_string(prop, cp), index++) { + if (of_compat_cmp(cp, compat, strlen(compat)) == 0) { + score = INT_MAX/2 - (index << 2); + break; + } + } + if (!score) + return 0; + } + + /* Matching type is better than matching name */ + if (type && type[0]) { + if (!device->type || of_node_cmp(type, device->type)) + return 0; + score += 2; + } + + /* Matching name is a bit better than not */ + if (name && name[0]) { + if (!device->name || of_node_cmp(name, device->name)) + return 0; + score++; + } + + return score; +} + +bool of_device_is_available(const struct device_node *device) +{ + const char *status; + int statlen; + + if (!device) + return false; + + status = of_get_property(device, "status", &statlen); + if (status == NULL) + return true; + + if (statlen > 0) { + if (!strcmp(status, "okay")) + return true; + } + + return false; +} + +struct device_node *of_get_parent(const struct device_node *node) +{ + const struct device_node *np; + + if (!node) + return NULL; + + np = of_node_get(node->parent); + + return (struct device_node *)np; +} + +static struct device_node *__of_get_next_child(const struct device_node *node, + struct device_node *prev) +{ + struct device_node *next; + + if (!node) + return NULL; + + next = prev ? prev->sibling : node->child; + for (; next; next = next->sibling) + if (of_node_get(next)) + break; + of_node_put(prev); + return next; +} + +#define __for_each_child_of_node(parent, child) \ + for (child = __of_get_next_child(parent, NULL); child != NULL; \ + child = __of_get_next_child(parent, child)) + +static struct device_node *__of_find_node_by_path(struct device_node *parent, + const char *path) +{ + struct device_node *child; + int len; + + len = strcspn(path, "/:"); + if (!len) + return NULL; + + __for_each_child_of_node(parent, child) { + const char *name = strrchr(child->full_name, '/'); + + name++; + if (strncmp(path, name, len) == 0 && (strlen(name) == len)) + return child; + } + return NULL; +} + +#define for_each_property_of_node(dn, pp) \ + for (pp = dn->properties; pp != NULL; pp = pp->next) + +struct device_node *of_find_node_opts_by_path(const char *path, + const char **opts) +{ + struct device_node *np = NULL; + struct property *pp; + const char *separator = strchr(path, ':'); + + if (opts) + *opts = separator ? separator + 1 : NULL; + + if (strcmp(path, "/") == 0) + return of_node_get(gd->of_root); + + /* The path could begin with an alias */ + if (*path != '/') { + int len; + const char *p = separator; + + if (!p) + p = strchrnul(path, '/'); + len = p - path; + + /* of_aliases must not be NULL */ + if (!of_aliases) + return NULL; + + for_each_property_of_node(of_aliases, pp) { + if (strlen(pp->name) == len && !strncmp(pp->name, path, + len)) { + np = of_find_node_by_path(pp->value); + break; + } + } + if (!np) + return NULL; + path = p; + } + + /* Step down the tree matching path components */ + if (!np) + np = of_node_get(gd->of_root); + while (np && *path == '/') { + struct device_node *tmp = np; + + path++; /* Increment past '/' delimiter */ + np = __of_find_node_by_path(np, path); + of_node_put(tmp); + path = strchrnul(path, '/'); + if (separator && separator < path) + break; + } + + return np; +} + +struct device_node *of_find_compatible_node(struct device_node *from, + const char *type, const char *compatible) +{ + struct device_node *np; + + for_each_of_allnodes_from(from, np) + if (of_device_is_compatible(np, compatible, type, NULL) && + of_node_get(np)) + break; + of_node_put(from); + + return np; +} + +struct device_node *of_find_node_by_phandle(phandle handle) +{ + struct device_node *np; + + if (!handle) + return NULL; + + for_each_of_allnodes(np) + if (np->phandle == handle) + break; + (void)of_node_get(np); + + return np; +} + +/** + * of_find_property_value_of_size() - find property of given size + * + * Search for a property in a device node and validate the requested size. + * + * @np: device node from which the property value is to be read. + * @propname: name of the property to be searched. + * @len: requested length of property value + * + * @return the property value on success, -EINVAL if the property does not + * exist, -ENODATA if property does not have a value, and -EOVERFLOW if the + * property data isn't large enough. + */ +static void *of_find_property_value_of_size(const struct device_node *np, + const char *propname, u32 len) +{ + struct property *prop = of_find_property(np, propname, NULL); + + if (!prop) + return ERR_PTR(-EINVAL); + if (!prop->value) + return ERR_PTR(-ENODATA); + if (len > prop->length) + return ERR_PTR(-EOVERFLOW); + + return prop->value; +} + +int of_read_u32(const struct device_node *np, const char *propname, u32 *outp) +{ + const __be32 *val; + + debug("%s: %s: ", __func__, propname); + if (!np) + return -EINVAL; + val = of_find_property_value_of_size(np, propname, sizeof(*outp)); + if (IS_ERR(val)) { + debug("(not found)\n"); + return PTR_ERR(val); + } + + *outp = be32_to_cpup(val); + debug("%#x (%d)\n", *outp, *outp); + + return 0; +} + +int of_read_u32_array(const struct device_node *np, const char *propname, + u32 *out_values, size_t sz) +{ + const __be32 *val; + + debug("%s: %s: ", __func__, propname); + val = of_find_property_value_of_size(np, propname, + sz * sizeof(*out_values)); + + if (IS_ERR(val)) + return PTR_ERR(val); + + debug("size %zd\n", sz); + while (sz--) + *out_values++ = be32_to_cpup(val++); + + return 0; +} + +int of_property_match_string(const struct device_node *np, const char *propname, + const char *string) +{ + const struct property *prop = of_find_property(np, propname, NULL); + size_t l; + int i; + const char *p, *end; + + if (!prop) + return -EINVAL; + if (!prop->value) + return -ENODATA; + + p = prop->value; + end = p + prop->length; + + for (i = 0; p < end; i++, p += l) { + l = strnlen(p, end - p) + 1; + if (p + l > end) + return -EILSEQ; + debug("comparing %s with %s\n", string, p); + if (strcmp(string, p) == 0) + return i; /* Found it; return index */ + } + return -ENODATA; +} + +/** + * of_property_read_string_helper() - Utility helper for parsing string properties + * @np: device node from which the property value is to be read. + * @propname: name of the property to be searched. + * @out_strs: output array of string pointers. + * @sz: number of array elements to read. + * @skip: Number of strings to skip over at beginning of list. + * + * Don't call this function directly. It is a utility helper for the + * of_property_read_string*() family of functions. + */ +int of_property_read_string_helper(const struct device_node *np, + const char *propname, const char **out_strs, + size_t sz, int skip) +{ + const struct property *prop = of_find_property(np, propname, NULL); + int l = 0, i = 0; + const char *p, *end; + + if (!prop) + return -EINVAL; + if (!prop->value) + return -ENODATA; + p = prop->value; + end = p + prop->length; + + for (i = 0; p < end && (!out_strs || i < skip + sz); i++, p += l) { + l = strnlen(p, end - p) + 1; + if (p + l > end) + return -EILSEQ; + if (out_strs && i >= skip) + *out_strs++ = p; + } + i -= skip; + return i <= 0 ? -ENODATA : i; +} + +static int __of_parse_phandle_with_args(const struct device_node *np, + const char *list_name, + const char *cells_name, + int cell_count, int index, + struct of_phandle_args *out_args) +{ + const __be32 *list, *list_end; + int rc = 0, cur_index = 0; + uint32_t count = 0; + struct device_node *node = NULL; + phandle phandle; + int size; + + /* Retrieve the phandle list property */ + list = of_get_property(np, list_name, &size); + if (!list) + return -ENOENT; + list_end = list + size / sizeof(*list); + + /* Loop over the phandles until all the requested entry is found */ + while (list < list_end) { + rc = -EINVAL; + count = 0; + + /* + * If phandle is 0, then it is an empty entry with no + * arguments. Skip forward to the next entry. + */ + phandle = be32_to_cpup(list++); + if (phandle) { + /* + * Find the provider node and parse the #*-cells + * property to determine the argument length. + * + * This is not needed if the cell count is hard-coded + * (i.e. cells_name not set, but cell_count is set), + * except when we're going to return the found node + * below. + */ + if (cells_name || cur_index == index) { + node = of_find_node_by_phandle(phandle); + if (!node) { + debug("%s: could not find phandle\n", + np->full_name); + goto err; + } + } + + if (cells_name) { + if (of_read_u32(node, cells_name, &count)) { + debug("%s: could not get %s for %s\n", + np->full_name, cells_name, + node->full_name); + goto err; + } + } else { + count = cell_count; + } + + /* + * Make sure that the arguments actually fit in the + * remaining property data length + */ + if (list + count > list_end) { + debug("%s: arguments longer than property\n", + np->full_name); + goto err; + } + } + + /* + * All of the error cases above bail out of the loop, so at + * this point, the parsing is successful. If the requested + * index matches, then fill the out_args structure and return, + * or return -ENOENT for an empty entry. + */ + rc = -ENOENT; + if (cur_index == index) { + if (!phandle) + goto err; + + if (out_args) { + int i; + if (WARN_ON(count > OF_MAX_PHANDLE_ARGS)) + count = OF_MAX_PHANDLE_ARGS; + out_args->np = node; + out_args->args_count = count; + for (i = 0; i < count; i++) + out_args->args[i] = + be32_to_cpup(list++); + } else { + of_node_put(node); + } + + /* Found it! return success */ + return 0; + } + + of_node_put(node); + node = NULL; + list += count; + cur_index++; + } + + /* + * Unlock node before returning result; will be one of: + * -ENOENT : index is for empty phandle + * -EINVAL : parsing error on data + * [1..n] : Number of phandle (count mode; when index = -1) + */ + rc = index < 0 ? cur_index : -ENOENT; + err: + if (node) + of_node_put(node); + return rc; +} + +struct device_node *of_parse_phandle(const struct device_node *np, + const char *phandle_name, int index) +{ + struct of_phandle_args args; + + if (index < 0) + return NULL; + + if (__of_parse_phandle_with_args(np, phandle_name, NULL, 0, index, + &args)) + return NULL; + + return args.np; +} + +int of_parse_phandle_with_args(const struct device_node *np, + const char *list_name, const char *cells_name, + int index, struct of_phandle_args *out_args) +{ + if (index < 0) + return -EINVAL; + + return __of_parse_phandle_with_args(np, list_name, cells_name, 0, + index, out_args); +} + +static void of_alias_add(struct alias_prop *ap, struct device_node *np, + int id, const char *stem, int stem_len) +{ + ap->np = np; + ap->id = id; + strncpy(ap->stem, stem, stem_len); + ap->stem[stem_len] = 0; + list_add_tail(&ap->link, &aliases_lookup); + debug("adding DT alias:%s: stem=%s id=%i node=%s\n", + ap->alias, ap->stem, ap->id, of_node_full_name(np)); +} + +int of_alias_scan(void) +{ + struct property *pp; + + of_aliases = of_find_node_by_path("/aliases"); + of_chosen = of_find_node_by_path("/chosen"); + if (of_chosen == NULL) + of_chosen = of_find_node_by_path("/chosen@0"); + + if (of_chosen) { + const char *name; + + name = of_get_property(of_chosen, "stdout-path", NULL); + if (name) + of_stdout = of_find_node_opts_by_path(name, + &of_stdout_options); + } + + if (!of_aliases) + return 0; + + for_each_property_of_node(of_aliases, pp) { + const char *start = pp->name; + const char *end = start + strlen(start); + struct device_node *np; + struct alias_prop *ap; + ulong id; + int len; + + /* Skip those we do not want to proceed */ + if (!strcmp(pp->name, "name") || + !strcmp(pp->name, "phandle") || + !strcmp(pp->name, "linux,phandle")) + continue; + + np = of_find_node_by_path(pp->value); + if (!np) + continue; + + /* + * walk the alias backwards to extract the id and work out + * the 'stem' string + */ + while (isdigit(*(end-1)) && end > start) + end--; + len = end - start; + + if (strict_strtoul(end, 10, &id) < 0) + continue; + + /* Allocate an alias_prop with enough space for the stem */ + ap = malloc(sizeof(*ap) + len + 1); + if (!ap) + return -ENOMEM; + memset(ap, 0, sizeof(*ap) + len + 1); + ap->alias = start; + of_alias_add(ap, np, id, start, len); + } + + return 0; +} + +int of_alias_get_id(const struct device_node *np, const char *stem) +{ + struct alias_prop *app; + int id = -ENODEV; + + mutex_lock(&of_mutex); + list_for_each_entry(app, &aliases_lookup, link) { + if (strcmp(app->stem, stem) != 0) + continue; + + if (np == app->np) { + id = app->id; + break; + } + } + mutex_unlock(&of_mutex); + + return id; +} + +struct device_node *of_get_stdout(void) +{ + return of_stdout; +} diff --git a/include/dm/of_access.h b/include/dm/of_access.h new file mode 100644 index 0000000000..142f0f43c9 --- /dev/null +++ b/include/dm/of_access.h @@ -0,0 +1,347 @@ +/* + * Originally from Linux v4.9 + * Copyright (C) 1996-2005 Paul Mackerras. + * + * Updates for PPC64 by Peter Bergner & David Engebretsen, IBM Corp. + * Updates for SPARC64 by David S. Miller + * Derived from PowerPC and Sparc prom.h files by Stephen Rothwell, IBM Corp. + * + * Copyright (c) 2017 Google, Inc + * Written by Simon Glass sjg@chromium.org + * + * Modified for U-Boot + * Copyright (c) 2017 Google, Inc + * + * SPDX-License-Identifier: GPL-2.0+ + */ + +#ifndef _DM_OF_ACCESS_H +#define _DM_OF_ACCESS_H + +#include <dm/of.h> + +/** + * of_find_all_nodes - Get next node in global list + * @prev: Previous node or NULL to start iteration + * of_node_put() will be called on it + * + * Returns a node pointer with refcount incremented, use + * of_node_put() on it when done. + */ +struct device_node *of_find_all_nodes(struct device_node *prev); + +#define for_each_of_allnodes_from(from, dn) \ + for (dn = of_find_all_nodes(from); dn; dn = of_find_all_nodes(dn)) +#define for_each_of_allnodes(dn) for_each_of_allnodes_from(NULL, dn) + +/* Dummy functions to mirror Linux. These are not used in U-Boot */ +#define of_node_get(x) (x) +static inline void of_node_put(const struct device_node *np) { } + +/** + * of_n_addr_cells() - Get the number of address cells for a node + * + * This walks back up the tree to find the closest #address-cells property + * which controls the given node. + * + * @np: Node pointer to check + * @return number of address cells this node uses + */ +int of_n_addr_cells(const struct device_node *np); + +/** + * of_n_size_cells() - Get the number of size cells for a node + * + * This walks back up the tree to find the closest #size-cells property + * which controls the given node. + * + * @np: Node pointer to check + * @return number of size cells this node uses + */ +int of_n_size_cells(const struct device_node *np); + +/** + * of_find_property() - find a property in a node + * + * @np: Pointer to device node holding property + * @name: Name of property + * @lenp: If non-NULL, returns length of property + * @return pointer to property, or NULL if not found + */ +struct property *of_find_property(const struct device_node *np, + const char *name, int *lenp); + +/** + * of_get_property() - get a property value + * + * Find a property with a given name for a given node and return the value. + * + * @np: Pointer to device node holding property + * @name: Name of property + * @lenp: If non-NULL, returns length of property + * @return pointer to property value, or NULL if not found + */ +const void *of_get_property(const struct device_node *np, const char *name, + int *lenp); + +/** + * of_device_is_compatible() - Check if the node matches given constraints + * @device: pointer to node + * @compat: required compatible string, NULL or "" for any match + * @type: required device_type value, NULL or "" for any match + * @name: required node name, NULL or "" for any match + * + * Checks if the given @compat, @type and @name strings match the + * properties of the given @device. A constraints can be skipped by + * passing NULL or an empty string as the constraint. + * + * @return 0 for no match, and a positive integer on match. The return + * value is a relative score with larger values indicating better + * matches. The score is weighted for the most specific compatible value + * to get the highest score. Matching type is next, followed by matching + * name. Practically speaking, this results in the following priority + * order for matches: + * + * 1. specific compatible && type && name + * 2. specific compatible && type + * 3. specific compatible && name + * 4. specific compatible + * 5. general compatible && type && name + * 6. general compatible && type + * 7. general compatible && name + * 8. general compatible + * 9. type && name + * 10. type + * 11. name + */ +int of_device_is_compatible(const struct device_node *np, const char *compat, + const char *type, const char *name); + +/** + * of_device_is_available() - check if a device is available for use + * + * @device: Node to check for availability + * + * @return true if the status property is absent or set to "okay", false + * otherwise + */ +bool of_device_is_available(const struct device_node *np); + +/** + * of_get_parent() - Get a node's parent, if any + * + * @node: Node to check + * @eturns a node pointer, or NULL if none + */ +struct device_node *of_get_parent(const struct device_node *np); + +/** + * of_find_node_opts_by_path() - Find a node matching a full OF path + * + * @path: Either the full path to match, or if the path does not start with + * '/', the name of a property of the /aliases node (an alias). In the + * case of an alias, the node matching the alias' value will be returned. + * @opts: Address of a pointer into which to store the start of an options + * string appended to the end of the path with a ':' separator. Can be NULL + * + * Valid paths: + * /foo/bar Full path + * foo Valid alias + * foo/bar Valid alias + relative path + * + * @return a node pointer or NULL if not found + */ +struct device_node *of_find_node_opts_by_path(const char *path, + const char **opts); + +static inline struct device_node *of_find_node_by_path(const char *path) +{ + return of_find_node_opts_by_path(path, NULL); +} + +/** + * of_find_compatible_node() - find a node based on its compatible string + * + * Find a node based on type and one of the tokens in its "compatible" property + * @from: Node to start searching from or NULL. the node you pass will not be + * searched, only the next one will; typically, you pass what the previous + * call returned. + * @type: The type string to match "device_type" or NULL to ignore + * @compatible: The string to match to one of the tokens in the device + * "compatible" list. + * @return node pointer or NULL if not found + */ +struct device_node *of_find_compatible_node(struct device_node *from, + const char *type, const char *compatible); + +/** + * of_find_node_by_phandle() - Find a node given a phandle + * + * @handle: phandle of the node to find + * + * @return node pointer, or NULL if not found + */ +struct device_node *of_find_node_by_phandle(phandle handle); + +/** + * of_read_u32() - Find and read a 32-bit integer from a property + * + * Search for a property in a device node and read a 32-bit value from + * it. + * + * @np: device node from which the property value is to be read. + * @propname: name of the property to be searched. + * @outp: pointer to return value, modified only if return value is 0. + * + * @return 0 on success, -EINVAL if the property does not exist, + * -ENODATA if property does not have a value, and -EOVERFLOW if the + * property data isn't large enough. + */ +int of_read_u32(const struct device_node *np, const char *propname, u32 *outp); + +/** + * of_read_u32_array() - Find and read an array of 32 bit integers + * + * Search for a property in a device node and read 32-bit value(s) from + * it. + * + * @np: device node from which the property value is to be read. + * @propname: name of the property to be searched. + * @out_values: pointer to return value, modified only if return value is 0. + * @sz: number of array elements to read + * @return 0 on success, -EINVAL if the property does not exist, -ENODATA + * if property does not have a value, and -EOVERFLOW is longer than sz. + */ +int of_read_u32_array(const struct device_node *np, const char *propname, + u32 *out_values, size_t sz); + +/** + * of_property_match_string() - Find string in a list and return index + * + * This function searches a string list property and returns the index + * of a specific string value. + * + * @np: pointer to node containing string list property + * @propname: string list property name + * @string: pointer to string to search for in string list + * @return 0 on success, -EINVAL if the property does not exist, -ENODATA + * if property does not have a value, and -EOVERFLOW is longer than sz. + */ +int of_property_match_string(const struct device_node *np, const char *propname, + const char *string); + +int of_property_read_string_helper(const struct device_node *np, + const char *propname, const char **out_strs, + size_t sz, int index); + +/** + * of_property_read_string_index() - Find and read a string from a multiple + * strings property. + * @np: device node from which the property value is to be read. + * @propname: name of the property to be searched. + * @index: index of the string in the list of strings + * @out_string: pointer to null terminated return string, modified only if + * return value is 0. + * + * Search for a property in a device tree node and retrieve a null + * terminated string value (pointer to data, not a copy) in the list of strings + * contained in that property. + * Returns 0 on success, -EINVAL if the property does not exist, -ENODATA if + * property does not have a value, and -EILSEQ if the string is not + * null-terminated within the length of the property data. + * + * The out_string pointer is modified only if a valid string can be decoded. + */ +static inline int of_property_read_string_index(const struct device_node *np, + const char *propname, + int index, const char **output) +{ + int rc = of_property_read_string_helper(np, propname, output, 1, index); + return rc < 0 ? rc : 0; +} + +/** + * of_parse_phandle - Resolve a phandle property to a device_node pointer + * @np: Pointer to device node holding phandle property + * @phandle_name: Name of property holding a phandle value + * @index: For properties holding a table of phandles, this is the index into + * the table + * + * Returns the device_node pointer with refcount incremented. Use + * of_node_put() on it when done. + */ +struct device_node *of_parse_phandle(const struct device_node *np, + const char *phandle_name, int index); + +/** + * of_parse_phandle_with_args() - Find a node pointed by phandle in a list + * + * @np: pointer to a device tree node containing a list + * @list_name: property name that contains a list + * @cells_name: property name that specifies phandles' arguments count + * @index: index of a phandle to parse out + * @out_args: optional pointer to output arguments structure (will be filled) + * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if + * @list_name does not exist, -EINVAL if a phandle was not found, + * @cells_name could not be found, the arguments were truncated or there + * were too many arguments. + * + * This function is useful to parse lists of phandles and their arguments. + * Returns 0 on success and fills out_args, on error returns appropriate + * errno value. + * + * Caller is responsible to call of_node_put() on the returned out_args->np + * pointer. + * + * Example: + * + * phandle1: node1 { + * #list-cells = <2>; + * } + * + * phandle2: node2 { + * #list-cells = <1>; + * } + * + * node3 { + * list = <&phandle1 1 2 &phandle2 3>; + * } + * + * To get a device_node of the `node2' node you may call this: + * of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args); + */ +int of_parse_phandle_with_args(const struct device_node *np, + const char *list_name, const char *cells_name, + int index, struct of_phandle_args *out_args); + +/** + * of_alias_scan() - Scan all properties of the 'aliases' node + * + * The function scans all the properties of the 'aliases' node and populates + * the lookup table with the properties. It returns the number of alias + * properties found, or an error code in case of failure. + * + * @return 9 if OK, -ENOMEM if not enough memory + */ +int of_alias_scan(void); + +/** + * of_alias_get_id - Get alias id for the given device_node + * + * Travels the lookup table to get the alias id for the given device_node and + * alias stem. + * + * @np: Pointer to the given device_node + * @stem: Alias stem of the given device_node + * @return alias ID, if found, else -ENODEV + */ +int of_alias_get_id(const struct device_node *np, const char *stem); + +/** + * of_get_stdout() - Get node to use for stdout + * + * @return node referred to by stdout-path alias, or NULL if none + */ +struct device_node *of_get_stdout(void); + +#endif