blob: b6a400a7a823ea2bd6a04e6fe3bbe7807a2252bb [file] [log] [blame]
Kumar Gala8d04f022007-10-24 11:04:22 -05001#ifndef _LIBFDT_H
2#define _LIBFDT_H
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04003/*
4 * libfdt - Flat Device Tree manipulation
5 * Copyright (C) 2006 David Gibson, IBM Corporation.
6 *
Kumar Gala8d04f022007-10-24 11:04:22 -05007 * libfdt is dual licensed: you can use it either under the terms of
8 * the GPL, or the BSD license, at your option.
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04009 *
Kumar Gala8d04f022007-10-24 11:04:22 -050010 * 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.
Gerald Van Baren7cd5da02007-03-31 11:59:59 -040014 *
Kumar Gala8d04f022007-10-24 11:04:22 -050015 * 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.
Gerald Van Baren7cd5da02007-03-31 11:59:59 -040052 */
53
Gerald Van Baren7cd5da02007-03-31 11:59:59 -040054#include <libfdt_env.h>
Kumar Gala8d04f022007-10-24 11:04:22 -050055#include <fdt.h>
Gerald Van Baren7cd5da02007-03-31 11:59:59 -040056
57#define FDT_FIRST_SUPPORTED_VERSION 0x10
58#define FDT_LAST_SUPPORTED_VERSION 0x11
59
60/* Error codes: informative error codes */
61#define FDT_ERR_NOTFOUND 1
Kumar Gala8d04f022007-10-24 11:04:22 -050062 /* FDT_ERR_NOTFOUND: The requested node or property does not exist */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -040063#define FDT_ERR_EXISTS 2
Kumar Gala8d04f022007-10-24 11:04:22 -050064 /* FDT_ERR_EXISTS: Attemped to create a node or property which
65 * already exists */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -040066#define FDT_ERR_NOSPACE 3
Kumar Gala8d04f022007-10-24 11:04:22 -050067 /* 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. */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -040071
72/* Error codes: codes for bad parameters */
73#define FDT_ERR_BADOFFSET 4
Kumar Gala8d04f022007-10-24 11:04:22 -050074 /* 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. */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -040077#define FDT_ERR_BADPATH 5
Kumar Gala8d04f022007-10-24 11:04:22 -050078 /* FDT_ERR_BADPATH: Function was passed a badly formatted path
79 * (e.g. missing a leading / for a function which requires an
80 * absolute path) */
81#define FDT_ERR_BADPHANDLE 6
82 /* FDT_ERR_BADPHANDLE: Function was passed an invalid phandle
83 * value. phandle values of 0 and -1 are not permitted. */
84#define FDT_ERR_BADSTATE 7
85 /* FDT_ERR_BADSTATE: Function was passed an incomplete device
86 * tree created by the sequential-write functions, which is
87 * not sufficiently complete for the requested operation. */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -040088
89/* Error codes: codes for bad device tree blobs */
Kumar Gala8d04f022007-10-24 11:04:22 -050090#define FDT_ERR_TRUNCATED 8
91 /* FDT_ERR_TRUNCATED: Structure block of the given device tree
92 * ends without an FDT_END tag. */
93#define FDT_ERR_BADMAGIC 9
94 /* FDT_ERR_BADMAGIC: Given "device tree" appears not to be a
95 * device tree at all - it is missing the flattened device
96 * tree magic number. */
97#define FDT_ERR_BADVERSION 10
98 /* FDT_ERR_BADVERSION: Given device tree has a version which
99 * can't be handled by the requested operation. For
100 * read-write functions, this may mean that fdt_open_into() is
101 * required to convert the tree to the expected version. */
102#define FDT_ERR_BADSTRUCTURE 11
103 /* FDT_ERR_BADSTRUCTURE: Given device tree has a corrupt
104 * structure block or other serious error (e.g. misnested
105 * nodes, or subnodes preceding properties). */
106#define FDT_ERR_BADLAYOUT 12
107 /* FDT_ERR_BADLAYOUT: For read-write functions, the given
108 * device tree has it's sub-blocks in an order that the
109 * function can't handle (memory reserve map, then structure,
110 * then strings). Use fdt_open_into() to reorganize the tree
111 * into a form suitable for the read-write operations. */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400112
Kumar Gala8d04f022007-10-24 11:04:22 -0500113/* "Can't happen" error indicating a bug in libfdt */
114#define FDT_ERR_INTERNAL 13
115 /* FDT_ERR_INTERNAL: libfdt has failed an internal assertion.
116 * Should never be returned, if it is, it indicates a bug in
117 * libfdt itself. */
118
Simon Glass0596d352014-07-30 03:59:03 -0600119/* Errors in device tree content */
120#define FDT_ERR_BADNCELLS 14
121 /* FDT_ERR_BADNCELLS: Device tree has a #address-cells, #size-cells
122 * or similar property with a bad format or value */
123
Simon Glassc3c4c002015-06-23 15:38:27 -0600124#define FDT_ERR_TOODEEP 15
125 /* FDT_ERR_TOODEEP: The depth of a node has exceeded the internal
126 * libfdt limit. This can happen if you have more than
127 * FDT_MAX_DEPTH nested nodes. */
128
129#define FDT_ERR_MAX 15
Kumar Gala8d04f022007-10-24 11:04:22 -0500130
131/**********************************************************************/
132/* Low-level functions (you probably don't need these) */
133/**********************************************************************/
134
Jon Loeliger741a6d02008-09-25 11:02:17 -0500135const void *fdt_offset_ptr(const void *fdt, int offset, unsigned int checklen);
Kumar Gala8d04f022007-10-24 11:04:22 -0500136static inline void *fdt_offset_ptr_w(void *fdt, int offset, int checklen)
137{
David Gibsonc6683022008-07-07 10:14:15 +1000138 return (void *)(uintptr_t)fdt_offset_ptr(fdt, offset, checklen);
Kumar Gala8d04f022007-10-24 11:04:22 -0500139}
140
141uint32_t fdt_next_tag(const void *fdt, int offset, int *nextoffset);
142
143/**********************************************************************/
David Gibsonae0b5902008-02-12 11:58:31 +1100144/* Traversal functions */
145/**********************************************************************/
146
147int fdt_next_node(const void *fdt, int offset, int *depth);
148
Simon Glass88f95bb2013-05-07 06:11:50 +0000149/**
150 * fdt_first_subnode() - get offset of first direct subnode
151 *
152 * @fdt: FDT blob
153 * @offset: Offset of node to check
154 * @return offset of first subnode, or -FDT_ERR_NOTFOUND if there is none
155 */
156int fdt_first_subnode(const void *fdt, int offset);
157
158/**
159 * fdt_next_subnode() - get offset of next direct subnode
160 *
161 * After first calling fdt_first_subnode(), call this function repeatedly to
162 * get direct subnodes of a parent node.
163 *
164 * @fdt: FDT blob
165 * @offset: Offset of previous subnode
166 * @return offset of next subnode, or -FDT_ERR_NOTFOUND if there are no more
167 * subnodes
168 */
169int fdt_next_subnode(const void *fdt, int offset);
170
Thierry Reding2f376042014-08-26 17:33:55 +0200171/**
172 * fdt_for_each_subnode - iterate over all subnodes of a parent
173 *
174 * This is actually a wrapper around a for loop and would be used like so:
175 *
176 * fdt_for_each_subnode(fdt, node, parent) {
177 * ...
178 * use node
179 * ...
180 * }
181 *
182 * Note that this is implemented as a macro and node is used as iterator in
183 * the loop. It should therefore be a locally allocated variable. The parent
184 * variable on the other hand is never modified, so it can be constant or
185 * even a literal.
186 *
187 * @fdt: FDT blob (const void *)
188 * @node: child node (int)
189 * @parent: parent node (int)
190 */
191#define fdt_for_each_subnode(fdt, node, parent) \
192 for (node = fdt_first_subnode(fdt, parent); \
193 node >= 0; \
194 node = fdt_next_subnode(fdt, node))
195
David Gibsonae0b5902008-02-12 11:58:31 +1100196/**********************************************************************/
Kumar Gala8d04f022007-10-24 11:04:22 -0500197/* General functions */
198/**********************************************************************/
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400199
200#define fdt_get_header(fdt, field) \
Kumar Gala8d04f022007-10-24 11:04:22 -0500201 (fdt32_to_cpu(((const struct fdt_header *)(fdt))->field))
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200202#define fdt_magic(fdt) (fdt_get_header(fdt, magic))
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400203#define fdt_totalsize(fdt) (fdt_get_header(fdt, totalsize))
204#define fdt_off_dt_struct(fdt) (fdt_get_header(fdt, off_dt_struct))
205#define fdt_off_dt_strings(fdt) (fdt_get_header(fdt, off_dt_strings))
206#define fdt_off_mem_rsvmap(fdt) (fdt_get_header(fdt, off_mem_rsvmap))
207#define fdt_version(fdt) (fdt_get_header(fdt, version))
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200208#define fdt_last_comp_version(fdt) (fdt_get_header(fdt, last_comp_version))
209#define fdt_boot_cpuid_phys(fdt) (fdt_get_header(fdt, boot_cpuid_phys))
210#define fdt_size_dt_strings(fdt) (fdt_get_header(fdt, size_dt_strings))
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400211#define fdt_size_dt_struct(fdt) (fdt_get_header(fdt, size_dt_struct))
212
Kumar Gala8d04f022007-10-24 11:04:22 -0500213#define __fdt_set_hdr(name) \
214 static inline void fdt_set_##name(void *fdt, uint32_t val) \
215 { \
Laurent Gregoire67b89c72009-03-03 14:23:59 +0100216 struct fdt_header *fdth = (struct fdt_header*)fdt; \
Kumar Gala8d04f022007-10-24 11:04:22 -0500217 fdth->name = cpu_to_fdt32(val); \
218 }
219__fdt_set_hdr(magic);
220__fdt_set_hdr(totalsize);
221__fdt_set_hdr(off_dt_struct);
222__fdt_set_hdr(off_dt_strings);
223__fdt_set_hdr(off_mem_rsvmap);
224__fdt_set_hdr(version);
225__fdt_set_hdr(last_comp_version);
226__fdt_set_hdr(boot_cpuid_phys);
227__fdt_set_hdr(size_dt_strings);
228__fdt_set_hdr(size_dt_struct);
229#undef __fdt_set_hdr
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400230
Kumar Gala8d04f022007-10-24 11:04:22 -0500231/**
232 * fdt_check_header - sanity check a device tree or possible device tree
233 * @fdt: pointer to data which might be a flattened device tree
234 *
235 * fdt_check_header() checks that the given buffer contains what
236 * appears to be a flattened device tree with sane information in its
237 * header.
238 *
239 * returns:
240 * 0, if the buffer appears to contain a valid device tree
241 * -FDT_ERR_BADMAGIC,
242 * -FDT_ERR_BADVERSION,
243 * -FDT_ERR_BADSTATE, standard meanings, as above
244 */
Gerald Van Baren6679f922007-04-06 14:17:14 -0400245int fdt_check_header(const void *fdt);
246
Kumar Gala8d04f022007-10-24 11:04:22 -0500247/**
248 * fdt_move - move a device tree around in memory
249 * @fdt: pointer to the device tree to move
250 * @buf: pointer to memory where the device is to be moved
251 * @bufsize: size of the memory space at buf
252 *
253 * fdt_move() relocates, if possible, the device tree blob located at
254 * fdt to the buffer at buf of size bufsize. The buffer may overlap
255 * with the existing device tree blob at fdt. Therefore,
256 * fdt_move(fdt, fdt, fdt_totalsize(fdt))
257 * should always succeed.
258 *
259 * returns:
260 * 0, on success
261 * -FDT_ERR_NOSPACE, bufsize is insufficient to contain the device tree
262 * -FDT_ERR_BADMAGIC,
263 * -FDT_ERR_BADVERSION,
264 * -FDT_ERR_BADSTATE, standard meanings
265 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400266int fdt_move(const void *fdt, void *buf, int bufsize);
267
Kumar Gala8d04f022007-10-24 11:04:22 -0500268/**********************************************************************/
269/* Read-only functions */
270/**********************************************************************/
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400271
Kumar Gala8d04f022007-10-24 11:04:22 -0500272/**
Wolfram Sang46390da2008-07-09 11:22:44 +0200273 * fdt_string - retrieve a string from the strings block of a device tree
Kumar Gala8d04f022007-10-24 11:04:22 -0500274 * @fdt: pointer to the device tree blob
275 * @stroffset: offset of the string within the strings block (native endian)
276 *
277 * fdt_string() retrieves a pointer to a single string from the
278 * strings block of the device tree blob at fdt.
279 *
280 * returns:
281 * a pointer to the string, on success
282 * NULL, if stroffset is out of bounds
283 */
284const char *fdt_string(const void *fdt, int stroffset);
285
286/**
Maxime Ripard57c78092016-07-05 10:26:39 +0200287 * fdt_get_max_phandle - retrieves the highest phandle in a tree
288 * @fdt: pointer to the device tree blob
289 *
290 * fdt_get_max_phandle retrieves the highest phandle in the given
291 * device tree
292 *
293 * returns:
294 * the highest phandle on success
295 * 0, if an error occurred
296 */
297uint32_t fdt_get_max_phandle(const void *fdt);
298
299/**
Wolfram Sang46390da2008-07-09 11:22:44 +0200300 * fdt_num_mem_rsv - retrieve the number of memory reserve map entries
Kumar Gala8d04f022007-10-24 11:04:22 -0500301 * @fdt: pointer to the device tree blob
302 *
303 * Returns the number of entries in the device tree blob's memory
304 * reservation map. This does not include the terminating 0,0 entry
305 * or any other (0,0) entries reserved for expansion.
306 *
307 * returns:
308 * the number of entries
309 */
310int fdt_num_mem_rsv(const void *fdt);
311
312/**
Wolfram Sang46390da2008-07-09 11:22:44 +0200313 * fdt_get_mem_rsv - retrieve one memory reserve map entry
Kumar Gala8d04f022007-10-24 11:04:22 -0500314 * @fdt: pointer to the device tree blob
315 * @address, @size: pointers to 64-bit variables
316 *
317 * On success, *address and *size will contain the address and size of
318 * the n-th reserve map entry from the device tree blob, in
319 * native-endian format.
320 *
321 * returns:
322 * 0, on success
323 * -FDT_ERR_BADMAGIC,
324 * -FDT_ERR_BADVERSION,
325 * -FDT_ERR_BADSTATE, standard meanings
326 */
327int fdt_get_mem_rsv(const void *fdt, int n, uint64_t *address, uint64_t *size);
328
329/**
330 * fdt_subnode_offset_namelen - find a subnode based on substring
331 * @fdt: pointer to the device tree blob
332 * @parentoffset: structure block offset of a node
333 * @name: name of the subnode to locate
334 * @namelen: number of characters of name to consider
335 *
336 * Identical to fdt_subnode_offset(), but only examine the first
337 * namelen characters of name for matching the subnode name. This is
338 * useful for finding subnodes based on a portion of a larger string,
339 * such as a full path.
340 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400341int fdt_subnode_offset_namelen(const void *fdt, int parentoffset,
342 const char *name, int namelen);
Kumar Gala8d04f022007-10-24 11:04:22 -0500343/**
344 * fdt_subnode_offset - find a subnode of a given node
345 * @fdt: pointer to the device tree blob
346 * @parentoffset: structure block offset of a node
347 * @name: name of the subnode to locate
348 *
349 * fdt_subnode_offset() finds a subnode of the node at structure block
350 * offset parentoffset with the given name. name may include a unit
351 * address, in which case fdt_subnode_offset() will find the subnode
352 * with that unit address, or the unit address may be omitted, in
353 * which case fdt_subnode_offset() will find an arbitrary subnode
354 * whose name excluding unit address matches the given name.
355 *
356 * returns:
357 * structure block offset of the requested subnode (>=0), on success
358 * -FDT_ERR_NOTFOUND, if the requested subnode does not exist
359 * -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE tag
360 * -FDT_ERR_BADMAGIC,
361 * -FDT_ERR_BADVERSION,
362 * -FDT_ERR_BADSTATE,
363 * -FDT_ERR_BADSTRUCTURE,
364 * -FDT_ERR_TRUNCATED, standard meanings.
365 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400366int fdt_subnode_offset(const void *fdt, int parentoffset, const char *name);
367
Kumar Gala8d04f022007-10-24 11:04:22 -0500368/**
Maxime Ripard8e968572016-07-05 10:26:41 +0200369 * fdt_path_offset_namelen - find a tree node based on substring
370 * @fdt: pointer to the device tree blob
371 * @path: full path of the node to locate
372 * @namelen: number of characters of name to consider
373 *
374 * Identical to fdt_path_offset(), but only examine the first
375 * namelen characters of path for matching the node path.
376 */
377int fdt_path_offset_namelen(const void *fdt, const char *path, int namelen);
378
379/**
Kumar Gala8d04f022007-10-24 11:04:22 -0500380 * fdt_path_offset - find a tree node by its full path
381 * @fdt: pointer to the device tree blob
382 * @path: full path of the node to locate
383 *
384 * fdt_path_offset() finds a node of a given path in the device tree.
385 * Each path component may omit the unit address portion, but the
386 * results of this are undefined if any such path component is
387 * ambiguous (that is if there are multiple nodes at the relevant
388 * level matching the given component, differentiated only by unit
389 * address).
390 *
391 * returns:
392 * structure block offset of the node with the requested path (>=0), on success
393 * -FDT_ERR_BADPATH, given path does not begin with '/' or is invalid
394 * -FDT_ERR_NOTFOUND, if the requested node does not exist
395 * -FDT_ERR_BADMAGIC,
396 * -FDT_ERR_BADVERSION,
397 * -FDT_ERR_BADSTATE,
398 * -FDT_ERR_BADSTRUCTURE,
399 * -FDT_ERR_TRUNCATED, standard meanings.
400 */
Maxime Ripard8e968572016-07-05 10:26:41 +0200401static inline int fdt_path_offset(const void *fdt, const char *path)
402{
403 return fdt_path_offset_namelen(fdt, path, strlen(path));
404}
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400405
Kumar Gala8d04f022007-10-24 11:04:22 -0500406/**
Wolfram Sang46390da2008-07-09 11:22:44 +0200407 * fdt_get_name - retrieve the name of a given node
Kumar Gala8d04f022007-10-24 11:04:22 -0500408 * @fdt: pointer to the device tree blob
409 * @nodeoffset: structure block offset of the starting node
410 * @lenp: pointer to an integer variable (will be overwritten) or NULL
411 *
412 * fdt_get_name() retrieves the name (including unit address) of the
413 * device tree node at structure block offset nodeoffset. If lenp is
414 * non-NULL, the length of this name is also returned, in the integer
415 * pointed to by lenp.
416 *
417 * returns:
418 * pointer to the node's name, on success
419 * If lenp is non-NULL, *lenp contains the length of that name (>=0)
420 * NULL, on error
421 * if lenp is non-NULL *lenp contains an error code (<0):
422 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
423 * -FDT_ERR_BADMAGIC,
424 * -FDT_ERR_BADVERSION,
425 * -FDT_ERR_BADSTATE, standard meanings
426 */
427const char *fdt_get_name(const void *fdt, int nodeoffset, int *lenp);
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400428
Kumar Gala8d04f022007-10-24 11:04:22 -0500429/**
David Gibsond1c63142010-03-09 17:39:14 +1100430 * fdt_first_property_offset - find the offset of a node's first property
431 * @fdt: pointer to the device tree blob
432 * @nodeoffset: structure block offset of a node
433 *
434 * fdt_first_property_offset() finds the first property of the node at
435 * the given structure block offset.
436 *
437 * returns:
438 * structure block offset of the property (>=0), on success
439 * -FDT_ERR_NOTFOUND, if the requested node has no properties
440 * -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_BEGIN_NODE tag
441 * -FDT_ERR_BADMAGIC,
442 * -FDT_ERR_BADVERSION,
443 * -FDT_ERR_BADSTATE,
444 * -FDT_ERR_BADSTRUCTURE,
445 * -FDT_ERR_TRUNCATED, standard meanings.
446 */
447int fdt_first_property_offset(const void *fdt, int nodeoffset);
448
449/**
450 * fdt_next_property_offset - step through a node's properties
451 * @fdt: pointer to the device tree blob
452 * @offset: structure block offset of a property
453 *
454 * fdt_next_property_offset() finds the property immediately after the
455 * one at the given structure block offset. This will be a property
456 * of the same node as the given property.
457 *
458 * returns:
459 * structure block offset of the next property (>=0), on success
460 * -FDT_ERR_NOTFOUND, if the given property is the last in its node
461 * -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_PROP tag
462 * -FDT_ERR_BADMAGIC,
463 * -FDT_ERR_BADVERSION,
464 * -FDT_ERR_BADSTATE,
465 * -FDT_ERR_BADSTRUCTURE,
466 * -FDT_ERR_TRUNCATED, standard meanings.
467 */
468int fdt_next_property_offset(const void *fdt, int offset);
469
470/**
Maxime Ripard67e610d2016-07-05 10:26:38 +0200471 * fdt_for_each_property - iterate over all properties of a node
472 * @property_offset: property offset (int)
473 * @fdt: FDT blob (const void *)
474 * @node: node offset (int)
475 *
476 * This is actually a wrapper around a for loop and would be used like so:
477 *
478 * fdt_for_each_property(fdt, node, property) {
479 * ...
480 * use property
481 * ...
482 * }
483 *
484 * Note that this is implemented as a macro and property is used as
485 * iterator in the loop. It should therefore be a locally allocated
486 * variable. The node variable on the other hand is never modified, so
487 * it can be constant or even a literal.
488 */
489#define fdt_for_each_property_offset(property, fdt, node) \
490 for (property = fdt_first_property_offset(fdt, node); \
491 property >= 0; \
492 property = fdt_next_property_offset(fdt, property))
493
494/**
David Gibsond1c63142010-03-09 17:39:14 +1100495 * fdt_get_property_by_offset - retrieve the property at a given offset
496 * @fdt: pointer to the device tree blob
497 * @offset: offset of the property to retrieve
498 * @lenp: pointer to an integer variable (will be overwritten) or NULL
499 *
500 * fdt_get_property_by_offset() retrieves a pointer to the
501 * fdt_property structure within the device tree blob at the given
502 * offset. If lenp is non-NULL, the length of the property value is
503 * also returned, in the integer pointed to by lenp.
504 *
505 * returns:
506 * pointer to the structure representing the property
507 * if lenp is non-NULL, *lenp contains the length of the property
508 * value (>=0)
509 * NULL, on error
510 * if lenp is non-NULL, *lenp contains an error code (<0):
511 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
512 * -FDT_ERR_BADMAGIC,
513 * -FDT_ERR_BADVERSION,
514 * -FDT_ERR_BADSTATE,
515 * -FDT_ERR_BADSTRUCTURE,
516 * -FDT_ERR_TRUNCATED, standard meanings
517 */
518const struct fdt_property *fdt_get_property_by_offset(const void *fdt,
519 int offset,
520 int *lenp);
521
522/**
David Gibson02193992008-08-06 14:50:49 +1000523 * fdt_get_property_namelen - find a property based on substring
524 * @fdt: pointer to the device tree blob
525 * @nodeoffset: offset of the node whose property to find
526 * @name: name of the property to find
527 * @namelen: number of characters of name to consider
528 * @lenp: pointer to an integer variable (will be overwritten) or NULL
529 *
530 * Identical to fdt_get_property_namelen(), but only examine the first
531 * namelen characters of name for matching the property name.
532 */
533const struct fdt_property *fdt_get_property_namelen(const void *fdt,
534 int nodeoffset,
535 const char *name,
536 int namelen, int *lenp);
537
538/**
Kumar Gala8d04f022007-10-24 11:04:22 -0500539 * fdt_get_property - find a given property in a given node
540 * @fdt: pointer to the device tree blob
541 * @nodeoffset: offset of the node whose property to find
542 * @name: name of the property to find
543 * @lenp: pointer to an integer variable (will be overwritten) or NULL
544 *
545 * fdt_get_property() retrieves a pointer to the fdt_property
546 * structure within the device tree blob corresponding to the property
547 * named 'name' of the node at offset nodeoffset. If lenp is
Wolfram Sang46390da2008-07-09 11:22:44 +0200548 * non-NULL, the length of the property value is also returned, in the
Kumar Gala8d04f022007-10-24 11:04:22 -0500549 * integer pointed to by lenp.
550 *
551 * returns:
552 * pointer to the structure representing the property
553 * if lenp is non-NULL, *lenp contains the length of the property
554 * value (>=0)
555 * NULL, on error
556 * if lenp is non-NULL, *lenp contains an error code (<0):
557 * -FDT_ERR_NOTFOUND, node does not have named property
558 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
559 * -FDT_ERR_BADMAGIC,
560 * -FDT_ERR_BADVERSION,
561 * -FDT_ERR_BADSTATE,
562 * -FDT_ERR_BADSTRUCTURE,
563 * -FDT_ERR_TRUNCATED, standard meanings
564 */
565const struct fdt_property *fdt_get_property(const void *fdt, int nodeoffset,
566 const char *name, int *lenp);
567static inline struct fdt_property *fdt_get_property_w(void *fdt, int nodeoffset,
568 const char *name,
569 int *lenp)
570{
David Gibsonc6683022008-07-07 10:14:15 +1000571 return (struct fdt_property *)(uintptr_t)
572 fdt_get_property(fdt, nodeoffset, name, lenp);
Kumar Gala8d04f022007-10-24 11:04:22 -0500573}
Gerald Van Baren3af0d582007-03-31 12:13:43 -0400574
Kumar Gala8d04f022007-10-24 11:04:22 -0500575/**
David Gibsond1c63142010-03-09 17:39:14 +1100576 * fdt_getprop_by_offset - retrieve the value of a property at a given offset
577 * @fdt: pointer to the device tree blob
578 * @ffset: offset of the property to read
579 * @namep: pointer to a string variable (will be overwritten) or NULL
580 * @lenp: pointer to an integer variable (will be overwritten) or NULL
581 *
582 * fdt_getprop_by_offset() retrieves a pointer to the value of the
583 * property at structure block offset 'offset' (this will be a pointer
584 * to within the device blob itself, not a copy of the value). If
585 * lenp is non-NULL, the length of the property value is also
586 * returned, in the integer pointed to by lenp. If namep is non-NULL,
587 * the property's namne will also be returned in the char * pointed to
588 * by namep (this will be a pointer to within the device tree's string
589 * block, not a new copy of the name).
590 *
591 * returns:
592 * pointer to the property's value
593 * if lenp is non-NULL, *lenp contains the length of the property
594 * value (>=0)
595 * if namep is non-NULL *namep contiains a pointer to the property
596 * name.
597 * NULL, on error
598 * if lenp is non-NULL, *lenp contains an error code (<0):
599 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
600 * -FDT_ERR_BADMAGIC,
601 * -FDT_ERR_BADVERSION,
602 * -FDT_ERR_BADSTATE,
603 * -FDT_ERR_BADSTRUCTURE,
604 * -FDT_ERR_TRUNCATED, standard meanings
605 */
606const void *fdt_getprop_by_offset(const void *fdt, int offset,
607 const char **namep, int *lenp);
608
609/**
David Gibson02193992008-08-06 14:50:49 +1000610 * fdt_getprop_namelen - get property value based on substring
611 * @fdt: pointer to the device tree blob
612 * @nodeoffset: offset of the node whose property to find
613 * @name: name of the property to find
614 * @namelen: number of characters of name to consider
615 * @lenp: pointer to an integer variable (will be overwritten) or NULL
616 *
617 * Identical to fdt_getprop(), but only examine the first namelen
618 * characters of name for matching the property name.
619 */
620const void *fdt_getprop_namelen(const void *fdt, int nodeoffset,
621 const char *name, int namelen, int *lenp);
Maxime Ripard2b941bf2016-07-05 10:26:42 +0200622static inline void *fdt_getprop_namelen_w(void *fdt, int nodeoffset,
623 const char *name, int namelen,
624 int *lenp)
625{
626 return (void *)(uintptr_t)fdt_getprop_namelen(fdt, nodeoffset, name,
627 namelen, lenp);
628}
David Gibson02193992008-08-06 14:50:49 +1000629
630/**
Kumar Gala8d04f022007-10-24 11:04:22 -0500631 * fdt_getprop - retrieve the value of a given property
632 * @fdt: pointer to the device tree blob
633 * @nodeoffset: offset of the node whose property to find
634 * @name: name of the property to find
635 * @lenp: pointer to an integer variable (will be overwritten) or NULL
636 *
637 * fdt_getprop() retrieves a pointer to the value of the property
638 * named 'name' of the node at offset nodeoffset (this will be a
639 * pointer to within the device blob itself, not a copy of the value).
Wolfram Sang46390da2008-07-09 11:22:44 +0200640 * If lenp is non-NULL, the length of the property value is also
Kumar Gala8d04f022007-10-24 11:04:22 -0500641 * returned, in the integer pointed to by lenp.
642 *
643 * returns:
644 * pointer to the property's value
645 * if lenp is non-NULL, *lenp contains the length of the property
646 * value (>=0)
647 * NULL, on error
648 * if lenp is non-NULL, *lenp contains an error code (<0):
649 * -FDT_ERR_NOTFOUND, node does not have named property
650 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
651 * -FDT_ERR_BADMAGIC,
652 * -FDT_ERR_BADVERSION,
653 * -FDT_ERR_BADSTATE,
654 * -FDT_ERR_BADSTRUCTURE,
655 * -FDT_ERR_TRUNCATED, standard meanings
656 */
657const void *fdt_getprop(const void *fdt, int nodeoffset,
658 const char *name, int *lenp);
659static inline void *fdt_getprop_w(void *fdt, int nodeoffset,
660 const char *name, int *lenp)
661{
David Gibsonc6683022008-07-07 10:14:15 +1000662 return (void *)(uintptr_t)fdt_getprop(fdt, nodeoffset, name, lenp);
Kumar Gala8d04f022007-10-24 11:04:22 -0500663}
664
665/**
Wolfram Sang46390da2008-07-09 11:22:44 +0200666 * fdt_get_phandle - retrieve the phandle of a given node
Kumar Gala8d04f022007-10-24 11:04:22 -0500667 * @fdt: pointer to the device tree blob
668 * @nodeoffset: structure block offset of the node
669 *
670 * fdt_get_phandle() retrieves the phandle of the device tree node at
671 * structure block offset nodeoffset.
672 *
673 * returns:
Wolfram Sang46390da2008-07-09 11:22:44 +0200674 * the phandle of the node at nodeoffset, on success (!= 0, != -1)
Kumar Gala8d04f022007-10-24 11:04:22 -0500675 * 0, if the node has no phandle, or another error occurs
676 */
677uint32_t fdt_get_phandle(const void *fdt, int nodeoffset);
678
679/**
Gerald Van Barencd3cb0d2008-10-04 07:56:06 -0400680 * fdt_get_alias_namelen - get alias based on substring
David Gibson9a6cf732008-08-20 16:55:14 +1000681 * @fdt: pointer to the device tree blob
682 * @name: name of the alias th look up
683 * @namelen: number of characters of name to consider
684 *
685 * Identical to fdt_get_alias(), but only examine the first namelen
686 * characters of name for matching the alias name.
687 */
688const char *fdt_get_alias_namelen(const void *fdt,
689 const char *name, int namelen);
690
691/**
Simon Glass0596d352014-07-30 03:59:03 -0600692 * fdt_get_alias - retreive the path referenced by a given alias
David Gibson9a6cf732008-08-20 16:55:14 +1000693 * @fdt: pointer to the device tree blob
Simon Glass0596d352014-07-30 03:59:03 -0600694 * @name: name of the alias th look up
David Gibson9a6cf732008-08-20 16:55:14 +1000695 *
696 * fdt_get_alias() retrieves the value of a given alias. That is, the
697 * value of the property named 'name' in the node /aliases.
698 *
699 * returns:
François Revolc73bd492013-02-03 00:52:21 +0100700 * a pointer to the expansion of the alias named 'name', if it exists
David Gibson9a6cf732008-08-20 16:55:14 +1000701 * NULL, if the given alias or the /aliases node does not exist
702 */
703const char *fdt_get_alias(const void *fdt, const char *name);
704
705/**
Kumar Gala8d04f022007-10-24 11:04:22 -0500706 * fdt_get_path - determine the full path of a node
707 * @fdt: pointer to the device tree blob
708 * @nodeoffset: offset of the node whose path to find
709 * @buf: character buffer to contain the returned path (will be overwritten)
710 * @buflen: size of the character buffer at buf
711 *
712 * fdt_get_path() computes the full path of the node at offset
713 * nodeoffset, and records that path in the buffer at buf.
714 *
715 * NOTE: This function is expensive, as it must scan the device tree
716 * structure from the start to nodeoffset.
717 *
718 * returns:
719 * 0, on success
720 * buf contains the absolute path of the node at
721 * nodeoffset, as a NUL-terminated string.
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200722 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500723 * -FDT_ERR_NOSPACE, the path of the given node is longer than (bufsize-1)
724 * characters and will not fit in the given buffer.
725 * -FDT_ERR_BADMAGIC,
726 * -FDT_ERR_BADVERSION,
727 * -FDT_ERR_BADSTATE,
728 * -FDT_ERR_BADSTRUCTURE, standard meanings
729 */
730int fdt_get_path(const void *fdt, int nodeoffset, char *buf, int buflen);
731
732/**
733 * fdt_supernode_atdepth_offset - find a specific ancestor of a node
734 * @fdt: pointer to the device tree blob
735 * @nodeoffset: offset of the node whose parent to find
736 * @supernodedepth: depth of the ancestor to find
737 * @nodedepth: pointer to an integer variable (will be overwritten) or NULL
738 *
739 * fdt_supernode_atdepth_offset() finds an ancestor of the given node
740 * at a specific depth from the root (where the root itself has depth
741 * 0, its immediate subnodes depth 1 and so forth). So
742 * fdt_supernode_atdepth_offset(fdt, nodeoffset, 0, NULL);
743 * will always return 0, the offset of the root node. If the node at
744 * nodeoffset has depth D, then:
745 * fdt_supernode_atdepth_offset(fdt, nodeoffset, D, NULL);
746 * will return nodeoffset itself.
747 *
748 * NOTE: This function is expensive, as it must scan the device tree
749 * structure from the start to nodeoffset.
750 *
751 * returns:
752
753 * structure block offset of the node at node offset's ancestor
754 * of depth supernodedepth (>=0), on success
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200755 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500756* -FDT_ERR_NOTFOUND, supernodedepth was greater than the depth of nodeoffset
757 * -FDT_ERR_BADMAGIC,
758 * -FDT_ERR_BADVERSION,
759 * -FDT_ERR_BADSTATE,
760 * -FDT_ERR_BADSTRUCTURE, standard meanings
761 */
762int fdt_supernode_atdepth_offset(const void *fdt, int nodeoffset,
763 int supernodedepth, int *nodedepth);
764
765/**
766 * fdt_node_depth - find the depth of a given node
767 * @fdt: pointer to the device tree blob
768 * @nodeoffset: offset of the node whose parent to find
769 *
770 * fdt_node_depth() finds the depth of a given node. The root node
771 * has depth 0, its immediate subnodes depth 1 and so forth.
772 *
773 * NOTE: This function is expensive, as it must scan the device tree
774 * structure from the start to nodeoffset.
775 *
776 * returns:
777 * depth of the node at nodeoffset (>=0), on success
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200778 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500779 * -FDT_ERR_BADMAGIC,
780 * -FDT_ERR_BADVERSION,
781 * -FDT_ERR_BADSTATE,
782 * -FDT_ERR_BADSTRUCTURE, standard meanings
783 */
784int fdt_node_depth(const void *fdt, int nodeoffset);
785
786/**
787 * fdt_parent_offset - find the parent of a given node
788 * @fdt: pointer to the device tree blob
789 * @nodeoffset: offset of the node whose parent to find
790 *
791 * fdt_parent_offset() locates the parent node of a given node (that
792 * is, it finds the offset of the node which contains the node at
793 * nodeoffset as a subnode).
794 *
795 * NOTE: This function is expensive, as it must scan the device tree
796 * structure from the start to nodeoffset, *twice*.
797 *
798 * returns:
Wolfram Sang46390da2008-07-09 11:22:44 +0200799 * structure block offset of the parent of the node at nodeoffset
Kumar Gala8d04f022007-10-24 11:04:22 -0500800 * (>=0), on success
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200801 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500802 * -FDT_ERR_BADMAGIC,
803 * -FDT_ERR_BADVERSION,
804 * -FDT_ERR_BADSTATE,
805 * -FDT_ERR_BADSTRUCTURE, standard meanings
806 */
807int fdt_parent_offset(const void *fdt, int nodeoffset);
808
809/**
810 * fdt_node_offset_by_prop_value - find nodes with a given property value
811 * @fdt: pointer to the device tree blob
812 * @startoffset: only find nodes after this offset
813 * @propname: property name to check
814 * @propval: property value to search for
815 * @proplen: length of the value in propval
816 *
817 * fdt_node_offset_by_prop_value() returns the offset of the first
818 * node after startoffset, which has a property named propname whose
819 * value is of length proplen and has value equal to propval; or if
820 * startoffset is -1, the very first such node in the tree.
821 *
822 * To iterate through all nodes matching the criterion, the following
823 * idiom can be used:
824 * offset = fdt_node_offset_by_prop_value(fdt, -1, propname,
825 * propval, proplen);
826 * while (offset != -FDT_ERR_NOTFOUND) {
Simon Glass0596d352014-07-30 03:59:03 -0600827 * // other code here
Kumar Gala8d04f022007-10-24 11:04:22 -0500828 * offset = fdt_node_offset_by_prop_value(fdt, offset, propname,
829 * propval, proplen);
830 * }
831 *
832 * Note the -1 in the first call to the function, if 0 is used here
833 * instead, the function will never locate the root node, even if it
834 * matches the criterion.
835 *
836 * returns:
837 * structure block offset of the located node (>= 0, >startoffset),
838 * on success
839 * -FDT_ERR_NOTFOUND, no node matching the criterion exists in the
840 * tree after startoffset
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200841 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500842 * -FDT_ERR_BADMAGIC,
843 * -FDT_ERR_BADVERSION,
844 * -FDT_ERR_BADSTATE,
845 * -FDT_ERR_BADSTRUCTURE, standard meanings
846 */
847int fdt_node_offset_by_prop_value(const void *fdt, int startoffset,
848 const char *propname,
849 const void *propval, int proplen);
850
851/**
852 * fdt_node_offset_by_phandle - find the node with a given phandle
853 * @fdt: pointer to the device tree blob
854 * @phandle: phandle value
855 *
Wolfram Sang46390da2008-07-09 11:22:44 +0200856 * fdt_node_offset_by_phandle() returns the offset of the node
Kumar Gala8d04f022007-10-24 11:04:22 -0500857 * which has the given phandle value. If there is more than one node
858 * in the tree with the given phandle (an invalid tree), results are
859 * undefined.
860 *
861 * returns:
862 * structure block offset of the located node (>= 0), on success
863 * -FDT_ERR_NOTFOUND, no node with that phandle exists
864 * -FDT_ERR_BADPHANDLE, given phandle value was invalid (0 or -1)
865 * -FDT_ERR_BADMAGIC,
866 * -FDT_ERR_BADVERSION,
867 * -FDT_ERR_BADSTATE,
868 * -FDT_ERR_BADSTRUCTURE, standard meanings
869 */
870int fdt_node_offset_by_phandle(const void *fdt, uint32_t phandle);
871
872/**
873 * fdt_node_check_compatible: check a node's compatible property
874 * @fdt: pointer to the device tree blob
875 * @nodeoffset: offset of a tree node
876 * @compatible: string to match against
877 *
878 *
879 * fdt_node_check_compatible() returns 0 if the given node contains a
880 * 'compatible' property with the given string as one of its elements,
881 * it returns non-zero otherwise, or on error.
882 *
883 * returns:
884 * 0, if the node has a 'compatible' property listing the given string
885 * 1, if the node has a 'compatible' property, but it does not list
886 * the given string
887 * -FDT_ERR_NOTFOUND, if the given node has no 'compatible' property
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200888 * -FDT_ERR_BADOFFSET, if nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500889 * -FDT_ERR_BADMAGIC,
890 * -FDT_ERR_BADVERSION,
891 * -FDT_ERR_BADSTATE,
892 * -FDT_ERR_BADSTRUCTURE, standard meanings
893 */
894int fdt_node_check_compatible(const void *fdt, int nodeoffset,
895 const char *compatible);
896
897/**
898 * fdt_node_offset_by_compatible - find nodes with a given 'compatible' value
899 * @fdt: pointer to the device tree blob
900 * @startoffset: only find nodes after this offset
901 * @compatible: 'compatible' string to match against
902 *
903 * fdt_node_offset_by_compatible() returns the offset of the first
904 * node after startoffset, which has a 'compatible' property which
905 * lists the given compatible string; or if startoffset is -1, the
906 * very first such node in the tree.
907 *
908 * To iterate through all nodes matching the criterion, the following
909 * idiom can be used:
910 * offset = fdt_node_offset_by_compatible(fdt, -1, compatible);
911 * while (offset != -FDT_ERR_NOTFOUND) {
Simon Glass0596d352014-07-30 03:59:03 -0600912 * // other code here
Kumar Gala8d04f022007-10-24 11:04:22 -0500913 * offset = fdt_node_offset_by_compatible(fdt, offset, compatible);
914 * }
915 *
916 * Note the -1 in the first call to the function, if 0 is used here
917 * instead, the function will never locate the root node, even if it
918 * matches the criterion.
919 *
920 * returns:
921 * structure block offset of the located node (>= 0, >startoffset),
922 * on success
923 * -FDT_ERR_NOTFOUND, no node matching the criterion exists in the
924 * tree after startoffset
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200925 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500926 * -FDT_ERR_BADMAGIC,
927 * -FDT_ERR_BADVERSION,
928 * -FDT_ERR_BADSTATE,
929 * -FDT_ERR_BADSTRUCTURE, standard meanings
930 */
931int fdt_node_offset_by_compatible(const void *fdt, int startoffset,
932 const char *compatible);
933
Simon Glasse853b322013-01-21 12:59:18 -0800934/**
935 * fdt_stringlist_contains - check a string list property for a string
936 * @strlist: Property containing a list of strings to check
937 * @listlen: Length of property
938 * @str: String to search for
939 *
940 * This is a utility function provided for convenience. The list contains
941 * one or more strings, each terminated by \0, as is found in a device tree
942 * "compatible" property.
943 *
944 * @return: 1 if the string is found in the list, 0 not found, or invalid list
945 */
946int fdt_stringlist_contains(const char *strlist, int listlen, const char *str);
947
Thierry Redingbc4147a2014-08-26 17:33:50 +0200948/**
949 * fdt_count_strings - count the number of strings in a string list
950 * @fdt: pointer to the device tree blob
951 * @node: offset of the node
952 * @property: name of the property containing the string list
953 * @return: the number of strings in the given property
954 */
955int fdt_count_strings(const void *fdt, int node, const char *property);
956
Thierry Redingfc503c12014-08-26 17:33:51 +0200957/**
958 * fdt_find_string - find a string in a string list and return its index
959 * @fdt: pointer to the device tree blob
960 * @node: offset of the node
961 * @property: name of the property containing the string list
962 * @string: string to look up in the string list
963 * @return: the index of the string or negative on error
964 */
965int fdt_find_string(const void *fdt, int node, const char *property,
966 const char *string);
967
Thierry Reding5094eb42014-08-26 17:33:52 +0200968/**
969 * fdt_get_string_index() - obtain the string at a given index in a string list
970 * @fdt: pointer to the device tree blob
971 * @node: offset of the node
972 * @property: name of the property containing the string list
973 * @index: index of the string to return
974 * @output: return location for the string
975 * @return: 0 if the string was found or a negative error code otherwise
976 */
977int fdt_get_string_index(const void *fdt, int node, const char *property,
978 int index, const char **output);
979
980/**
Masahiro Yamada965fab12015-07-15 01:08:42 +0900981 * fdt_get_string() - obtain the first string in a string list
Thierry Reding5094eb42014-08-26 17:33:52 +0200982 * @fdt: pointer to the device tree blob
983 * @node: offset of the node
984 * @property: name of the property containing the string list
985 * @output: return location for the string
986 * @return: 0 if the string was found or a negative error code otherwise
987 *
988 * This is a shortcut for:
989 *
990 * fdt_get_string_index(fdt, node, property, 0, output).
991 */
992int fdt_get_string(const void *fdt, int node, const char *property,
993 const char **output);
994
Kumar Gala8d04f022007-10-24 11:04:22 -0500995/**********************************************************************/
Simon Glass0596d352014-07-30 03:59:03 -0600996/* Read-only functions (addressing related) */
997/**********************************************************************/
998
999/**
1000 * FDT_MAX_NCELLS - maximum value for #address-cells and #size-cells
1001 *
1002 * This is the maximum value for #address-cells, #size-cells and
1003 * similar properties that will be processed by libfdt. IEE1275
1004 * requires that OF implementations handle values up to 4.
1005 * Implementations may support larger values, but in practice higher
1006 * values aren't used.
1007 */
1008#define FDT_MAX_NCELLS 4
1009
1010/**
1011 * fdt_address_cells - retrieve address size for a bus represented in the tree
1012 * @fdt: pointer to the device tree blob
1013 * @nodeoffset: offset of the node to find the address size for
1014 *
1015 * When the node has a valid #address-cells property, returns its value.
1016 *
1017 * returns:
1018 * 0 <= n < FDT_MAX_NCELLS, on success
1019 * 2, if the node has no #address-cells property
1020 * -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid
1021 * #address-cells property
1022 * -FDT_ERR_BADMAGIC,
1023 * -FDT_ERR_BADVERSION,
1024 * -FDT_ERR_BADSTATE,
1025 * -FDT_ERR_BADSTRUCTURE,
1026 * -FDT_ERR_TRUNCATED, standard meanings
1027 */
1028int fdt_address_cells(const void *fdt, int nodeoffset);
1029
1030/**
1031 * fdt_size_cells - retrieve address range size for a bus represented in the
1032 * tree
1033 * @fdt: pointer to the device tree blob
1034 * @nodeoffset: offset of the node to find the address range size for
1035 *
1036 * When the node has a valid #size-cells property, returns its value.
1037 *
1038 * returns:
1039 * 0 <= n < FDT_MAX_NCELLS, on success
1040 * 2, if the node has no #address-cells property
1041 * -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid
1042 * #size-cells property
1043 * -FDT_ERR_BADMAGIC,
1044 * -FDT_ERR_BADVERSION,
1045 * -FDT_ERR_BADSTATE,
1046 * -FDT_ERR_BADSTRUCTURE,
1047 * -FDT_ERR_TRUNCATED, standard meanings
1048 */
1049int fdt_size_cells(const void *fdt, int nodeoffset);
1050
1051
1052/**********************************************************************/
Kumar Gala8d04f022007-10-24 11:04:22 -05001053/* Write-in-place functions */
1054/**********************************************************************/
1055
David Gibson9d4450b2007-12-17 14:41:52 +11001056/**
Maxime Ripardea7b1a22016-07-05 10:26:43 +02001057 * fdt_setprop_inplace_namelen_partial - change a property's value,
1058 * but not its size
1059 * @fdt: pointer to the device tree blob
1060 * @nodeoffset: offset of the node whose property to change
1061 * @name: name of the property to change
1062 * @namelen: number of characters of name to consider
1063 * @index: index of the property to change in the array
1064 * @val: pointer to data to replace the property value with
1065 * @len: length of the property value
1066 *
1067 * Identical to fdt_setprop_inplace(), but modifies the given property
1068 * starting from the given index, and using only the first characters
1069 * of the name. It is useful when you want to manipulate only one value of
1070 * an array and you have a string that doesn't end with \0.
1071 */
1072int fdt_setprop_inplace_namelen_partial(void *fdt, int nodeoffset,
1073 const char *name, int namelen,
1074 uint32_t index, const void *val,
1075 int len);
1076
1077/**
David Gibson9d4450b2007-12-17 14:41:52 +11001078 * fdt_setprop_inplace - change a property's value, but not its size
1079 * @fdt: pointer to the device tree blob
1080 * @nodeoffset: offset of the node whose property to change
1081 * @name: name of the property to change
1082 * @val: pointer to data to replace the property value with
1083 * @len: length of the property value
1084 *
1085 * fdt_setprop_inplace() replaces the value of a given property with
1086 * the data in val, of length len. This function cannot change the
1087 * size of a property, and so will only work if len is equal to the
1088 * current length of the property.
1089 *
1090 * This function will alter only the bytes in the blob which contain
1091 * the given property value, and will not alter or move any other part
1092 * of the tree.
1093 *
1094 * returns:
1095 * 0, on success
1096 * -FDT_ERR_NOSPACE, if len is not equal to the property's current length
1097 * -FDT_ERR_NOTFOUND, node does not have the named property
1098 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1099 * -FDT_ERR_BADMAGIC,
1100 * -FDT_ERR_BADVERSION,
1101 * -FDT_ERR_BADSTATE,
1102 * -FDT_ERR_BADSTRUCTURE,
1103 * -FDT_ERR_TRUNCATED, standard meanings
1104 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001105int fdt_setprop_inplace(void *fdt, int nodeoffset, const char *name,
1106 const void *val, int len);
David Gibson9d4450b2007-12-17 14:41:52 +11001107
1108/**
David Gibson24fa0e52012-08-27 19:39:00 -05001109 * fdt_setprop_inplace_u32 - change the value of a 32-bit integer property
David Gibson9d4450b2007-12-17 14:41:52 +11001110 * @fdt: pointer to the device tree blob
1111 * @nodeoffset: offset of the node whose property to change
1112 * @name: name of the property to change
David Gibson24fa0e52012-08-27 19:39:00 -05001113 * @val: 32-bit integer value to replace the property with
David Gibson9d4450b2007-12-17 14:41:52 +11001114 *
David Gibson24fa0e52012-08-27 19:39:00 -05001115 * fdt_setprop_inplace_u32() replaces the value of a given property
1116 * with the 32-bit integer value in val, converting val to big-endian
1117 * if necessary. This function cannot change the size of a property,
1118 * and so will only work if the property already exists and has length
1119 * 4.
David Gibson9d4450b2007-12-17 14:41:52 +11001120 *
1121 * This function will alter only the bytes in the blob which contain
1122 * the given property value, and will not alter or move any other part
1123 * of the tree.
1124 *
1125 * returns:
1126 * 0, on success
1127 * -FDT_ERR_NOSPACE, if the property's length is not equal to 4
David Gibson24fa0e52012-08-27 19:39:00 -05001128 * -FDT_ERR_NOTFOUND, node does not have the named property
David Gibson9d4450b2007-12-17 14:41:52 +11001129 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1130 * -FDT_ERR_BADMAGIC,
1131 * -FDT_ERR_BADVERSION,
1132 * -FDT_ERR_BADSTATE,
1133 * -FDT_ERR_BADSTRUCTURE,
1134 * -FDT_ERR_TRUNCATED, standard meanings
1135 */
David Gibson24fa0e52012-08-27 19:39:00 -05001136static inline int fdt_setprop_inplace_u32(void *fdt, int nodeoffset,
1137 const char *name, uint32_t val)
Kumar Gala8d04f022007-10-24 11:04:22 -05001138{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001139 fdt32_t tmp = cpu_to_fdt32(val);
1140 return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
Kumar Gala8d04f022007-10-24 11:04:22 -05001141}
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001142
David Gibson9d4450b2007-12-17 14:41:52 +11001143/**
David Gibson24fa0e52012-08-27 19:39:00 -05001144 * fdt_setprop_inplace_u64 - change the value of a 64-bit integer property
1145 * @fdt: pointer to the device tree blob
1146 * @nodeoffset: offset of the node whose property to change
1147 * @name: name of the property to change
1148 * @val: 64-bit integer value to replace the property with
1149 *
1150 * fdt_setprop_inplace_u64() replaces the value of a given property
1151 * with the 64-bit integer value in val, converting val to big-endian
1152 * if necessary. This function cannot change the size of a property,
1153 * and so will only work if the property already exists and has length
1154 * 8.
1155 *
1156 * This function will alter only the bytes in the blob which contain
1157 * the given property value, and will not alter or move any other part
1158 * of the tree.
1159 *
1160 * returns:
1161 * 0, on success
1162 * -FDT_ERR_NOSPACE, if the property's length is not equal to 8
1163 * -FDT_ERR_NOTFOUND, node does not have the named property
1164 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1165 * -FDT_ERR_BADMAGIC,
1166 * -FDT_ERR_BADVERSION,
1167 * -FDT_ERR_BADSTATE,
1168 * -FDT_ERR_BADSTRUCTURE,
1169 * -FDT_ERR_TRUNCATED, standard meanings
1170 */
1171static inline int fdt_setprop_inplace_u64(void *fdt, int nodeoffset,
1172 const char *name, uint64_t val)
1173{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001174 fdt64_t tmp = cpu_to_fdt64(val);
1175 return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
David Gibson24fa0e52012-08-27 19:39:00 -05001176}
1177
1178/**
1179 * fdt_setprop_inplace_cell - change the value of a single-cell property
1180 *
1181 * This is an alternative name for fdt_setprop_inplace_u32()
1182 */
1183static inline int fdt_setprop_inplace_cell(void *fdt, int nodeoffset,
1184 const char *name, uint32_t val)
1185{
1186 return fdt_setprop_inplace_u32(fdt, nodeoffset, name, val);
1187}
1188
1189/**
David Gibson9d4450b2007-12-17 14:41:52 +11001190 * fdt_nop_property - replace a property with nop tags
1191 * @fdt: pointer to the device tree blob
1192 * @nodeoffset: offset of the node whose property to nop
1193 * @name: name of the property to nop
1194 *
1195 * fdt_nop_property() will replace a given property's representation
1196 * in the blob with FDT_NOP tags, effectively removing it from the
1197 * tree.
1198 *
1199 * This function will alter only the bytes in the blob which contain
1200 * the property, and will not alter or move any other part of the
1201 * tree.
1202 *
1203 * returns:
1204 * 0, on success
1205 * -FDT_ERR_NOTFOUND, node does not have the named property
1206 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1207 * -FDT_ERR_BADMAGIC,
1208 * -FDT_ERR_BADVERSION,
1209 * -FDT_ERR_BADSTATE,
1210 * -FDT_ERR_BADSTRUCTURE,
1211 * -FDT_ERR_TRUNCATED, standard meanings
1212 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001213int fdt_nop_property(void *fdt, int nodeoffset, const char *name);
David Gibson9d4450b2007-12-17 14:41:52 +11001214
1215/**
1216 * fdt_nop_node - replace a node (subtree) with nop tags
1217 * @fdt: pointer to the device tree blob
1218 * @nodeoffset: offset of the node to nop
1219 *
1220 * fdt_nop_node() will replace a given node's representation in the
1221 * blob, including all its subnodes, if any, with FDT_NOP tags,
1222 * effectively removing it from the tree.
1223 *
1224 * This function will alter only the bytes in the blob which contain
1225 * the node and its properties and subnodes, and will not alter or
1226 * move any other part of the tree.
1227 *
1228 * returns:
1229 * 0, on success
1230 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1231 * -FDT_ERR_BADMAGIC,
1232 * -FDT_ERR_BADVERSION,
1233 * -FDT_ERR_BADSTATE,
1234 * -FDT_ERR_BADSTRUCTURE,
1235 * -FDT_ERR_TRUNCATED, standard meanings
1236 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001237int fdt_nop_node(void *fdt, int nodeoffset);
Gerald Van Baren3f9f08c2007-04-14 22:46:41 -04001238
Kumar Gala8d04f022007-10-24 11:04:22 -05001239/**********************************************************************/
1240/* Sequential write functions */
1241/**********************************************************************/
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001242
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001243int fdt_create(void *buf, int bufsize);
Simon Glass0596d352014-07-30 03:59:03 -06001244int fdt_resize(void *fdt, void *buf, int bufsize);
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001245int fdt_add_reservemap_entry(void *fdt, uint64_t addr, uint64_t size);
1246int fdt_finish_reservemap(void *fdt);
1247int fdt_begin_node(void *fdt, const char *name);
1248int fdt_property(void *fdt, const char *name, const void *val, int len);
David Gibson24fa0e52012-08-27 19:39:00 -05001249static inline int fdt_property_u32(void *fdt, const char *name, uint32_t val)
Kumar Gala8d04f022007-10-24 11:04:22 -05001250{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001251 fdt32_t tmp = cpu_to_fdt32(val);
1252 return fdt_property(fdt, name, &tmp, sizeof(tmp));
Kumar Gala8d04f022007-10-24 11:04:22 -05001253}
David Gibson24fa0e52012-08-27 19:39:00 -05001254static inline int fdt_property_u64(void *fdt, const char *name, uint64_t val)
1255{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001256 fdt64_t tmp = cpu_to_fdt64(val);
1257 return fdt_property(fdt, name, &tmp, sizeof(tmp));
David Gibson24fa0e52012-08-27 19:39:00 -05001258}
1259static inline int fdt_property_cell(void *fdt, const char *name, uint32_t val)
1260{
1261 return fdt_property_u32(fdt, name, val);
1262}
Simon Glassf8a2d7a2016-02-22 22:55:39 -07001263
1264/**
1265 * fdt_property_placeholder - add a new property and return a ptr to its value
1266 *
1267 * @fdt: pointer to the device tree blob
1268 * @name: name of property to add
1269 * @len: length of property value in bytes
1270 * @valp: returns a pointer to where where the value should be placed
1271 *
1272 * returns:
1273 * 0, on success
1274 * -FDT_ERR_BADMAGIC,
1275 * -FDT_ERR_NOSPACE, standard meanings
1276 */
1277int fdt_property_placeholder(void *fdt, const char *name, int len, void **valp);
1278
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001279#define fdt_property_string(fdt, name, str) \
1280 fdt_property(fdt, name, str, strlen(str)+1)
1281int fdt_end_node(void *fdt);
1282int fdt_finish(void *fdt);
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001283
Kumar Gala8d04f022007-10-24 11:04:22 -05001284/**********************************************************************/
1285/* Read-write functions */
1286/**********************************************************************/
1287
Gerald Van Barenc71b64f2012-10-15 22:24:36 -04001288int fdt_create_empty_tree(void *buf, int bufsize);
Kumar Gala8d04f022007-10-24 11:04:22 -05001289int fdt_open_into(const void *fdt, void *buf, int bufsize);
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001290int fdt_pack(void *fdt);
1291
David Gibsonaec71352007-12-17 14:42:07 +11001292/**
1293 * fdt_add_mem_rsv - add one memory reserve map entry
1294 * @fdt: pointer to the device tree blob
Wolfram Sang46390da2008-07-09 11:22:44 +02001295 * @address, @size: 64-bit values (native endian)
David Gibsonaec71352007-12-17 14:42:07 +11001296 *
1297 * Adds a reserve map entry to the given blob reserving a region at
1298 * address address of length size.
1299 *
1300 * This function will insert data into the reserve map and will
Wolfram Sang46390da2008-07-09 11:22:44 +02001301 * therefore change the indexes of some entries in the table.
David Gibsonaec71352007-12-17 14:42:07 +11001302 *
1303 * returns:
1304 * 0, on success
1305 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1306 * contain the new reservation entry
1307 * -FDT_ERR_BADMAGIC,
1308 * -FDT_ERR_BADVERSION,
1309 * -FDT_ERR_BADSTATE,
1310 * -FDT_ERR_BADSTRUCTURE,
1311 * -FDT_ERR_BADLAYOUT,
1312 * -FDT_ERR_TRUNCATED, standard meanings
1313 */
Kumar Gala8d04f022007-10-24 11:04:22 -05001314int fdt_add_mem_rsv(void *fdt, uint64_t address, uint64_t size);
David Gibsonaec71352007-12-17 14:42:07 +11001315
1316/**
1317 * fdt_del_mem_rsv - remove a memory reserve map entry
1318 * @fdt: pointer to the device tree blob
1319 * @n: entry to remove
1320 *
1321 * fdt_del_mem_rsv() removes the n-th memory reserve map entry from
1322 * the blob.
1323 *
1324 * This function will delete data from the reservation table and will
Wolfram Sang46390da2008-07-09 11:22:44 +02001325 * therefore change the indexes of some entries in the table.
David Gibsonaec71352007-12-17 14:42:07 +11001326 *
1327 * returns:
1328 * 0, on success
1329 * -FDT_ERR_NOTFOUND, there is no entry of the given index (i.e. there
1330 * are less than n+1 reserve map entries)
1331 * -FDT_ERR_BADMAGIC,
1332 * -FDT_ERR_BADVERSION,
1333 * -FDT_ERR_BADSTATE,
1334 * -FDT_ERR_BADSTRUCTURE,
1335 * -FDT_ERR_BADLAYOUT,
1336 * -FDT_ERR_TRUNCATED, standard meanings
1337 */
Kumar Gala8d04f022007-10-24 11:04:22 -05001338int fdt_del_mem_rsv(void *fdt, int n);
1339
David Gibsonaec71352007-12-17 14:42:07 +11001340/**
David Gibson9eaeb072008-01-11 14:55:05 +11001341 * fdt_set_name - change the name of a given node
1342 * @fdt: pointer to the device tree blob
1343 * @nodeoffset: structure block offset of a node
1344 * @name: name to give the node
1345 *
1346 * fdt_set_name() replaces the name (including unit address, if any)
1347 * of the given node with the given string. NOTE: this function can't
1348 * efficiently check if the new name is unique amongst the given
1349 * node's siblings; results are undefined if this function is invoked
1350 * with a name equal to one of the given node's siblings.
1351 *
1352 * This function may insert or delete data from the blob, and will
1353 * therefore change the offsets of some existing nodes.
1354 *
1355 * returns:
1356 * 0, on success
1357 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob
1358 * to contain the new name
1359 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1360 * -FDT_ERR_BADMAGIC,
1361 * -FDT_ERR_BADVERSION,
1362 * -FDT_ERR_BADSTATE, standard meanings
1363 */
1364int fdt_set_name(void *fdt, int nodeoffset, const char *name);
1365
1366/**
David Gibsonaec71352007-12-17 14:42:07 +11001367 * fdt_setprop - create or change a property
1368 * @fdt: pointer to the device tree blob
1369 * @nodeoffset: offset of the node whose property to change
1370 * @name: name of the property to change
1371 * @val: pointer to data to set the property value to
1372 * @len: length of the property value
1373 *
1374 * fdt_setprop() sets the value of the named property in the given
Wolfram Sang46390da2008-07-09 11:22:44 +02001375 * node to the given value and length, creating the property if it
David Gibsonaec71352007-12-17 14:42:07 +11001376 * does not already exist.
1377 *
1378 * This function may insert or delete data from the blob, and will
1379 * therefore change the offsets of some existing nodes.
1380 *
1381 * returns:
1382 * 0, on success
1383 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1384 * contain the new property value
1385 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1386 * -FDT_ERR_BADLAYOUT,
1387 * -FDT_ERR_BADMAGIC,
1388 * -FDT_ERR_BADVERSION,
1389 * -FDT_ERR_BADSTATE,
1390 * -FDT_ERR_BADSTRUCTURE,
1391 * -FDT_ERR_BADLAYOUT,
1392 * -FDT_ERR_TRUNCATED, standard meanings
1393 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001394int fdt_setprop(void *fdt, int nodeoffset, const char *name,
1395 const void *val, int len);
David Gibsonaec71352007-12-17 14:42:07 +11001396
1397/**
David Gibson24fa0e52012-08-27 19:39:00 -05001398 * fdt_setprop_u32 - set a property to a 32-bit integer
David Gibsonaec71352007-12-17 14:42:07 +11001399 * @fdt: pointer to the device tree blob
1400 * @nodeoffset: offset of the node whose property to change
1401 * @name: name of the property to change
1402 * @val: 32-bit integer value for the property (native endian)
1403 *
David Gibson24fa0e52012-08-27 19:39:00 -05001404 * fdt_setprop_u32() sets the value of the named property in the given
1405 * node to the given 32-bit integer value (converting to big-endian if
David Gibsonaec71352007-12-17 14:42:07 +11001406 * necessary), or creates a new property with that value if it does
1407 * not already exist.
1408 *
1409 * This function may insert or delete data from the blob, and will
1410 * therefore change the offsets of some existing nodes.
1411 *
1412 * returns:
1413 * 0, on success
1414 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1415 * contain the new property value
1416 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1417 * -FDT_ERR_BADLAYOUT,
1418 * -FDT_ERR_BADMAGIC,
1419 * -FDT_ERR_BADVERSION,
1420 * -FDT_ERR_BADSTATE,
1421 * -FDT_ERR_BADSTRUCTURE,
1422 * -FDT_ERR_BADLAYOUT,
1423 * -FDT_ERR_TRUNCATED, standard meanings
1424 */
David Gibson24fa0e52012-08-27 19:39:00 -05001425static inline int fdt_setprop_u32(void *fdt, int nodeoffset, const char *name,
1426 uint32_t val)
Kumar Gala8d04f022007-10-24 11:04:22 -05001427{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001428 fdt32_t tmp = cpu_to_fdt32(val);
1429 return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
Kumar Gala8d04f022007-10-24 11:04:22 -05001430}
David Gibsonaec71352007-12-17 14:42:07 +11001431
1432/**
David Gibson24fa0e52012-08-27 19:39:00 -05001433 * fdt_setprop_u64 - set a property to a 64-bit integer
1434 * @fdt: pointer to the device tree blob
1435 * @nodeoffset: offset of the node whose property to change
1436 * @name: name of the property to change
1437 * @val: 64-bit integer value for the property (native endian)
1438 *
1439 * fdt_setprop_u64() sets the value of the named property in the given
1440 * node to the given 64-bit integer value (converting to big-endian if
1441 * necessary), or creates a new property with that value if it does
1442 * not already exist.
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 to
1450 * contain the new property value
1451 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1452 * -FDT_ERR_BADLAYOUT,
1453 * -FDT_ERR_BADMAGIC,
1454 * -FDT_ERR_BADVERSION,
1455 * -FDT_ERR_BADSTATE,
1456 * -FDT_ERR_BADSTRUCTURE,
1457 * -FDT_ERR_BADLAYOUT,
1458 * -FDT_ERR_TRUNCATED, standard meanings
1459 */
1460static inline int fdt_setprop_u64(void *fdt, int nodeoffset, const char *name,
1461 uint64_t val)
1462{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001463 fdt64_t tmp = cpu_to_fdt64(val);
1464 return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
David Gibson24fa0e52012-08-27 19:39:00 -05001465}
1466
1467/**
1468 * fdt_setprop_cell - set a property to a single cell value
1469 *
1470 * This is an alternative name for fdt_setprop_u32()
1471 */
1472static inline int fdt_setprop_cell(void *fdt, int nodeoffset, const char *name,
1473 uint32_t val)
1474{
1475 return fdt_setprop_u32(fdt, nodeoffset, name, val);
1476}
1477
1478/**
David Gibsonaec71352007-12-17 14:42:07 +11001479 * fdt_setprop_string - set a property to a string value
1480 * @fdt: pointer to the device tree blob
1481 * @nodeoffset: offset of the node whose property to change
1482 * @name: name of the property to change
1483 * @str: string value for the property
1484 *
1485 * fdt_setprop_string() sets the value of the named property in the
1486 * given node to the given string value (using the length of the
1487 * string to determine the new length of the property), or creates a
1488 * new property with that value if it does not already exist.
1489 *
1490 * This function may insert or delete data from the blob, and will
1491 * therefore change the offsets of some existing nodes.
1492 *
1493 * returns:
1494 * 0, on success
1495 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1496 * contain the new property value
1497 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1498 * -FDT_ERR_BADLAYOUT,
1499 * -FDT_ERR_BADMAGIC,
1500 * -FDT_ERR_BADVERSION,
1501 * -FDT_ERR_BADSTATE,
1502 * -FDT_ERR_BADSTRUCTURE,
1503 * -FDT_ERR_BADLAYOUT,
1504 * -FDT_ERR_TRUNCATED, standard meanings
1505 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001506#define fdt_setprop_string(fdt, nodeoffset, name, str) \
1507 fdt_setprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)
David Gibsonaec71352007-12-17 14:42:07 +11001508
1509/**
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001510 * fdt_appendprop - append to or create a property
1511 * @fdt: pointer to the device tree blob
1512 * @nodeoffset: offset of the node whose property to change
1513 * @name: name of the property to append to
1514 * @val: pointer to data to append to the property value
1515 * @len: length of the data to append to the property value
1516 *
1517 * fdt_appendprop() appends the value to the named property in the
1518 * given node, creating the property if it does not already exist.
1519 *
1520 * This function may insert data into the blob, and will therefore
1521 * change the offsets of some existing nodes.
1522 *
1523 * returns:
1524 * 0, on success
1525 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1526 * contain the new property value
1527 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1528 * -FDT_ERR_BADLAYOUT,
1529 * -FDT_ERR_BADMAGIC,
1530 * -FDT_ERR_BADVERSION,
1531 * -FDT_ERR_BADSTATE,
1532 * -FDT_ERR_BADSTRUCTURE,
1533 * -FDT_ERR_BADLAYOUT,
1534 * -FDT_ERR_TRUNCATED, standard meanings
1535 */
1536int fdt_appendprop(void *fdt, int nodeoffset, const char *name,
1537 const void *val, int len);
1538
1539/**
David Gibson24fa0e52012-08-27 19:39:00 -05001540 * fdt_appendprop_u32 - append a 32-bit integer value to a property
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001541 * @fdt: pointer to the device tree blob
1542 * @nodeoffset: offset of the node whose property to change
1543 * @name: name of the property to change
1544 * @val: 32-bit integer value to append to the property (native endian)
1545 *
David Gibson24fa0e52012-08-27 19:39:00 -05001546 * fdt_appendprop_u32() appends the given 32-bit integer value
1547 * (converting to big-endian if necessary) to the value of the named
1548 * property in the given node, or creates a new property with that
1549 * value if it does not already exist.
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001550 *
1551 * This function may insert data into the blob, and will therefore
1552 * change the offsets of some existing nodes.
1553 *
1554 * returns:
1555 * 0, on success
1556 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1557 * contain the new property value
1558 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1559 * -FDT_ERR_BADLAYOUT,
1560 * -FDT_ERR_BADMAGIC,
1561 * -FDT_ERR_BADVERSION,
1562 * -FDT_ERR_BADSTATE,
1563 * -FDT_ERR_BADSTRUCTURE,
1564 * -FDT_ERR_BADLAYOUT,
1565 * -FDT_ERR_TRUNCATED, standard meanings
1566 */
David Gibson24fa0e52012-08-27 19:39:00 -05001567static inline int fdt_appendprop_u32(void *fdt, int nodeoffset,
1568 const char *name, uint32_t val)
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001569{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001570 fdt32_t tmp = cpu_to_fdt32(val);
1571 return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001572}
1573
1574/**
David Gibson24fa0e52012-08-27 19:39:00 -05001575 * fdt_appendprop_u64 - append a 64-bit integer value to a property
1576 * @fdt: pointer to the device tree blob
1577 * @nodeoffset: offset of the node whose property to change
1578 * @name: name of the property to change
1579 * @val: 64-bit integer value to append to the property (native endian)
1580 *
1581 * fdt_appendprop_u64() appends the given 64-bit integer value
1582 * (converting to big-endian if necessary) to the value of the named
1583 * property in the given node, or creates a new property with that
1584 * value if it does not already exist.
1585 *
1586 * This function may insert data into the blob, and will therefore
1587 * change the offsets of some existing nodes.
1588 *
1589 * returns:
1590 * 0, on success
1591 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1592 * contain the new property value
1593 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1594 * -FDT_ERR_BADLAYOUT,
1595 * -FDT_ERR_BADMAGIC,
1596 * -FDT_ERR_BADVERSION,
1597 * -FDT_ERR_BADSTATE,
1598 * -FDT_ERR_BADSTRUCTURE,
1599 * -FDT_ERR_BADLAYOUT,
1600 * -FDT_ERR_TRUNCATED, standard meanings
1601 */
1602static inline int fdt_appendprop_u64(void *fdt, int nodeoffset,
1603 const char *name, uint64_t val)
1604{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001605 fdt64_t tmp = cpu_to_fdt64(val);
1606 return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
David Gibson24fa0e52012-08-27 19:39:00 -05001607}
1608
1609/**
1610 * fdt_appendprop_cell - append a single cell value to a property
1611 *
1612 * This is an alternative name for fdt_appendprop_u32()
1613 */
1614static inline int fdt_appendprop_cell(void *fdt, int nodeoffset,
1615 const char *name, uint32_t val)
1616{
1617 return fdt_appendprop_u32(fdt, nodeoffset, name, val);
1618}
1619
1620/**
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001621 * fdt_appendprop_string - append a string to a property
1622 * @fdt: pointer to the device tree blob
1623 * @nodeoffset: offset of the node whose property to change
1624 * @name: name of the property to change
1625 * @str: string value to append to the property
1626 *
1627 * fdt_appendprop_string() appends the given string to the value of
1628 * the named property in the given node, or creates a new property
1629 * with that value if it does not already exist.
1630 *
1631 * This function may insert data into the blob, and will therefore
1632 * change the offsets of some existing nodes.
1633 *
1634 * returns:
1635 * 0, on success
1636 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1637 * contain the new property value
1638 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1639 * -FDT_ERR_BADLAYOUT,
1640 * -FDT_ERR_BADMAGIC,
1641 * -FDT_ERR_BADVERSION,
1642 * -FDT_ERR_BADSTATE,
1643 * -FDT_ERR_BADSTRUCTURE,
1644 * -FDT_ERR_BADLAYOUT,
1645 * -FDT_ERR_TRUNCATED, standard meanings
1646 */
1647#define fdt_appendprop_string(fdt, nodeoffset, name, str) \
1648 fdt_appendprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)
1649
1650/**
David Gibsonaec71352007-12-17 14:42:07 +11001651 * fdt_delprop - delete a property
1652 * @fdt: pointer to the device tree blob
1653 * @nodeoffset: offset of the node whose property to nop
1654 * @name: name of the property to nop
1655 *
1656 * fdt_del_property() will delete the given property.
1657 *
1658 * This function will delete data from the blob, and will therefore
1659 * change the offsets of some existing nodes.
1660 *
1661 * returns:
1662 * 0, on success
1663 * -FDT_ERR_NOTFOUND, node does not have the named property
1664 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1665 * -FDT_ERR_BADLAYOUT,
1666 * -FDT_ERR_BADMAGIC,
1667 * -FDT_ERR_BADVERSION,
1668 * -FDT_ERR_BADSTATE,
1669 * -FDT_ERR_BADSTRUCTURE,
1670 * -FDT_ERR_TRUNCATED, standard meanings
1671 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001672int fdt_delprop(void *fdt, int nodeoffset, const char *name);
David Gibsonaec71352007-12-17 14:42:07 +11001673
1674/**
1675 * fdt_add_subnode_namelen - creates a new node based on substring
1676 * @fdt: pointer to the device tree blob
1677 * @parentoffset: structure block offset of a node
1678 * @name: name of the subnode to locate
1679 * @namelen: number of characters of name to consider
1680 *
1681 * Identical to fdt_add_subnode(), but use only the first namelen
1682 * characters of name as the name of the new node. This is useful for
1683 * creating subnodes based on a portion of a larger string, such as a
1684 * full path.
1685 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001686int fdt_add_subnode_namelen(void *fdt, int parentoffset,
1687 const char *name, int namelen);
David Gibsonaec71352007-12-17 14:42:07 +11001688
1689/**
1690 * fdt_add_subnode - creates a new node
1691 * @fdt: pointer to the device tree blob
1692 * @parentoffset: structure block offset of a node
1693 * @name: name of the subnode to locate
1694 *
1695 * fdt_add_subnode() creates a new node as a subnode of the node at
1696 * structure block offset parentoffset, with the given name (which
1697 * should include the unit address, if any).
1698 *
1699 * This function will insert data into the blob, and will therefore
1700 * change the offsets of some existing nodes.
1701
1702 * returns:
1703 * structure block offset of the created nodeequested subnode (>=0), on success
1704 * -FDT_ERR_NOTFOUND, if the requested subnode does not exist
1705 * -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE tag
1706 * -FDT_ERR_EXISTS, if the node at parentoffset already has a subnode of
1707 * the given name
1708 * -FDT_ERR_NOSPACE, if there is insufficient free space in the
1709 * blob to contain the new node
1710 * -FDT_ERR_NOSPACE
1711 * -FDT_ERR_BADLAYOUT
1712 * -FDT_ERR_BADMAGIC,
1713 * -FDT_ERR_BADVERSION,
1714 * -FDT_ERR_BADSTATE,
1715 * -FDT_ERR_BADSTRUCTURE,
1716 * -FDT_ERR_TRUNCATED, standard meanings.
1717 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001718int fdt_add_subnode(void *fdt, int parentoffset, const char *name);
David Gibsonaec71352007-12-17 14:42:07 +11001719
1720/**
1721 * fdt_del_node - delete a node (subtree)
1722 * @fdt: pointer to the device tree blob
1723 * @nodeoffset: offset of the node to nop
1724 *
1725 * fdt_del_node() will remove the given node, including all its
1726 * subnodes if any, from the blob.
1727 *
1728 * This function will delete data from the blob, and will therefore
1729 * change the offsets of some existing nodes.
1730 *
1731 * returns:
1732 * 0, on success
1733 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1734 * -FDT_ERR_BADLAYOUT,
1735 * -FDT_ERR_BADMAGIC,
1736 * -FDT_ERR_BADVERSION,
1737 * -FDT_ERR_BADSTATE,
1738 * -FDT_ERR_BADSTRUCTURE,
1739 * -FDT_ERR_TRUNCATED, standard meanings
1740 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001741int fdt_del_node(void *fdt, int nodeoffset);
1742
Maxime Ripardddf67f72016-07-05 10:26:44 +02001743/**
1744 * fdt_overlay_apply - Applies a DT overlay on a base DT
1745 * @fdt: pointer to the base device tree blob
1746 * @fdto: pointer to the device tree overlay blob
1747 *
1748 * fdt_overlay_apply() will apply the given device tree overlay on the
1749 * given base device tree.
1750 *
1751 * Expect the base device tree to be modified, even if the function
1752 * returns an error.
1753 *
1754 * returns:
1755 * 0, on success
1756 * -FDT_ERR_NOSPACE, there's not enough space in the base device tree
1757 * -FDT_ERR_NOTFOUND, the overlay points to some inexistant nodes or
1758 * properties in the base DT
1759 * -FDT_ERR_BADPHANDLE, the phandles in the overlay do not have the right
1760 * magic
1761 * -FDT_ERR_INTERNAL,
1762 * -FDT_ERR_BADLAYOUT,
1763 * -FDT_ERR_BADMAGIC,
1764 * -FDT_ERR_BADOFFSET,
1765 * -FDT_ERR_BADPATH,
1766 * -FDT_ERR_BADVERSION,
1767 * -FDT_ERR_BADSTRUCTURE,
1768 * -FDT_ERR_BADSTATE,
1769 * -FDT_ERR_TRUNCATED, standard meanings
1770 */
1771int fdt_overlay_apply(void *fdt, void *fdto);
1772
Kumar Gala8d04f022007-10-24 11:04:22 -05001773/**********************************************************************/
1774/* Debugging / informational functions */
1775/**********************************************************************/
1776
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001777const char *fdt_strerror(int errval);
1778
Simon Glass8f6e2e12015-06-23 15:38:26 -06001779/**
1780 * fdt_remove_unused_strings() - Remove any unused strings from an FDT
1781 *
1782 * This creates a new device tree in @new with unused strings removed. The
1783 * called can then use fdt_pack() to minimise the space consumed.
1784 *
1785 * @old: Old device tree blog
1786 * @new: Place to put new device tree blob, which must be as large as
1787 * @old
1788 * @return
1789 * 0, on success
1790 * -FDT_ERR_BADOFFSET, corrupt device tree
1791 * -FDT_ERR_NOSPACE, out of space, which should not happen unless there
1792 * is something very wrong with the device tree input
1793 */
1794int fdt_remove_unused_strings(const void *old, void *new);
1795
Simon Glass3e06cd12013-06-13 15:10:08 -07001796struct fdt_region {
1797 int offset;
1798 int size;
1799};
1800
Simon Glassc3c4c002015-06-23 15:38:27 -06001801/*
1802 * Flags for fdt_find_regions()
1803 *
1804 * Add a region for the string table (always the last region)
1805 */
1806#define FDT_REG_ADD_STRING_TAB (1 << 0)
1807
1808/*
1809 * Add all supernodes of a matching node/property, useful for creating a
1810 * valid subset tree
1811 */
1812#define FDT_REG_SUPERNODES (1 << 1)
1813
1814/* Add the FDT_BEGIN_NODE tags of subnodes, including their names */
1815#define FDT_REG_DIRECT_SUBNODES (1 << 2)
1816
1817/* Add all subnodes of a matching node */
1818#define FDT_REG_ALL_SUBNODES (1 << 3)
1819
1820/* Add a region for the mem_rsvmap table (always the first region) */
1821#define FDT_REG_ADD_MEM_RSVMAP (1 << 4)
1822
1823/* Indicates what an fdt part is (node, property, value) */
1824#define FDT_IS_NODE (1 << 0)
1825#define FDT_IS_PROP (1 << 1)
1826#define FDT_IS_VALUE (1 << 2) /* not supported */
1827#define FDT_IS_COMPAT (1 << 3) /* used internally */
1828#define FDT_NODE_HAS_PROP (1 << 4) /* node contains prop */
1829
1830#define FDT_ANY_GLOBAL (FDT_IS_NODE | FDT_IS_PROP | FDT_IS_VALUE | \
1831 FDT_IS_COMPAT)
1832#define FDT_IS_ANY 0x1f /* all the above */
1833
1834/* We set a reasonable limit on the number of nested nodes */
1835#define FDT_MAX_DEPTH 32
1836
1837/* Decribes what we want to include from the current tag */
1838enum want_t {
1839 WANT_NOTHING,
1840 WANT_NODES_ONLY, /* No properties */
1841 WANT_NODES_AND_PROPS, /* Everything for one level */
1842 WANT_ALL_NODES_AND_PROPS /* Everything for all levels */
1843};
1844
1845/* Keeps track of the state at parent nodes */
1846struct fdt_subnode_stack {
1847 int offset; /* Offset of node */
1848 enum want_t want; /* The 'want' value here */
1849 int included; /* 1 if we included this node, 0 if not */
1850};
1851
1852struct fdt_region_ptrs {
1853 int depth; /* Current tree depth */
1854 int done; /* What we have completed scanning */
1855 enum want_t want; /* What we are currently including */
1856 char *end; /* Pointer to end of full node path */
1857 int nextoffset; /* Next node offset to check */
1858};
1859
1860/* The state of our finding algortihm */
1861struct fdt_region_state {
1862 struct fdt_subnode_stack stack[FDT_MAX_DEPTH]; /* node stack */
1863 struct fdt_region *region; /* Contains list of regions found */
1864 int count; /* Numnber of regions found */
1865 const void *fdt; /* FDT blob */
1866 int max_regions; /* Maximum regions to find */
1867 int can_merge; /* 1 if we can merge with previous region */
1868 int start; /* Start position of current region */
1869 struct fdt_region_ptrs ptrs; /* Pointers for what we are up to */
1870};
1871
Simon Glass3e06cd12013-06-13 15:10:08 -07001872/**
1873 * fdt_find_regions() - find regions in device tree
1874 *
1875 * Given a list of nodes to include and properties to exclude, find
1876 * the regions of the device tree which describe those included parts.
1877 *
1878 * The intent is to get a list of regions which will be invariant provided
1879 * those parts are invariant. For example, if you request a list of regions
1880 * for all nodes but exclude the property "data", then you will get the
1881 * same region contents regardless of any change to "data" properties.
1882 *
1883 * This function can be used to produce a byte-stream to send to a hashing
1884 * function to verify that critical parts of the FDT have not changed.
1885 *
1886 * Nodes which are given in 'inc' are included in the region list, as
1887 * are the names of the immediate subnodes nodes (but not the properties
1888 * or subnodes of those subnodes).
1889 *
1890 * For eaxample "/" means to include the root node, all root properties
1891 * and the FDT_BEGIN_NODE and FDT_END_NODE of all subnodes of /. The latter
1892 * ensures that we capture the names of the subnodes. In a hashing situation
1893 * it prevents the root node from changing at all Any change to non-excluded
1894 * properties, names of subnodes or number of subnodes would be detected.
1895 *
1896 * When used with FITs this provides the ability to hash and sign parts of
1897 * the FIT based on different configurations in the FIT. Then it is
1898 * impossible to change anything about that configuration (include images
1899 * attached to the configuration), but it may be possible to add new
1900 * configurations, new images or new signatures within the existing
1901 * framework.
1902 *
1903 * Adding new properties to a device tree may result in the string table
1904 * being extended (if the new property names are different from those
1905 * already added). This function can optionally include a region for
1906 * the string table so that this can be part of the hash too.
1907 *
1908 * The device tree header is not included in the list.
1909 *
1910 * @fdt: Device tree to check
1911 * @inc: List of node paths to included
1912 * @inc_count: Number of node paths in list
1913 * @exc_prop: List of properties names to exclude
1914 * @exc_prop_count: Number of properties in exclude list
1915 * @region: Returns list of regions
1916 * @max_region: Maximum length of region list
1917 * @path: Pointer to a temporary string for the function to use for
1918 * building path names
1919 * @path_len: Length of path, must be large enough to hold the longest
1920 * path in the tree
1921 * @add_string_tab: 1 to add a region for the string table
1922 * @return number of regions in list. If this is >max_regions then the
1923 * region array was exhausted. You should increase max_regions and try
1924 * the call again.
1925 */
1926int fdt_find_regions(const void *fdt, char * const inc[], int inc_count,
1927 char * const exc_prop[], int exc_prop_count,
1928 struct fdt_region region[], int max_regions,
1929 char *path, int path_len, int add_string_tab);
1930
Simon Glassc3c4c002015-06-23 15:38:27 -06001931/**
1932 * fdt_first_region() - find regions in device tree
1933 *
1934 * Given a nodes and properties to include and properties to exclude, find
1935 * the regions of the device tree which describe those included parts.
1936 *
1937 * The use for this function is twofold. Firstly it provides a convenient
1938 * way of performing a structure-aware grep of the tree. For example it is
1939 * possible to grep for a node and get all the properties associated with
1940 * that node. Trees can be subsetted easily, by specifying the nodes that
1941 * are required, and then writing out the regions returned by this function.
1942 * This is useful for small resource-constrained systems, such as boot
1943 * loaders, which want to use an FDT but do not need to know about all of
1944 * it.
1945 *
1946 * Secondly it makes it easy to hash parts of the tree and detect changes.
1947 * The intent is to get a list of regions which will be invariant provided
1948 * those parts are invariant. For example, if you request a list of regions
1949 * for all nodes but exclude the property "data", then you will get the
1950 * same region contents regardless of any change to "data" properties.
1951 *
1952 * This function can be used to produce a byte-stream to send to a hashing
1953 * function to verify that critical parts of the FDT have not changed.
1954 * Note that semantically null changes in order could still cause false
1955 * hash misses. Such reordering might happen if the tree is regenerated
1956 * from source, and nodes are reordered (the bytes-stream will be emitted
1957 * in a different order and mnay hash functions will detect this). However
1958 * if an existing tree is modified using libfdt functions, such as
1959 * fdt_add_subnode() and fdt_setprop(), then this problem is avoided.
1960 *
1961 * The nodes/properties to include/exclude are defined by a function
1962 * provided by the caller. This function is called for each node and
1963 * property, and must return:
1964 *
1965 * 0 - to exclude this part
1966 * 1 - to include this part
1967 * -1 - for FDT_IS_PROP only: no information is available, so include
1968 * if its containing node is included
1969 *
1970 * The last case is only used to deal with properties. Often a property is
1971 * included if its containing node is included - this is the case where
1972 * -1 is returned.. However if the property is specifically required to be
1973 * included/excluded, then 0 or 1 can be returned. Note that including a
1974 * property when the FDT_REG_SUPERNODES flag is given will force its
1975 * containing node to be included since it is not valid to have a property
1976 * that is not in a node.
1977 *
1978 * Using the information provided, the inclusion of a node can be controlled
1979 * either by a node name or its compatible string, or any other property
1980 * that the function can determine.
1981 *
1982 * As an example, including node "/" means to include the root node and all
1983 * root properties. A flag provides a way of also including supernodes (of
1984 * which there is none for the root node), and another flag includes
1985 * immediate subnodes, so in this case we would get the FDT_BEGIN_NODE and
1986 * FDT_END_NODE of all subnodes of /.
1987 *
1988 * The subnode feature helps in a hashing situation since it prevents the
1989 * root node from changing at all. Any change to non-excluded properties,
1990 * names of subnodes or number of subnodes would be detected.
1991 *
1992 * When used with FITs this provides the ability to hash and sign parts of
1993 * the FIT based on different configurations in the FIT. Then it is
1994 * impossible to change anything about that configuration (include images
1995 * attached to the configuration), but it may be possible to add new
1996 * configurations, new images or new signatures within the existing
1997 * framework.
1998 *
1999 * Adding new properties to a device tree may result in the string table
2000 * being extended (if the new property names are different from those
2001 * already added). This function can optionally include a region for
2002 * the string table so that this can be part of the hash too. This is always
2003 * the last region.
2004 *
2005 * The FDT also has a mem_rsvmap table which can also be included, and is
2006 * always the first region if so.
2007 *
2008 * The device tree header is not included in the region list. Since the
2009 * contents of the FDT are changing (shrinking, often), the caller will need
2010 * to regenerate the header anyway.
2011 *
2012 * @fdt: Device tree to check
2013 * @h_include: Function to call to determine whether to include a part or
2014 * not:
2015 *
2016 * @priv: Private pointer as passed to fdt_find_regions()
2017 * @fdt: Pointer to FDT blob
2018 * @offset: Offset of this node / property
2019 * @type: Type of this part, FDT_IS_...
2020 * @data: Pointer to data (node name, property name, compatible
2021 * string, value (not yet supported)
2022 * @size: Size of data, or 0 if none
2023 * @return 0 to exclude, 1 to include, -1 if no information is
2024 * available
2025 * @priv: Private pointer passed to h_include
2026 * @region: Returns list of regions, sorted by offset
2027 * @max_regions: Maximum length of region list
2028 * @path: Pointer to a temporary string for the function to use for
2029 * building path names
2030 * @path_len: Length of path, must be large enough to hold the longest
2031 * path in the tree
2032 * @flags: Various flags that control the region algortihm, see
2033 * FDT_REG_...
2034 * @return number of regions in list. If this is >max_regions then the
2035 * region array was exhausted. You should increase max_regions and try
2036 * the call again. Only the first max_regions elements are available in the
2037 * array.
2038 *
2039 * On error a -ve value is return, which can be:
2040 *
2041 * -FDT_ERR_BADSTRUCTURE (too deep or more END tags than BEGIN tags
2042 * -FDT_ERR_BADLAYOUT
2043 * -FDT_ERR_NOSPACE (path area is too small)
2044 */
2045int fdt_first_region(const void *fdt,
2046 int (*h_include)(void *priv, const void *fdt, int offset,
2047 int type, const char *data, int size),
2048 void *priv, struct fdt_region *region,
2049 char *path, int path_len, int flags,
2050 struct fdt_region_state *info);
2051
2052/** fdt_next_region() - find next region
2053 *
2054 * See fdt_first_region() for full description. This function finds the
2055 * next region according to the provided parameters, which must be the same
2056 * as passed to fdt_first_region().
2057 *
2058 * This function can additionally return -FDT_ERR_NOTFOUND when there are no
2059 * more regions
2060 */
2061int fdt_next_region(const void *fdt,
2062 int (*h_include)(void *priv, const void *fdt, int offset,
2063 int type, const char *data, int size),
2064 void *priv, struct fdt_region *region,
2065 char *path, int path_len, int flags,
2066 struct fdt_region_state *info);
2067
2068/**
2069 * fdt_add_alias_regions() - find aliases that point to existing regions
2070 *
2071 * Once a device tree grep is complete some of the nodes will be present
2072 * and some will have been dropped. This function checks all the alias nodes
2073 * to figure out which points point to nodes which are still present. These
2074 * aliases need to be kept, along with the nodes they reference.
2075 *
2076 * Given a list of regions function finds the aliases that still apply and
2077 * adds more regions to the list for these. This function is called after
2078 * fdt_next_region() has finished returning regions and requires the same
2079 * state.
2080 *
2081 * @fdt: Device tree file to reference
2082 * @region: List of regions that will be kept
2083 * @count: Number of regions
2084 * @max_regions: Number of entries that can fit in @region
2085 * @info: Region state as returned from fdt_next_region()
2086 * @return new number of regions in @region (i.e. count + the number added)
2087 * or -FDT_ERR_NOSPACE if there was not enough space.
2088 */
2089int fdt_add_alias_regions(const void *fdt, struct fdt_region *region, int count,
2090 int max_regions, struct fdt_region_state *info);
2091
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04002092#endif /* _LIBFDT_H */