scripts/dtc/libfdt/libfdt.h

   1 #ifndef _LIBFDT_H
   2 #define _LIBFDT_H
   3 /*
   4  * libfdt - Flat Device Tree manipulation
   5  * Copyright (C) 2006 David Gibson, IBM Corporation.
   6  *
   7  * libfdt is dual licensed: you can use it either under the terms of
   8  * the GPL, or the BSD license, at your option.
   9  *
  10  *  a) This library is free software; you can redistribute it and/or
  11  *     modify it under the terms of the GNU General Public License as
  12  *     published by the Free Software Foundation; either version 2 of the
  13  *     License, or (at your option) any later version.
  14  *
  15  *     This library is distributed in the hope that it will be useful,
  16  *     but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  *     GNU General Public License for more details.
  19  *
  20  *     You should have received a copy of the GNU General Public
  21  *     License along with this library; if not, write to the Free
  22  *     Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
  23  *     MA 02110-1301 USA
  24  *
  25  * Alternatively,
  26  *
  27  *  b) Redistribution and use in source and binary forms, with or
  28  *     without modification, are permitted provided that the following
  29  *     conditions are met:
  30  *
  31  *     1. Redistributions of source code must retain the above
  32  *        copyright notice, this list of conditions and the following
  33  *        disclaimer.
  34  *     2. Redistributions in binary form must reproduce the above
  35  *        copyright notice, this list of conditions and the following
  36  *        disclaimer in the documentation and/or other materials
  37  *        provided with the distribution.
  38  *
  39  *     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  40  *     CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  41  *     INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  42  *     MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  43  *     DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  44  *     CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  45  *     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  46  *     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  47  *     LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  48  *     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  49  *     CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  50  *     OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  51  *     EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  52  */
  53
  54 #include "libfdt_env.h"
  55 #include "fdt.h"
  56
  57 #define FDT_FIRST_SUPPORTED_VERSION     0x10
  58 #define FDT_LAST_SUPPORTED_VERSION      0x11
  59
  60 /* Error codes: informative error codes */
  61 #define FDT_ERR_NOTFOUND        1
  62         /* FDT_ERR_NOTFOUND: The requested node or property does not exist */
  63 #define FDT_ERR_EXISTS          2
  64         /* FDT_ERR_EXISTS: Attemped to create a node or property which
  65          * already exists */
  66 #define FDT_ERR_NOSPACE         3
  67         /* FDT_ERR_NOSPACE: Operation needed to expand the device
  68          * tree, but its buffer did not have sufficient space to
  69          * contain the expanded tree. Use fdt_open_into() to move the
  70          * device tree to a buffer with more space. */
  71
  72 /* Error codes: codes for bad parameters */
  73 #define FDT_ERR_BADOFFSET       4
  74         /* FDT_ERR_BADOFFSET: Function was passed a structure block
  75          * offset which is out-of-bounds, or which points to an
  76          * unsuitable part of the structure for the operation. */
  77 #define FDT_ERR_BADPATH         5
  78         /* FDT_ERR_BADPATH: Function was passed a badly formatted path
  79          * (e.g. missing a leading / for a function which requires an
  80          * absolute path) */
  81 #define FDT_ERR_BADPHANDLE      6
  82         /* FDT_ERR_BADPHANDLE: Function was passed an invalid phandle
  83          * value.  phandle values of 0 and -1 are not permitted. */
  84 #define FDT_ERR_BADSTATE        7
  85         /* FDT_ERR_BADSTATE: Function was passed an incomplete device
  86          * tree created by the sequential-write functions, which is
  87          * not sufficiently complete for the requested operation. */
  88
  89 /* Error codes: codes for bad device tree blobs */
  90 #define FDT_ERR_TRUNCATED       8
  91         /* FDT_ERR_TRUNCATED: Structure block of the given device tree
  92          * ends without an FDT_END tag. */
  93 #define FDT_ERR_BADMAGIC        9
  94         /* FDT_ERR_BADMAGIC: Given "device tree" appears not to be a
  95          * device tree at all - it is missing the flattened device
  96          * tree magic number. */
  97 #define FDT_ERR_BADVERSION      10
  98         /* FDT_ERR_BADVERSION: Given device tree has a version which
  99          * can't be handled by the requested operation.  For
 100          * read-write functions, this may mean that fdt_open_into() is
 101          * required to convert the tree to the expected version. */
 102 #define FDT_ERR_BADSTRUCTURE    11
 103         /* FDT_ERR_BADSTRUCTURE: Given device tree has a corrupt
 104          * structure block or other serious error (e.g. misnested
 105          * nodes, or subnodes preceding properties). */
 106 #define FDT_ERR_BADLAYOUT       12
 107         /* FDT_ERR_BADLAYOUT: For read-write functions, the given
 108          * device tree has it's sub-blocks in an order that the
 109          * function can't handle (memory reserve map, then structure,
 110          * then strings).  Use fdt_open_into() to reorganize the tree
 111          * into a form suitable for the read-write operations. */
 112
 113 /* "Can't happen" error indicating a bug in libfdt */
 114 #define FDT_ERR_INTERNAL        13
 115         /* FDT_ERR_INTERNAL: libfdt has failed an internal assertion.
 116          * Should never be returned, if it is, it indicates a bug in
 117          * libfdt itself. */
 118
 119 /* Errors in device tree content */
 120 #define FDT_ERR_BADNCELLS       14
 121         /* FDT_ERR_BADNCELLS: Device tree has a #address-cells, #size-cells
 122          * or similar property with a bad format or value */
 123
 124 #define FDT_ERR_MAX             14
 125
 126 /**********************************************************************/
 127 /* Low-level functions (you probably don't need these)                */
 128 /**********************************************************************/
 129
 130 const void *fdt_offset_ptr(const void *fdt, int offset, unsigned int checklen);
 131 static inline void *fdt_offset_ptr_w(void *fdt, int offset, int checklen)
 132 {
 133         return (void *)(uintptr_t)fdt_offset_ptr(fdt, offset, checklen);
 134 }
 135
 136 uint32_t fdt_next_tag(const void *fdt, int offset, int *nextoffset);
 137
 138 /**********************************************************************/
 139 /* Traversal functions                                                */
 140 /**********************************************************************/
 141
 142 int fdt_next_node(const void *fdt, int offset, int *depth);
 143
 144 /**
 145  * fdt_first_subnode() - get offset of first direct subnode
 146  *
 147  * @fdt:        FDT blob
 148  * @offset:     Offset of node to check
 149  * @return offset of first subnode, or -FDT_ERR_NOTFOUND if there is none
 150  */
 151 int fdt_first_subnode(const void *fdt, int offset);
 152
 153 /**
 154  * fdt_next_subnode() - get offset of next direct subnode
 155  *
 156  * After first calling fdt_first_subnode(), call this function repeatedly to
 157  * get direct subnodes of a parent node.
 158  *
 159  * @fdt:        FDT blob
 160  * @offset:     Offset of previous subnode
 161  * @return offset of next subnode, or -FDT_ERR_NOTFOUND if there are no more
 162  * subnodes
 163  */
 164 int fdt_next_subnode(const void *fdt, int offset);
 165
 166 /**********************************************************************/
 167 /* General functions                                                  */
 168 /**********************************************************************/
 169
 170 #define fdt_get_header(fdt, field) \
 171         (fdt32_to_cpu(((const struct fdt_header *)(fdt))->field))
 172 #define fdt_magic(fdt)                  (fdt_get_header(fdt, magic))
 173 #define fdt_totalsize(fdt)              (fdt_get_header(fdt, totalsize))
 174 #define fdt_off_dt_struct(fdt)          (fdt_get_header(fdt, off_dt_struct))
 175 #define fdt_off_dt_strings(fdt)         (fdt_get_header(fdt, off_dt_strings))
 176 #define fdt_off_mem_rsvmap(fdt)         (fdt_get_header(fdt, off_mem_rsvmap))
 177 #define fdt_version(fdt)                (fdt_get_header(fdt, version))
 178 #define fdt_last_comp_version(fdt)      (fdt_get_header(fdt, last_comp_version))
 179 #define fdt_boot_cpuid_phys(fdt)        (fdt_get_header(fdt, boot_cpuid_phys))
 180 #define fdt_size_dt_strings(fdt)        (fdt_get_header(fdt, size_dt_strings))
 181 #define fdt_size_dt_struct(fdt)         (fdt_get_header(fdt, size_dt_struct))
 182
 183 #define __fdt_set_hdr(name) \
 184         static inline void fdt_set_##name(void *fdt, uint32_t val) \
 185         { \
 186                 struct fdt_header *fdth = (struct fdt_header*)fdt; \
 187                 fdth->name = cpu_to_fdt32(val); \
 188         }
 189 __fdt_set_hdr(magic);
 190 __fdt_set_hdr(totalsize);
 191 __fdt_set_hdr(off_dt_struct);
 192 __fdt_set_hdr(off_dt_strings);
 193 __fdt_set_hdr(off_mem_rsvmap);
 194 __fdt_set_hdr(version);
 195 __fdt_set_hdr(last_comp_version);
 196 __fdt_set_hdr(boot_cpuid_phys);
 197 __fdt_set_hdr(size_dt_strings);
 198 __fdt_set_hdr(size_dt_struct);
 199 #undef __fdt_set_hdr
 200
 201 /**
 202  * fdt_check_header - sanity check a device tree or possible device tree
 203  * @fdt: pointer to data which might be a flattened device tree
 204  *
 205  * fdt_check_header() checks that the given buffer contains what
 206  * appears to be a flattened device tree with sane information in its
 207  * header.
 208  *
 209  * returns:
 210  *     0, if the buffer appears to contain a valid device tree
 211  *     -FDT_ERR_BADMAGIC,
 212  *     -FDT_ERR_BADVERSION,
 213  *     -FDT_ERR_BADSTATE, standard meanings, as above
 214  */
 215 int fdt_check_header(const void *fdt);
 216
 217 /**
 218  * fdt_move - move a device tree around in memory
 219  * @fdt: pointer to the device tree to move
 220  * @buf: pointer to memory where the device is to be moved
 221  * @bufsize: size of the memory space at buf
 222  *
 223  * fdt_move() relocates, if possible, the device tree blob located at
 224  * fdt to the buffer at buf of size bufsize.  The buffer may overlap
 225  * with the existing device tree blob at fdt.  Therefore,
 226  *     fdt_move(fdt, fdt, fdt_totalsize(fdt))
 227  * should always succeed.
 228  *
 229  * returns:
 230  *     0, on success
 231  *     -FDT_ERR_NOSPACE, bufsize is insufficient to contain the device tree
 232  *     -FDT_ERR_BADMAGIC,
 233  *     -FDT_ERR_BADVERSION,
 234  *     -FDT_ERR_BADSTATE, standard meanings
 235  */
 236 int fdt_move(const void *fdt, void *buf, int bufsize);
 237
 238 /**********************************************************************/
 239 /* Read-only functions                                                */
 240 /**********************************************************************/
 241
 242 /**
 243  * fdt_string - retrieve a string from the strings block of a device tree
 244  * @fdt: pointer to the device tree blob
 245  * @stroffset: offset of the string within the strings block (native endian)
 246  *
 247  * fdt_string() retrieves a pointer to a single string from the
 248  * strings block of the device tree blob at fdt.
 249  *
 250  * returns:
 251  *     a pointer to the string, on success
 252  *     NULL, if stroffset is out of bounds
 253  */
 254 const char *fdt_string(const void *fdt, int stroffset);
 255
 256 /**
 257  * fdt_num_mem_rsv - retrieve the number of memory reserve map entries
 258  * @fdt: pointer to the device tree blob
 259  *
 260  * Returns the number of entries in the device tree blob's memory
 261  * reservation map.  This does not include the terminating 0,0 entry
 262  * or any other (0,0) entries reserved for expansion.
 263  *
 264  * returns:
 265  *     the number of entries
 266  */
 267 int fdt_num_mem_rsv(const void *fdt);
 268
 269 /**
 270  * fdt_get_mem_rsv - retrieve one memory reserve map entry
 271  * @fdt: pointer to the device tree blob
 272  * @address, @size: pointers to 64-bit variables
 273  *
 274  * On success, *address and *size will contain the address and size of
 275  * the n-th reserve map entry from the device tree blob, in
 276  * native-endian format.
 277  *
 278  * returns:
 279  *     0, on success
 280  *     -FDT_ERR_BADMAGIC,
 281  *     -FDT_ERR_BADVERSION,
 282  *     -FDT_ERR_BADSTATE, standard meanings
 283  */
 284 int fdt_get_mem_rsv(const void *fdt, int n, uint64_t *address, uint64_t *size);
 285
 286 /**
 287  * fdt_subnode_offset_namelen - find a subnode based on substring
 288  * @fdt: pointer to the device tree blob
 289  * @parentoffset: structure block offset of a node
 290  * @name: name of the subnode to locate
 291  * @namelen: number of characters of name to consider
 292  *
 293  * Identical to fdt_subnode_offset(), but only examine the first
 294  * namelen characters of name for matching the subnode name.  This is
 295  * useful for finding subnodes based on a portion of a larger string,
 296  * such as a full path.
 297  */
 298 int fdt_subnode_offset_namelen(const void *fdt, int parentoffset,
 299                                const char *name, int namelen);
 300 /**
 301  * fdt_subnode_offset - find a subnode of a given node
 302  * @fdt: pointer to the device tree blob
 303  * @parentoffset: structure block offset of a node
 304  * @name: name of the subnode to locate
 305  *
 306  * fdt_subnode_offset() finds a subnode of the node at structure block
 307  * offset parentoffset with the given name.  name may include a unit
 308  * address, in which case fdt_subnode_offset() will find the subnode
 309  * with that unit address, or the unit address may be omitted, in
 310  * which case fdt_subnode_offset() will find an arbitrary subnode
 311  * whose name excluding unit address matches the given name.
 312  *
 313  * returns:
 314  *      structure block offset of the requested subnode (>=0), on success
 315  *      -FDT_ERR_NOTFOUND, if the requested subnode does not exist
 316  *      -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE tag
 317  *      -FDT_ERR_BADMAGIC,
 318  *      -FDT_ERR_BADVERSION,
 319  *      -FDT_ERR_BADSTATE,
 320  *      -FDT_ERR_BADSTRUCTURE,
 321  *      -FDT_ERR_TRUNCATED, standard meanings.
 322  */
 323 int fdt_subnode_offset(const void *fdt, int parentoffset, const char *name);
 324
 325 /**
 326  * fdt_path_offset_namelen - find a tree node by its full path
 327  * @fdt: pointer to the device tree blob
 328  * @path: full path of the node to locate
 329  * @namelen: number of characters of path to consider
 330  *
 331  * Identical to fdt_path_offset(), but only consider the first namelen
 332  * characters of path as the path name.
 333  */
 334 int fdt_path_offset_namelen(const void *fdt, const char *path, int namelen);
 335
 336 /**
 337  * fdt_path_offset - find a tree node by its full path
 338  * @fdt: pointer to the device tree blob
 339  * @path: full path of the node to locate
 340  *
 341  * fdt_path_offset() finds a node of a given path in the device tree.
 342  * Each path component may omit the unit address portion, but the
 343  * results of this are undefined if any such path component is
 344  * ambiguous (that is if there are multiple nodes at the relevant
 345  * level matching the given component, differentiated only by unit
 346  * address).
 347  *
 348  * returns:
 349  *      structure block offset of the node with the requested path (>=0), on success
 350  *      -FDT_ERR_BADPATH, given path does not begin with '/' or is invalid
 351  *      -FDT_ERR_NOTFOUND, if the requested node does not exist
 352  *      -FDT_ERR_BADMAGIC,
 353  *      -FDT_ERR_BADVERSION,
 354  *      -FDT_ERR_BADSTATE,
 355  *      -FDT_ERR_BADSTRUCTURE,
 356  *      -FDT_ERR_TRUNCATED, standard meanings.
 357  */
 358 int fdt_path_offset(const void *fdt, const char *path);
 359
 360 /**
 361  * fdt_get_name - retrieve the name of a given node
 362  * @fdt: pointer to the device tree blob
 363  * @nodeoffset: structure block offset of the starting node
 364  * @lenp: pointer to an integer variable (will be overwritten) or NULL
 365  *
 366  * fdt_get_name() retrieves the name (including unit address) of the
 367  * device tree node at structure block offset nodeoffset.  If lenp is
 368  * non-NULL, the length of this name is also returned, in the integer
 369  * pointed to by lenp.
 370  *
 371  * returns:
 372  *      pointer to the node's name, on success
 373  *              If lenp is non-NULL, *lenp contains the length of that name (>=0)
 374  *      NULL, on error
 375  *              if lenp is non-NULL *lenp contains an error code (<0):
 376  *              -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
 377  *              -FDT_ERR_BADMAGIC,
 378  *              -FDT_ERR_BADVERSION,
 379  *              -FDT_ERR_BADSTATE, standard meanings
 380  */
 381 const char *fdt_get_name(const void *fdt, int nodeoffset, int *lenp);
 382
 383 /**
 384  * fdt_first_property_offset - find the offset of a node's first property
 385  * @fdt: pointer to the device tree blob
 386  * @nodeoffset: structure block offset of a node
 387  *
 388  * fdt_first_property_offset() finds the first property of the node at
 389  * the given structure block offset.
 390  *
 391  * returns:
 392  *      structure block offset of the property (>=0), on success
 393  *      -FDT_ERR_NOTFOUND, if the requested node has no properties
 394  *      -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_BEGIN_NODE tag
 395  *      -FDT_ERR_BADMAGIC,
 396  *      -FDT_ERR_BADVERSION,
 397  *      -FDT_ERR_BADSTATE,
 398  *      -FDT_ERR_BADSTRUCTURE,
 399  *      -FDT_ERR_TRUNCATED, standard meanings.
 400  */
 401 int fdt_first_property_offset(const void *fdt, int nodeoffset);
 402
 403 /**
 404  * fdt_next_property_offset - step through a node's properties
 405  * @fdt: pointer to the device tree blob
 406  * @offset: structure block offset of a property
 407  *
 408  * fdt_next_property_offset() finds the property immediately after the
 409  * one at the given structure block offset.  This will be a property
 410  * of the same node as the given property.
 411  *
 412  * returns:
 413  *      structure block offset of the next property (>=0), on success
 414  *      -FDT_ERR_NOTFOUND, if the given property is the last in its node
 415  *      -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_PROP tag
 416  *      -FDT_ERR_BADMAGIC,
 417  *      -FDT_ERR_BADVERSION,
 418  *      -FDT_ERR_BADSTATE,
 419  *      -FDT_ERR_BADSTRUCTURE,
 420  *      -FDT_ERR_TRUNCATED, standard meanings.
 421  */
 422 int fdt_next_property_offset(const void *fdt, int offset);
 423
 424 /**
 425  * fdt_get_property_by_offset - retrieve the property at a given offset
 426  * @fdt: pointer to the device tree blob
 427  * @offset: offset of the property to retrieve
 428  * @lenp: pointer to an integer variable (will be overwritten) or NULL
 429  *
 430  * fdt_get_property_by_offset() retrieves a pointer to the
 431  * fdt_property structure within the device tree blob at the given
 432  * offset.  If lenp is non-NULL, the length of the property value is
 433  * also returned, in the integer pointed to by lenp.
 434  *
 435  * returns:
 436  *      pointer to the structure representing the property
 437  *              if lenp is non-NULL, *lenp contains the length of the property
 438  *              value (>=0)
 439  *      NULL, on error
 440  *              if lenp is non-NULL, *lenp contains an error code (<0):
 441  *              -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
 442  *              -FDT_ERR_BADMAGIC,
 443  *              -FDT_ERR_BADVERSION,
 444  *              -FDT_ERR_BADSTATE,
 445  *              -FDT_ERR_BADSTRUCTURE,
 446  *              -FDT_ERR_TRUNCATED, standard meanings
 447  */
 448 const struct fdt_property *fdt_get_property_by_offset(const void *fdt,
 449                                                       int offset,
 450                                                       int *lenp);
 451
 452 /**
 453  * fdt_get_property_namelen - find a property based on substring
 454  * @fdt: pointer to the device tree blob
 455  * @nodeoffset: offset of the node whose property to find
 456  * @name: name of the property to find
 457  * @namelen: number of characters of name to consider
 458  * @lenp: pointer to an integer variable (will be overwritten) or NULL
 459  *
 460  * Identical to fdt_get_property_namelen(), but only examine the first
 461  * namelen characters of name for matching the property name.
 462  */
 463 const struct fdt_property *fdt_get_property_namelen(const void *fdt,
 464                                                     int nodeoffset,
 465                                                     const char *name,
 466                                                     int namelen, int *lenp);
 467
 468 /**
 469  * fdt_get_property - find a given property in a given node
 470  * @fdt: pointer to the device tree blob
 471  * @nodeoffset: offset of the node whose property to find
 472  * @name: name of the property to find
 473  * @lenp: pointer to an integer variable (will be overwritten) or NULL
 474  *
 475  * fdt_get_property() retrieves a pointer to the fdt_property
 476  * structure within the device tree blob corresponding to the property
 477  * named 'name' of the node at offset nodeoffset.  If lenp is
 478  * non-NULL, the length of the property value is also returned, in the
 479  * integer pointed to by lenp.
 480  *
 481  * returns:
 482  *      pointer to the structure representing the property
 483  *              if lenp is non-NULL, *lenp contains the length of the property
 484  *              value (>=0)
 485  *      NULL, on error
 486  *              if lenp is non-NULL, *lenp contains an error code (<0):
 487  *              -FDT_ERR_NOTFOUND, node does not have named property
 488  *              -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
 489  *              -FDT_ERR_BADMAGIC,
 490  *              -FDT_ERR_BADVERSION,
 491  *              -FDT_ERR_BADSTATE,
 492  *              -FDT_ERR_BADSTRUCTURE,
 493  *              -FDT_ERR_TRUNCATED, standard meanings
 494  */
 495 const struct fdt_property *fdt_get_property(const void *fdt, int nodeoffset,
 496                                             const char *name, int *lenp);
 497 static inline struct fdt_property *fdt_get_property_w(void *fdt, int nodeoffset,
 498                                                       const char *name,
 499                                                       int *lenp)
 500 {
 501         return (struct fdt_property *)(uintptr_t)
 502                 fdt_get_property(fdt, nodeoffset, name, lenp);
 503 }
 504
 505 /**
 506  * fdt_getprop_by_offset - retrieve the value of a property at a given offset
 507  * @fdt: pointer to the device tree blob
 508  * @ffset: offset of the property to read
 509  * @namep: pointer to a string variable (will be overwritten) or NULL
 510  * @lenp: pointer to an integer variable (will be overwritten) or NULL
 511  *
 512  * fdt_getprop_by_offset() retrieves a pointer to the value of the
 513  * property at structure block offset 'offset' (this will be a pointer
 514  * to within the device blob itself, not a copy of the value).  If
 515  * lenp is non-NULL, the length of the property value is also
 516  * returned, in the integer pointed to by lenp.  If namep is non-NULL,
 517  * the property's namne will also be returned in the char * pointed to
 518  * by namep (this will be a pointer to within the device tree's string
 519  * block, not a new copy of the name).
 520  *
 521  * returns:
 522  *      pointer to the property's value
 523  *              if lenp is non-NULL, *lenp contains the length of the property
 524  *              value (>=0)
 525  *              if namep is non-NULL *namep contiains a pointer to the property
 526  *              name.
 527  *      NULL, on error
 528  *              if lenp is non-NULL, *lenp contains an error code (<0):
 529  *              -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
 530  *              -FDT_ERR_BADMAGIC,
 531  *              -FDT_ERR_BADVERSION,
 532  *              -FDT_ERR_BADSTATE,
 533  *              -FDT_ERR_BADSTRUCTURE,
 534  *              -FDT_ERR_TRUNCATED, standard meanings
 535  */
 536 const void *fdt_getprop_by_offset(const void *fdt, int offset,
 537                                   const char **namep, int *lenp);
 538
 539 /**
 540  * fdt_getprop_namelen - get property value based on substring
 541  * @fdt: pointer to the device tree blob
 542  * @nodeoffset: offset of the node whose property to find
 543  * @name: name of the property to find
 544  * @namelen: number of characters of name to consider
 545  * @lenp: pointer to an integer variable (will be overwritten) or NULL
 546  *
 547  * Identical to fdt_getprop(), but only examine the first namelen
 548  * characters of name for matching the property name.
 549  */
 550 const void *fdt_getprop_namelen(const void *fdt, int nodeoffset,
 551                                 const char *name, int namelen, int *lenp);
 552
 553 /**
 554  * fdt_getprop - retrieve the value of a given property
 555  * @fdt: pointer to the device tree blob
 556  * @nodeoffset: offset of the node whose property to find
 557  * @name: name of the property to find
 558  * @lenp: pointer to an integer variable (will be overwritten) or NULL
 559  *
 560  * fdt_getprop() retrieves a pointer to the value of the property
 561  * named 'name' of the node at offset nodeoffset (this will be a
 562  * pointer to within the device blob itself, not a copy of the value).
 563  * If lenp is non-NULL, the length of the property value is also
 564  * returned, in the integer pointed to by lenp.
 565  *
 566  * returns:
 567  *      pointer to the property's value
 568  *              if lenp is non-NULL, *lenp contains the length of the property
 569  *              value (>=0)
 570  *      NULL, on error
 571  *              if lenp is non-NULL, *lenp contains an error code (<0):
 572  *              -FDT_ERR_NOTFOUND, node does not have named property
 573  *              -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
 574  *              -FDT_ERR_BADMAGIC,
 575  *              -FDT_ERR_BADVERSION,
 576  *              -FDT_ERR_BADSTATE,
 577  *              -FDT_ERR_BADSTRUCTURE,
 578  *              -FDT_ERR_TRUNCATED, standard meanings
 579  */
 580 const void *fdt_getprop(const void *fdt, int nodeoffset,
 581                         const char *name, int *lenp);
 582 static inline void *fdt_getprop_w(void *fdt, int nodeoffset,
 583                                   const char *name, int *lenp)
 584 {
 585         return (void *)(uintptr_t)fdt_getprop(fdt, nodeoffset, name, lenp);
 586 }
 587
 588 /**
 589  * fdt_get_phandle - retrieve the phandle of a given node
 590  * @fdt: pointer to the device tree blob
 591  * @nodeoffset: structure block offset of the node
 592  *
 593  * fdt_get_phandle() retrieves the phandle of the device tree node at
 594  * structure block offset nodeoffset.
 595  *
 596  * returns:
 597  *      the phandle of the node at nodeoffset, on success (!= 0, != -1)
 598  *      0, if the node has no phandle, or another error occurs
 599  */
 600 uint32_t fdt_get_phandle(const void *fdt, int nodeoffset);
 601
 602 /**
 603  * fdt_get_alias_namelen - get alias based on substring
 604  * @fdt: pointer to the device tree blob
 605  * @name: name of the alias th look up
 606  * @namelen: number of characters of name to consider
 607  *
 608  * Identical to fdt_get_alias(), but only examine the first namelen
 609  * characters of name for matching the alias name.
 610  */
 611 const char *fdt_get_alias_namelen(const void *fdt,
 612                                   const char *name, int namelen);
 613
 614 /**
 615  * fdt_get_alias - retreive the path referenced by a given alias
 616  * @fdt: pointer to the device tree blob
 617  * @name: name of the alias th look up
 618  *
 619  * fdt_get_alias() retrieves the value of a given alias.  That is, the
 620  * value of the property named 'name' in the node /aliases.
 621  *
 622  * returns:
 623  *      a pointer to the expansion of the alias named 'name', if it exists
 624  *      NULL, if the given alias or the /aliases node does not exist
 625  */
 626 const char *fdt_get_alias(const void *fdt, const char *name);
 627
 628 /**
 629  * fdt_get_path - determine the full path of a node
 630  * @fdt: pointer to the device tree blob
 631  * @nodeoffset: offset of the node whose path to find
 632  * @buf: character buffer to contain the returned path (will be overwritten)
 633  * @buflen: size of the character buffer at buf
 634  *
 635  * fdt_get_path() computes the full path of the node at offset
 636  * nodeoffset, and records that path in the buffer at buf.
 637  *
 638  * NOTE: This function is expensive, as it must scan the device tree
 639  * structure from the start to nodeoffset.
 640  *
 641  * returns:
 642  *      0, on success
 643  *              buf contains the absolute path of the node at
 644  *              nodeoffset, as a NUL-terminated string.
 645  *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
 646  *      -FDT_ERR_NOSPACE, the path of the given node is longer than (bufsize-1)
 647  *              characters and will not fit in the given buffer.
 648  *      -FDT_ERR_BADMAGIC,
 649  *      -FDT_ERR_BADVERSION,
 650  *      -FDT_ERR_BADSTATE,
 651  *      -FDT_ERR_BADSTRUCTURE, standard meanings
 652  */
 653 int fdt_get_path(const void *fdt, int nodeoffset, char *buf, int buflen);
 654
 655 /**
 656  * fdt_supernode_atdepth_offset - find a specific ancestor of a node
 657  * @fdt: pointer to the device tree blob
 658  * @nodeoffset: offset of the node whose parent to find
 659  * @supernodedepth: depth of the ancestor to find
 660  * @nodedepth: pointer to an integer variable (will be overwritten) or NULL
 661  *
 662  * fdt_supernode_atdepth_offset() finds an ancestor of the given node
 663  * at a specific depth from the root (where the root itself has depth
 664  * 0, its immediate subnodes depth 1 and so forth).  So
 665  *      fdt_supernode_atdepth_offset(fdt, nodeoffset, 0, NULL);
 666  * will always return 0, the offset of the root node.  If the node at
 667  * nodeoffset has depth D, then:
 668  *      fdt_supernode_atdepth_offset(fdt, nodeoffset, D, NULL);
 669  * will return nodeoffset itself.
 670  *
 671  * NOTE: This function is expensive, as it must scan the device tree
 672  * structure from the start to nodeoffset.
 673  *
 674  * returns:
 675
 676  *      structure block offset of the node at node offset's ancestor
 677  *              of depth supernodedepth (>=0), on success
 678  *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
 679 *       -FDT_ERR_NOTFOUND, supernodedepth was greater than the depth of nodeoffset
 680  *      -FDT_ERR_BADMAGIC,
 681  *      -FDT_ERR_BADVERSION,
 682  *      -FDT_ERR_BADSTATE,
 683  *      -FDT_ERR_BADSTRUCTURE, standard meanings
 684  */
 685 int fdt_supernode_atdepth_offset(const void *fdt, int nodeoffset,
 686                                  int supernodedepth, int *nodedepth);
 687
 688 /**
 689  * fdt_node_depth - find the depth of a given node
 690  * @fdt: pointer to the device tree blob
 691  * @nodeoffset: offset of the node whose parent to find
 692  *
 693  * fdt_node_depth() finds the depth of a given node.  The root node
 694  * has depth 0, its immediate subnodes depth 1 and so forth.
 695  *
 696  * NOTE: This function is expensive, as it must scan the device tree
 697  * structure from the start to nodeoffset.
 698  *
 699  * returns:
 700  *      depth of the node at nodeoffset (>=0), on success
 701  *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
 702  *      -FDT_ERR_BADMAGIC,
 703  *      -FDT_ERR_BADVERSION,
 704  *      -FDT_ERR_BADSTATE,
 705  *      -FDT_ERR_BADSTRUCTURE, standard meanings
 706  */
 707 int fdt_node_depth(const void *fdt, int nodeoffset);
 708
 709 /**
 710  * fdt_parent_offset - find the parent of a given node
 711  * @fdt: pointer to the device tree blob
 712  * @nodeoffset: offset of the node whose parent to find
 713  *
 714  * fdt_parent_offset() locates the parent node of a given node (that
 715  * is, it finds the offset of the node which contains the node at
 716  * nodeoffset as a subnode).
 717  *
 718  * NOTE: This function is expensive, as it must scan the device tree
 719  * structure from the start to nodeoffset, *twice*.
 720  *
 721  * returns:
 722  *      structure block offset of the parent of the node at nodeoffset
 723  *              (>=0), on success
 724  *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
 725  *      -FDT_ERR_BADMAGIC,
 726  *      -FDT_ERR_BADVERSION,
 727  *      -FDT_ERR_BADSTATE,
 728  *      -FDT_ERR_BADSTRUCTURE, standard meanings
 729  */
 730 int fdt_parent_offset(const void *fdt, int nodeoffset);
 731
 732 /**
 733  * fdt_node_offset_by_prop_value - find nodes with a given property value
 734  * @fdt: pointer to the device tree blob
 735  * @startoffset: only find nodes after this offset
 736  * @propname: property name to check
 737  * @propval: property value to search for
 738  * @proplen: length of the value in propval
 739  *
 740  * fdt_node_offset_by_prop_value() returns the offset of the first
 741  * node after startoffset, which has a property named propname whose
 742  * value is of length proplen and has value equal to propval; or if
 743  * startoffset is -1, the very first such node in the tree.
 744  *
 745  * To iterate through all nodes matching the criterion, the following
 746  * idiom can be used:
 747  *      offset = fdt_node_offset_by_prop_value(fdt, -1, propname,
 748  *                                             propval, proplen);
 749  *      while (offset != -FDT_ERR_NOTFOUND) {
 750  *              // other code here
 751  *              offset = fdt_node_offset_by_prop_value(fdt, offset, propname,
 752  *                                                     propval, proplen);
 753  *      }
 754  *
 755  * Note the -1 in the first call to the function, if 0 is used here
 756  * instead, the function will never locate the root node, even if it
 757  * matches the criterion.
 758  *
 759  * returns:
 760  *      structure block offset of the located node (>= 0, >startoffset),
 761  *               on success
 762  *      -FDT_ERR_NOTFOUND, no node matching the criterion exists in the
 763  *              tree after startoffset
 764  *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
 765  *      -FDT_ERR_BADMAGIC,
 766  *      -FDT_ERR_BADVERSION,
 767  *      -FDT_ERR_BADSTATE,
 768  *      -FDT_ERR_BADSTRUCTURE, standard meanings
 769  */
 770 int fdt_node_offset_by_prop_value(const void *fdt, int startoffset,
 771                                   const char *propname,
 772                                   const void *propval, int proplen);
 773
 774 /**
 775  * fdt_node_offset_by_phandle - find the node with a given phandle
 776  * @fdt: pointer to the device tree blob
 777  * @phandle: phandle value
 778  *
 779  * fdt_node_offset_by_phandle() returns the offset of the node
 780  * which has the given phandle value.  If there is more than one node
 781  * in the tree with the given phandle (an invalid tree), results are
 782  * undefined.
 783  *
 784  * returns:
 785  *      structure block offset of the located node (>= 0), on success
 786  *      -FDT_ERR_NOTFOUND, no node with that phandle exists
 787  *      -FDT_ERR_BADPHANDLE, given phandle value was invalid (0 or -1)
 788  *      -FDT_ERR_BADMAGIC,
 789  *      -FDT_ERR_BADVERSION,
 790  *      -FDT_ERR_BADSTATE,
 791  *      -FDT_ERR_BADSTRUCTURE, standard meanings
 792  */
 793 int fdt_node_offset_by_phandle(const void *fdt, uint32_t phandle);
 794
 795 /**
 796  * fdt_node_check_compatible: check a node's compatible property
 797  * @fdt: pointer to the device tree blob
 798  * @nodeoffset: offset of a tree node
 799  * @compatible: string to match against
 800  *
 801  *
 802  * fdt_node_check_compatible() returns 0 if the given node contains a
 803  * 'compatible' property with the given string as one of its elements,
 804  * it returns non-zero otherwise, or on error.
 805  *
 806  * returns:
 807  *      0, if the node has a 'compatible' property listing the given string
 808  *      1, if the node has a 'compatible' property, but it does not list
 809  *              the given string
 810  *      -FDT_ERR_NOTFOUND, if the given node has no 'compatible' property
 811  *      -FDT_ERR_BADOFFSET, if nodeoffset does not refer to a BEGIN_NODE tag
 812  *      -FDT_ERR_BADMAGIC,
 813  *      -FDT_ERR_BADVERSION,
 814  *      -FDT_ERR_BADSTATE,
 815  *      -FDT_ERR_BADSTRUCTURE, standard meanings
 816  */
 817 int fdt_node_check_compatible(const void *fdt, int nodeoffset,
 818                               const char *compatible);
 819
 820 /**
 821  * fdt_node_offset_by_compatible - find nodes with a given 'compatible' value
 822  * @fdt: pointer to the device tree blob
 823  * @startoffset: only find nodes after this offset
 824  * @compatible: 'compatible' string to match against
 825  *
 826  * fdt_node_offset_by_compatible() returns the offset of the first
 827  * node after startoffset, which has a 'compatible' property which
 828  * lists the given compatible string; or if startoffset is -1, the
 829  * very first such node in the tree.
 830  *
 831  * To iterate through all nodes matching the criterion, the following
 832  * idiom can be used:
 833  *      offset = fdt_node_offset_by_compatible(fdt, -1, compatible);
 834  *      while (offset != -FDT_ERR_NOTFOUND) {
 835  *              // other code here
 836  *              offset = fdt_node_offset_by_compatible(fdt, offset, compatible);
 837  *      }
 838  *
 839  * Note the -1 in the first call to the function, if 0 is used here
 840  * instead, the function will never locate the root node, even if it
 841  * matches the criterion.
 842  *
 843  * returns:
 844  *      structure block offset of the located node (>= 0, >startoffset),
 845  *               on success
 846  *      -FDT_ERR_NOTFOUND, no node matching the criterion exists in the
 847  *              tree after startoffset
 848  *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
 849  *      -FDT_ERR_BADMAGIC,
 850  *      -FDT_ERR_BADVERSION,
 851  *      -FDT_ERR_BADSTATE,
 852  *      -FDT_ERR_BADSTRUCTURE, standard meanings
 853  */
 854 int fdt_node_offset_by_compatible(const void *fdt, int startoffset,
 855                                   const char *compatible);
 856
 857 /**
 858  * fdt_stringlist_contains - check a string list property for a string
 859  * @strlist: Property containing a list of strings to check
 860  * @listlen: Length of property
 861  * @str: String to search for
 862  *
 863  * This is a utility function provided for convenience. The list contains
 864  * one or more strings, each terminated by \0, as is found in a device tree
 865  * "compatible" property.
 866  *
 867  * @return: 1 if the string is found in the list, 0 not found, or invalid list
 868  */
 869 int fdt_stringlist_contains(const char *strlist, int listlen, const char *str);
 870
 871 /**********************************************************************/
 872 /* Read-only functions (addressing related)                           */
 873 /**********************************************************************/
 874
 875 /**
 876  * FDT_MAX_NCELLS - maximum value for #address-cells and #size-cells
 877  *
 878  * This is the maximum value for #address-cells, #size-cells and
 879  * similar properties that will be processed by libfdt.  IEE1275
 880  * requires that OF implementations handle values up to 4.
 881  * Implementations may support larger values, but in practice higher
 882  * values aren't used.
 883  */
 884 #define FDT_MAX_NCELLS          4
 885
 886 /**
 887  * fdt_address_cells - retrieve address size for a bus represented in the tree
 888  * @fdt: pointer to the device tree blob
 889  * @nodeoffset: offset of the node to find the address size for
 890  *
 891  * When the node has a valid #address-cells property, returns its value.
 892  *
 893  * returns:
 894  *      0 <= n < FDT_MAX_NCELLS, on success
 895  *      2, if the node has no #address-cells property
 896  *      -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid #address-cells property
 897  *      -FDT_ERR_BADMAGIC,
 898  *      -FDT_ERR_BADVERSION,
 899  *      -FDT_ERR_BADSTATE,
 900  *      -FDT_ERR_BADSTRUCTURE,
 901  *      -FDT_ERR_TRUNCATED, standard meanings
 902  */
 903 int fdt_address_cells(const void *fdt, int nodeoffset);
 904
 905 /**
 906  * fdt_size_cells - retrieve address range size for a bus represented in the
 907  *                  tree
 908  * @fdt: pointer to the device tree blob
 909  * @nodeoffset: offset of the node to find the address range size for
 910  *
 911  * When the node has a valid #size-cells property, returns its value.
 912  *
 913  * returns:
 914  *      0 <= n < FDT_MAX_NCELLS, on success
 915  *      2, if the node has no #address-cells property
 916  *      -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid #size-cells property
 917  *      -FDT_ERR_BADMAGIC,
 918  *      -FDT_ERR_BADVERSION,
 919  *      -FDT_ERR_BADSTATE,
 920  *      -FDT_ERR_BADSTRUCTURE,
 921  *      -FDT_ERR_TRUNCATED, standard meanings
 922  */
 923 int fdt_size_cells(const void *fdt, int nodeoffset);
 924
 925
 926 /**********************************************************************/
 927 /* Write-in-place functions                                           */
 928 /**********************************************************************/
 929
 930 /**
 931  * fdt_setprop_inplace - change a property's value, but not its size
 932  * @fdt: pointer to the device tree blob
 933  * @nodeoffset: offset of the node whose property to change
 934  * @name: name of the property to change
 935  * @val: pointer to data to replace the property value with
 936  * @len: length of the property value
 937  *
 938  * fdt_setprop_inplace() replaces the value of a given property with
 939  * the data in val, of length len.  This function cannot change the
 940  * size of a property, and so will only work if len is equal to the
 941  * current length of the property.
 942  *
 943  * This function will alter only the bytes in the blob which contain
 944  * the given property value, and will not alter or move any other part
 945  * of the tree.
 946  *
 947  * returns:
 948  *      0, on success
 949  *      -FDT_ERR_NOSPACE, if len is not equal to the property's current length
 950  *      -FDT_ERR_NOTFOUND, node does not have the named property
 951  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
 952  *      -FDT_ERR_BADMAGIC,
 953  *      -FDT_ERR_BADVERSION,
 954  *      -FDT_ERR_BADSTATE,
 955  *      -FDT_ERR_BADSTRUCTURE,
 956  *      -FDT_ERR_TRUNCATED, standard meanings
 957  */
 958 int fdt_setprop_inplace(void *fdt, int nodeoffset, const char *name,
 959                         const void *val, int len);
 960
 961 /**
 962  * fdt_setprop_inplace_u32 - change the value of a 32-bit integer property
 963  * @fdt: pointer to the device tree blob
 964  * @nodeoffset: offset of the node whose property to change
 965  * @name: name of the property to change
 966  * @val: 32-bit integer value to replace the property with
 967  *
 968  * fdt_setprop_inplace_u32() replaces the value of a given property
 969  * with the 32-bit integer value in val, converting val to big-endian
 970  * if necessary.  This function cannot change the size of a property,
 971  * and so will only work if the property already exists and has length
 972  * 4.
 973  *
 974  * This function will alter only the bytes in the blob which contain
 975  * the given property value, and will not alter or move any other part
 976  * of the tree.
 977  *
 978  * returns:
 979  *      0, on success
 980  *      -FDT_ERR_NOSPACE, if the property's length is not equal to 4
 981  *      -FDT_ERR_NOTFOUND, node does not have the named property
 982  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
 983  *      -FDT_ERR_BADMAGIC,
 984  *      -FDT_ERR_BADVERSION,
 985  *      -FDT_ERR_BADSTATE,
 986  *      -FDT_ERR_BADSTRUCTURE,
 987  *      -FDT_ERR_TRUNCATED, standard meanings
 988  */
 989 static inline int fdt_setprop_inplace_u32(void *fdt, int nodeoffset,
 990                                           const char *name, uint32_t val)
 991 {
 992         fdt32_t tmp = cpu_to_fdt32(val);
 993         return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
 994 }
 995
 996 /**
 997  * fdt_setprop_inplace_u64 - change the value of a 64-bit integer property
 998  * @fdt: pointer to the device tree blob
 999  * @nodeoffset: offset of the node whose property to change
1000  * @name: name of the property to change
1001  * @val: 64-bit integer value to replace the property with
1002  *
1003  * fdt_setprop_inplace_u64() replaces the value of a given property
1004  * with the 64-bit integer value in val, converting val to big-endian
1005  * if necessary.  This function cannot change the size of a property,
1006  * and so will only work if the property already exists and has length
1007  * 8.
1008  *
1009  * This function will alter only the bytes in the blob which contain
1010  * the given property value, and will not alter or move any other part
1011  * of the tree.
1012  *
1013  * returns:
1014  *      0, on success
1015  *      -FDT_ERR_NOSPACE, if the property's length is not equal to 8
1016  *      -FDT_ERR_NOTFOUND, node does not have the named property
1017  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1018  *      -FDT_ERR_BADMAGIC,
1019  *      -FDT_ERR_BADVERSION,
1020  *      -FDT_ERR_BADSTATE,
1021  *      -FDT_ERR_BADSTRUCTURE,
1022  *      -FDT_ERR_TRUNCATED, standard meanings
1023  */
1024 static inline int fdt_setprop_inplace_u64(void *fdt, int nodeoffset,
1025                                           const char *name, uint64_t val)
1026 {
1027         fdt64_t tmp = cpu_to_fdt64(val);
1028         return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
1029 }
1030
1031 /**
1032  * fdt_setprop_inplace_cell - change the value of a single-cell property
1033  *
1034  * This is an alternative name for fdt_setprop_inplace_u32()
1035  */
1036 static inline int fdt_setprop_inplace_cell(void *fdt, int nodeoffset,
1037                                            const char *name, uint32_t val)
1038 {
1039         return fdt_setprop_inplace_u32(fdt, nodeoffset, name, val);
1040 }
1041
1042 /**
1043  * fdt_nop_property - replace a property with nop tags
1044  * @fdt: pointer to the device tree blob
1045  * @nodeoffset: offset of the node whose property to nop
1046  * @name: name of the property to nop
1047  *
1048  * fdt_nop_property() will replace a given property's representation
1049  * in the blob with FDT_NOP tags, effectively removing it from the
1050  * tree.
1051  *
1052  * This function will alter only the bytes in the blob which contain
1053  * the property, and will not alter or move any other part of the
1054  * tree.
1055  *
1056  * returns:
1057  *      0, on success
1058  *      -FDT_ERR_NOTFOUND, node does not have the named property
1059  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1060  *      -FDT_ERR_BADMAGIC,
1061  *      -FDT_ERR_BADVERSION,
1062  *      -FDT_ERR_BADSTATE,
1063  *      -FDT_ERR_BADSTRUCTURE,
1064  *      -FDT_ERR_TRUNCATED, standard meanings
1065  */
1066 int fdt_nop_property(void *fdt, int nodeoffset, const char *name);
1067
1068 /**
1069  * fdt_nop_node - replace a node (subtree) with nop tags
1070  * @fdt: pointer to the device tree blob
1071  * @nodeoffset: offset of the node to nop
1072  *
1073  * fdt_nop_node() will replace a given node's representation in the
1074  * blob, including all its subnodes, if any, with FDT_NOP tags,
1075  * effectively removing it from the tree.
1076  *
1077  * This function will alter only the bytes in the blob which contain
1078  * the node and its properties and subnodes, and will not alter or
1079  * move any other part of the tree.
1080  *
1081  * returns:
1082  *      0, on success
1083  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1084  *      -FDT_ERR_BADMAGIC,
1085  *      -FDT_ERR_BADVERSION,
1086  *      -FDT_ERR_BADSTATE,
1087  *      -FDT_ERR_BADSTRUCTURE,
1088  *      -FDT_ERR_TRUNCATED, standard meanings
1089  */
1090 int fdt_nop_node(void *fdt, int nodeoffset);
1091
1092 /**********************************************************************/
1093 /* Sequential write functions                                         */
1094 /**********************************************************************/
1095
1096 int fdt_create(void *buf, int bufsize);
1097 int fdt_resize(void *fdt, void *buf, int bufsize);
1098 int fdt_add_reservemap_entry(void *fdt, uint64_t addr, uint64_t size);
1099 int fdt_finish_reservemap(void *fdt);
1100 int fdt_begin_node(void *fdt, const char *name);
1101 int fdt_property(void *fdt, const char *name, const void *val, int len);
1102 static inline int fdt_property_u32(void *fdt, const char *name, uint32_t val)
1103 {
1104         fdt32_t tmp = cpu_to_fdt32(val);
1105         return fdt_property(fdt, name, &tmp, sizeof(tmp));
1106 }
1107 static inline int fdt_property_u64(void *fdt, const char *name, uint64_t val)
1108 {
1109         fdt64_t tmp = cpu_to_fdt64(val);
1110         return fdt_property(fdt, name, &tmp, sizeof(tmp));
1111 }
1112 static inline int fdt_property_cell(void *fdt, const char *name, uint32_t val)
1113 {
1114         return fdt_property_u32(fdt, name, val);
1115 }
1116 #define fdt_property_string(fdt, name, str) \
1117         fdt_property(fdt, name, str, strlen(str)+1)
1118 int fdt_end_node(void *fdt);
1119 int fdt_finish(void *fdt);
1120
1121 /**********************************************************************/
1122 /* Read-write functions                                               */
1123 /**********************************************************************/
1124
1125 int fdt_create_empty_tree(void *buf, int bufsize);
1126 int fdt_open_into(const void *fdt, void *buf, int bufsize);
1127 int fdt_pack(void *fdt);
1128
1129 /**
1130  * fdt_add_mem_rsv - add one memory reserve map entry
1131  * @fdt: pointer to the device tree blob
1132  * @address, @size: 64-bit values (native endian)
1133  *
1134  * Adds a reserve map entry to the given blob reserving a region at
1135  * address address of length size.
1136  *
1137  * This function will insert data into the reserve map and will
1138  * therefore change the indexes of some entries in the table.
1139  *
1140  * returns:
1141  *      0, on success
1142  *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1143  *              contain the new reservation entry
1144  *      -FDT_ERR_BADMAGIC,
1145  *      -FDT_ERR_BADVERSION,
1146  *      -FDT_ERR_BADSTATE,
1147  *      -FDT_ERR_BADSTRUCTURE,
1148  *      -FDT_ERR_BADLAYOUT,
1149  *      -FDT_ERR_TRUNCATED, standard meanings
1150  */
1151 int fdt_add_mem_rsv(void *fdt, uint64_t address, uint64_t size);
1152
1153 /**
1154  * fdt_del_mem_rsv - remove a memory reserve map entry
1155  * @fdt: pointer to the device tree blob
1156  * @n: entry to remove
1157  *
1158  * fdt_del_mem_rsv() removes the n-th memory reserve map entry from
1159  * the blob.
1160  *
1161  * This function will delete data from the reservation table and will
1162  * therefore change the indexes of some entries in the table.
1163  *
1164  * returns:
1165  *      0, on success
1166  *      -FDT_ERR_NOTFOUND, there is no entry of the given index (i.e. there
1167  *              are less than n+1 reserve map entries)
1168  *      -FDT_ERR_BADMAGIC,
1169  *      -FDT_ERR_BADVERSION,
1170  *      -FDT_ERR_BADSTATE,
1171  *      -FDT_ERR_BADSTRUCTURE,
1172  *      -FDT_ERR_BADLAYOUT,
1173  *      -FDT_ERR_TRUNCATED, standard meanings
1174  */
1175 int fdt_del_mem_rsv(void *fdt, int n);
1176
1177 /**
1178  * fdt_set_name - change the name of a given node
1179  * @fdt: pointer to the device tree blob
1180  * @nodeoffset: structure block offset of a node
1181  * @name: name to give the node
1182  *
1183  * fdt_set_name() replaces the name (including unit address, if any)
1184  * of the given node with the given string.  NOTE: this function can't
1185  * efficiently check if the new name is unique amongst the given
1186  * node's siblings; results are undefined if this function is invoked
1187  * with a name equal to one of the given node's siblings.
1188  *
1189  * This function may insert or delete data from the blob, and will
1190  * therefore change the offsets of some existing nodes.
1191  *
1192  * returns:
1193  *      0, on success
1194  *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob
1195  *              to contain the new name
1196  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1197  *      -FDT_ERR_BADMAGIC,
1198  *      -FDT_ERR_BADVERSION,
1199  *      -FDT_ERR_BADSTATE, standard meanings
1200  */
1201 int fdt_set_name(void *fdt, int nodeoffset, const char *name);
1202
1203 /**
1204  * fdt_setprop - create or change a property
1205  * @fdt: pointer to the device tree blob
1206  * @nodeoffset: offset of the node whose property to change
1207  * @name: name of the property to change
1208  * @val: pointer to data to set the property value to
1209  * @len: length of the property value
1210  *
1211  * fdt_setprop() sets the value of the named property in the given
1212  * node to the given value and length, creating the property if it
1213  * does not already exist.
1214  *
1215  * This function may insert or delete data from the blob, and will
1216  * therefore change the offsets of some existing nodes.
1217  *
1218  * returns:
1219  *      0, on success
1220  *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1221  *              contain the new property value
1222  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1223  *      -FDT_ERR_BADLAYOUT,
1224  *      -FDT_ERR_BADMAGIC,
1225  *      -FDT_ERR_BADVERSION,
1226  *      -FDT_ERR_BADSTATE,
1227  *      -FDT_ERR_BADSTRUCTURE,
1228  *      -FDT_ERR_BADLAYOUT,
1229  *      -FDT_ERR_TRUNCATED, standard meanings
1230  */
1231 int fdt_setprop(void *fdt, int nodeoffset, const char *name,
1232                 const void *val, int len);
1233
1234 /**
1235  * fdt_setprop_u32 - set a property to a 32-bit integer
1236  * @fdt: pointer to the device tree blob
1237  * @nodeoffset: offset of the node whose property to change
1238  * @name: name of the property to change
1239  * @val: 32-bit integer value for the property (native endian)
1240  *
1241  * fdt_setprop_u32() sets the value of the named property in the given
1242  * node to the given 32-bit integer value (converting to big-endian if
1243  * necessary), or creates a new property with that value if it does
1244  * not already exist.
1245  *
1246  * This function may insert or delete data from the blob, and will
1247  * therefore change the offsets of some existing nodes.
1248  *
1249  * returns:
1250  *      0, on success
1251  *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1252  *              contain the new property value
1253  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1254  *      -FDT_ERR_BADLAYOUT,
1255  *      -FDT_ERR_BADMAGIC,
1256  *      -FDT_ERR_BADVERSION,
1257  *      -FDT_ERR_BADSTATE,
1258  *      -FDT_ERR_BADSTRUCTURE,
1259  *      -FDT_ERR_BADLAYOUT,
1260  *      -FDT_ERR_TRUNCATED, standard meanings
1261  */
1262 static inline int fdt_setprop_u32(void *fdt, int nodeoffset, const char *name,
1263                                   uint32_t val)
1264 {
1265         fdt32_t tmp = cpu_to_fdt32(val);
1266         return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
1267 }
1268
1269 /**
1270  * fdt_setprop_u64 - set a property to a 64-bit integer
1271  * @fdt: pointer to the device tree blob
1272  * @nodeoffset: offset of the node whose property to change
1273  * @name: name of the property to change
1274  * @val: 64-bit integer value for the property (native endian)
1275  *
1276  * fdt_setprop_u64() sets the value of the named property in the given
1277  * node to the given 64-bit integer value (converting to big-endian if
1278  * necessary), or creates a new property with that value if it does
1279  * not already exist.
1280  *
1281  * This function may insert or delete data from the blob, and will
1282  * therefore change the offsets of some existing nodes.
1283  *
1284  * returns:
1285  *      0, on success
1286  *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1287  *              contain the new property value
1288  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1289  *      -FDT_ERR_BADLAYOUT,
1290  *      -FDT_ERR_BADMAGIC,
1291  *      -FDT_ERR_BADVERSION,
1292  *      -FDT_ERR_BADSTATE,
1293  *      -FDT_ERR_BADSTRUCTURE,
1294  *      -FDT_ERR_BADLAYOUT,
1295  *      -FDT_ERR_TRUNCATED, standard meanings
1296  */
1297 static inline int fdt_setprop_u64(void *fdt, int nodeoffset, const char *name,
1298                                   uint64_t val)
1299 {
1300         fdt64_t tmp = cpu_to_fdt64(val);
1301         return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
1302 }
1303
1304 /**
1305  * fdt_setprop_cell - set a property to a single cell value
1306  *
1307  * This is an alternative name for fdt_setprop_u32()
1308  */
1309 static inline int fdt_setprop_cell(void *fdt, int nodeoffset, const char *name,
1310                                    uint32_t val)
1311 {
1312         return fdt_setprop_u32(fdt, nodeoffset, name, val);
1313 }
1314
1315 /**
1316  * fdt_setprop_string - set a property to a string value
1317  * @fdt: pointer to the device tree blob
1318  * @nodeoffset: offset of the node whose property to change
1319  * @name: name of the property to change
1320  * @str: string value for the property
1321  *
1322  * fdt_setprop_string() sets the value of the named property in the
1323  * given node to the given string value (using the length of the
1324  * string to determine the new length of the property), or creates a
1325  * new property with that value if it does not already exist.
1326  *
1327  * This function may insert or delete data from the blob, and will
1328  * therefore change the offsets of some existing nodes.
1329  *
1330  * returns:
1331  *      0, on success
1332  *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1333  *              contain the new property value
1334  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1335  *      -FDT_ERR_BADLAYOUT,
1336  *      -FDT_ERR_BADMAGIC,
1337  *      -FDT_ERR_BADVERSION,
1338  *      -FDT_ERR_BADSTATE,
1339  *      -FDT_ERR_BADSTRUCTURE,
1340  *      -FDT_ERR_BADLAYOUT,
1341  *      -FDT_ERR_TRUNCATED, standard meanings
1342  */
1343 #define fdt_setprop_string(fdt, nodeoffset, name, str) \
1344         fdt_setprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)
1345
1346 /**
1347  * fdt_appendprop - append to or create a property
1348  * @fdt: pointer to the device tree blob
1349  * @nodeoffset: offset of the node whose property to change
1350  * @name: name of the property to append to
1351  * @val: pointer to data to append to the property value
1352  * @len: length of the data to append to the property value
1353  *
1354  * fdt_appendprop() appends the value to the named property in the
1355  * given node, creating the property if it does not already exist.
1356  *
1357  * This function may insert data into the blob, and will therefore
1358  * change the offsets of some existing nodes.
1359  *
1360  * returns:
1361  *      0, on success
1362  *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1363  *              contain the new property value
1364  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1365  *      -FDT_ERR_BADLAYOUT,
1366  *      -FDT_ERR_BADMAGIC,
1367  *      -FDT_ERR_BADVERSION,
1368  *      -FDT_ERR_BADSTATE,
1369  *      -FDT_ERR_BADSTRUCTURE,
1370  *      -FDT_ERR_BADLAYOUT,
1371  *      -FDT_ERR_TRUNCATED, standard meanings
1372  */
1373 int fdt_appendprop(void *fdt, int nodeoffset, const char *name,
1374                    const void *val, int len);
1375
1376 /**
1377  * fdt_appendprop_u32 - append a 32-bit integer value to a property
1378  * @fdt: pointer to the device tree blob
1379  * @nodeoffset: offset of the node whose property to change
1380  * @name: name of the property to change
1381  * @val: 32-bit integer value to append to the property (native endian)
1382  *
1383  * fdt_appendprop_u32() appends the given 32-bit integer value
1384  * (converting to big-endian if necessary) to the value of the named
1385  * property in the given node, or creates a new property with that
1386  * value if it does not already exist.
1387  *
1388  * This function may insert data into the blob, and will therefore
1389  * change the offsets of some existing nodes.
1390  *
1391  * returns:
1392  *      0, on success
1393  *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1394  *              contain the new property value
1395  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1396  *      -FDT_ERR_BADLAYOUT,
1397  *      -FDT_ERR_BADMAGIC,
1398  *      -FDT_ERR_BADVERSION,
1399  *      -FDT_ERR_BADSTATE,
1400  *      -FDT_ERR_BADSTRUCTURE,
1401  *      -FDT_ERR_BADLAYOUT,
1402  *      -FDT_ERR_TRUNCATED, standard meanings
1403  */
1404 static inline int fdt_appendprop_u32(void *fdt, int nodeoffset,
1405                                      const char *name, uint32_t val)
1406 {
1407         fdt32_t tmp = cpu_to_fdt32(val);
1408         return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
1409 }
1410
1411 /**
1412  * fdt_appendprop_u64 - append a 64-bit integer value to a property
1413  * @fdt: pointer to the device tree blob
1414  * @nodeoffset: offset of the node whose property to change
1415  * @name: name of the property to change
1416  * @val: 64-bit integer value to append to the property (native endian)
1417  *
1418  * fdt_appendprop_u64() appends the given 64-bit integer value
1419  * (converting to big-endian if necessary) to the value of the named
1420  * property in the given node, or creates a new property with that
1421  * value if it does not already exist.
1422  *
1423  * This function may insert data into the blob, and will therefore
1424  * change the offsets of some existing nodes.
1425  *
1426  * returns:
1427  *      0, on success
1428  *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1429  *              contain the new property value
1430  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1431  *      -FDT_ERR_BADLAYOUT,
1432  *      -FDT_ERR_BADMAGIC,
1433  *      -FDT_ERR_BADVERSION,
1434  *      -FDT_ERR_BADSTATE,
1435  *      -FDT_ERR_BADSTRUCTURE,
1436  *      -FDT_ERR_BADLAYOUT,
1437  *      -FDT_ERR_TRUNCATED, standard meanings
1438  */
1439 static inline int fdt_appendprop_u64(void *fdt, int nodeoffset,
1440                                      const char *name, uint64_t val)
1441 {
1442         fdt64_t tmp = cpu_to_fdt64(val);
1443         return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
1444 }
1445
1446 /**
1447  * fdt_appendprop_cell - append a single cell value to a property
1448  *
1449  * This is an alternative name for fdt_appendprop_u32()
1450  */
1451 static inline int fdt_appendprop_cell(void *fdt, int nodeoffset,
1452                                       const char *name, uint32_t val)
1453 {
1454         return fdt_appendprop_u32(fdt, nodeoffset, name, val);
1455 }
1456
1457 /**
1458  * fdt_appendprop_string - append a string to a property
1459  * @fdt: pointer to the device tree blob
1460  * @nodeoffset: offset of the node whose property to change
1461  * @name: name of the property to change
1462  * @str: string value to append to the property
1463  *
1464  * fdt_appendprop_string() appends the given string to the value of
1465  * the named property in the given node, or creates a new property
1466  * with that value if it does not already exist.
1467  *
1468  * This function may insert data into the blob, and will therefore
1469  * change the offsets of some existing nodes.
1470  *
1471  * returns:
1472  *      0, on success
1473  *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1474  *              contain the new property value
1475  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1476  *      -FDT_ERR_BADLAYOUT,
1477  *      -FDT_ERR_BADMAGIC,
1478  *      -FDT_ERR_BADVERSION,
1479  *      -FDT_ERR_BADSTATE,
1480  *      -FDT_ERR_BADSTRUCTURE,
1481  *      -FDT_ERR_BADLAYOUT,
1482  *      -FDT_ERR_TRUNCATED, standard meanings
1483  */
1484 #define fdt_appendprop_string(fdt, nodeoffset, name, str) \
1485         fdt_appendprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)
1486
1487 /**
1488  * fdt_delprop - delete a property
1489  * @fdt: pointer to the device tree blob
1490  * @nodeoffset: offset of the node whose property to nop
1491  * @name: name of the property to nop
1492  *
1493  * fdt_del_property() will delete the given property.
1494  *
1495  * This function will delete data from the blob, and will therefore
1496  * change the offsets of some existing nodes.
1497  *
1498  * returns:
1499  *      0, on success
1500  *      -FDT_ERR_NOTFOUND, node does not have the named property
1501  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1502  *      -FDT_ERR_BADLAYOUT,
1503  *      -FDT_ERR_BADMAGIC,
1504  *      -FDT_ERR_BADVERSION,
1505  *      -FDT_ERR_BADSTATE,
1506  *      -FDT_ERR_BADSTRUCTURE,
1507  *      -FDT_ERR_TRUNCATED, standard meanings
1508  */
1509 int fdt_delprop(void *fdt, int nodeoffset, const char *name);
1510
1511 /**
1512  * fdt_add_subnode_namelen - creates a new node based on substring
1513  * @fdt: pointer to the device tree blob
1514  * @parentoffset: structure block offset of a node
1515  * @name: name of the subnode to locate
1516  * @namelen: number of characters of name to consider
1517  *
1518  * Identical to fdt_add_subnode(), but use only the first namelen
1519  * characters of name as the name of the new node.  This is useful for
1520  * creating subnodes based on a portion of a larger string, such as a
1521  * full path.
1522  */
1523 int fdt_add_subnode_namelen(void *fdt, int parentoffset,
1524                             const char *name, int namelen);
1525
1526 /**
1527  * fdt_add_subnode - creates a new node
1528  * @fdt: pointer to the device tree blob
1529  * @parentoffset: structure block offset of a node
1530  * @name: name of the subnode to locate
1531  *
1532  * fdt_add_subnode() creates a new node as a subnode of the node at
1533  * structure block offset parentoffset, with the given name (which
1534  * should include the unit address, if any).
1535  *
1536  * This function will insert data into the blob, and will therefore
1537  * change the offsets of some existing nodes.
1538
1539  * returns:
1540  *      structure block offset of the created nodeequested subnode (>=0), on success
1541  *      -FDT_ERR_NOTFOUND, if the requested subnode does not exist
1542  *      -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE tag
1543  *      -FDT_ERR_EXISTS, if the node at parentoffset already has a subnode of
1544  *              the given name
1545  *      -FDT_ERR_NOSPACE, if there is insufficient free space in the
1546  *              blob to contain the new node
1547  *      -FDT_ERR_NOSPACE
1548  *      -FDT_ERR_BADLAYOUT
1549  *      -FDT_ERR_BADMAGIC,
1550  *      -FDT_ERR_BADVERSION,
1551  *      -FDT_ERR_BADSTATE,
1552  *      -FDT_ERR_BADSTRUCTURE,
1553  *      -FDT_ERR_TRUNCATED, standard meanings.
1554  */
1555 int fdt_add_subnode(void *fdt, int parentoffset, const char *name);
1556
1557 /**
1558  * fdt_del_node - delete a node (subtree)
1559  * @fdt: pointer to the device tree blob
1560  * @nodeoffset: offset of the node to nop
1561  *
1562  * fdt_del_node() will remove the given node, including all its
1563  * subnodes if any, from the blob.
1564  *
1565  * This function will delete data from the blob, and will therefore
1566  * change the offsets of some existing nodes.
1567  *
1568  * returns:
1569  *      0, on success
1570  *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1571  *      -FDT_ERR_BADLAYOUT,
1572  *      -FDT_ERR_BADMAGIC,
1573  *      -FDT_ERR_BADVERSION,
1574  *      -FDT_ERR_BADSTATE,
1575  *      -FDT_ERR_BADSTRUCTURE,
1576  *      -FDT_ERR_TRUNCATED, standard meanings
1577  */
1578 int fdt_del_node(void *fdt, int nodeoffset);
1579
1580 /**********************************************************************/
1581 /* Debugging / informational functions                                */
1582 /**********************************************************************/
1583
1584 const char *fdt_strerror(int errval);
1585
1586 #endif /* _LIBFDT_H */