libfdt: Implement property iteration functions
authorDavid Gibson <david@gibson.dropbear.id.au>
Tue, 9 Mar 2010 06:39:14 +0000 (17:39 +1100)
committerGerald Van Baren <gvb@unssw.com>
Fri, 15 Jul 2011 01:10:34 +0000 (21:10 -0400)
For ages, we've been talking about adding functions to libfdt to allow
iteration through properties.  So, finally, here are some.

I got bogged down on this for a long time because I didn't want to
expose offsets directly to properties to the callers.  But without
that, attempting to make reasonable iteration functions just became
horrible.  So eventually, I settled on an interface which does now
expose property offsets.  fdt_first_property_offset() and
fdt_next_property_offset() are used to step through the offsets of the
properties starting from a particularly node offset.  The details of
the property at each offset can then be retrieved with either
fdt_get_property_by_offset() or fdt_getprop_by_offset() which have
interfaces similar to fdt_get_property() and fdt_getprop()
respectively.

No explicit testcases are included, but we do use the new functions to
reimplement the existing fdt_get_property() function.

Signed-off-by: David Gibson <david@gibson.dropbear.id.au>
This was extracted from the DTC commit:
73dca9ae0b9abe6924ba640164ecce9f8df69c5a Mon Sep 17 00:00:00 2001

Signed-off-by: Gerald Van Baren <vanbaren@cideas.com>
include/libfdt.h
lib/libfdt/fdt.c
lib/libfdt/fdt_ro.c
lib/libfdt/libfdt_internal.h

