source: rtems/cpukit/include/libfdt.h @ 78ad048

5
Last change on this file since 78ad048 was 78ad048, checked in by David Gibson <david@…>, on Jun 21, 2018 at 5:32:40 AM

libfdt: Add helpers for accessing unaligned words

This adds some helpers to load (32 or 64 bit) words from an fdt blob, even
if they're unaligned and we're on a platform that doesn't like plain
unaligned loads and stores. We then use the helpers in a number of places.
There are two purposes for this:

1) This makes libfdt more robust against a blob loaded at an unaligned

address. It's usually good practice to load a blob at a 64-bit
alignment, but it's nice to work even then.

2) Users can use these helpers to load integer values from within property

values. These can often be unaligned, even if the blob as a whole is
aligned, since some property encodings have integers and strings mixed
together without any alignment gaps.

Signed-off-by: David Gibson <david@…>

  • Property mode set to 100644
File size: 69.3 KB
Line 
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     0x02
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: Attempted 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         * This can be caused either by an invalid phandle property
84         * length, or the phandle value was either 0 or -1, which are
85         * not permitted. */
86#define FDT_ERR_BADSTATE        7
87        /* FDT_ERR_BADSTATE: Function was passed an incomplete device
88         * tree created by the sequential-write functions, which is
89         * not sufficiently complete for the requested operation. */
90
91/* Error codes: codes for bad device tree blobs */
92#define FDT_ERR_TRUNCATED       8
93        /* FDT_ERR_TRUNCATED: FDT or a sub-block is improperly
94         * terminated (overflows, goes outside allowed bounds, or
95         * isn't properly terminated).  */
96#define FDT_ERR_BADMAGIC        9
97        /* FDT_ERR_BADMAGIC: Given "device tree" appears not to be a
98         * device tree at all - it is missing the flattened device
99         * tree magic number. */
100#define FDT_ERR_BADVERSION      10
101        /* FDT_ERR_BADVERSION: Given device tree has a version which
102         * can't be handled by the requested operation.  For
103         * read-write functions, this may mean that fdt_open_into() is
104         * required to convert the tree to the expected version. */
105#define FDT_ERR_BADSTRUCTURE    11
106        /* FDT_ERR_BADSTRUCTURE: Given device tree has a corrupt
107         * structure block or other serious error (e.g. misnested
108         * nodes, or subnodes preceding properties). */
109#define FDT_ERR_BADLAYOUT       12
110        /* FDT_ERR_BADLAYOUT: For read-write functions, the given
111         * device tree has it's sub-blocks in an order that the
112         * function can't handle (memory reserve map, then structure,
113         * then strings).  Use fdt_open_into() to reorganize the tree
114         * into a form suitable for the read-write operations. */
115
116/* "Can't happen" error indicating a bug in libfdt */
117#define FDT_ERR_INTERNAL        13
118        /* FDT_ERR_INTERNAL: libfdt has failed an internal assertion.
119         * Should never be returned, if it is, it indicates a bug in
120         * libfdt itself. */
121
122/* Errors in device tree content */
123#define FDT_ERR_BADNCELLS       14
124        /* FDT_ERR_BADNCELLS: Device tree has a #address-cells, #size-cells
125         * or similar property with a bad format or value */
126
127#define FDT_ERR_BADVALUE        15
128        /* FDT_ERR_BADVALUE: Device tree has a property with an unexpected
129         * value. For example: a property expected to contain a string list
130         * is not NUL-terminated within the length of its value. */
131
132#define FDT_ERR_BADOVERLAY      16
133        /* FDT_ERR_BADOVERLAY: The device tree overlay, while
134         * correctly structured, cannot be applied due to some
135         * unexpected or missing value, property or node. */
136
137#define FDT_ERR_NOPHANDLES      17
138        /* FDT_ERR_NOPHANDLES: The device tree doesn't have any
139         * phandle available anymore without causing an overflow */
140
141#define FDT_ERR_MAX             17
142
143/**********************************************************************/
144/* Low-level functions (you probably don't need these)                */
145/**********************************************************************/
146
147#ifndef SWIG /* This function is not useful in Python */
148const void *fdt_offset_ptr(const void *fdt, int offset, unsigned int checklen);
149#endif
150static inline void *fdt_offset_ptr_w(void *fdt, int offset, int checklen)
151{
152        return (void *)(uintptr_t)fdt_offset_ptr(fdt, offset, checklen);
153}
154
155uint32_t fdt_next_tag(const void *fdt, int offset, int *nextoffset);
156
157/*
158 * Alignment helpers:
159 *     These helpers access words from a device tree blob.  They're
160 *     built to work even with unaligned pointers on platforms (ike
161 *     ARM) that don't like unaligned loads and stores
162 */
163
164static inline uint32_t fdt32_ld(const fdt32_t *p)
165{
166        fdt32_t v;
167
168        memcpy(&v, p, sizeof(v));
169        return fdt32_to_cpu(v);
170}
171
172static inline uint64_t fdt64_ld(const fdt64_t *p)
173{
174        fdt64_t v;
175
176        memcpy(&v, p, sizeof(v));
177        return fdt64_to_cpu(v);
178}
179
180/**********************************************************************/
181/* Traversal functions                                                */
182/**********************************************************************/
183
184int fdt_next_node(const void *fdt, int offset, int *depth);
185
186/**
187 * fdt_first_subnode() - get offset of first direct subnode
188 *
189 * @fdt:        FDT blob
190 * @offset:     Offset of node to check
191 * @return offset of first subnode, or -FDT_ERR_NOTFOUND if there is none
192 */
193int fdt_first_subnode(const void *fdt, int offset);
194
195/**
196 * fdt_next_subnode() - get offset of next direct subnode
197 *
198 * After first calling fdt_first_subnode(), call this function repeatedly to
199 * get direct subnodes of a parent node.
200 *
201 * @fdt:        FDT blob
202 * @offset:     Offset of previous subnode
203 * @return offset of next subnode, or -FDT_ERR_NOTFOUND if there are no more
204 * subnodes
205 */
206int fdt_next_subnode(const void *fdt, int offset);
207
208/**
209 * fdt_for_each_subnode - iterate over all subnodes of a parent
210 *
211 * @node:       child node (int, lvalue)
212 * @fdt:        FDT blob (const void *)
213 * @parent:     parent node (int)
214 *
215 * This is actually a wrapper around a for loop and would be used like so:
216 *
217 *      fdt_for_each_subnode(node, fdt, parent) {
218 *              Use node
219 *              ...
220 *      }
221 *
222 *      if ((node < 0) && (node != -FDT_ERR_NOT_FOUND)) {
223 *              Error handling
224 *      }
225 *
226 * Note that this is implemented as a macro and @node is used as
227 * iterator in the loop. The parent variable be constant or even a
228 * literal.
229 *
230 */
231#define fdt_for_each_subnode(node, fdt, parent)         \
232        for (node = fdt_first_subnode(fdt, parent);     \
233             node >= 0;                                 \
234             node = fdt_next_subnode(fdt, node))
235
236/**********************************************************************/
237/* General functions                                                  */
238/**********************************************************************/
239#define fdt_get_header(fdt, field) \
240        (fdt32_ld(&((const struct fdt_header *)(fdt))->field))
241#define fdt_magic(fdt)                  (fdt_get_header(fdt, magic))
242#define fdt_totalsize(fdt)              (fdt_get_header(fdt, totalsize))
243#define fdt_off_dt_struct(fdt)          (fdt_get_header(fdt, off_dt_struct))
244#define fdt_off_dt_strings(fdt)         (fdt_get_header(fdt, off_dt_strings))
245#define fdt_off_mem_rsvmap(fdt)         (fdt_get_header(fdt, off_mem_rsvmap))
246#define fdt_version(fdt)                (fdt_get_header(fdt, version))
247#define fdt_last_comp_version(fdt)      (fdt_get_header(fdt, last_comp_version))
248#define fdt_boot_cpuid_phys(fdt)        (fdt_get_header(fdt, boot_cpuid_phys))
249#define fdt_size_dt_strings(fdt)        (fdt_get_header(fdt, size_dt_strings))
250#define fdt_size_dt_struct(fdt)         (fdt_get_header(fdt, size_dt_struct))
251
252#define fdt_set_hdr_(name) \
253        static inline void fdt_set_##name(void *fdt, uint32_t val) \
254        { \
255                struct fdt_header *fdth = (struct fdt_header *)fdt; \
256                fdth->name = cpu_to_fdt32(val); \
257        }
258fdt_set_hdr_(magic);
259fdt_set_hdr_(totalsize);
260fdt_set_hdr_(off_dt_struct);
261fdt_set_hdr_(off_dt_strings);
262fdt_set_hdr_(off_mem_rsvmap);
263fdt_set_hdr_(version);
264fdt_set_hdr_(last_comp_version);
265fdt_set_hdr_(boot_cpuid_phys);
266fdt_set_hdr_(size_dt_strings);
267fdt_set_hdr_(size_dt_struct);
268#undef fdt_set_hdr_
269
270/**
271 * fdt_header_size - return the size of the tree's header
272 * @fdt: pointer to a flattened device tree
273 */
274size_t fdt_header_size_(uint32_t version);
275static inline size_t fdt_header_size(const void *fdt)
276{
277        return fdt_header_size_(fdt_version(fdt));
278}
279
280/**
281 * fdt_check_header - sanity check a device tree header
282
283 * @fdt: pointer to data which might be a flattened device tree
284 *
285 * fdt_check_header() checks that the given buffer contains what
286 * appears to be a flattened device tree, and that the header contains
287 * valid information (to the extent that can be determined from the
288 * header alone).
289 *
290 * returns:
291 *     0, if the buffer appears to contain a valid device tree
292 *     -FDT_ERR_BADMAGIC,
293 *     -FDT_ERR_BADVERSION,
294 *     -FDT_ERR_BADSTATE,
295 *     -FDT_ERR_TRUNCATED, standard meanings, as above
296 */
297int fdt_check_header(const void *fdt);
298
299/**
300 * fdt_move - move a device tree around in memory
301 * @fdt: pointer to the device tree to move
302 * @buf: pointer to memory where the device is to be moved
303 * @bufsize: size of the memory space at buf
304 *
305 * fdt_move() relocates, if possible, the device tree blob located at
306 * fdt to the buffer at buf of size bufsize.  The buffer may overlap
307 * with the existing device tree blob at fdt.  Therefore,
308 *     fdt_move(fdt, fdt, fdt_totalsize(fdt))
309 * should always succeed.
310 *
311 * returns:
312 *     0, on success
313 *     -FDT_ERR_NOSPACE, bufsize is insufficient to contain the device tree
314 *     -FDT_ERR_BADMAGIC,
315 *     -FDT_ERR_BADVERSION,
316 *     -FDT_ERR_BADSTATE, standard meanings
317 */
318int fdt_move(const void *fdt, void *buf, int bufsize);
319
320/**********************************************************************/
321/* Read-only functions                                                */
322/**********************************************************************/
323
324int fdt_check_full(const void *fdt, size_t bufsize);
325
326/**
327 * fdt_get_string - retrieve a string from the strings block of a device tree
328 * @fdt: pointer to the device tree blob
329 * @stroffset: offset of the string within the strings block (native endian)
330 * @lenp: optional pointer to return the string's length
331 *
332 * fdt_get_string() retrieves a pointer to a single string from the
333 * strings block of the device tree blob at fdt, and optionally also
334 * returns the string's length in *lenp.
335 *
336 * returns:
337 *     a pointer to the string, on success
338 *     NULL, if stroffset is out of bounds, or doesn't point to a valid string
339 */
340const char *fdt_get_string(const void *fdt, int stroffset, int *lenp);
341
342/**
343 * fdt_string - retrieve a string from the strings block of a device tree
344 * @fdt: pointer to the device tree blob
345 * @stroffset: offset of the string within the strings block (native endian)
346 *
347 * fdt_string() retrieves a pointer to a single string from the
348 * strings block of the device tree blob at fdt.
349 *
350 * returns:
351 *     a pointer to the string, on success
352 *     NULL, if stroffset is out of bounds, or doesn't point to a valid string
353 */
354const char *fdt_string(const void *fdt, int stroffset);
355
356/**
357 * fdt_get_max_phandle - retrieves the highest phandle in a tree
358 * @fdt: pointer to the device tree blob
359 *
360 * fdt_get_max_phandle retrieves the highest phandle in the given
361 * device tree. This will ignore badly formatted phandles, or phandles
362 * with a value of 0 or -1.
363 *
364 * returns:
365 *      the highest phandle on success
366 *      0, if no phandle was found in the device tree
367 *      -1, if an error occurred
368 */
369uint32_t fdt_get_max_phandle(const void *fdt);
370
371/**
372 * fdt_num_mem_rsv - retrieve the number of memory reserve map entries
373 * @fdt: pointer to the device tree blob
374 *
375 * Returns the number of entries in the device tree blob's memory
376 * reservation map.  This does not include the terminating 0,0 entry
377 * or any other (0,0) entries reserved for expansion.
378 *
379 * returns:
380 *     the number of entries
381 */
382int fdt_num_mem_rsv(const void *fdt);
383
384/**
385 * fdt_get_mem_rsv - retrieve one memory reserve map entry
386 * @fdt: pointer to the device tree blob
387 * @address, @size: pointers to 64-bit variables
388 *
389 * On success, *address and *size will contain the address and size of
390 * the n-th reserve map entry from the device tree blob, in
391 * native-endian format.
392 *
393 * returns:
394 *     0, on success
395 *     -FDT_ERR_BADMAGIC,
396 *     -FDT_ERR_BADVERSION,
397 *     -FDT_ERR_BADSTATE, standard meanings
398 */
399int fdt_get_mem_rsv(const void *fdt, int n, uint64_t *address, uint64_t *size);
400
401/**
402 * fdt_subnode_offset_namelen - find a subnode based on substring
403 * @fdt: pointer to the device tree blob
404 * @parentoffset: structure block offset of a node
405 * @name: name of the subnode to locate
406 * @namelen: number of characters of name to consider
407 *
408 * Identical to fdt_subnode_offset(), but only examine the first
409 * namelen characters of name for matching the subnode name.  This is
410 * useful for finding subnodes based on a portion of a larger string,
411 * such as a full path.
412 */
413#ifndef SWIG /* Not available in Python */
414int fdt_subnode_offset_namelen(const void *fdt, int parentoffset,
415                               const char *name, int namelen);
416#endif
417/**
418 * fdt_subnode_offset - find a subnode of a given node
419 * @fdt: pointer to the device tree blob
420 * @parentoffset: structure block offset of a node
421 * @name: name of the subnode to locate
422 *
423 * fdt_subnode_offset() finds a subnode of the node at structure block
424 * offset parentoffset with the given name.  name may include a unit
425 * address, in which case fdt_subnode_offset() will find the subnode
426 * with that unit address, or the unit address may be omitted, in
427 * which case fdt_subnode_offset() will find an arbitrary subnode
428 * whose name excluding unit address matches the given name.
429 *
430 * returns:
431 *      structure block offset of the requested subnode (>=0), on success
432 *      -FDT_ERR_NOTFOUND, if the requested subnode does not exist
433 *      -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE
434 *              tag
435 *      -FDT_ERR_BADMAGIC,
436 *      -FDT_ERR_BADVERSION,
437 *      -FDT_ERR_BADSTATE,
438 *      -FDT_ERR_BADSTRUCTURE,
439 *      -FDT_ERR_TRUNCATED, standard meanings.
440 */
441int fdt_subnode_offset(const void *fdt, int parentoffset, const char *name);
442
443/**
444 * fdt_path_offset_namelen - find a tree node by its full path
445 * @fdt: pointer to the device tree blob
446 * @path: full path of the node to locate
447 * @namelen: number of characters of path to consider
448 *
449 * Identical to fdt_path_offset(), but only consider the first namelen
450 * characters of path as the path name.
451 */
452#ifndef SWIG /* Not available in Python */
453int fdt_path_offset_namelen(const void *fdt, const char *path, int namelen);
454#endif
455
456/**
457 * fdt_path_offset - find a tree node by its full path
458 * @fdt: pointer to the device tree blob
459 * @path: full path of the node to locate
460 *
461 * fdt_path_offset() finds a node of a given path in the device tree.
462 * Each path component may omit the unit address portion, but the
463 * results of this are undefined if any such path component is
464 * ambiguous (that is if there are multiple nodes at the relevant
465 * level matching the given component, differentiated only by unit
466 * address).
467 *
468 * returns:
469 *      structure block offset of the node with the requested path (>=0), on
470 *              success
471 *      -FDT_ERR_BADPATH, given path does not begin with '/' or is invalid
472 *      -FDT_ERR_NOTFOUND, if the requested node does not exist
473 *      -FDT_ERR_BADMAGIC,
474 *      -FDT_ERR_BADVERSION,
475 *      -FDT_ERR_BADSTATE,
476 *      -FDT_ERR_BADSTRUCTURE,
477 *      -FDT_ERR_TRUNCATED, standard meanings.
478 */
479int fdt_path_offset(const void *fdt, const char *path);
480
481/**
482 * fdt_get_name - retrieve the name of a given node
483 * @fdt: pointer to the device tree blob
484 * @nodeoffset: structure block offset of the starting node
485 * @lenp: pointer to an integer variable (will be overwritten) or NULL
486 *
487 * fdt_get_name() retrieves the name (including unit address) of the
488 * device tree node at structure block offset nodeoffset.  If lenp is
489 * non-NULL, the length of this name is also returned, in the integer
490 * pointed to by lenp.
491 *
492 * returns:
493 *      pointer to the node's name, on success
494 *              If lenp is non-NULL, *lenp contains the length of that name
495 *                      (>=0)
496 *      NULL, on error
497 *              if lenp is non-NULL *lenp contains an error code (<0):
498 *              -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE
499 *                      tag
500 *              -FDT_ERR_BADMAGIC,
501 *              -FDT_ERR_BADVERSION,
502 *              -FDT_ERR_BADSTATE, standard meanings
503 */
504const char *fdt_get_name(const void *fdt, int nodeoffset, int *lenp);
505
506/**
507 * fdt_first_property_offset - find the offset of a node's first property
508 * @fdt: pointer to the device tree blob
509 * @nodeoffset: structure block offset of a node
510 *
511 * fdt_first_property_offset() finds the first property of the node at
512 * the given structure block offset.
513 *
514 * returns:
515 *      structure block offset of the property (>=0), on success
516 *      -FDT_ERR_NOTFOUND, if the requested node has no properties
517 *      -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_BEGIN_NODE tag
518 *      -FDT_ERR_BADMAGIC,
519 *      -FDT_ERR_BADVERSION,
520 *      -FDT_ERR_BADSTATE,
521 *      -FDT_ERR_BADSTRUCTURE,
522 *      -FDT_ERR_TRUNCATED, standard meanings.
523 */
524int fdt_first_property_offset(const void *fdt, int nodeoffset);
525
526/**
527 * fdt_next_property_offset - step through a node's properties
528 * @fdt: pointer to the device tree blob
529 * @offset: structure block offset of a property
530 *
531 * fdt_next_property_offset() finds the property immediately after the
532 * one at the given structure block offset.  This will be a property
533 * of the same node as the given property.
534 *
535 * returns:
536 *      structure block offset of the next property (>=0), on success
537 *      -FDT_ERR_NOTFOUND, if the given property is the last in its node
538 *      -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_PROP tag
539 *      -FDT_ERR_BADMAGIC,
540 *      -FDT_ERR_BADVERSION,
541 *      -FDT_ERR_BADSTATE,
542 *      -FDT_ERR_BADSTRUCTURE,
543 *      -FDT_ERR_TRUNCATED, standard meanings.
544 */
545int fdt_next_property_offset(const void *fdt, int offset);
546
547/**
548 * fdt_for_each_property_offset - iterate over all properties of a node
549 *
550 * @property_offset:    property offset (int, lvalue)
551 * @fdt:                FDT blob (const void *)
552 * @node:               node offset (int)
553 *
554 * This is actually a wrapper around a for loop and would be used like so:
555 *
556 *      fdt_for_each_property_offset(property, fdt, node) {
557 *              Use property
558 *              ...
559 *      }
560 *
561 *      if ((property < 0) && (property != -FDT_ERR_NOT_FOUND)) {
562 *              Error handling
563 *      }
564 *
565 * Note that this is implemented as a macro and property is used as
566 * iterator in the loop. The node variable can be constant or even a
567 * literal.
568 */
569#define fdt_for_each_property_offset(property, fdt, node)       \
570        for (property = fdt_first_property_offset(fdt, node);   \
571             property >= 0;                                     \
572             property = fdt_next_property_offset(fdt, property))
573
574/**
575 * fdt_get_property_by_offset - retrieve the property at a given offset
576 * @fdt: pointer to the device tree blob
577 * @offset: offset of the property to retrieve
578 * @lenp: pointer to an integer variable (will be overwritten) or NULL
579 *
580 * fdt_get_property_by_offset() retrieves a pointer to the
581 * fdt_property structure within the device tree blob at the given
582 * offset.  If lenp is non-NULL, the length of the property value is
583 * also returned, in the integer pointed to by lenp.
584 *
585 * Note that this code only works on device tree versions >= 16. fdt_getprop()
586 * works on all versions.
587 *
588 * returns:
589 *      pointer to the structure representing the property
590 *              if lenp is non-NULL, *lenp contains the length of the property
591 *              value (>=0)
592 *      NULL, on error
593 *              if lenp is non-NULL, *lenp contains an error code (<0):
594 *              -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
595 *              -FDT_ERR_BADMAGIC,
596 *              -FDT_ERR_BADVERSION,
597 *              -FDT_ERR_BADSTATE,
598 *              -FDT_ERR_BADSTRUCTURE,
599 *              -FDT_ERR_TRUNCATED, standard meanings
600 */
601const struct fdt_property *fdt_get_property_by_offset(const void *fdt,
602                                                      int offset,
603                                                      int *lenp);
604
605/**
606 * fdt_get_property_namelen - find a property based on substring
607 * @fdt: pointer to the device tree blob
608 * @nodeoffset: offset of the node whose property to find
609 * @name: name of the property to find
610 * @namelen: number of characters of name to consider
611 * @lenp: pointer to an integer variable (will be overwritten) or NULL
612 *
613 * Identical to fdt_get_property(), but only examine the first namelen
614 * characters of name for matching the property name.
615 */
616#ifndef SWIG /* Not available in Python */
617const struct fdt_property *fdt_get_property_namelen(const void *fdt,
618                                                    int nodeoffset,
619                                                    const char *name,
620                                                    int namelen, int *lenp);
621#endif
622
623/**
624 * fdt_get_property - find a given property in a given node
625 * @fdt: pointer to the device tree blob
626 * @nodeoffset: offset of the node whose property to find
627 * @name: name of the property to find
628 * @lenp: pointer to an integer variable (will be overwritten) or NULL
629 *
630 * fdt_get_property() retrieves a pointer to the fdt_property
631 * structure within the device tree blob corresponding to the property
632 * named 'name' of the node at offset nodeoffset.  If lenp is
633 * non-NULL, the length of the property value is also returned, in the
634 * integer pointed to by lenp.
635 *
636 * returns:
637 *      pointer to the structure representing the property
638 *              if lenp is non-NULL, *lenp contains the length of the property
639 *              value (>=0)
640 *      NULL, on error
641 *              if lenp is non-NULL, *lenp contains an error code (<0):
642 *              -FDT_ERR_NOTFOUND, node does not have named property
643 *              -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE
644 *                      tag
645 *              -FDT_ERR_BADMAGIC,
646 *              -FDT_ERR_BADVERSION,
647 *              -FDT_ERR_BADSTATE,
648 *              -FDT_ERR_BADSTRUCTURE,
649 *              -FDT_ERR_TRUNCATED, standard meanings
650 */
651const struct fdt_property *fdt_get_property(const void *fdt, int nodeoffset,
652                                            const char *name, int *lenp);
653static inline struct fdt_property *fdt_get_property_w(void *fdt, int nodeoffset,
654                                                      const char *name,
655                                                      int *lenp)
656{
657        return (struct fdt_property *)(uintptr_t)
658                fdt_get_property(fdt, nodeoffset, name, lenp);
659}
660
661/**
662 * fdt_getprop_by_offset - retrieve the value of a property at a given offset
663 * @fdt: pointer to the device tree blob
664 * @ffset: offset of the property to read
665 * @namep: pointer to a string variable (will be overwritten) or NULL
666 * @lenp: pointer to an integer variable (will be overwritten) or NULL
667 *
668 * fdt_getprop_by_offset() retrieves a pointer to the value of the
669 * property at structure block offset 'offset' (this will be a pointer
670 * to within the device blob itself, not a copy of the value).  If
671 * lenp is non-NULL, the length of the property value is also
672 * returned, in the integer pointed to by lenp.  If namep is non-NULL,
673 * the property's namne will also be returned in the char * pointed to
674 * by namep (this will be a pointer to within the device tree's string
675 * block, not a new copy of the name).
676 *
677 * returns:
678 *      pointer to the property's value
679 *              if lenp is non-NULL, *lenp contains the length of the property
680 *              value (>=0)
681 *              if namep is non-NULL *namep contiains a pointer to the property
682 *              name.
683 *      NULL, on error
684 *              if lenp is non-NULL, *lenp contains an error code (<0):
685 *              -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
686 *              -FDT_ERR_BADMAGIC,
687 *              -FDT_ERR_BADVERSION,
688 *              -FDT_ERR_BADSTATE,
689 *              -FDT_ERR_BADSTRUCTURE,
690 *              -FDT_ERR_TRUNCATED, standard meanings
691 */
692#ifndef SWIG /* This function is not useful in Python */
693const void *fdt_getprop_by_offset(const void *fdt, int offset,
694                                  const char **namep, int *lenp);
695#endif
696
697/**
698 * fdt_getprop_namelen - get property value based on substring
699 * @fdt: pointer to the device tree blob
700 * @nodeoffset: offset of the node whose property to find
701 * @name: name of the property to find
702 * @namelen: number of characters of name to consider
703 * @lenp: pointer to an integer variable (will be overwritten) or NULL
704 *
705 * Identical to fdt_getprop(), but only examine the first namelen
706 * characters of name for matching the property name.
707 */
708#ifndef SWIG /* Not available in Python */
709const void *fdt_getprop_namelen(const void *fdt, int nodeoffset,
710                                const char *name, int namelen, int *lenp);
711static inline void *fdt_getprop_namelen_w(void *fdt, int nodeoffset,
712                                          const char *name, int namelen,
713                                          int *lenp)
714{
715        return (void *)(uintptr_t)fdt_getprop_namelen(fdt, nodeoffset, name,
716                                                      namelen, lenp);
717}
718#endif
719
720/**
721 * fdt_getprop - retrieve the value of a given property
722 * @fdt: pointer to the device tree blob
723 * @nodeoffset: offset of the node whose property to find
724 * @name: name of the property to find
725 * @lenp: pointer to an integer variable (will be overwritten) or NULL
726 *
727 * fdt_getprop() retrieves a pointer to the value of the property
728 * named 'name' of the node at offset nodeoffset (this will be a
729 * pointer to within the device blob itself, not a copy of the value).
730 * If lenp is non-NULL, the length of the property value is also
731 * returned, in the integer pointed to by lenp.
732 *
733 * returns:
734 *      pointer to the property's value
735 *              if lenp is non-NULL, *lenp contains the length of the property
736 *              value (>=0)
737 *      NULL, on error
738 *              if lenp is non-NULL, *lenp contains an error code (<0):
739 *              -FDT_ERR_NOTFOUND, node does not have named property
740 *              -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE
741 *                      tag
742 *              -FDT_ERR_BADMAGIC,
743 *              -FDT_ERR_BADVERSION,
744 *              -FDT_ERR_BADSTATE,
745 *              -FDT_ERR_BADSTRUCTURE,
746 *              -FDT_ERR_TRUNCATED, standard meanings
747 */
748const void *fdt_getprop(const void *fdt, int nodeoffset,
749                        const char *name, int *lenp);
750static inline void *fdt_getprop_w(void *fdt, int nodeoffset,
751                                  const char *name, int *lenp)
752{
753        return (void *)(uintptr_t)fdt_getprop(fdt, nodeoffset, name, lenp);
754}
755
756/**
757 * fdt_get_phandle - retrieve the phandle of a given node
758 * @fdt: pointer to the device tree blob
759 * @nodeoffset: structure block offset of the node
760 *
761 * fdt_get_phandle() retrieves the phandle of the device tree node at
762 * structure block offset nodeoffset.
763 *
764 * returns:
765 *      the phandle of the node at nodeoffset, on success (!= 0, != -1)
766 *      0, if the node has no phandle, or another error occurs
767 */
768uint32_t fdt_get_phandle(const void *fdt, int nodeoffset);
769
770/**
771 * fdt_get_alias_namelen - get alias based on substring
772 * @fdt: pointer to the device tree blob
773 * @name: name of the alias th look up
774 * @namelen: number of characters of name to consider
775 *
776 * Identical to fdt_get_alias(), but only examine the first namelen
777 * characters of name for matching the alias name.
778 */
779#ifndef SWIG /* Not available in Python */
780const char *fdt_get_alias_namelen(const void *fdt,
781                                  const char *name, int namelen);
782#endif
783
784/**
785 * fdt_get_alias - retrieve the path referenced by a given alias
786 * @fdt: pointer to the device tree blob
787 * @name: name of the alias th look up
788 *
789 * fdt_get_alias() retrieves the value of a given alias.  That is, the
790 * value of the property named 'name' in the node /aliases.
791 *
792 * returns:
793 *      a pointer to the expansion of the alias named 'name', if it exists
794 *      NULL, if the given alias or the /aliases node does not exist
795 */
796const char *fdt_get_alias(const void *fdt, const char *name);
797
798/**
799 * fdt_get_path - determine the full path of a node
800 * @fdt: pointer to the device tree blob
801 * @nodeoffset: offset of the node whose path to find
802 * @buf: character buffer to contain the returned path (will be overwritten)
803 * @buflen: size of the character buffer at buf
804 *
805 * fdt_get_path() computes the full path of the node at offset
806 * nodeoffset, and records that path in the buffer at buf.
807 *
808 * NOTE: This function is expensive, as it must scan the device tree
809 * structure from the start to nodeoffset.
810 *
811 * returns:
812 *      0, on success
813 *              buf contains the absolute path of the node at
814 *              nodeoffset, as a NUL-terminated string.
815 *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
816 *      -FDT_ERR_NOSPACE, the path of the given node is longer than (bufsize-1)
817 *              characters and will not fit in the given buffer.
818 *      -FDT_ERR_BADMAGIC,
819 *      -FDT_ERR_BADVERSION,
820 *      -FDT_ERR_BADSTATE,
821 *      -FDT_ERR_BADSTRUCTURE, standard meanings
822 */
823int fdt_get_path(const void *fdt, int nodeoffset, char *buf, int buflen);
824
825/**
826 * fdt_supernode_atdepth_offset - find a specific ancestor of a node
827 * @fdt: pointer to the device tree blob
828 * @nodeoffset: offset of the node whose parent to find
829 * @supernodedepth: depth of the ancestor to find
830 * @nodedepth: pointer to an integer variable (will be overwritten) or NULL
831 *
832 * fdt_supernode_atdepth_offset() finds an ancestor of the given node
833 * at a specific depth from the root (where the root itself has depth
834 * 0, its immediate subnodes depth 1 and so forth).  So
835 *      fdt_supernode_atdepth_offset(fdt, nodeoffset, 0, NULL);
836 * will always return 0, the offset of the root node.  If the node at
837 * nodeoffset has depth D, then:
838 *      fdt_supernode_atdepth_offset(fdt, nodeoffset, D, NULL);
839 * will return nodeoffset itself.
840 *
841 * NOTE: This function is expensive, as it must scan the device tree
842 * structure from the start to nodeoffset.
843 *
844 * returns:
845 *      structure block offset of the node at node offset's ancestor
846 *              of depth supernodedepth (>=0), on success
847 *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
848 *      -FDT_ERR_NOTFOUND, supernodedepth was greater than the depth of
849 *              nodeoffset
850 *      -FDT_ERR_BADMAGIC,
851 *      -FDT_ERR_BADVERSION,
852 *      -FDT_ERR_BADSTATE,
853 *      -FDT_ERR_BADSTRUCTURE, standard meanings
854 */
855int fdt_supernode_atdepth_offset(const void *fdt, int nodeoffset,
856                                 int supernodedepth, int *nodedepth);
857
858/**
859 * fdt_node_depth - find the depth of a given node
860 * @fdt: pointer to the device tree blob
861 * @nodeoffset: offset of the node whose parent to find
862 *
863 * fdt_node_depth() finds the depth of a given node.  The root node
864 * has depth 0, its immediate subnodes depth 1 and so forth.
865 *
866 * NOTE: This function is expensive, as it must scan the device tree
867 * structure from the start to nodeoffset.
868 *
869 * returns:
870 *      depth of the node at nodeoffset (>=0), on success
871 *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
872 *      -FDT_ERR_BADMAGIC,
873 *      -FDT_ERR_BADVERSION,
874 *      -FDT_ERR_BADSTATE,
875 *      -FDT_ERR_BADSTRUCTURE, standard meanings
876 */
877int fdt_node_depth(const void *fdt, int nodeoffset);
878
879/**
880 * fdt_parent_offset - find the parent of a given node
881 * @fdt: pointer to the device tree blob
882 * @nodeoffset: offset of the node whose parent to find
883 *
884 * fdt_parent_offset() locates the parent node of a given node (that
885 * is, it finds the offset of the node which contains the node at
886 * nodeoffset as a subnode).
887 *
888 * NOTE: This function is expensive, as it must scan the device tree
889 * structure from the start to nodeoffset, *twice*.
890 *
891 * returns:
892 *      structure block offset of the parent of the node at nodeoffset
893 *              (>=0), on success
894 *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
895 *      -FDT_ERR_BADMAGIC,
896 *      -FDT_ERR_BADVERSION,
897 *      -FDT_ERR_BADSTATE,
898 *      -FDT_ERR_BADSTRUCTURE, standard meanings
899 */
900int fdt_parent_offset(const void *fdt, int nodeoffset);
901
902/**
903 * fdt_node_offset_by_prop_value - find nodes with a given property value
904 * @fdt: pointer to the device tree blob
905 * @startoffset: only find nodes after this offset
906 * @propname: property name to check
907 * @propval: property value to search for
908 * @proplen: length of the value in propval
909 *
910 * fdt_node_offset_by_prop_value() returns the offset of the first
911 * node after startoffset, which has a property named propname whose
912 * value is of length proplen and has value equal to propval; or if
913 * startoffset is -1, the very first such node in the tree.
914 *
915 * To iterate through all nodes matching the criterion, the following
916 * idiom can be used:
917 *      offset = fdt_node_offset_by_prop_value(fdt, -1, propname,
918 *                                             propval, proplen);
919 *      while (offset != -FDT_ERR_NOTFOUND) {
920 *              // other code here
921 *              offset = fdt_node_offset_by_prop_value(fdt, offset, propname,
922 *                                                     propval, proplen);
923 *      }
924 *
925 * Note the -1 in the first call to the function, if 0 is used here
926 * instead, the function will never locate the root node, even if it
927 * matches the criterion.
928 *
929 * returns:
930 *      structure block offset of the located node (>= 0, >startoffset),
931 *               on success
932 *      -FDT_ERR_NOTFOUND, no node matching the criterion exists in the
933 *              tree after startoffset
934 *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
935 *      -FDT_ERR_BADMAGIC,
936 *      -FDT_ERR_BADVERSION,
937 *      -FDT_ERR_BADSTATE,
938 *      -FDT_ERR_BADSTRUCTURE, standard meanings
939 */
940int fdt_node_offset_by_prop_value(const void *fdt, int startoffset,
941                                  const char *propname,
942                                  const void *propval, int proplen);
943
944/**
945 * fdt_node_offset_by_phandle - find the node with a given phandle
946 * @fdt: pointer to the device tree blob
947 * @phandle: phandle value
948 *
949 * fdt_node_offset_by_phandle() returns the offset of the node
950 * which has the given phandle value.  If there is more than one node
951 * in the tree with the given phandle (an invalid tree), results are
952 * undefined.
953 *
954 * returns:
955 *      structure block offset of the located node (>= 0), on success
956 *      -FDT_ERR_NOTFOUND, no node with that phandle exists
957 *      -FDT_ERR_BADPHANDLE, given phandle value was invalid (0 or -1)
958 *      -FDT_ERR_BADMAGIC,
959 *      -FDT_ERR_BADVERSION,
960 *      -FDT_ERR_BADSTATE,
961 *      -FDT_ERR_BADSTRUCTURE, standard meanings
962 */
963int fdt_node_offset_by_phandle(const void *fdt, uint32_t phandle);
964
965/**
966 * fdt_node_check_compatible: check a node's compatible property
967 * @fdt: pointer to the device tree blob
968 * @nodeoffset: offset of a tree node
969 * @compatible: string to match against
970 *
971 *
972 * fdt_node_check_compatible() returns 0 if the given node contains a
973 * 'compatible' property with the given string as one of its elements,
974 * it returns non-zero otherwise, or on error.
975 *
976 * returns:
977 *      0, if the node has a 'compatible' property listing the given string
978 *      1, if the node has a 'compatible' property, but it does not list
979 *              the given string
980 *      -FDT_ERR_NOTFOUND, if the given node has no 'compatible' property
981 *      -FDT_ERR_BADOFFSET, if nodeoffset does not refer to a BEGIN_NODE tag
982 *      -FDT_ERR_BADMAGIC,
983 *      -FDT_ERR_BADVERSION,
984 *      -FDT_ERR_BADSTATE,
985 *      -FDT_ERR_BADSTRUCTURE, standard meanings
986 */
987int fdt_node_check_compatible(const void *fdt, int nodeoffset,
988                              const char *compatible);
989
990/**
991 * fdt_node_offset_by_compatible - find nodes with a given 'compatible' value
992 * @fdt: pointer to the device tree blob
993 * @startoffset: only find nodes after this offset
994 * @compatible: 'compatible' string to match against
995 *
996 * fdt_node_offset_by_compatible() returns the offset of the first
997 * node after startoffset, which has a 'compatible' property which
998 * lists the given compatible string; or if startoffset is -1, the
999 * very first such node in the tree.
1000 *
1001 * To iterate through all nodes matching the criterion, the following
1002 * idiom can be used:
1003 *      offset = fdt_node_offset_by_compatible(fdt, -1, compatible);
1004 *      while (offset != -FDT_ERR_NOTFOUND) {
1005 *              // other code here
1006 *              offset = fdt_node_offset_by_compatible(fdt, offset, compatible);
1007 *      }
1008 *
1009 * Note the -1 in the first call to the function, if 0 is used here
1010 * instead, the function will never locate the root node, even if it
1011 * matches the criterion.
1012 *
1013 * returns:
1014 *      structure block offset of the located node (>= 0, >startoffset),
1015 *               on success
1016 *      -FDT_ERR_NOTFOUND, no node matching the criterion exists in the
1017 *              tree after startoffset
1018 *      -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
1019 *      -FDT_ERR_BADMAGIC,
1020 *      -FDT_ERR_BADVERSION,
1021 *      -FDT_ERR_BADSTATE,
1022 *      -FDT_ERR_BADSTRUCTURE, standard meanings
1023 */
1024int fdt_node_offset_by_compatible(const void *fdt, int startoffset,
1025                                  const char *compatible);
1026
1027/**
1028 * fdt_stringlist_contains - check a string list property for a string
1029 * @strlist: Property containing a list of strings to check
1030 * @listlen: Length of property
1031 * @str: String to search for
1032 *
1033 * This is a utility function provided for convenience. The list contains
1034 * one or more strings, each terminated by \0, as is found in a device tree
1035 * "compatible" property.
1036 *
1037 * @return: 1 if the string is found in the list, 0 not found, or invalid list
1038 */
1039int fdt_stringlist_contains(const char *strlist, int listlen, const char *str);
1040
1041/**
1042 * fdt_stringlist_count - count the number of strings in a string list
1043 * @fdt: pointer to the device tree blob
1044 * @nodeoffset: offset of a tree node
1045 * @property: name of the property containing the string list
1046 * @return:
1047 *   the number of strings in the given property
1048 *   -FDT_ERR_BADVALUE if the property value is not NUL-terminated
1049 *   -FDT_ERR_NOTFOUND if the property does not exist
1050 */
1051int fdt_stringlist_count(const void *fdt, int nodeoffset, const char *property);
1052
1053/**
1054 * fdt_stringlist_search - find a string in a string list and return its index
1055 * @fdt: pointer to the device tree blob
1056 * @nodeoffset: offset of a tree node
1057 * @property: name of the property containing the string list
1058 * @string: string to look up in the string list
1059 *
1060 * Note that it is possible for this function to succeed on property values
1061 * that are not NUL-terminated. That's because the function will stop after
1062 * finding the first occurrence of @string. This can for example happen with
1063 * small-valued cell properties, such as #address-cells, when searching for
1064 * the empty string.
1065 *
1066 * @return:
1067 *   the index of the string in the list of strings
1068 *   -FDT_ERR_BADVALUE if the property value is not NUL-terminated
1069 *   -FDT_ERR_NOTFOUND if the property does not exist or does not contain
1070 *                     the given string
1071 */
1072int fdt_stringlist_search(const void *fdt, int nodeoffset, const char *property,
1073                          const char *string);
1074
1075/**
1076 * fdt_stringlist_get() - obtain the string at a given index in a string list
1077 * @fdt: pointer to the device tree blob
1078 * @nodeoffset: offset of a tree node
1079 * @property: name of the property containing the string list
1080 * @index: index of the string to return
1081 * @lenp: return location for the string length or an error code on failure
1082 *
1083 * Note that this will successfully extract strings from properties with
1084 * non-NUL-terminated values. For example on small-valued cell properties
1085 * this function will return the empty string.
1086 *
1087 * If non-NULL, the length of the string (on success) or a negative error-code
1088 * (on failure) will be stored in the integer pointer to by lenp.
1089 *
1090 * @return:
1091 *   A pointer to the string at the given index in the string list or NULL on
1092 *   failure. On success the length of the string will be stored in the memory
1093 *   location pointed to by the lenp parameter, if non-NULL. On failure one of
1094 *   the following negative error codes will be returned in the lenp parameter
1095 *   (if non-NULL):
1096 *     -FDT_ERR_BADVALUE if the property value is not NUL-terminated
1097 *     -FDT_ERR_NOTFOUND if the property does not exist
1098 */
1099const char *fdt_stringlist_get(const void *fdt, int nodeoffset,
1100                               const char *property, int index,
1101                               int *lenp);
1102
1103/**********************************************************************/
1104/* Read-only functions (addressing related)                           */
1105/**********************************************************************/
1106
1107/**
1108 * FDT_MAX_NCELLS - maximum value for #address-cells and #size-cells
1109 *
1110 * This is the maximum value for #address-cells, #size-cells and
1111 * similar properties that will be processed by libfdt.  IEE1275
1112 * requires that OF implementations handle values up to 4.
1113 * Implementations may support larger values, but in practice higher
1114 * values aren't used.
1115 */
1116#define FDT_MAX_NCELLS          4
1117
1118/**
1119 * fdt_address_cells - retrieve address size for a bus represented in the tree
1120 * @fdt: pointer to the device tree blob
1121 * @nodeoffset: offset of the node to find the address size for
1122 *
1123 * When the node has a valid #address-cells property, returns its value.
1124 *
1125 * returns:
1126 *      0 <= n < FDT_MAX_NCELLS, on success
1127 *      2, if the node has no #address-cells property
1128 *      -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid
1129 *              #address-cells property
1130 *      -FDT_ERR_BADMAGIC,
1131 *      -FDT_ERR_BADVERSION,
1132 *      -FDT_ERR_BADSTATE,
1133 *      -FDT_ERR_BADSTRUCTURE,
1134 *      -FDT_ERR_TRUNCATED, standard meanings
1135 */
1136int fdt_address_cells(const void *fdt, int nodeoffset);
1137
1138/**
1139 * fdt_size_cells - retrieve address range size for a bus represented in the
1140 *                  tree
1141 * @fdt: pointer to the device tree blob
1142 * @nodeoffset: offset of the node to find the address range size for
1143 *
1144 * When the node has a valid #size-cells property, returns its value.
1145 *
1146 * returns:
1147 *      0 <= n < FDT_MAX_NCELLS, on success
1148 *      2, if the node has no #address-cells property
1149 *      -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid
1150 *              #size-cells property
1151 *      -FDT_ERR_BADMAGIC,
1152 *      -FDT_ERR_BADVERSION,
1153 *      -FDT_ERR_BADSTATE,
1154 *      -FDT_ERR_BADSTRUCTURE,
1155 *      -FDT_ERR_TRUNCATED, standard meanings
1156 */
1157int fdt_size_cells(const void *fdt, int nodeoffset);
1158
1159
1160/**********************************************************************/
1161/* Write-in-place functions                                           */
1162/**********************************************************************/
1163
1164/**
1165 * fdt_setprop_inplace_namelen_partial - change a property's value,
1166 *                                       but not its size
1167 * @fdt: pointer to the device tree blob
1168 * @nodeoffset: offset of the node whose property to change
1169 * @name: name of the property to change
1170 * @namelen: number of characters of name to consider
1171 * @idx: index of the property to change in the array
1172 * @val: pointer to data to replace the property value with
1173 * @len: length of the property value
1174 *
1175 * Identical to fdt_setprop_inplace(), but modifies the given property
1176 * starting from the given index, and using only the first characters
1177 * of the name. It is useful when you want to manipulate only one value of
1178 * an array and you have a string that doesn't end with \0.
1179 */
1180#ifndef SWIG /* Not available in Python */
1181int fdt_setprop_inplace_namelen_partial(void *fdt, int nodeoffset,
1182                                        const char *name, int namelen,
1183                                        uint32_t idx, const void *val,
1184                                        int len);
1185#endif
1186
1187/**
1188 * fdt_setprop_inplace - change a property's value, but not its size
1189 * @fdt: pointer to the device tree blob
1190 * @nodeoffset: offset of the node whose property to change
1191 * @name: name of the property to change
1192 * @val: pointer to data to replace the property value with
1193 * @len: length of the property value
1194 *
1195 * fdt_setprop_inplace() replaces the value of a given property with
1196 * the data in val, of length len.  This function cannot change the
1197 * size of a property, and so will only work if len is equal to the
1198 * current length of the property.
1199 *
1200 * This function will alter only the bytes in the blob which contain
1201 * the given property value, and will not alter or move any other part
1202 * of the tree.
1203 *
1204 * returns:
1205 *      0, on success
1206 *      -FDT_ERR_NOSPACE, if len is not equal to the property's current length
1207 *      -FDT_ERR_NOTFOUND, node does not have the named property
1208 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1209 *      -FDT_ERR_BADMAGIC,
1210 *      -FDT_ERR_BADVERSION,
1211 *      -FDT_ERR_BADSTATE,
1212 *      -FDT_ERR_BADSTRUCTURE,
1213 *      -FDT_ERR_TRUNCATED, standard meanings
1214 */
1215#ifndef SWIG /* Not available in Python */
1216int fdt_setprop_inplace(void *fdt, int nodeoffset, const char *name,
1217                        const void *val, int len);
1218#endif
1219
1220/**
1221 * fdt_setprop_inplace_u32 - change the value of a 32-bit integer property
1222 * @fdt: pointer to the device tree blob
1223 * @nodeoffset: offset of the node whose property to change
1224 * @name: name of the property to change
1225 * @val: 32-bit integer value to replace the property with
1226 *
1227 * fdt_setprop_inplace_u32() replaces the value of a given property
1228 * with the 32-bit integer value in val, converting val to big-endian
1229 * if necessary.  This function cannot change the size of a property,
1230 * and so will only work if the property already exists and has length
1231 * 4.
1232 *
1233 * This function will alter only the bytes in the blob which contain
1234 * the given property value, and will not alter or move any other part
1235 * of the tree.
1236 *
1237 * returns:
1238 *      0, on success
1239 *      -FDT_ERR_NOSPACE, if the property's length is not equal to 4
1240 *      -FDT_ERR_NOTFOUND, node does not have the named property
1241 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1242 *      -FDT_ERR_BADMAGIC,
1243 *      -FDT_ERR_BADVERSION,
1244 *      -FDT_ERR_BADSTATE,
1245 *      -FDT_ERR_BADSTRUCTURE,
1246 *      -FDT_ERR_TRUNCATED, standard meanings
1247 */
1248static inline int fdt_setprop_inplace_u32(void *fdt, int nodeoffset,
1249                                          const char *name, uint32_t val)
1250{
1251        fdt32_t tmp = cpu_to_fdt32(val);
1252        return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
1253}
1254
1255/**
1256 * fdt_setprop_inplace_u64 - change the value of a 64-bit integer property
1257 * @fdt: pointer to the device tree blob
1258 * @nodeoffset: offset of the node whose property to change
1259 * @name: name of the property to change
1260 * @val: 64-bit integer value to replace the property with
1261 *
1262 * fdt_setprop_inplace_u64() replaces the value of a given property
1263 * with the 64-bit integer value in val, converting val to big-endian
1264 * if necessary.  This function cannot change the size of a property,
1265 * and so will only work if the property already exists and has length
1266 * 8.
1267 *
1268 * This function will alter only the bytes in the blob which contain
1269 * the given property value, and will not alter or move any other part
1270 * of the tree.
1271 *
1272 * returns:
1273 *      0, on success
1274 *      -FDT_ERR_NOSPACE, if the property's length is not equal to 8
1275 *      -FDT_ERR_NOTFOUND, node does not have the named property
1276 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1277 *      -FDT_ERR_BADMAGIC,
1278 *      -FDT_ERR_BADVERSION,
1279 *      -FDT_ERR_BADSTATE,
1280 *      -FDT_ERR_BADSTRUCTURE,
1281 *      -FDT_ERR_TRUNCATED, standard meanings
1282 */
1283static inline int fdt_setprop_inplace_u64(void *fdt, int nodeoffset,
1284                                          const char *name, uint64_t val)
1285{
1286        fdt64_t tmp = cpu_to_fdt64(val);
1287        return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
1288}
1289
1290/**
1291 * fdt_setprop_inplace_cell - change the value of a single-cell property
1292 *
1293 * This is an alternative name for fdt_setprop_inplace_u32()
1294 */
1295static inline int fdt_setprop_inplace_cell(void *fdt, int nodeoffset,
1296                                           const char *name, uint32_t val)
1297{
1298        return fdt_setprop_inplace_u32(fdt, nodeoffset, name, val);
1299}
1300
1301/**
1302 * fdt_nop_property - replace a property with nop tags
1303 * @fdt: pointer to the device tree blob
1304 * @nodeoffset: offset of the node whose property to nop
1305 * @name: name of the property to nop
1306 *
1307 * fdt_nop_property() will replace a given property's representation
1308 * in the blob with FDT_NOP tags, effectively removing it from the
1309 * tree.
1310 *
1311 * This function will alter only the bytes in the blob which contain
1312 * the property, and will not alter or move any other part of the
1313 * tree.
1314 *
1315 * returns:
1316 *      0, on success
1317 *      -FDT_ERR_NOTFOUND, node does not have the named property
1318 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1319 *      -FDT_ERR_BADMAGIC,
1320 *      -FDT_ERR_BADVERSION,
1321 *      -FDT_ERR_BADSTATE,
1322 *      -FDT_ERR_BADSTRUCTURE,
1323 *      -FDT_ERR_TRUNCATED, standard meanings
1324 */
1325int fdt_nop_property(void *fdt, int nodeoffset, const char *name);
1326
1327/**
1328 * fdt_nop_node - replace a node (subtree) with nop tags
1329 * @fdt: pointer to the device tree blob
1330 * @nodeoffset: offset of the node to nop
1331 *
1332 * fdt_nop_node() will replace a given node's representation in the
1333 * blob, including all its subnodes, if any, with FDT_NOP tags,
1334 * effectively removing it from the tree.
1335 *
1336 * This function will alter only the bytes in the blob which contain
1337 * the node and its properties and subnodes, and will not alter or
1338 * move any other part of the tree.
1339 *
1340 * returns:
1341 *      0, on success
1342 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1343 *      -FDT_ERR_BADMAGIC,
1344 *      -FDT_ERR_BADVERSION,
1345 *      -FDT_ERR_BADSTATE,
1346 *      -FDT_ERR_BADSTRUCTURE,
1347 *      -FDT_ERR_TRUNCATED, standard meanings
1348 */
1349int fdt_nop_node(void *fdt, int nodeoffset);
1350
1351/**********************************************************************/
1352/* Sequential write functions                                         */
1353/**********************************************************************/
1354
1355int fdt_create(void *buf, int bufsize);
1356int fdt_resize(void *fdt, void *buf, int bufsize);
1357int fdt_add_reservemap_entry(void *fdt, uint64_t addr, uint64_t size);
1358int fdt_finish_reservemap(void *fdt);
1359int fdt_begin_node(void *fdt, const char *name);
1360int fdt_property(void *fdt, const char *name, const void *val, int len);
1361static inline int fdt_property_u32(void *fdt, const char *name, uint32_t val)
1362{
1363        fdt32_t tmp = cpu_to_fdt32(val);
1364        return fdt_property(fdt, name, &tmp, sizeof(tmp));
1365}
1366static inline int fdt_property_u64(void *fdt, const char *name, uint64_t val)
1367{
1368        fdt64_t tmp = cpu_to_fdt64(val);
1369        return fdt_property(fdt, name, &tmp, sizeof(tmp));
1370}
1371
1372#ifndef SWIG /* Not available in Python */
1373static inline int fdt_property_cell(void *fdt, const char *name, uint32_t val)
1374{
1375        return fdt_property_u32(fdt, name, val);
1376}
1377#endif
1378
1379/**
1380 * fdt_property_placeholder - add a new property and return a ptr to its value
1381 *
1382 * @fdt: pointer to the device tree blob
1383 * @name: name of property to add
1384 * @len: length of property value in bytes
1385 * @valp: returns a pointer to where where the value should be placed
1386 *
1387 * returns:
1388 *      0, on success
1389 *      -FDT_ERR_BADMAGIC,
1390 *      -FDT_ERR_NOSPACE, standard meanings
1391 */
1392int fdt_property_placeholder(void *fdt, const char *name, int len, void **valp);
1393
1394#define fdt_property_string(fdt, name, str) \
1395        fdt_property(fdt, name, str, strlen(str)+1)
1396int fdt_end_node(void *fdt);
1397int fdt_finish(void *fdt);
1398
1399/**********************************************************************/
1400/* Read-write functions                                               */
1401/**********************************************************************/
1402
1403int fdt_create_empty_tree(void *buf, int bufsize);
1404int fdt_open_into(const void *fdt, void *buf, int bufsize);
1405int fdt_pack(void *fdt);
1406
1407/**
1408 * fdt_add_mem_rsv - add one memory reserve map entry
1409 * @fdt: pointer to the device tree blob
1410 * @address, @size: 64-bit values (native endian)
1411 *
1412 * Adds a reserve map entry to the given blob reserving a region at
1413 * address address of length size.
1414 *
1415 * This function will insert data into the reserve map and will
1416 * therefore change the indexes of some entries in the table.
1417 *
1418 * returns:
1419 *      0, on success
1420 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1421 *              contain the new reservation entry
1422 *      -FDT_ERR_BADMAGIC,
1423 *      -FDT_ERR_BADVERSION,
1424 *      -FDT_ERR_BADSTATE,
1425 *      -FDT_ERR_BADSTRUCTURE,
1426 *      -FDT_ERR_BADLAYOUT,
1427 *      -FDT_ERR_TRUNCATED, standard meanings
1428 */
1429int fdt_add_mem_rsv(void *fdt, uint64_t address, uint64_t size);
1430
1431/**
1432 * fdt_del_mem_rsv - remove a memory reserve map entry
1433 * @fdt: pointer to the device tree blob
1434 * @n: entry to remove
1435 *
1436 * fdt_del_mem_rsv() removes the n-th memory reserve map entry from
1437 * the blob.
1438 *
1439 * This function will delete data from the reservation table and will
1440 * therefore change the indexes of some entries in the table.
1441 *
1442 * returns:
1443 *      0, on success
1444 *      -FDT_ERR_NOTFOUND, there is no entry of the given index (i.e. there
1445 *              are less than n+1 reserve map entries)
1446 *      -FDT_ERR_BADMAGIC,
1447 *      -FDT_ERR_BADVERSION,
1448 *      -FDT_ERR_BADSTATE,
1449 *      -FDT_ERR_BADSTRUCTURE,
1450 *      -FDT_ERR_BADLAYOUT,
1451 *      -FDT_ERR_TRUNCATED, standard meanings
1452 */
1453int fdt_del_mem_rsv(void *fdt, int n);
1454
1455/**
1456 * fdt_set_name - change the name of a given node
1457 * @fdt: pointer to the device tree blob
1458 * @nodeoffset: structure block offset of a node
1459 * @name: name to give the node
1460 *
1461 * fdt_set_name() replaces the name (including unit address, if any)
1462 * of the given node with the given string.  NOTE: this function can't
1463 * efficiently check if the new name is unique amongst the given
1464 * node's siblings; results are undefined if this function is invoked
1465 * with a name equal to one of the given node's siblings.
1466 *
1467 * This function may insert or delete data from the blob, and will
1468 * therefore change the offsets of some existing nodes.
1469 *
1470 * returns:
1471 *      0, on success
1472 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob
1473 *              to contain the new name
1474 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1475 *      -FDT_ERR_BADMAGIC,
1476 *      -FDT_ERR_BADVERSION,
1477 *      -FDT_ERR_BADSTATE, standard meanings
1478 */
1479int fdt_set_name(void *fdt, int nodeoffset, const char *name);
1480
1481/**
1482 * fdt_setprop - create or change a property
1483 * @fdt: pointer to the device tree blob
1484 * @nodeoffset: offset of the node whose property to change
1485 * @name: name of the property to change
1486 * @val: pointer to data to set the property value to
1487 * @len: length of the property value
1488 *
1489 * fdt_setprop() sets the value of the named property in the given
1490 * node to the given value and length, creating the property if it
1491 * does not already exist.
1492 *
1493 * This function may insert or delete data from the blob, and will
1494 * therefore change the offsets of some existing nodes.
1495 *
1496 * returns:
1497 *      0, on success
1498 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1499 *              contain the new property value
1500 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1501 *      -FDT_ERR_BADLAYOUT,
1502 *      -FDT_ERR_BADMAGIC,
1503 *      -FDT_ERR_BADVERSION,
1504 *      -FDT_ERR_BADSTATE,
1505 *      -FDT_ERR_BADSTRUCTURE,
1506 *      -FDT_ERR_BADLAYOUT,
1507 *      -FDT_ERR_TRUNCATED, standard meanings
1508 */
1509int fdt_setprop(void *fdt, int nodeoffset, const char *name,
1510                const void *val, int len);
1511
1512/**
1513 * fdt_setprop_placeholder - allocate space for a property
1514 * @fdt: pointer to the device tree blob
1515 * @nodeoffset: offset of the node whose property to change
1516 * @name: name of the property to change
1517 * @len: length of the property value
1518 * @prop_data: return pointer to property data
1519 *
1520 * fdt_setprop_placeholer() allocates the named property in the given node.
1521 * If the property exists it is resized. In either case a pointer to the
1522 * property data is returned.
1523 *
1524 * This function may insert or delete data from the blob, and will
1525 * therefore change the offsets of some existing nodes.
1526 *
1527 * returns:
1528 *      0, on success
1529 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1530 *              contain the new property value
1531 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1532 *      -FDT_ERR_BADLAYOUT,
1533 *      -FDT_ERR_BADMAGIC,
1534 *      -FDT_ERR_BADVERSION,
1535 *      -FDT_ERR_BADSTATE,
1536 *      -FDT_ERR_BADSTRUCTURE,
1537 *      -FDT_ERR_BADLAYOUT,
1538 *      -FDT_ERR_TRUNCATED, standard meanings
1539 */
1540int fdt_setprop_placeholder(void *fdt, int nodeoffset, const char *name,
1541                            int len, void **prop_data);
1542
1543/**
1544 * fdt_setprop_u32 - set a property to a 32-bit integer
1545 * @fdt: pointer to the device tree blob
1546 * @nodeoffset: offset of the node whose property to change
1547 * @name: name of the property to change
1548 * @val: 32-bit integer value for the property (native endian)
1549 *
1550 * fdt_setprop_u32() sets the value of the named property in the given
1551 * node to the given 32-bit integer value (converting to big-endian if
1552 * necessary), or creates a new property with that value if it does
1553 * not already exist.
1554 *
1555 * This function may insert or delete data from the blob, and will
1556 * therefore change the offsets of some existing nodes.
1557 *
1558 * returns:
1559 *      0, on success
1560 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1561 *              contain the new property value
1562 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1563 *      -FDT_ERR_BADLAYOUT,
1564 *      -FDT_ERR_BADMAGIC,
1565 *      -FDT_ERR_BADVERSION,
1566 *      -FDT_ERR_BADSTATE,
1567 *      -FDT_ERR_BADSTRUCTURE,
1568 *      -FDT_ERR_BADLAYOUT,
1569 *      -FDT_ERR_TRUNCATED, standard meanings
1570 */
1571static inline int fdt_setprop_u32(void *fdt, int nodeoffset, const char *name,
1572                                  uint32_t val)
1573{
1574        fdt32_t tmp = cpu_to_fdt32(val);
1575        return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
1576}
1577
1578/**
1579 * fdt_setprop_u64 - set a property to a 64-bit integer
1580 * @fdt: pointer to the device tree blob
1581 * @nodeoffset: offset of the node whose property to change
1582 * @name: name of the property to change
1583 * @val: 64-bit integer value for the property (native endian)
1584 *
1585 * fdt_setprop_u64() sets the value of the named property in the given
1586 * node to the given 64-bit integer value (converting to big-endian if
1587 * necessary), or creates a new property with that value if it does
1588 * not already exist.
1589 *
1590 * This function may insert or delete data from the blob, and will
1591 * therefore change the offsets of some existing nodes.
1592 *
1593 * returns:
1594 *      0, on success
1595 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1596 *              contain the new property value
1597 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1598 *      -FDT_ERR_BADLAYOUT,
1599 *      -FDT_ERR_BADMAGIC,
1600 *      -FDT_ERR_BADVERSION,
1601 *      -FDT_ERR_BADSTATE,
1602 *      -FDT_ERR_BADSTRUCTURE,
1603 *      -FDT_ERR_BADLAYOUT,
1604 *      -FDT_ERR_TRUNCATED, standard meanings
1605 */
1606static inline int fdt_setprop_u64(void *fdt, int nodeoffset, const char *name,
1607                                  uint64_t val)
1608{
1609        fdt64_t tmp = cpu_to_fdt64(val);
1610        return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
1611}
1612
1613/**
1614 * fdt_setprop_cell - set a property to a single cell value
1615 *
1616 * This is an alternative name for fdt_setprop_u32()
1617 */
1618static inline int fdt_setprop_cell(void *fdt, int nodeoffset, const char *name,
1619                                   uint32_t val)
1620{
1621        return fdt_setprop_u32(fdt, nodeoffset, name, val);
1622}
1623
1624/**
1625 * fdt_setprop_string - set a property to a string value
1626 * @fdt: pointer to the device tree blob
1627 * @nodeoffset: offset of the node whose property to change
1628 * @name: name of the property to change
1629 * @str: string value for the property
1630 *
1631 * fdt_setprop_string() sets the value of the named property in the
1632 * given node to the given string value (using the length of the
1633 * string to determine the new length of the property), or creates a
1634 * new property with that value if it does not already exist.
1635 *
1636 * This function may insert or delete data from the blob, and will
1637 * therefore change the offsets of some existing nodes.
1638 *
1639 * returns:
1640 *      0, on success
1641 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1642 *              contain the new property value
1643 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1644 *      -FDT_ERR_BADLAYOUT,
1645 *      -FDT_ERR_BADMAGIC,
1646 *      -FDT_ERR_BADVERSION,
1647 *      -FDT_ERR_BADSTATE,
1648 *      -FDT_ERR_BADSTRUCTURE,
1649 *      -FDT_ERR_BADLAYOUT,
1650 *      -FDT_ERR_TRUNCATED, standard meanings
1651 */
1652#define fdt_setprop_string(fdt, nodeoffset, name, str) \
1653        fdt_setprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)
1654
1655
1656/**
1657 * fdt_setprop_empty - set a property to an empty value
1658 * @fdt: pointer to the device tree blob
1659 * @nodeoffset: offset of the node whose property to change
1660 * @name: name of the property to change
1661 *
1662 * fdt_setprop_empty() sets the value of the named property in the
1663 * given node to an empty (zero length) value, or creates a new empty
1664 * property if it does not already exist.
1665 *
1666 * This function may insert or delete data from the blob, and will
1667 * therefore change the offsets of some existing nodes.
1668 *
1669 * returns:
1670 *      0, on success
1671 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1672 *              contain the new property value
1673 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1674 *      -FDT_ERR_BADLAYOUT,
1675 *      -FDT_ERR_BADMAGIC,
1676 *      -FDT_ERR_BADVERSION,
1677 *      -FDT_ERR_BADSTATE,
1678 *      -FDT_ERR_BADSTRUCTURE,
1679 *      -FDT_ERR_BADLAYOUT,
1680 *      -FDT_ERR_TRUNCATED, standard meanings
1681 */
1682#define fdt_setprop_empty(fdt, nodeoffset, name) \
1683        fdt_setprop((fdt), (nodeoffset), (name), NULL, 0)
1684
1685/**
1686 * fdt_appendprop - append to or create a property
1687 * @fdt: pointer to the device tree blob
1688 * @nodeoffset: offset of the node whose property to change
1689 * @name: name of the property to append to
1690 * @val: pointer to data to append to the property value
1691 * @len: length of the data to append to the property value
1692 *
1693 * fdt_appendprop() appends the value to the named property in the
1694 * given node, creating the property if it does not already exist.
1695 *
1696 * This function may insert data into the blob, and will therefore
1697 * change the offsets of some existing nodes.
1698 *
1699 * returns:
1700 *      0, on success
1701 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1702 *              contain the new property value
1703 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1704 *      -FDT_ERR_BADLAYOUT,
1705 *      -FDT_ERR_BADMAGIC,
1706 *      -FDT_ERR_BADVERSION,
1707 *      -FDT_ERR_BADSTATE,
1708 *      -FDT_ERR_BADSTRUCTURE,
1709 *      -FDT_ERR_BADLAYOUT,
1710 *      -FDT_ERR_TRUNCATED, standard meanings
1711 */
1712int fdt_appendprop(void *fdt, int nodeoffset, const char *name,
1713                   const void *val, int len);
1714
1715/**
1716 * fdt_appendprop_u32 - append a 32-bit integer value to a property
1717 * @fdt: pointer to the device tree blob
1718 * @nodeoffset: offset of the node whose property to change
1719 * @name: name of the property to change
1720 * @val: 32-bit integer value to append to the property (native endian)
1721 *
1722 * fdt_appendprop_u32() appends the given 32-bit integer value
1723 * (converting to big-endian if necessary) to the value of the named
1724 * property in the given node, or creates a new property with that
1725 * value if it does not already exist.
1726 *
1727 * This function may insert data into the blob, and will therefore
1728 * change the offsets of some existing nodes.
1729 *
1730 * returns:
1731 *      0, on success
1732 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1733 *              contain the new property value
1734 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1735 *      -FDT_ERR_BADLAYOUT,
1736 *      -FDT_ERR_BADMAGIC,
1737 *      -FDT_ERR_BADVERSION,
1738 *      -FDT_ERR_BADSTATE,
1739 *      -FDT_ERR_BADSTRUCTURE,
1740 *      -FDT_ERR_BADLAYOUT,
1741 *      -FDT_ERR_TRUNCATED, standard meanings
1742 */
1743static inline int fdt_appendprop_u32(void *fdt, int nodeoffset,
1744                                     const char *name, uint32_t val)
1745{
1746        fdt32_t tmp = cpu_to_fdt32(val);
1747        return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
1748}
1749
1750/**
1751 * fdt_appendprop_u64 - append a 64-bit integer value to a property
1752 * @fdt: pointer to the device tree blob
1753 * @nodeoffset: offset of the node whose property to change
1754 * @name: name of the property to change
1755 * @val: 64-bit integer value to append to the property (native endian)
1756 *
1757 * fdt_appendprop_u64() appends the given 64-bit integer value
1758 * (converting to big-endian if necessary) to the value of the named
1759 * property in the given node, or creates a new property with that
1760 * value if it does not already exist.
1761 *
1762 * This function may insert data into the blob, and will therefore
1763 * change the offsets of some existing nodes.
1764 *
1765 * returns:
1766 *      0, on success
1767 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1768 *              contain the new property value
1769 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1770 *      -FDT_ERR_BADLAYOUT,
1771 *      -FDT_ERR_BADMAGIC,
1772 *      -FDT_ERR_BADVERSION,
1773 *      -FDT_ERR_BADSTATE,
1774 *      -FDT_ERR_BADSTRUCTURE,
1775 *      -FDT_ERR_BADLAYOUT,
1776 *      -FDT_ERR_TRUNCATED, standard meanings
1777 */
1778static inline int fdt_appendprop_u64(void *fdt, int nodeoffset,
1779                                     const char *name, uint64_t val)
1780{
1781        fdt64_t tmp = cpu_to_fdt64(val);
1782        return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
1783}
1784
1785/**
1786 * fdt_appendprop_cell - append a single cell value to a property
1787 *
1788 * This is an alternative name for fdt_appendprop_u32()
1789 */
1790static inline int fdt_appendprop_cell(void *fdt, int nodeoffset,
1791                                      const char *name, uint32_t val)
1792{
1793        return fdt_appendprop_u32(fdt, nodeoffset, name, val);
1794}
1795
1796/**
1797 * fdt_appendprop_string - append a string to a property
1798 * @fdt: pointer to the device tree blob
1799 * @nodeoffset: offset of the node whose property to change
1800 * @name: name of the property to change
1801 * @str: string value to append to the property
1802 *
1803 * fdt_appendprop_string() appends the given string to the value of
1804 * the named property in the given node, or creates a new property
1805 * with that value if it does not already exist.
1806 *
1807 * This function may insert data into the blob, and will therefore
1808 * change the offsets of some existing nodes.
1809 *
1810 * returns:
1811 *      0, on success
1812 *      -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1813 *              contain the new property value
1814 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1815 *      -FDT_ERR_BADLAYOUT,
1816 *      -FDT_ERR_BADMAGIC,
1817 *      -FDT_ERR_BADVERSION,
1818 *      -FDT_ERR_BADSTATE,
1819 *      -FDT_ERR_BADSTRUCTURE,
1820 *      -FDT_ERR_BADLAYOUT,
1821 *      -FDT_ERR_TRUNCATED, standard meanings
1822 */
1823#define fdt_appendprop_string(fdt, nodeoffset, name, str) \
1824        fdt_appendprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)
1825
1826/**
1827 * fdt_delprop - delete a property
1828 * @fdt: pointer to the device tree blob
1829 * @nodeoffset: offset of the node whose property to nop
1830 * @name: name of the property to nop
1831 *
1832 * fdt_del_property() will delete the given property.
1833 *
1834 * This function will delete data from the blob, and will therefore
1835 * change the offsets of some existing nodes.
1836 *
1837 * returns:
1838 *      0, on success
1839 *      -FDT_ERR_NOTFOUND, node does not have the named property
1840 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1841 *      -FDT_ERR_BADLAYOUT,
1842 *      -FDT_ERR_BADMAGIC,
1843 *      -FDT_ERR_BADVERSION,
1844 *      -FDT_ERR_BADSTATE,
1845 *      -FDT_ERR_BADSTRUCTURE,
1846 *      -FDT_ERR_TRUNCATED, standard meanings
1847 */
1848int fdt_delprop(void *fdt, int nodeoffset, const char *name);
1849
1850/**
1851 * fdt_add_subnode_namelen - creates a new node based on substring
1852 * @fdt: pointer to the device tree blob
1853 * @parentoffset: structure block offset of a node
1854 * @name: name of the subnode to locate
1855 * @namelen: number of characters of name to consider
1856 *
1857 * Identical to fdt_add_subnode(), but use only the first namelen
1858 * characters of name as the name of the new node.  This is useful for
1859 * creating subnodes based on a portion of a larger string, such as a
1860 * full path.
1861 */
1862#ifndef SWIG /* Not available in Python */
1863int fdt_add_subnode_namelen(void *fdt, int parentoffset,
1864                            const char *name, int namelen);
1865#endif
1866
1867/**
1868 * fdt_add_subnode - creates a new node
1869 * @fdt: pointer to the device tree blob
1870 * @parentoffset: structure block offset of a node
1871 * @name: name of the subnode to locate
1872 *
1873 * fdt_add_subnode() creates a new node as a subnode of the node at
1874 * structure block offset parentoffset, with the given name (which
1875 * should include the unit address, if any).
1876 *
1877 * This function will insert data into the blob, and will therefore
1878 * change the offsets of some existing nodes.
1879
1880 * returns:
1881 *      structure block offset of the created nodeequested subnode (>=0), on
1882 *              success
1883 *      -FDT_ERR_NOTFOUND, if the requested subnode does not exist
1884 *      -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE
1885 *              tag
1886 *      -FDT_ERR_EXISTS, if the node at parentoffset already has a subnode of
1887 *              the given name
1888 *      -FDT_ERR_NOSPACE, if there is insufficient free space in the
1889 *              blob to contain the new node
1890 *      -FDT_ERR_NOSPACE
1891 *      -FDT_ERR_BADLAYOUT
1892 *      -FDT_ERR_BADMAGIC,
1893 *      -FDT_ERR_BADVERSION,
1894 *      -FDT_ERR_BADSTATE,
1895 *      -FDT_ERR_BADSTRUCTURE,
1896 *      -FDT_ERR_TRUNCATED, standard meanings.
1897 */
1898int fdt_add_subnode(void *fdt, int parentoffset, const char *name);
1899
1900/**
1901 * fdt_del_node - delete a node (subtree)
1902 * @fdt: pointer to the device tree blob
1903 * @nodeoffset: offset of the node to nop
1904 *
1905 * fdt_del_node() will remove the given node, including all its
1906 * subnodes if any, from the blob.
1907 *
1908 * This function will delete data from the blob, and will therefore
1909 * change the offsets of some existing nodes.
1910 *
1911 * returns:
1912 *      0, on success
1913 *      -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1914 *      -FDT_ERR_BADLAYOUT,
1915 *      -FDT_ERR_BADMAGIC,
1916 *      -FDT_ERR_BADVERSION,
1917 *      -FDT_ERR_BADSTATE,
1918 *      -FDT_ERR_BADSTRUCTURE,
1919 *      -FDT_ERR_TRUNCATED, standard meanings
1920 */
1921int fdt_del_node(void *fdt, int nodeoffset);
1922
1923/**
1924 * fdt_overlay_apply - Applies a DT overlay on a base DT
1925 * @fdt: pointer to the base device tree blob
1926 * @fdto: pointer to the device tree overlay blob
1927 *
1928 * fdt_overlay_apply() will apply the given device tree overlay on the
1929 * given base device tree.
1930 *
1931 * Expect the base device tree to be modified, even if the function
1932 * returns an error.
1933 *
1934 * returns:
1935 *      0, on success
1936 *      -FDT_ERR_NOSPACE, there's not enough space in the base device tree
1937 *      -FDT_ERR_NOTFOUND, the overlay points to some inexistant nodes or
1938 *              properties in the base DT
1939 *      -FDT_ERR_BADPHANDLE,
1940 *      -FDT_ERR_BADOVERLAY,
1941 *      -FDT_ERR_NOPHANDLES,
1942 *      -FDT_ERR_INTERNAL,
1943 *      -FDT_ERR_BADLAYOUT,
1944 *      -FDT_ERR_BADMAGIC,
1945 *      -FDT_ERR_BADOFFSET,
1946 *      -FDT_ERR_BADPATH,
1947 *      -FDT_ERR_BADVERSION,
1948 *      -FDT_ERR_BADSTRUCTURE,
1949 *      -FDT_ERR_BADSTATE,
1950 *      -FDT_ERR_TRUNCATED, standard meanings
1951 */
1952int fdt_overlay_apply(void *fdt, void *fdto);
1953
1954/**********************************************************************/
1955/* Debugging / informational functions                                */
1956/**********************************************************************/
1957
1958const char *fdt_strerror(int errval);
1959
1960#endif /* LIBFDT_H */
Note: See TracBrowser for help on using the repository browser.