source: rtems/cpukit/include/libfdt.h @ 3848f14b

5
Last change on this file since 3848f14b was 3848f14b, checked in by Simon Glass <sjg@…>, on Jun 6, 2018 at 9:37:05 PM

pylibfdt: Add functions to update properties

Allow updating and creating properties, including special methods for
integers.

Signed-off-by: Simon Glass <sjg@…>
Reviewed-by: David Gibson <david@…>
Signed-off-by: David Gibson <david@…>

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