index d23d40e..de82ed5 100644 (file)
@@ -343,6 +343,75 @@ int fdt_path_offset(const void *fdt, const char *path);
 const char *fdt_get_name(const void *fdt, int nodeoffset, int *lenp);
 
 /**
+ * fdt_first_property_offset - find the offset of a node's first property
+ * @fdt: pointer to the device tree blob
+ * @nodeoffset: structure block offset of a node
+ *
+ * fdt_first_property_offset() finds the first property of the node at
+ * the given structure block offset.
+ *
+ * returns:
+ *     structure block offset of the property (>=0), on success
+ *     -FDT_ERR_NOTFOUND, if the requested node has no properties
+ *     -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_BEGIN_NODE tag
+ *      -FDT_ERR_BADMAGIC,
+ *     -FDT_ERR_BADVERSION,
+ *     -FDT_ERR_BADSTATE,
+ *     -FDT_ERR_BADSTRUCTURE,
+ *     -FDT_ERR_TRUNCATED, standard meanings.
+ */
+int fdt_first_property_offset(const void *fdt, int nodeoffset);
+
+/**
+ * fdt_next_property_offset - step through a node's properties
+ * @fdt: pointer to the device tree blob
+ * @offset: structure block offset of a property
+ *
+ * fdt_next_property_offset() finds the property immediately after the
+ * one at the given structure block offset.  This will be a property
+ * of the same node as the given property.
+ *
+ * returns:
+ *     structure block offset of the next property (>=0), on success
+ *     -FDT_ERR_NOTFOUND, if the given property is the last in its node
+ *     -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_PROP tag
+ *      -FDT_ERR_BADMAGIC,
+ *     -FDT_ERR_BADVERSION,
+ *     -FDT_ERR_BADSTATE,
+ *     -FDT_ERR_BADSTRUCTURE,
+ *     -FDT_ERR_TRUNCATED, standard meanings.
+ */
+int fdt_next_property_offset(const void *fdt, int offset);
+
+/**
+ * fdt_get_property_by_offset - retrieve the property at a given offset
+ * @fdt: pointer to the device tree blob
+ * @offset: offset of the property to retrieve
+ * @lenp: pointer to an integer variable (will be overwritten) or NULL
+ *
+ * fdt_get_property_by_offset() retrieves a pointer to the
+ * fdt_property structure within the device tree blob at the given
+ * offset.  If lenp is non-NULL, the length of the property value is
+ * also returned, in the integer pointed to by lenp.
+ *
+ * returns:
+ *     pointer to the structure representing the property
+ *             if lenp is non-NULL, *lenp contains the length of the property
+ *             value (>=0)
+ *     NULL, on error
+ *             if lenp is non-NULL, *lenp contains an error code (<0):
+ *             -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
+ *             -FDT_ERR_BADMAGIC,
+ *             -FDT_ERR_BADVERSION,
+ *             -FDT_ERR_BADSTATE,
+ *             -FDT_ERR_BADSTRUCTURE,
+ *             -FDT_ERR_TRUNCATED, standard meanings
+ */
+const struct fdt_property *fdt_get_property_by_offset(const void *fdt,
+                                                     int offset,
+                                                     int *lenp);
+
+/**
  * fdt_get_property_namelen - find a property based on substring
  * @fdt: pointer to the device tree blob
  * @nodeoffset: offset of the node whose property to find
@@ -396,6 +465,40 @@ static inline struct fdt_property *fdt_get_property_w(void *fdt, int nodeoffset,
 }
 
 /**
+ * fdt_getprop_by_offset - retrieve the value of a property at a given offset
+ * @fdt: pointer to the device tree blob
+ * @ffset: offset of the property to read
+ * @namep: pointer to a string variable (will be overwritten) or NULL
+ * @lenp: pointer to an integer variable (will be overwritten) or NULL
+ *
+ * fdt_getprop_by_offset() retrieves a pointer to the value of the
+ * property at structure block offset 'offset' (this will be a pointer
+ * to within the device blob itself, not a copy of the value).  If
+ * lenp is non-NULL, the length of the property value is also
+ * returned, in the integer pointed to by lenp.  If namep is non-NULL,
+ * the property's namne will also be returned in the char * pointed to
+ * by namep (this will be a pointer to within the device tree's string
+ * block, not a new copy of the name).
+ *
+ * returns:
+ *     pointer to the property's value
+ *             if lenp is non-NULL, *lenp contains the length of the property
+ *             value (>=0)
+ *             if namep is non-NULL *namep contiains a pointer to the property
+ *             name.
+ *     NULL, on error
+ *             if lenp is non-NULL, *lenp contains an error code (<0):
+ *             -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
+ *             -FDT_ERR_BADMAGIC,
+ *             -FDT_ERR_BADVERSION,
+ *             -FDT_ERR_BADSTATE,
+ *             -FDT_ERR_BADSTRUCTURE,
+ *             -FDT_ERR_TRUNCATED, standard meanings
+ */
+const void *fdt_getprop_by_offset(const void *fdt, int offset,
+                                 const char **namep, int *lenp);
+
+/**
  * fdt_getprop_namelen - get property value based on substring
  * @fdt: pointer to the device tree blob
  * @nodeoffset: offset of the node whose property to find
index b09ea6f..4157b21 100644 (file)
@@ -153,6 +153,15 @@ int _fdt_check_node_offset(const void *fdt, int offset)
        return offset;
 }
 
+int _fdt_check_prop_offset(const void *fdt, int offset)
+{
+       if ((offset < 0) || (offset % FDT_TAGSIZE)
+           || (fdt_next_tag(fdt, offset, &offset) != FDT_PROP))
+               return -FDT_ERR_BADOFFSET;
+
+       return offset;
+}
+
 int fdt_next_node(const void *fdt, int offset, int *depth)
 {
        int nextoffset = 0;
index 91a354e..1933010 100644 (file)
@@ -109,6 +109,30 @@ int fdt_num_mem_rsv(const void *fdt)
        return i;
 }
 
+static int _nextprop(const void *fdt, int offset)
+{
+       uint32_t tag;
+       int nextoffset;
+
+       do {
+               tag = fdt_next_tag(fdt, offset, &nextoffset);
+
+               switch (tag) {
+               case FDT_END:
+                       if (nextoffset >= 0)
+                               return -FDT_ERR_BADSTRUCTURE;
+                       else
+                               return nextoffset;
+
+               case FDT_PROP:
+                       return offset;
+               }
+               offset = nextoffset;
+       } while (tag == FDT_NOP);
+
+       return -FDT_ERR_NOTFOUND;
+}
+
 int fdt_subnode_offset_namelen(const void *fdt, int offset,
                               const char *name, int namelen)
 {
@@ -198,52 +222,66 @@ const char *fdt_get_name(const void *fdt, int nodeoffset, int *len)
        return NULL;
 }
 
-const struct fdt_property *fdt_get_property_namelen(const void *fdt,
-                                                   int nodeoffset,
-                                                   const char *name,
-                                                   int namelen, int *lenp)
+int fdt_first_property_offset(const void *fdt, int nodeoffset)
+{
+       int offset;
+
+       if ((offset = _fdt_check_node_offset(fdt, nodeoffset)) < 0)
+               return offset;
+
+       return _nextprop(fdt, offset);
+}
+
+int fdt_next_property_offset(const void *fdt, int offset)
+{
+       if ((offset = _fdt_check_prop_offset(fdt, offset)) < 0)
+               return offset;
+
+       return _nextprop(fdt, offset);
+}
+
+const struct fdt_property *fdt_get_property_by_offset(const void *fdt,
+                                                     int offset,
+                                                     int *lenp)
 {
-       uint32_t tag;
-       const struct fdt_property *prop;
-       int offset, nextoffset;
        int err;
+       const struct fdt_property *prop;
 
-       if (((err = fdt_check_header(fdt)) != 0)
-           || ((err = _fdt_check_node_offset(fdt, nodeoffset)) < 0))
-                       goto fail;
+       if ((err = _fdt_check_prop_offset(fdt, offset)) < 0) {
+               if (lenp)
+                       *lenp = err;
+               return NULL;
+       }
 
-       nextoffset = err;
-       do {
-               offset = nextoffset;
+       prop = _fdt_offset_ptr(fdt, offset);
 
-               tag = fdt_next_tag(fdt, offset, &nextoffset);
-               switch (tag) {
-               case FDT_END:
-                       if (nextoffset < 0)
-                               err = nextoffset;
-                       else
-                               /* FDT_END tag with unclosed nodes */
-                               err = -FDT_ERR_BADSTRUCTURE;
-                       goto fail;
+       if (lenp)
+               *lenp = fdt32_to_cpu(prop->len);
 
-               case FDT_PROP:
-                       prop = _fdt_offset_ptr(fdt, offset);
-                       if (_fdt_string_eq(fdt, fdt32_to_cpu(prop->nameoff),
-                                          name, namelen)) {
-                               /* Found it! */
-                               if (lenp)
-                                       *lenp = fdt32_to_cpu(prop->len);
-
-                               return prop;
-                       }
+       return prop;
+}
+
+const struct fdt_property *fdt_get_property_namelen(const void *fdt,
+                                                   int offset,
+                                                   const char *name,
+                                                   int namelen, int *lenp)
+{
+       for (offset = fdt_first_property_offset(fdt, offset);
+            (offset >= 0);
+            (offset = fdt_next_property_offset(fdt, offset))) {
+               const struct fdt_property *prop;
+
+               if (!(prop = fdt_get_property_by_offset(fdt, offset, lenp))) {
+                       offset = -FDT_ERR_INTERNAL;
                        break;
                }
-       } while ((tag != FDT_BEGIN_NODE) && (tag != FDT_END_NODE));
+               if (_fdt_string_eq(fdt, fdt32_to_cpu(prop->nameoff),
+                                  name, namelen))
+                       return prop;
+       }
 
-       err = -FDT_ERR_NOTFOUND;
- fail:
        if (lenp)
-               *lenp = err;
+               *lenp = offset;
        return NULL;
 }
 
@@ -267,6 +305,19 @@ const void *fdt_getprop_namelen(const void *fdt, int nodeoffset,
        return prop->data;
 }
 
+const void *fdt_getprop_by_offset(const void *fdt, int offset,
+                                 const char **namep, int *lenp)
+{
+       const struct fdt_property *prop;
+
+       prop = fdt_get_property_by_offset(fdt, offset, lenp);
+       if (!prop)
+               return NULL;
+       if (namep)
+               *namep = fdt_string(fdt, fdt32_to_cpu(prop->nameoff));
+       return prop->data;
+}
+
 const void *fdt_getprop(const void *fdt, int nodeoffset,
                        const char *name, int *lenp)
 {
index d2dcbd6..381133b 100644 (file)
@@ -63,6 +63,7 @@
        }
 
 int _fdt_check_node_offset(const void *fdt, int offset);
+int _fdt_check_prop_offset(const void *fdt, int offset);
 const char *_fdt_find_string(const char *strtab, int tabsize, const char *s);
 int _fdt_node_end_offset(void *fdt, int nodeoffset);