blob: e2bc2e00c184e6e163711b18e02aea340dd4b126 [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
Simon Glass9c07b982016-10-02 17:59:27 -060064 /* FDT_ERR_EXISTS: Attempted to create a node or property which
Kumar Gala8d04f022007-10-24 11:04:22 -050065 * 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
Maxime Ripard610db702016-10-17 22:50:18 +020082 /* FDT_ERR_BADPHANDLE: Function was passed an invalid phandle.
83 * This can be caused either by an invalid phandle property
84 * length, or the phandle value was either 0 or -1, which are
85 * not permitted. */
Kumar Gala8d04f022007-10-24 11:04:22 -050086#define FDT_ERR_BADSTATE 7
87 /* FDT_ERR_BADSTATE: Function was passed an incomplete device
88 * tree created by the sequential-write functions, which is
89 * not sufficiently complete for the requested operation. */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -040090
91/* Error codes: codes for bad device tree blobs */
Kumar Gala8d04f022007-10-24 11:04:22 -050092#define FDT_ERR_TRUNCATED 8
93 /* FDT_ERR_TRUNCATED: Structure block of the given device tree
94 * ends without an FDT_END tag. */
95#define FDT_ERR_BADMAGIC 9
96 /* FDT_ERR_BADMAGIC: Given "device tree" appears not to be a
97 * device tree at all - it is missing the flattened device
98 * tree magic number. */
99#define FDT_ERR_BADVERSION 10
100 /* FDT_ERR_BADVERSION: Given device tree has a version which
101 * can't be handled by the requested operation. For
102 * read-write functions, this may mean that fdt_open_into() is
103 * required to convert the tree to the expected version. */
104#define FDT_ERR_BADSTRUCTURE 11
105 /* FDT_ERR_BADSTRUCTURE: Given device tree has a corrupt
106 * structure block or other serious error (e.g. misnested
107 * nodes, or subnodes preceding properties). */
108#define FDT_ERR_BADLAYOUT 12
109 /* FDT_ERR_BADLAYOUT: For read-write functions, the given
110 * device tree has it's sub-blocks in an order that the
111 * function can't handle (memory reserve map, then structure,
112 * then strings). Use fdt_open_into() to reorganize the tree
113 * into a form suitable for the read-write operations. */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400114
Kumar Gala8d04f022007-10-24 11:04:22 -0500115/* "Can't happen" error indicating a bug in libfdt */
116#define FDT_ERR_INTERNAL 13
117 /* FDT_ERR_INTERNAL: libfdt has failed an internal assertion.
118 * Should never be returned, if it is, it indicates a bug in
119 * libfdt itself. */
120
Simon Glass0596d352014-07-30 03:59:03 -0600121/* Errors in device tree content */
122#define FDT_ERR_BADNCELLS 14
123 /* FDT_ERR_BADNCELLS: Device tree has a #address-cells, #size-cells
124 * or similar property with a bad format or value */
125
Simon Glassb02e4042016-10-02 17:59:28 -0600126#define FDT_ERR_BADVALUE 15
127 /* FDT_ERR_BADVALUE: Device tree has a property with an unexpected
128 * value. For example: a property expected to contain a string list
129 * is not NUL-terminated within the length of its value. */
130
Maxime Ripard610db702016-10-17 22:50:18 +0200131#define FDT_ERR_BADOVERLAY 16
132 /* FDT_ERR_BADOVERLAY: The device tree overlay, while
133 * correctly structured, cannot be applied due to some
134 * unexpected or missing value, property or node. */
135
136#define FDT_ERR_NOPHANDLES 17
137 /* FDT_ERR_NOPHANDLES: The device tree doesn't have any
138 * phandle available anymore without causing an overflow */
139
140#define FDT_ERR_TOODEEP 18
Simon Glassc3c4c002015-06-23 15:38:27 -0600141 /* FDT_ERR_TOODEEP: The depth of a node has exceeded the internal
142 * libfdt limit. This can happen if you have more than
143 * FDT_MAX_DEPTH nested nodes. */
144
Maxime Ripard610db702016-10-17 22:50:18 +0200145#define FDT_ERR_MAX 18
Kumar Gala8d04f022007-10-24 11:04:22 -0500146
147/**********************************************************************/
148/* Low-level functions (you probably don't need these) */
149/**********************************************************************/
150
Jon Loeliger741a6d02008-09-25 11:02:17 -0500151const void *fdt_offset_ptr(const void *fdt, int offset, unsigned int checklen);
Kumar Gala8d04f022007-10-24 11:04:22 -0500152static inline void *fdt_offset_ptr_w(void *fdt, int offset, int checklen)
153{
David Gibsonc6683022008-07-07 10:14:15 +1000154 return (void *)(uintptr_t)fdt_offset_ptr(fdt, offset, checklen);
Kumar Gala8d04f022007-10-24 11:04:22 -0500155}
156
157uint32_t fdt_next_tag(const void *fdt, int offset, int *nextoffset);
158
159/**********************************************************************/
David Gibsonae0b5902008-02-12 11:58:31 +1100160/* Traversal functions */
161/**********************************************************************/
162
163int fdt_next_node(const void *fdt, int offset, int *depth);
164
Simon Glass88f95bb2013-05-07 06:11:50 +0000165/**
166 * fdt_first_subnode() - get offset of first direct subnode
167 *
168 * @fdt: FDT blob
169 * @offset: Offset of node to check
170 * @return offset of first subnode, or -FDT_ERR_NOTFOUND if there is none
171 */
172int fdt_first_subnode(const void *fdt, int offset);
173
174/**
175 * fdt_next_subnode() - get offset of next direct subnode
176 *
177 * After first calling fdt_first_subnode(), call this function repeatedly to
178 * get direct subnodes of a parent node.
179 *
180 * @fdt: FDT blob
181 * @offset: Offset of previous subnode
182 * @return offset of next subnode, or -FDT_ERR_NOTFOUND if there are no more
183 * subnodes
184 */
185int fdt_next_subnode(const void *fdt, int offset);
186
Thierry Reding2f376042014-08-26 17:33:55 +0200187/**
188 * fdt_for_each_subnode - iterate over all subnodes of a parent
189 *
Simon Glassdf87e6b2016-10-02 17:59:29 -0600190 * @node: child node (int, lvalue)
191 * @fdt: FDT blob (const void *)
192 * @parent: parent node (int)
193 *
Thierry Reding2f376042014-08-26 17:33:55 +0200194 * This is actually a wrapper around a for loop and would be used like so:
195 *
Simon Glassdf87e6b2016-10-02 17:59:29 -0600196 * fdt_for_each_subnode(node, fdt, parent) {
197 * Use node
Thierry Reding2f376042014-08-26 17:33:55 +0200198 * ...
199 * }
200 *
Simon Glassdf87e6b2016-10-02 17:59:29 -0600201 * if ((node < 0) && (node != -FDT_ERR_NOT_FOUND)) {
202 * Error handling
203 * }
Thierry Reding2f376042014-08-26 17:33:55 +0200204 *
Simon Glassdf87e6b2016-10-02 17:59:29 -0600205 * Note that this is implemented as a macro and @node is used as
206 * iterator in the loop. The parent variable be constant or even a
207 * literal.
208 *
Thierry Reding2f376042014-08-26 17:33:55 +0200209 */
Simon Glassdf87e6b2016-10-02 17:59:29 -0600210#define fdt_for_each_subnode(node, fdt, parent) \
Thierry Reding2f376042014-08-26 17:33:55 +0200211 for (node = fdt_first_subnode(fdt, parent); \
212 node >= 0; \
213 node = fdt_next_subnode(fdt, node))
214
David Gibsonae0b5902008-02-12 11:58:31 +1100215/**********************************************************************/
Kumar Gala8d04f022007-10-24 11:04:22 -0500216/* General functions */
217/**********************************************************************/
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400218
219#define fdt_get_header(fdt, field) \
Kumar Gala8d04f022007-10-24 11:04:22 -0500220 (fdt32_to_cpu(((const struct fdt_header *)(fdt))->field))
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200221#define fdt_magic(fdt) (fdt_get_header(fdt, magic))
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400222#define fdt_totalsize(fdt) (fdt_get_header(fdt, totalsize))
223#define fdt_off_dt_struct(fdt) (fdt_get_header(fdt, off_dt_struct))
224#define fdt_off_dt_strings(fdt) (fdt_get_header(fdt, off_dt_strings))
225#define fdt_off_mem_rsvmap(fdt) (fdt_get_header(fdt, off_mem_rsvmap))
226#define fdt_version(fdt) (fdt_get_header(fdt, version))
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200227#define fdt_last_comp_version(fdt) (fdt_get_header(fdt, last_comp_version))
228#define fdt_boot_cpuid_phys(fdt) (fdt_get_header(fdt, boot_cpuid_phys))
229#define fdt_size_dt_strings(fdt) (fdt_get_header(fdt, size_dt_strings))
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400230#define fdt_size_dt_struct(fdt) (fdt_get_header(fdt, size_dt_struct))
231
Kumar Gala8d04f022007-10-24 11:04:22 -0500232#define __fdt_set_hdr(name) \
233 static inline void fdt_set_##name(void *fdt, uint32_t val) \
234 { \
Simon Glass9c07b982016-10-02 17:59:27 -0600235 struct fdt_header *fdth = (struct fdt_header *)fdt; \
Kumar Gala8d04f022007-10-24 11:04:22 -0500236 fdth->name = cpu_to_fdt32(val); \
237 }
238__fdt_set_hdr(magic);
239__fdt_set_hdr(totalsize);
240__fdt_set_hdr(off_dt_struct);
241__fdt_set_hdr(off_dt_strings);
242__fdt_set_hdr(off_mem_rsvmap);
243__fdt_set_hdr(version);
244__fdt_set_hdr(last_comp_version);
245__fdt_set_hdr(boot_cpuid_phys);
246__fdt_set_hdr(size_dt_strings);
247__fdt_set_hdr(size_dt_struct);
248#undef __fdt_set_hdr
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400249
Kumar Gala8d04f022007-10-24 11:04:22 -0500250/**
251 * fdt_check_header - sanity check a device tree or possible device tree
252 * @fdt: pointer to data which might be a flattened device tree
253 *
254 * fdt_check_header() checks that the given buffer contains what
255 * appears to be a flattened device tree with sane information in its
256 * header.
257 *
258 * returns:
259 * 0, if the buffer appears to contain a valid device tree
260 * -FDT_ERR_BADMAGIC,
261 * -FDT_ERR_BADVERSION,
262 * -FDT_ERR_BADSTATE, standard meanings, as above
263 */
Gerald Van Baren6679f922007-04-06 14:17:14 -0400264int fdt_check_header(const void *fdt);
265
Kumar Gala8d04f022007-10-24 11:04:22 -0500266/**
267 * fdt_move - move a device tree around in memory
268 * @fdt: pointer to the device tree to move
269 * @buf: pointer to memory where the device is to be moved
270 * @bufsize: size of the memory space at buf
271 *
272 * fdt_move() relocates, if possible, the device tree blob located at
273 * fdt to the buffer at buf of size bufsize. The buffer may overlap
274 * with the existing device tree blob at fdt. Therefore,
275 * fdt_move(fdt, fdt, fdt_totalsize(fdt))
276 * should always succeed.
277 *
278 * returns:
279 * 0, on success
280 * -FDT_ERR_NOSPACE, bufsize is insufficient to contain the device tree
281 * -FDT_ERR_BADMAGIC,
282 * -FDT_ERR_BADVERSION,
283 * -FDT_ERR_BADSTATE, standard meanings
284 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400285int fdt_move(const void *fdt, void *buf, int bufsize);
286
Kumar Gala8d04f022007-10-24 11:04:22 -0500287/**********************************************************************/
288/* Read-only functions */
289/**********************************************************************/
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400290
Kumar Gala8d04f022007-10-24 11:04:22 -0500291/**
Wolfram Sang46390da2008-07-09 11:22:44 +0200292 * fdt_string - retrieve a string from the strings block of a device tree
Kumar Gala8d04f022007-10-24 11:04:22 -0500293 * @fdt: pointer to the device tree blob
294 * @stroffset: offset of the string within the strings block (native endian)
295 *
296 * fdt_string() retrieves a pointer to a single string from the
297 * strings block of the device tree blob at fdt.
298 *
299 * returns:
300 * a pointer to the string, on success
301 * NULL, if stroffset is out of bounds
302 */
303const char *fdt_string(const void *fdt, int stroffset);
304
305/**
Maxime Ripard57c78092016-07-05 10:26:39 +0200306 * fdt_get_max_phandle - retrieves the highest phandle in a tree
307 * @fdt: pointer to the device tree blob
308 *
309 * fdt_get_max_phandle retrieves the highest phandle in the given
Simon Glass9c07b982016-10-02 17:59:27 -0600310 * device tree. This will ignore badly formatted phandles, or phandles
311 * with a value of 0 or -1.
Maxime Ripard57c78092016-07-05 10:26:39 +0200312 *
313 * returns:
314 * the highest phandle on success
Simon Glass9c07b982016-10-02 17:59:27 -0600315 * 0, if no phandle was found in the device tree
316 * -1, if an error occurred
Maxime Ripard57c78092016-07-05 10:26:39 +0200317 */
318uint32_t fdt_get_max_phandle(const void *fdt);
319
320/**
Wolfram Sang46390da2008-07-09 11:22:44 +0200321 * fdt_num_mem_rsv - retrieve the number of memory reserve map entries
Kumar Gala8d04f022007-10-24 11:04:22 -0500322 * @fdt: pointer to the device tree blob
323 *
324 * Returns the number of entries in the device tree blob's memory
325 * reservation map. This does not include the terminating 0,0 entry
326 * or any other (0,0) entries reserved for expansion.
327 *
328 * returns:
329 * the number of entries
330 */
331int fdt_num_mem_rsv(const void *fdt);
332
333/**
Wolfram Sang46390da2008-07-09 11:22:44 +0200334 * fdt_get_mem_rsv - retrieve one memory reserve map entry
Kumar Gala8d04f022007-10-24 11:04:22 -0500335 * @fdt: pointer to the device tree blob
336 * @address, @size: pointers to 64-bit variables
337 *
338 * On success, *address and *size will contain the address and size of
339 * the n-th reserve map entry from the device tree blob, in
340 * native-endian format.
341 *
342 * returns:
343 * 0, on success
344 * -FDT_ERR_BADMAGIC,
345 * -FDT_ERR_BADVERSION,
346 * -FDT_ERR_BADSTATE, standard meanings
347 */
348int fdt_get_mem_rsv(const void *fdt, int n, uint64_t *address, uint64_t *size);
349
350/**
351 * fdt_subnode_offset_namelen - find a subnode based on substring
352 * @fdt: pointer to the device tree blob
353 * @parentoffset: structure block offset of a node
354 * @name: name of the subnode to locate
355 * @namelen: number of characters of name to consider
356 *
357 * Identical to fdt_subnode_offset(), but only examine the first
358 * namelen characters of name for matching the subnode name. This is
359 * useful for finding subnodes based on a portion of a larger string,
360 * such as a full path.
361 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400362int fdt_subnode_offset_namelen(const void *fdt, int parentoffset,
363 const char *name, int namelen);
Kumar Gala8d04f022007-10-24 11:04:22 -0500364/**
365 * fdt_subnode_offset - find a subnode of a given node
366 * @fdt: pointer to the device tree blob
367 * @parentoffset: structure block offset of a node
368 * @name: name of the subnode to locate
369 *
370 * fdt_subnode_offset() finds a subnode of the node at structure block
371 * offset parentoffset with the given name. name may include a unit
372 * address, in which case fdt_subnode_offset() will find the subnode
373 * with that unit address, or the unit address may be omitted, in
374 * which case fdt_subnode_offset() will find an arbitrary subnode
375 * whose name excluding unit address matches the given name.
376 *
377 * returns:
378 * structure block offset of the requested subnode (>=0), on success
379 * -FDT_ERR_NOTFOUND, if the requested subnode does not exist
Simon Glass9c07b982016-10-02 17:59:27 -0600380 * -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE
381 * tag
382 * -FDT_ERR_BADMAGIC,
Kumar Gala8d04f022007-10-24 11:04:22 -0500383 * -FDT_ERR_BADVERSION,
384 * -FDT_ERR_BADSTATE,
385 * -FDT_ERR_BADSTRUCTURE,
386 * -FDT_ERR_TRUNCATED, standard meanings.
387 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400388int fdt_subnode_offset(const void *fdt, int parentoffset, const char *name);
389
Kumar Gala8d04f022007-10-24 11:04:22 -0500390/**
Simon Glass9c07b982016-10-02 17:59:27 -0600391 * fdt_path_offset_namelen - find a tree node by its full path
Maxime Ripard8e968572016-07-05 10:26:41 +0200392 * @fdt: pointer to the device tree blob
393 * @path: full path of the node to locate
Simon Glass9c07b982016-10-02 17:59:27 -0600394 * @namelen: number of characters of path to consider
Maxime Ripard8e968572016-07-05 10:26:41 +0200395 *
Simon Glass9c07b982016-10-02 17:59:27 -0600396 * Identical to fdt_path_offset(), but only consider the first namelen
397 * characters of path as the path name.
Maxime Ripard8e968572016-07-05 10:26:41 +0200398 */
399int fdt_path_offset_namelen(const void *fdt, const char *path, int namelen);
400
401/**
Kumar Gala8d04f022007-10-24 11:04:22 -0500402 * fdt_path_offset - find a tree node by its full path
403 * @fdt: pointer to the device tree blob
404 * @path: full path of the node to locate
405 *
406 * fdt_path_offset() finds a node of a given path in the device tree.
407 * Each path component may omit the unit address portion, but the
408 * results of this are undefined if any such path component is
409 * ambiguous (that is if there are multiple nodes at the relevant
410 * level matching the given component, differentiated only by unit
411 * address).
412 *
413 * returns:
Simon Glass9c07b982016-10-02 17:59:27 -0600414 * structure block offset of the node with the requested path (>=0), on
415 * success
Kumar Gala8d04f022007-10-24 11:04:22 -0500416 * -FDT_ERR_BADPATH, given path does not begin with '/' or is invalid
417 * -FDT_ERR_NOTFOUND, if the requested node does not exist
418 * -FDT_ERR_BADMAGIC,
419 * -FDT_ERR_BADVERSION,
420 * -FDT_ERR_BADSTATE,
421 * -FDT_ERR_BADSTRUCTURE,
422 * -FDT_ERR_TRUNCATED, standard meanings.
423 */
Simon Glass42b76002016-10-02 17:59:30 -0600424int fdt_path_offset(const void *fdt, const char *path);
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400425
Kumar Gala8d04f022007-10-24 11:04:22 -0500426/**
Wolfram Sang46390da2008-07-09 11:22:44 +0200427 * fdt_get_name - retrieve the name of a given node
Kumar Gala8d04f022007-10-24 11:04:22 -0500428 * @fdt: pointer to the device tree blob
429 * @nodeoffset: structure block offset of the starting node
430 * @lenp: pointer to an integer variable (will be overwritten) or NULL
431 *
432 * fdt_get_name() retrieves the name (including unit address) of the
433 * device tree node at structure block offset nodeoffset. If lenp is
434 * non-NULL, the length of this name is also returned, in the integer
435 * pointed to by lenp.
436 *
437 * returns:
438 * pointer to the node's name, on success
Simon Glass9c07b982016-10-02 17:59:27 -0600439 * If lenp is non-NULL, *lenp contains the length of that name
440 * (>=0)
Kumar Gala8d04f022007-10-24 11:04:22 -0500441 * NULL, on error
442 * if lenp is non-NULL *lenp contains an error code (<0):
Simon Glass9c07b982016-10-02 17:59:27 -0600443 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE
444 * tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500445 * -FDT_ERR_BADMAGIC,
446 * -FDT_ERR_BADVERSION,
447 * -FDT_ERR_BADSTATE, standard meanings
448 */
449const char *fdt_get_name(const void *fdt, int nodeoffset, int *lenp);
Gerald Van Baren7cd5da02007-03-31 11:59:59 -0400450
Kumar Gala8d04f022007-10-24 11:04:22 -0500451/**
David Gibsond1c63142010-03-09 17:39:14 +1100452 * fdt_first_property_offset - find the offset of a node's first property
453 * @fdt: pointer to the device tree blob
454 * @nodeoffset: structure block offset of a node
455 *
456 * fdt_first_property_offset() finds the first property of the node at
457 * the given structure block offset.
458 *
459 * returns:
460 * structure block offset of the property (>=0), on success
461 * -FDT_ERR_NOTFOUND, if the requested node has no properties
462 * -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_BEGIN_NODE tag
463 * -FDT_ERR_BADMAGIC,
464 * -FDT_ERR_BADVERSION,
465 * -FDT_ERR_BADSTATE,
466 * -FDT_ERR_BADSTRUCTURE,
467 * -FDT_ERR_TRUNCATED, standard meanings.
468 */
469int fdt_first_property_offset(const void *fdt, int nodeoffset);
470
471/**
472 * fdt_next_property_offset - step through a node's properties
473 * @fdt: pointer to the device tree blob
474 * @offset: structure block offset of a property
475 *
476 * fdt_next_property_offset() finds the property immediately after the
477 * one at the given structure block offset. This will be a property
478 * of the same node as the given property.
479 *
480 * returns:
481 * structure block offset of the next property (>=0), on success
482 * -FDT_ERR_NOTFOUND, if the given property is the last in its node
483 * -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_PROP tag
484 * -FDT_ERR_BADMAGIC,
485 * -FDT_ERR_BADVERSION,
486 * -FDT_ERR_BADSTATE,
487 * -FDT_ERR_BADSTRUCTURE,
488 * -FDT_ERR_TRUNCATED, standard meanings.
489 */
490int fdt_next_property_offset(const void *fdt, int offset);
491
492/**
Simon Glass9c07b982016-10-02 17:59:27 -0600493 * fdt_for_each_property_offset - iterate over all properties of a node
494 *
495 * @property_offset: property offset (int, lvalue)
Maxime Ripard67e610d2016-07-05 10:26:38 +0200496 * @fdt: FDT blob (const void *)
497 * @node: node offset (int)
498 *
499 * This is actually a wrapper around a for loop and would be used like so:
500 *
Simon Glass9c07b982016-10-02 17:59:27 -0600501 * fdt_for_each_property_offset(property, fdt, node) {
502 * Use property
Maxime Ripard67e610d2016-07-05 10:26:38 +0200503 * ...
504 * }
505 *
Simon Glass9c07b982016-10-02 17:59:27 -0600506 * if ((property < 0) && (property != -FDT_ERR_NOT_FOUND)) {
507 * Error handling
508 * }
509 *
Maxime Ripard67e610d2016-07-05 10:26:38 +0200510 * Note that this is implemented as a macro and property is used as
Simon Glass9c07b982016-10-02 17:59:27 -0600511 * iterator in the loop. The node variable can be constant or even a
512 * literal.
Maxime Ripard67e610d2016-07-05 10:26:38 +0200513 */
514#define fdt_for_each_property_offset(property, fdt, node) \
515 for (property = fdt_first_property_offset(fdt, node); \
516 property >= 0; \
517 property = fdt_next_property_offset(fdt, property))
518
519/**
David Gibsond1c63142010-03-09 17:39:14 +1100520 * fdt_get_property_by_offset - retrieve the property at a given offset
521 * @fdt: pointer to the device tree blob
522 * @offset: offset of the property to retrieve
523 * @lenp: pointer to an integer variable (will be overwritten) or NULL
524 *
525 * fdt_get_property_by_offset() retrieves a pointer to the
526 * fdt_property structure within the device tree blob at the given
527 * offset. If lenp is non-NULL, the length of the property value is
528 * also returned, in the integer pointed to by lenp.
529 *
530 * returns:
531 * pointer to the structure representing the property
532 * if lenp is non-NULL, *lenp contains the length of the property
533 * value (>=0)
534 * NULL, on error
535 * if lenp is non-NULL, *lenp contains an error code (<0):
536 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
537 * -FDT_ERR_BADMAGIC,
538 * -FDT_ERR_BADVERSION,
539 * -FDT_ERR_BADSTATE,
540 * -FDT_ERR_BADSTRUCTURE,
541 * -FDT_ERR_TRUNCATED, standard meanings
542 */
543const struct fdt_property *fdt_get_property_by_offset(const void *fdt,
544 int offset,
545 int *lenp);
546
547/**
David Gibson02193992008-08-06 14:50:49 +1000548 * fdt_get_property_namelen - find a property based on substring
549 * @fdt: pointer to the device tree blob
550 * @nodeoffset: offset of the node whose property to find
551 * @name: name of the property to find
552 * @namelen: number of characters of name to consider
553 * @lenp: pointer to an integer variable (will be overwritten) or NULL
554 *
Simon Glass9c07b982016-10-02 17:59:27 -0600555 * Identical to fdt_get_property(), but only examine the first namelen
556 * characters of name for matching the property name.
David Gibson02193992008-08-06 14:50:49 +1000557 */
558const struct fdt_property *fdt_get_property_namelen(const void *fdt,
559 int nodeoffset,
560 const char *name,
561 int namelen, int *lenp);
562
563/**
Kumar Gala8d04f022007-10-24 11:04:22 -0500564 * fdt_get_property - find a given property in a given node
565 * @fdt: pointer to the device tree blob
566 * @nodeoffset: offset of the node whose property to find
567 * @name: name of the property to find
568 * @lenp: pointer to an integer variable (will be overwritten) or NULL
569 *
570 * fdt_get_property() retrieves a pointer to the fdt_property
571 * structure within the device tree blob corresponding to the property
572 * named 'name' of the node at offset nodeoffset. If lenp is
Wolfram Sang46390da2008-07-09 11:22:44 +0200573 * non-NULL, the length of the property value is also returned, in the
Kumar Gala8d04f022007-10-24 11:04:22 -0500574 * integer pointed to by lenp.
575 *
576 * returns:
577 * pointer to the structure representing the property
578 * if lenp is non-NULL, *lenp contains the length of the property
579 * value (>=0)
580 * NULL, on error
581 * if lenp is non-NULL, *lenp contains an error code (<0):
582 * -FDT_ERR_NOTFOUND, node does not have named property
Simon Glass9c07b982016-10-02 17:59:27 -0600583 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE
584 * tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500585 * -FDT_ERR_BADMAGIC,
586 * -FDT_ERR_BADVERSION,
587 * -FDT_ERR_BADSTATE,
588 * -FDT_ERR_BADSTRUCTURE,
589 * -FDT_ERR_TRUNCATED, standard meanings
590 */
591const struct fdt_property *fdt_get_property(const void *fdt, int nodeoffset,
592 const char *name, int *lenp);
593static inline struct fdt_property *fdt_get_property_w(void *fdt, int nodeoffset,
594 const char *name,
595 int *lenp)
596{
David Gibsonc6683022008-07-07 10:14:15 +1000597 return (struct fdt_property *)(uintptr_t)
598 fdt_get_property(fdt, nodeoffset, name, lenp);
Kumar Gala8d04f022007-10-24 11:04:22 -0500599}
Gerald Van Baren3af0d582007-03-31 12:13:43 -0400600
Kumar Gala8d04f022007-10-24 11:04:22 -0500601/**
David Gibsond1c63142010-03-09 17:39:14 +1100602 * fdt_getprop_by_offset - retrieve the value of a property at a given offset
603 * @fdt: pointer to the device tree blob
604 * @ffset: offset of the property to read
605 * @namep: pointer to a string variable (will be overwritten) or NULL
606 * @lenp: pointer to an integer variable (will be overwritten) or NULL
607 *
608 * fdt_getprop_by_offset() retrieves a pointer to the value of the
609 * property at structure block offset 'offset' (this will be a pointer
610 * to within the device blob itself, not a copy of the value). If
611 * lenp is non-NULL, the length of the property value is also
612 * returned, in the integer pointed to by lenp. If namep is non-NULL,
613 * the property's namne will also be returned in the char * pointed to
614 * by namep (this will be a pointer to within the device tree's string
615 * block, not a new copy of the name).
616 *
617 * returns:
618 * pointer to the property's value
619 * if lenp is non-NULL, *lenp contains the length of the property
620 * value (>=0)
621 * if namep is non-NULL *namep contiains a pointer to the property
622 * name.
623 * NULL, on error
624 * if lenp is non-NULL, *lenp contains an error code (<0):
625 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag
626 * -FDT_ERR_BADMAGIC,
627 * -FDT_ERR_BADVERSION,
628 * -FDT_ERR_BADSTATE,
629 * -FDT_ERR_BADSTRUCTURE,
630 * -FDT_ERR_TRUNCATED, standard meanings
631 */
632const void *fdt_getprop_by_offset(const void *fdt, int offset,
633 const char **namep, int *lenp);
634
635/**
David Gibson02193992008-08-06 14:50:49 +1000636 * fdt_getprop_namelen - get property value based on substring
637 * @fdt: pointer to the device tree blob
638 * @nodeoffset: offset of the node whose property to find
639 * @name: name of the property to find
640 * @namelen: number of characters of name to consider
641 * @lenp: pointer to an integer variable (will be overwritten) or NULL
642 *
643 * Identical to fdt_getprop(), but only examine the first namelen
644 * characters of name for matching the property name.
645 */
646const void *fdt_getprop_namelen(const void *fdt, int nodeoffset,
647 const char *name, int namelen, int *lenp);
Maxime Ripard2b941bf2016-07-05 10:26:42 +0200648static inline void *fdt_getprop_namelen_w(void *fdt, int nodeoffset,
649 const char *name, int namelen,
650 int *lenp)
651{
652 return (void *)(uintptr_t)fdt_getprop_namelen(fdt, nodeoffset, name,
653 namelen, lenp);
654}
David Gibson02193992008-08-06 14:50:49 +1000655
656/**
Kumar Gala8d04f022007-10-24 11:04:22 -0500657 * fdt_getprop - retrieve the value of a given property
658 * @fdt: pointer to the device tree blob
659 * @nodeoffset: offset of the node whose property to find
660 * @name: name of the property to find
661 * @lenp: pointer to an integer variable (will be overwritten) or NULL
662 *
663 * fdt_getprop() retrieves a pointer to the value of the property
664 * named 'name' of the node at offset nodeoffset (this will be a
665 * pointer to within the device blob itself, not a copy of the value).
Wolfram Sang46390da2008-07-09 11:22:44 +0200666 * If lenp is non-NULL, the length of the property value is also
Kumar Gala8d04f022007-10-24 11:04:22 -0500667 * returned, in the integer pointed to by lenp.
668 *
669 * returns:
670 * pointer to the property's value
671 * if lenp is non-NULL, *lenp contains the length of the property
672 * value (>=0)
673 * NULL, on error
674 * if lenp is non-NULL, *lenp contains an error code (<0):
675 * -FDT_ERR_NOTFOUND, node does not have named property
Simon Glass9c07b982016-10-02 17:59:27 -0600676 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE
677 * tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500678 * -FDT_ERR_BADMAGIC,
679 * -FDT_ERR_BADVERSION,
680 * -FDT_ERR_BADSTATE,
681 * -FDT_ERR_BADSTRUCTURE,
682 * -FDT_ERR_TRUNCATED, standard meanings
683 */
684const void *fdt_getprop(const void *fdt, int nodeoffset,
685 const char *name, int *lenp);
686static inline void *fdt_getprop_w(void *fdt, int nodeoffset,
687 const char *name, int *lenp)
688{
David Gibsonc6683022008-07-07 10:14:15 +1000689 return (void *)(uintptr_t)fdt_getprop(fdt, nodeoffset, name, lenp);
Kumar Gala8d04f022007-10-24 11:04:22 -0500690}
691
692/**
Wolfram Sang46390da2008-07-09 11:22:44 +0200693 * fdt_get_phandle - retrieve the phandle of a given node
Kumar Gala8d04f022007-10-24 11:04:22 -0500694 * @fdt: pointer to the device tree blob
695 * @nodeoffset: structure block offset of the node
696 *
697 * fdt_get_phandle() retrieves the phandle of the device tree node at
698 * structure block offset nodeoffset.
699 *
700 * returns:
Wolfram Sang46390da2008-07-09 11:22:44 +0200701 * the phandle of the node at nodeoffset, on success (!= 0, != -1)
Kumar Gala8d04f022007-10-24 11:04:22 -0500702 * 0, if the node has no phandle, or another error occurs
703 */
704uint32_t fdt_get_phandle(const void *fdt, int nodeoffset);
705
706/**
Gerald Van Barencd3cb0d2008-10-04 07:56:06 -0400707 * fdt_get_alias_namelen - get alias based on substring
David Gibson9a6cf732008-08-20 16:55:14 +1000708 * @fdt: pointer to the device tree blob
709 * @name: name of the alias th look up
710 * @namelen: number of characters of name to consider
711 *
712 * Identical to fdt_get_alias(), but only examine the first namelen
713 * characters of name for matching the alias name.
714 */
715const char *fdt_get_alias_namelen(const void *fdt,
716 const char *name, int namelen);
717
718/**
Simon Glass9c07b982016-10-02 17:59:27 -0600719 * fdt_get_alias - retrieve the path referenced by a given alias
David Gibson9a6cf732008-08-20 16:55:14 +1000720 * @fdt: pointer to the device tree blob
Simon Glass0596d352014-07-30 03:59:03 -0600721 * @name: name of the alias th look up
David Gibson9a6cf732008-08-20 16:55:14 +1000722 *
723 * fdt_get_alias() retrieves the value of a given alias. That is, the
724 * value of the property named 'name' in the node /aliases.
725 *
726 * returns:
François Revolc73bd492013-02-03 00:52:21 +0100727 * a pointer to the expansion of the alias named 'name', if it exists
David Gibson9a6cf732008-08-20 16:55:14 +1000728 * NULL, if the given alias or the /aliases node does not exist
729 */
730const char *fdt_get_alias(const void *fdt, const char *name);
731
732/**
Kumar Gala8d04f022007-10-24 11:04:22 -0500733 * fdt_get_path - determine the full path of a node
734 * @fdt: pointer to the device tree blob
735 * @nodeoffset: offset of the node whose path to find
736 * @buf: character buffer to contain the returned path (will be overwritten)
737 * @buflen: size of the character buffer at buf
738 *
739 * fdt_get_path() computes the full path of the node at offset
740 * nodeoffset, and records that path in the buffer at buf.
741 *
742 * NOTE: This function is expensive, as it must scan the device tree
743 * structure from the start to nodeoffset.
744 *
745 * returns:
746 * 0, on success
747 * buf contains the absolute path of the node at
748 * nodeoffset, as a NUL-terminated string.
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200749 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500750 * -FDT_ERR_NOSPACE, the path of the given node is longer than (bufsize-1)
751 * characters and will not fit in the given buffer.
752 * -FDT_ERR_BADMAGIC,
753 * -FDT_ERR_BADVERSION,
754 * -FDT_ERR_BADSTATE,
755 * -FDT_ERR_BADSTRUCTURE, standard meanings
756 */
757int fdt_get_path(const void *fdt, int nodeoffset, char *buf, int buflen);
758
759/**
760 * fdt_supernode_atdepth_offset - find a specific ancestor of a node
761 * @fdt: pointer to the device tree blob
762 * @nodeoffset: offset of the node whose parent to find
763 * @supernodedepth: depth of the ancestor to find
764 * @nodedepth: pointer to an integer variable (will be overwritten) or NULL
765 *
766 * fdt_supernode_atdepth_offset() finds an ancestor of the given node
767 * at a specific depth from the root (where the root itself has depth
768 * 0, its immediate subnodes depth 1 and so forth). So
769 * fdt_supernode_atdepth_offset(fdt, nodeoffset, 0, NULL);
770 * will always return 0, the offset of the root node. If the node at
771 * nodeoffset has depth D, then:
772 * fdt_supernode_atdepth_offset(fdt, nodeoffset, D, NULL);
773 * will return nodeoffset itself.
774 *
775 * NOTE: This function is expensive, as it must scan the device tree
776 * structure from the start to nodeoffset.
777 *
778 * returns:
Kumar Gala8d04f022007-10-24 11:04:22 -0500779 * structure block offset of the node at node offset's ancestor
780 * of depth supernodedepth (>=0), on success
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200781 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Simon Glass9c07b982016-10-02 17:59:27 -0600782 * -FDT_ERR_NOTFOUND, supernodedepth was greater than the depth of
783 * nodeoffset
Kumar Gala8d04f022007-10-24 11:04:22 -0500784 * -FDT_ERR_BADMAGIC,
785 * -FDT_ERR_BADVERSION,
786 * -FDT_ERR_BADSTATE,
787 * -FDT_ERR_BADSTRUCTURE, standard meanings
788 */
789int fdt_supernode_atdepth_offset(const void *fdt, int nodeoffset,
790 int supernodedepth, int *nodedepth);
791
792/**
793 * fdt_node_depth - find the depth of a given node
794 * @fdt: pointer to the device tree blob
795 * @nodeoffset: offset of the node whose parent to find
796 *
797 * fdt_node_depth() finds the depth of a given node. The root node
798 * has depth 0, its immediate subnodes depth 1 and so forth.
799 *
800 * NOTE: This function is expensive, as it must scan the device tree
801 * structure from the start to nodeoffset.
802 *
803 * returns:
804 * depth of the node at nodeoffset (>=0), on success
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200805 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500806 * -FDT_ERR_BADMAGIC,
807 * -FDT_ERR_BADVERSION,
808 * -FDT_ERR_BADSTATE,
809 * -FDT_ERR_BADSTRUCTURE, standard meanings
810 */
811int fdt_node_depth(const void *fdt, int nodeoffset);
812
813/**
814 * fdt_parent_offset - find the parent of a given node
815 * @fdt: pointer to the device tree blob
816 * @nodeoffset: offset of the node whose parent to find
817 *
818 * fdt_parent_offset() locates the parent node of a given node (that
819 * is, it finds the offset of the node which contains the node at
820 * nodeoffset as a subnode).
821 *
822 * NOTE: This function is expensive, as it must scan the device tree
823 * structure from the start to nodeoffset, *twice*.
824 *
825 * returns:
Wolfram Sang46390da2008-07-09 11:22:44 +0200826 * structure block offset of the parent of the node at nodeoffset
Kumar Gala8d04f022007-10-24 11:04:22 -0500827 * (>=0), on success
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200828 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500829 * -FDT_ERR_BADMAGIC,
830 * -FDT_ERR_BADVERSION,
831 * -FDT_ERR_BADSTATE,
832 * -FDT_ERR_BADSTRUCTURE, standard meanings
833 */
834int fdt_parent_offset(const void *fdt, int nodeoffset);
835
836/**
837 * fdt_node_offset_by_prop_value - find nodes with a given property value
838 * @fdt: pointer to the device tree blob
839 * @startoffset: only find nodes after this offset
840 * @propname: property name to check
841 * @propval: property value to search for
842 * @proplen: length of the value in propval
843 *
844 * fdt_node_offset_by_prop_value() returns the offset of the first
845 * node after startoffset, which has a property named propname whose
846 * value is of length proplen and has value equal to propval; or if
847 * startoffset is -1, the very first such node in the tree.
848 *
849 * To iterate through all nodes matching the criterion, the following
850 * idiom can be used:
851 * offset = fdt_node_offset_by_prop_value(fdt, -1, propname,
852 * propval, proplen);
853 * while (offset != -FDT_ERR_NOTFOUND) {
Simon Glass0596d352014-07-30 03:59:03 -0600854 * // other code here
Kumar Gala8d04f022007-10-24 11:04:22 -0500855 * offset = fdt_node_offset_by_prop_value(fdt, offset, propname,
856 * propval, proplen);
857 * }
858 *
859 * Note the -1 in the first call to the function, if 0 is used here
860 * instead, the function will never locate the root node, even if it
861 * matches the criterion.
862 *
863 * returns:
864 * structure block offset of the located node (>= 0, >startoffset),
865 * on success
866 * -FDT_ERR_NOTFOUND, no node matching the criterion exists in the
867 * tree after startoffset
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200868 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500869 * -FDT_ERR_BADMAGIC,
870 * -FDT_ERR_BADVERSION,
871 * -FDT_ERR_BADSTATE,
872 * -FDT_ERR_BADSTRUCTURE, standard meanings
873 */
874int fdt_node_offset_by_prop_value(const void *fdt, int startoffset,
875 const char *propname,
876 const void *propval, int proplen);
877
878/**
879 * fdt_node_offset_by_phandle - find the node with a given phandle
880 * @fdt: pointer to the device tree blob
881 * @phandle: phandle value
882 *
Wolfram Sang46390da2008-07-09 11:22:44 +0200883 * fdt_node_offset_by_phandle() returns the offset of the node
Kumar Gala8d04f022007-10-24 11:04:22 -0500884 * which has the given phandle value. If there is more than one node
885 * in the tree with the given phandle (an invalid tree), results are
886 * undefined.
887 *
888 * returns:
889 * structure block offset of the located node (>= 0), on success
890 * -FDT_ERR_NOTFOUND, no node with that phandle exists
891 * -FDT_ERR_BADPHANDLE, given phandle value was invalid (0 or -1)
892 * -FDT_ERR_BADMAGIC,
893 * -FDT_ERR_BADVERSION,
894 * -FDT_ERR_BADSTATE,
895 * -FDT_ERR_BADSTRUCTURE, standard meanings
896 */
897int fdt_node_offset_by_phandle(const void *fdt, uint32_t phandle);
898
899/**
900 * fdt_node_check_compatible: check a node's compatible property
901 * @fdt: pointer to the device tree blob
902 * @nodeoffset: offset of a tree node
903 * @compatible: string to match against
904 *
905 *
906 * fdt_node_check_compatible() returns 0 if the given node contains a
907 * 'compatible' property with the given string as one of its elements,
908 * it returns non-zero otherwise, or on error.
909 *
910 * returns:
911 * 0, if the node has a 'compatible' property listing the given string
912 * 1, if the node has a 'compatible' property, but it does not list
913 * the given string
914 * -FDT_ERR_NOTFOUND, if the given node has no 'compatible' property
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200915 * -FDT_ERR_BADOFFSET, if nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500916 * -FDT_ERR_BADMAGIC,
917 * -FDT_ERR_BADVERSION,
918 * -FDT_ERR_BADSTATE,
919 * -FDT_ERR_BADSTRUCTURE, standard meanings
920 */
921int fdt_node_check_compatible(const void *fdt, int nodeoffset,
922 const char *compatible);
923
924/**
925 * fdt_node_offset_by_compatible - find nodes with a given 'compatible' value
926 * @fdt: pointer to the device tree blob
927 * @startoffset: only find nodes after this offset
928 * @compatible: 'compatible' string to match against
929 *
930 * fdt_node_offset_by_compatible() returns the offset of the first
931 * node after startoffset, which has a 'compatible' property which
932 * lists the given compatible string; or if startoffset is -1, the
933 * very first such node in the tree.
934 *
935 * To iterate through all nodes matching the criterion, the following
936 * idiom can be used:
937 * offset = fdt_node_offset_by_compatible(fdt, -1, compatible);
938 * while (offset != -FDT_ERR_NOTFOUND) {
Simon Glass0596d352014-07-30 03:59:03 -0600939 * // other code here
Kumar Gala8d04f022007-10-24 11:04:22 -0500940 * offset = fdt_node_offset_by_compatible(fdt, offset, compatible);
941 * }
942 *
943 * Note the -1 in the first call to the function, if 0 is used here
944 * instead, the function will never locate the root node, even if it
945 * matches the criterion.
946 *
947 * returns:
948 * structure block offset of the located node (>= 0, >startoffset),
949 * on success
950 * -FDT_ERR_NOTFOUND, no node matching the criterion exists in the
951 * tree after startoffset
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200952 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag
Kumar Gala8d04f022007-10-24 11:04:22 -0500953 * -FDT_ERR_BADMAGIC,
954 * -FDT_ERR_BADVERSION,
955 * -FDT_ERR_BADSTATE,
956 * -FDT_ERR_BADSTRUCTURE, standard meanings
957 */
958int fdt_node_offset_by_compatible(const void *fdt, int startoffset,
959 const char *compatible);
960
Simon Glasse853b322013-01-21 12:59:18 -0800961/**
962 * fdt_stringlist_contains - check a string list property for a string
963 * @strlist: Property containing a list of strings to check
964 * @listlen: Length of property
965 * @str: String to search for
966 *
967 * This is a utility function provided for convenience. The list contains
968 * one or more strings, each terminated by \0, as is found in a device tree
969 * "compatible" property.
970 *
971 * @return: 1 if the string is found in the list, 0 not found, or invalid list
972 */
973int fdt_stringlist_contains(const char *strlist, int listlen, const char *str);
974
Thierry Redingbc4147a2014-08-26 17:33:50 +0200975/**
Simon Glassb02e4042016-10-02 17:59:28 -0600976 * fdt_stringlist_count - count the number of strings in a string list
Thierry Redingbc4147a2014-08-26 17:33:50 +0200977 * @fdt: pointer to the device tree blob
Simon Glassb02e4042016-10-02 17:59:28 -0600978 * @nodeoffset: offset of a tree node
Thierry Redingbc4147a2014-08-26 17:33:50 +0200979 * @property: name of the property containing the string list
Simon Glassb02e4042016-10-02 17:59:28 -0600980 * @return:
981 * the number of strings in the given property
982 * -FDT_ERR_BADVALUE if the property value is not NUL-terminated
983 * -FDT_ERR_NOTFOUND if the property does not exist
Thierry Redingbc4147a2014-08-26 17:33:50 +0200984 */
Simon Glassb02e4042016-10-02 17:59:28 -0600985int fdt_stringlist_count(const void *fdt, int nodeoffset, const char *property);
Thierry Redingbc4147a2014-08-26 17:33:50 +0200986
Thierry Redingfc503c12014-08-26 17:33:51 +0200987/**
Simon Glassb02e4042016-10-02 17:59:28 -0600988 * fdt_stringlist_search - find a string in a string list and return its index
Thierry Redingfc503c12014-08-26 17:33:51 +0200989 * @fdt: pointer to the device tree blob
Simon Glassb02e4042016-10-02 17:59:28 -0600990 * @nodeoffset: offset of a tree node
Thierry Redingfc503c12014-08-26 17:33:51 +0200991 * @property: name of the property containing the string list
992 * @string: string to look up in the string list
Simon Glassb02e4042016-10-02 17:59:28 -0600993 *
994 * Note that it is possible for this function to succeed on property values
995 * that are not NUL-terminated. That's because the function will stop after
996 * finding the first occurrence of @string. This can for example happen with
997 * small-valued cell properties, such as #address-cells, when searching for
998 * the empty string.
999 *
1000 * @return:
1001 * the index of the string in the list of strings
1002 * -FDT_ERR_BADVALUE if the property value is not NUL-terminated
1003 * -FDT_ERR_NOTFOUND if the property does not exist or does not contain
1004 * the given string
Thierry Redingfc503c12014-08-26 17:33:51 +02001005 */
Simon Glassb02e4042016-10-02 17:59:28 -06001006int fdt_stringlist_search(const void *fdt, int nodeoffset, const char *property,
1007 const char *string);
Thierry Redingfc503c12014-08-26 17:33:51 +02001008
Thierry Reding5094eb42014-08-26 17:33:52 +02001009/**
Simon Glassb02e4042016-10-02 17:59:28 -06001010 * fdt_stringlist_get() - obtain the string at a given index in a string list
Thierry Reding5094eb42014-08-26 17:33:52 +02001011 * @fdt: pointer to the device tree blob
Simon Glassb02e4042016-10-02 17:59:28 -06001012 * @nodeoffset: offset of a tree node
Thierry Reding5094eb42014-08-26 17:33:52 +02001013 * @property: name of the property containing the string list
1014 * @index: index of the string to return
Simon Glassb02e4042016-10-02 17:59:28 -06001015 * @lenp: return location for the string length or an error code on failure
Thierry Reding5094eb42014-08-26 17:33:52 +02001016 *
Simon Glassb02e4042016-10-02 17:59:28 -06001017 * Note that this will successfully extract strings from properties with
1018 * non-NUL-terminated values. For example on small-valued cell properties
1019 * this function will return the empty string.
Thierry Reding5094eb42014-08-26 17:33:52 +02001020 *
Simon Glassb02e4042016-10-02 17:59:28 -06001021 * If non-NULL, the length of the string (on success) or a negative error-code
1022 * (on failure) will be stored in the integer pointer to by lenp.
1023 *
1024 * @return:
1025 * A pointer to the string at the given index in the string list or NULL on
1026 * failure. On success the length of the string will be stored in the memory
1027 * location pointed to by the lenp parameter, if non-NULL. On failure one of
1028 * the following negative error codes will be returned in the lenp parameter
1029 * (if non-NULL):
1030 * -FDT_ERR_BADVALUE if the property value is not NUL-terminated
1031 * -FDT_ERR_NOTFOUND if the property does not exist
Thierry Reding5094eb42014-08-26 17:33:52 +02001032 */
Simon Glassb02e4042016-10-02 17:59:28 -06001033const char *fdt_stringlist_get(const void *fdt, int nodeoffset,
1034 const char *property, int index,
1035 int *lenp);
Thierry Reding5094eb42014-08-26 17:33:52 +02001036
Kumar Gala8d04f022007-10-24 11:04:22 -05001037/**********************************************************************/
Simon Glass0596d352014-07-30 03:59:03 -06001038/* Read-only functions (addressing related) */
1039/**********************************************************************/
1040
1041/**
1042 * FDT_MAX_NCELLS - maximum value for #address-cells and #size-cells
1043 *
1044 * This is the maximum value for #address-cells, #size-cells and
1045 * similar properties that will be processed by libfdt. IEE1275
1046 * requires that OF implementations handle values up to 4.
1047 * Implementations may support larger values, but in practice higher
1048 * values aren't used.
1049 */
1050#define FDT_MAX_NCELLS 4
1051
1052/**
1053 * fdt_address_cells - retrieve address size for a bus represented in the tree
1054 * @fdt: pointer to the device tree blob
1055 * @nodeoffset: offset of the node to find the address size for
1056 *
1057 * When the node has a valid #address-cells property, returns its value.
1058 *
1059 * returns:
1060 * 0 <= n < FDT_MAX_NCELLS, on success
1061 * 2, if the node has no #address-cells property
1062 * -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid
1063 * #address-cells property
1064 * -FDT_ERR_BADMAGIC,
1065 * -FDT_ERR_BADVERSION,
1066 * -FDT_ERR_BADSTATE,
1067 * -FDT_ERR_BADSTRUCTURE,
1068 * -FDT_ERR_TRUNCATED, standard meanings
1069 */
1070int fdt_address_cells(const void *fdt, int nodeoffset);
1071
1072/**
1073 * fdt_size_cells - retrieve address range size for a bus represented in the
1074 * tree
1075 * @fdt: pointer to the device tree blob
1076 * @nodeoffset: offset of the node to find the address range size for
1077 *
1078 * When the node has a valid #size-cells property, returns its value.
1079 *
1080 * returns:
1081 * 0 <= n < FDT_MAX_NCELLS, on success
1082 * 2, if the node has no #address-cells property
1083 * -FDT_ERR_BADNCELLS, if the node has a badly formatted or invalid
1084 * #size-cells property
1085 * -FDT_ERR_BADMAGIC,
1086 * -FDT_ERR_BADVERSION,
1087 * -FDT_ERR_BADSTATE,
1088 * -FDT_ERR_BADSTRUCTURE,
1089 * -FDT_ERR_TRUNCATED, standard meanings
1090 */
1091int fdt_size_cells(const void *fdt, int nodeoffset);
1092
1093
1094/**********************************************************************/
Kumar Gala8d04f022007-10-24 11:04:22 -05001095/* Write-in-place functions */
1096/**********************************************************************/
1097
David Gibson9d4450b2007-12-17 14:41:52 +11001098/**
Maxime Ripardea7b1a22016-07-05 10:26:43 +02001099 * fdt_setprop_inplace_namelen_partial - change a property's value,
1100 * but not its size
1101 * @fdt: pointer to the device tree blob
1102 * @nodeoffset: offset of the node whose property to change
1103 * @name: name of the property to change
1104 * @namelen: number of characters of name to consider
Simon Glass9c07b982016-10-02 17:59:27 -06001105 * @idx: index of the property to change in the array
Maxime Ripardea7b1a22016-07-05 10:26:43 +02001106 * @val: pointer to data to replace the property value with
1107 * @len: length of the property value
1108 *
1109 * Identical to fdt_setprop_inplace(), but modifies the given property
1110 * starting from the given index, and using only the first characters
1111 * of the name. It is useful when you want to manipulate only one value of
1112 * an array and you have a string that doesn't end with \0.
1113 */
1114int fdt_setprop_inplace_namelen_partial(void *fdt, int nodeoffset,
1115 const char *name, int namelen,
Simon Glass9c07b982016-10-02 17:59:27 -06001116 uint32_t idx, const void *val,
Maxime Ripardea7b1a22016-07-05 10:26:43 +02001117 int len);
1118
1119/**
David Gibson9d4450b2007-12-17 14:41:52 +11001120 * fdt_setprop_inplace - change a property's value, but not its size
1121 * @fdt: pointer to the device tree blob
1122 * @nodeoffset: offset of the node whose property to change
1123 * @name: name of the property to change
1124 * @val: pointer to data to replace the property value with
1125 * @len: length of the property value
1126 *
1127 * fdt_setprop_inplace() replaces the value of a given property with
1128 * the data in val, of length len. This function cannot change the
1129 * size of a property, and so will only work if len is equal to the
1130 * current length of the property.
1131 *
1132 * This function will alter only the bytes in the blob which contain
1133 * the given property value, and will not alter or move any other part
1134 * of the tree.
1135 *
1136 * returns:
1137 * 0, on success
1138 * -FDT_ERR_NOSPACE, if len is not equal to the property's current length
1139 * -FDT_ERR_NOTFOUND, node does not have the named property
1140 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1141 * -FDT_ERR_BADMAGIC,
1142 * -FDT_ERR_BADVERSION,
1143 * -FDT_ERR_BADSTATE,
1144 * -FDT_ERR_BADSTRUCTURE,
1145 * -FDT_ERR_TRUNCATED, standard meanings
1146 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001147int fdt_setprop_inplace(void *fdt, int nodeoffset, const char *name,
1148 const void *val, int len);
David Gibson9d4450b2007-12-17 14:41:52 +11001149
1150/**
David Gibson24fa0e52012-08-27 19:39:00 -05001151 * fdt_setprop_inplace_u32 - change the value of a 32-bit integer property
David Gibson9d4450b2007-12-17 14:41:52 +11001152 * @fdt: pointer to the device tree blob
1153 * @nodeoffset: offset of the node whose property to change
1154 * @name: name of the property to change
David Gibson24fa0e52012-08-27 19:39:00 -05001155 * @val: 32-bit integer value to replace the property with
David Gibson9d4450b2007-12-17 14:41:52 +11001156 *
David Gibson24fa0e52012-08-27 19:39:00 -05001157 * fdt_setprop_inplace_u32() replaces the value of a given property
1158 * with the 32-bit integer value in val, converting val to big-endian
1159 * if necessary. This function cannot change the size of a property,
1160 * and so will only work if the property already exists and has length
1161 * 4.
David Gibson9d4450b2007-12-17 14:41:52 +11001162 *
1163 * This function will alter only the bytes in the blob which contain
1164 * the given property value, and will not alter or move any other part
1165 * of the tree.
1166 *
1167 * returns:
1168 * 0, on success
1169 * -FDT_ERR_NOSPACE, if the property's length is not equal to 4
David Gibson24fa0e52012-08-27 19:39:00 -05001170 * -FDT_ERR_NOTFOUND, node does not have the named property
David Gibson9d4450b2007-12-17 14:41:52 +11001171 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1172 * -FDT_ERR_BADMAGIC,
1173 * -FDT_ERR_BADVERSION,
1174 * -FDT_ERR_BADSTATE,
1175 * -FDT_ERR_BADSTRUCTURE,
1176 * -FDT_ERR_TRUNCATED, standard meanings
1177 */
David Gibson24fa0e52012-08-27 19:39:00 -05001178static inline int fdt_setprop_inplace_u32(void *fdt, int nodeoffset,
1179 const char *name, uint32_t val)
Kumar Gala8d04f022007-10-24 11:04:22 -05001180{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001181 fdt32_t tmp = cpu_to_fdt32(val);
1182 return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
Kumar Gala8d04f022007-10-24 11:04:22 -05001183}
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001184
David Gibson9d4450b2007-12-17 14:41:52 +11001185/**
David Gibson24fa0e52012-08-27 19:39:00 -05001186 * fdt_setprop_inplace_u64 - change the value of a 64-bit integer property
1187 * @fdt: pointer to the device tree blob
1188 * @nodeoffset: offset of the node whose property to change
1189 * @name: name of the property to change
1190 * @val: 64-bit integer value to replace the property with
1191 *
1192 * fdt_setprop_inplace_u64() replaces the value of a given property
1193 * with the 64-bit integer value in val, converting val to big-endian
1194 * if necessary. This function cannot change the size of a property,
1195 * and so will only work if the property already exists and has length
1196 * 8.
1197 *
1198 * This function will alter only the bytes in the blob which contain
1199 * the given property value, and will not alter or move any other part
1200 * of the tree.
1201 *
1202 * returns:
1203 * 0, on success
1204 * -FDT_ERR_NOSPACE, if the property's length is not equal to 8
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 */
1213static inline int fdt_setprop_inplace_u64(void *fdt, int nodeoffset,
1214 const char *name, uint64_t val)
1215{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001216 fdt64_t tmp = cpu_to_fdt64(val);
1217 return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
David Gibson24fa0e52012-08-27 19:39:00 -05001218}
1219
1220/**
1221 * fdt_setprop_inplace_cell - change the value of a single-cell property
1222 *
1223 * This is an alternative name for fdt_setprop_inplace_u32()
1224 */
1225static inline int fdt_setprop_inplace_cell(void *fdt, int nodeoffset,
1226 const char *name, uint32_t val)
1227{
1228 return fdt_setprop_inplace_u32(fdt, nodeoffset, name, val);
1229}
1230
1231/**
David Gibson9d4450b2007-12-17 14:41:52 +11001232 * fdt_nop_property - replace a property with nop tags
1233 * @fdt: pointer to the device tree blob
1234 * @nodeoffset: offset of the node whose property to nop
1235 * @name: name of the property to nop
1236 *
1237 * fdt_nop_property() will replace a given property's representation
1238 * in the blob with FDT_NOP tags, effectively removing it from the
1239 * tree.
1240 *
1241 * This function will alter only the bytes in the blob which contain
1242 * the property, and will not alter or move any other part of the
1243 * tree.
1244 *
1245 * returns:
1246 * 0, on success
1247 * -FDT_ERR_NOTFOUND, node does not have the named property
1248 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1249 * -FDT_ERR_BADMAGIC,
1250 * -FDT_ERR_BADVERSION,
1251 * -FDT_ERR_BADSTATE,
1252 * -FDT_ERR_BADSTRUCTURE,
1253 * -FDT_ERR_TRUNCATED, standard meanings
1254 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001255int fdt_nop_property(void *fdt, int nodeoffset, const char *name);
David Gibson9d4450b2007-12-17 14:41:52 +11001256
1257/**
1258 * fdt_nop_node - replace a node (subtree) with nop tags
1259 * @fdt: pointer to the device tree blob
1260 * @nodeoffset: offset of the node to nop
1261 *
1262 * fdt_nop_node() will replace a given node's representation in the
1263 * blob, including all its subnodes, if any, with FDT_NOP tags,
1264 * effectively removing it from the tree.
1265 *
1266 * This function will alter only the bytes in the blob which contain
1267 * the node and its properties and subnodes, and will not alter or
1268 * move any other part of the tree.
1269 *
1270 * returns:
1271 * 0, on success
1272 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1273 * -FDT_ERR_BADMAGIC,
1274 * -FDT_ERR_BADVERSION,
1275 * -FDT_ERR_BADSTATE,
1276 * -FDT_ERR_BADSTRUCTURE,
1277 * -FDT_ERR_TRUNCATED, standard meanings
1278 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001279int fdt_nop_node(void *fdt, int nodeoffset);
Gerald Van Baren3f9f08c2007-04-14 22:46:41 -04001280
Kumar Gala8d04f022007-10-24 11:04:22 -05001281/**********************************************************************/
1282/* Sequential write functions */
1283/**********************************************************************/
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001284
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001285int fdt_create(void *buf, int bufsize);
Simon Glass0596d352014-07-30 03:59:03 -06001286int fdt_resize(void *fdt, void *buf, int bufsize);
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001287int fdt_add_reservemap_entry(void *fdt, uint64_t addr, uint64_t size);
1288int fdt_finish_reservemap(void *fdt);
1289int fdt_begin_node(void *fdt, const char *name);
1290int fdt_property(void *fdt, const char *name, const void *val, int len);
David Gibson24fa0e52012-08-27 19:39:00 -05001291static inline int fdt_property_u32(void *fdt, const char *name, uint32_t val)
Kumar Gala8d04f022007-10-24 11:04:22 -05001292{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001293 fdt32_t tmp = cpu_to_fdt32(val);
1294 return fdt_property(fdt, name, &tmp, sizeof(tmp));
Kumar Gala8d04f022007-10-24 11:04:22 -05001295}
David Gibson24fa0e52012-08-27 19:39:00 -05001296static inline int fdt_property_u64(void *fdt, const char *name, uint64_t val)
1297{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001298 fdt64_t tmp = cpu_to_fdt64(val);
1299 return fdt_property(fdt, name, &tmp, sizeof(tmp));
David Gibson24fa0e52012-08-27 19:39:00 -05001300}
1301static inline int fdt_property_cell(void *fdt, const char *name, uint32_t val)
1302{
1303 return fdt_property_u32(fdt, name, val);
1304}
Simon Glassf8a2d7a2016-02-22 22:55:39 -07001305
1306/**
1307 * fdt_property_placeholder - add a new property and return a ptr to its value
1308 *
1309 * @fdt: pointer to the device tree blob
1310 * @name: name of property to add
1311 * @len: length of property value in bytes
1312 * @valp: returns a pointer to where where the value should be placed
1313 *
1314 * returns:
1315 * 0, on success
1316 * -FDT_ERR_BADMAGIC,
1317 * -FDT_ERR_NOSPACE, standard meanings
1318 */
1319int fdt_property_placeholder(void *fdt, const char *name, int len, void **valp);
1320
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001321#define fdt_property_string(fdt, name, str) \
1322 fdt_property(fdt, name, str, strlen(str)+1)
1323int fdt_end_node(void *fdt);
1324int fdt_finish(void *fdt);
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001325
Kumar Gala8d04f022007-10-24 11:04:22 -05001326/**********************************************************************/
1327/* Read-write functions */
1328/**********************************************************************/
1329
Gerald Van Barenc71b64f2012-10-15 22:24:36 -04001330int fdt_create_empty_tree(void *buf, int bufsize);
Kumar Gala8d04f022007-10-24 11:04:22 -05001331int fdt_open_into(const void *fdt, void *buf, int bufsize);
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001332int fdt_pack(void *fdt);
1333
David Gibsonaec71352007-12-17 14:42:07 +11001334/**
1335 * fdt_add_mem_rsv - add one memory reserve map entry
1336 * @fdt: pointer to the device tree blob
Wolfram Sang46390da2008-07-09 11:22:44 +02001337 * @address, @size: 64-bit values (native endian)
David Gibsonaec71352007-12-17 14:42:07 +11001338 *
1339 * Adds a reserve map entry to the given blob reserving a region at
1340 * address address of length size.
1341 *
1342 * This function will insert data into the reserve map and will
Wolfram Sang46390da2008-07-09 11:22:44 +02001343 * therefore change the indexes of some entries in the table.
David Gibsonaec71352007-12-17 14:42:07 +11001344 *
1345 * returns:
1346 * 0, on success
1347 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1348 * contain the new reservation entry
1349 * -FDT_ERR_BADMAGIC,
1350 * -FDT_ERR_BADVERSION,
1351 * -FDT_ERR_BADSTATE,
1352 * -FDT_ERR_BADSTRUCTURE,
1353 * -FDT_ERR_BADLAYOUT,
1354 * -FDT_ERR_TRUNCATED, standard meanings
1355 */
Kumar Gala8d04f022007-10-24 11:04:22 -05001356int fdt_add_mem_rsv(void *fdt, uint64_t address, uint64_t size);
David Gibsonaec71352007-12-17 14:42:07 +11001357
1358/**
1359 * fdt_del_mem_rsv - remove a memory reserve map entry
1360 * @fdt: pointer to the device tree blob
1361 * @n: entry to remove
1362 *
1363 * fdt_del_mem_rsv() removes the n-th memory reserve map entry from
1364 * the blob.
1365 *
1366 * This function will delete data from the reservation table and will
Wolfram Sang46390da2008-07-09 11:22:44 +02001367 * therefore change the indexes of some entries in the table.
David Gibsonaec71352007-12-17 14:42:07 +11001368 *
1369 * returns:
1370 * 0, on success
1371 * -FDT_ERR_NOTFOUND, there is no entry of the given index (i.e. there
1372 * are less than n+1 reserve map entries)
1373 * -FDT_ERR_BADMAGIC,
1374 * -FDT_ERR_BADVERSION,
1375 * -FDT_ERR_BADSTATE,
1376 * -FDT_ERR_BADSTRUCTURE,
1377 * -FDT_ERR_BADLAYOUT,
1378 * -FDT_ERR_TRUNCATED, standard meanings
1379 */
Kumar Gala8d04f022007-10-24 11:04:22 -05001380int fdt_del_mem_rsv(void *fdt, int n);
1381
David Gibsonaec71352007-12-17 14:42:07 +11001382/**
David Gibson9eaeb072008-01-11 14:55:05 +11001383 * fdt_set_name - change the name of a given node
1384 * @fdt: pointer to the device tree blob
1385 * @nodeoffset: structure block offset of a node
1386 * @name: name to give the node
1387 *
1388 * fdt_set_name() replaces the name (including unit address, if any)
1389 * of the given node with the given string. NOTE: this function can't
1390 * efficiently check if the new name is unique amongst the given
1391 * node's siblings; results are undefined if this function is invoked
1392 * with a name equal to one of the given node's siblings.
1393 *
1394 * This function may insert or delete data from the blob, and will
1395 * therefore change the offsets of some existing nodes.
1396 *
1397 * returns:
1398 * 0, on success
1399 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob
1400 * to contain the new name
1401 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1402 * -FDT_ERR_BADMAGIC,
1403 * -FDT_ERR_BADVERSION,
1404 * -FDT_ERR_BADSTATE, standard meanings
1405 */
1406int fdt_set_name(void *fdt, int nodeoffset, const char *name);
1407
1408/**
David Gibsonaec71352007-12-17 14:42:07 +11001409 * fdt_setprop - create or change a property
1410 * @fdt: pointer to the device tree blob
1411 * @nodeoffset: offset of the node whose property to change
1412 * @name: name of the property to change
1413 * @val: pointer to data to set the property value to
1414 * @len: length of the property value
1415 *
1416 * fdt_setprop() sets the value of the named property in the given
Wolfram Sang46390da2008-07-09 11:22:44 +02001417 * node to the given value and length, creating the property if it
David Gibsonaec71352007-12-17 14:42:07 +11001418 * does not already exist.
1419 *
1420 * This function may insert or delete data from the blob, and will
1421 * therefore change the offsets of some existing nodes.
1422 *
1423 * returns:
1424 * 0, on success
1425 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1426 * contain the new property value
1427 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1428 * -FDT_ERR_BADLAYOUT,
1429 * -FDT_ERR_BADMAGIC,
1430 * -FDT_ERR_BADVERSION,
1431 * -FDT_ERR_BADSTATE,
1432 * -FDT_ERR_BADSTRUCTURE,
1433 * -FDT_ERR_BADLAYOUT,
1434 * -FDT_ERR_TRUNCATED, standard meanings
1435 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001436int fdt_setprop(void *fdt, int nodeoffset, const char *name,
1437 const void *val, int len);
David Gibsonaec71352007-12-17 14:42:07 +11001438
1439/**
David Gibson24fa0e52012-08-27 19:39:00 -05001440 * fdt_setprop_u32 - set a property to a 32-bit integer
David Gibsonaec71352007-12-17 14:42:07 +11001441 * @fdt: pointer to the device tree blob
1442 * @nodeoffset: offset of the node whose property to change
1443 * @name: name of the property to change
1444 * @val: 32-bit integer value for the property (native endian)
1445 *
David Gibson24fa0e52012-08-27 19:39:00 -05001446 * fdt_setprop_u32() sets the value of the named property in the given
1447 * node to the given 32-bit integer value (converting to big-endian if
David Gibsonaec71352007-12-17 14:42:07 +11001448 * necessary), or creates a new property with that value if it does
1449 * not already exist.
1450 *
1451 * This function may insert or delete data from the blob, and will
1452 * therefore change the offsets of some existing nodes.
1453 *
1454 * returns:
1455 * 0, on success
1456 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1457 * contain the new property value
1458 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1459 * -FDT_ERR_BADLAYOUT,
1460 * -FDT_ERR_BADMAGIC,
1461 * -FDT_ERR_BADVERSION,
1462 * -FDT_ERR_BADSTATE,
1463 * -FDT_ERR_BADSTRUCTURE,
1464 * -FDT_ERR_BADLAYOUT,
1465 * -FDT_ERR_TRUNCATED, standard meanings
1466 */
David Gibson24fa0e52012-08-27 19:39:00 -05001467static inline int fdt_setprop_u32(void *fdt, int nodeoffset, const char *name,
1468 uint32_t val)
Kumar Gala8d04f022007-10-24 11:04:22 -05001469{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001470 fdt32_t tmp = cpu_to_fdt32(val);
1471 return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
Kumar Gala8d04f022007-10-24 11:04:22 -05001472}
David Gibsonaec71352007-12-17 14:42:07 +11001473
1474/**
David Gibson24fa0e52012-08-27 19:39:00 -05001475 * fdt_setprop_u64 - set a property to a 64-bit integer
1476 * @fdt: pointer to the device tree blob
1477 * @nodeoffset: offset of the node whose property to change
1478 * @name: name of the property to change
1479 * @val: 64-bit integer value for the property (native endian)
1480 *
1481 * fdt_setprop_u64() sets the value of the named property in the given
1482 * node to the given 64-bit integer value (converting to big-endian if
1483 * necessary), or creates a new property with that value if it does
1484 * not already exist.
1485 *
1486 * This function may insert or delete data from the blob, and will
1487 * therefore change the offsets of some existing nodes.
1488 *
1489 * returns:
1490 * 0, on success
1491 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1492 * contain the new property value
1493 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1494 * -FDT_ERR_BADLAYOUT,
1495 * -FDT_ERR_BADMAGIC,
1496 * -FDT_ERR_BADVERSION,
1497 * -FDT_ERR_BADSTATE,
1498 * -FDT_ERR_BADSTRUCTURE,
1499 * -FDT_ERR_BADLAYOUT,
1500 * -FDT_ERR_TRUNCATED, standard meanings
1501 */
1502static inline int fdt_setprop_u64(void *fdt, int nodeoffset, const char *name,
1503 uint64_t val)
1504{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001505 fdt64_t tmp = cpu_to_fdt64(val);
1506 return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
David Gibson24fa0e52012-08-27 19:39:00 -05001507}
1508
1509/**
1510 * fdt_setprop_cell - set a property to a single cell value
1511 *
1512 * This is an alternative name for fdt_setprop_u32()
1513 */
1514static inline int fdt_setprop_cell(void *fdt, int nodeoffset, const char *name,
1515 uint32_t val)
1516{
1517 return fdt_setprop_u32(fdt, nodeoffset, name, val);
1518}
1519
1520/**
David Gibsonaec71352007-12-17 14:42:07 +11001521 * fdt_setprop_string - set a property to a string value
1522 * @fdt: pointer to the device tree blob
1523 * @nodeoffset: offset of the node whose property to change
1524 * @name: name of the property to change
1525 * @str: string value for the property
1526 *
1527 * fdt_setprop_string() sets the value of the named property in the
1528 * given node to the given string value (using the length of the
1529 * string to determine the new length of the property), or creates a
1530 * new property with that value if it does not already exist.
1531 *
1532 * This function may insert or delete data from the blob, and will
1533 * therefore change the offsets of some existing nodes.
1534 *
1535 * returns:
1536 * 0, on success
1537 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1538 * contain the new property value
1539 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1540 * -FDT_ERR_BADLAYOUT,
1541 * -FDT_ERR_BADMAGIC,
1542 * -FDT_ERR_BADVERSION,
1543 * -FDT_ERR_BADSTATE,
1544 * -FDT_ERR_BADSTRUCTURE,
1545 * -FDT_ERR_BADLAYOUT,
1546 * -FDT_ERR_TRUNCATED, standard meanings
1547 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001548#define fdt_setprop_string(fdt, nodeoffset, name, str) \
1549 fdt_setprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)
David Gibsonaec71352007-12-17 14:42:07 +11001550
1551/**
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001552 * fdt_appendprop - append to or create a property
1553 * @fdt: pointer to the device tree blob
1554 * @nodeoffset: offset of the node whose property to change
1555 * @name: name of the property to append to
1556 * @val: pointer to data to append to the property value
1557 * @len: length of the data to append to the property value
1558 *
1559 * fdt_appendprop() appends the value to the named property in the
1560 * given node, creating the property if it does not already exist.
1561 *
1562 * This function may insert data into the blob, and will therefore
1563 * change the offsets of some existing nodes.
1564 *
1565 * returns:
1566 * 0, on success
1567 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1568 * contain the new property value
1569 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1570 * -FDT_ERR_BADLAYOUT,
1571 * -FDT_ERR_BADMAGIC,
1572 * -FDT_ERR_BADVERSION,
1573 * -FDT_ERR_BADSTATE,
1574 * -FDT_ERR_BADSTRUCTURE,
1575 * -FDT_ERR_BADLAYOUT,
1576 * -FDT_ERR_TRUNCATED, standard meanings
1577 */
1578int fdt_appendprop(void *fdt, int nodeoffset, const char *name,
1579 const void *val, int len);
1580
1581/**
David Gibson24fa0e52012-08-27 19:39:00 -05001582 * fdt_appendprop_u32 - append a 32-bit integer value to a property
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001583 * @fdt: pointer to the device tree blob
1584 * @nodeoffset: offset of the node whose property to change
1585 * @name: name of the property to change
1586 * @val: 32-bit integer value to append to the property (native endian)
1587 *
David Gibson24fa0e52012-08-27 19:39:00 -05001588 * fdt_appendprop_u32() appends the given 32-bit integer value
1589 * (converting to big-endian if necessary) to the value of the named
1590 * property in the given node, or creates a new property with that
1591 * value if it does not already exist.
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001592 *
1593 * This function may insert data into the blob, and will therefore
1594 * change the offsets of some existing nodes.
1595 *
1596 * returns:
1597 * 0, on success
1598 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1599 * contain the new property value
1600 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1601 * -FDT_ERR_BADLAYOUT,
1602 * -FDT_ERR_BADMAGIC,
1603 * -FDT_ERR_BADVERSION,
1604 * -FDT_ERR_BADSTATE,
1605 * -FDT_ERR_BADSTRUCTURE,
1606 * -FDT_ERR_BADLAYOUT,
1607 * -FDT_ERR_TRUNCATED, standard meanings
1608 */
David Gibson24fa0e52012-08-27 19:39:00 -05001609static inline int fdt_appendprop_u32(void *fdt, int nodeoffset,
1610 const char *name, uint32_t val)
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001611{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001612 fdt32_t tmp = cpu_to_fdt32(val);
1613 return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001614}
1615
1616/**
David Gibson24fa0e52012-08-27 19:39:00 -05001617 * fdt_appendprop_u64 - append a 64-bit integer value to a property
1618 * @fdt: pointer to the device tree blob
1619 * @nodeoffset: offset of the node whose property to change
1620 * @name: name of the property to change
1621 * @val: 64-bit integer value to append to the property (native endian)
1622 *
1623 * fdt_appendprop_u64() appends the given 64-bit integer value
1624 * (converting to big-endian if necessary) to the value of the named
1625 * property in the given node, or creates a new property with that
1626 * value if it does not already exist.
1627 *
1628 * This function may insert data into the blob, and will therefore
1629 * change the offsets of some existing nodes.
1630 *
1631 * returns:
1632 * 0, on success
1633 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1634 * contain the new property value
1635 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1636 * -FDT_ERR_BADLAYOUT,
1637 * -FDT_ERR_BADMAGIC,
1638 * -FDT_ERR_BADVERSION,
1639 * -FDT_ERR_BADSTATE,
1640 * -FDT_ERR_BADSTRUCTURE,
1641 * -FDT_ERR_BADLAYOUT,
1642 * -FDT_ERR_TRUNCATED, standard meanings
1643 */
1644static inline int fdt_appendprop_u64(void *fdt, int nodeoffset,
1645 const char *name, uint64_t val)
1646{
Kim Phillipsb2ba62a2013-01-16 13:59:50 +00001647 fdt64_t tmp = cpu_to_fdt64(val);
1648 return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
David Gibson24fa0e52012-08-27 19:39:00 -05001649}
1650
1651/**
1652 * fdt_appendprop_cell - append a single cell value to a property
1653 *
1654 * This is an alternative name for fdt_appendprop_u32()
1655 */
1656static inline int fdt_appendprop_cell(void *fdt, int nodeoffset,
1657 const char *name, uint32_t val)
1658{
1659 return fdt_appendprop_u32(fdt, nodeoffset, name, val);
1660}
1661
1662/**
Minghuan Lian36ad18a2012-08-27 19:38:59 -05001663 * fdt_appendprop_string - append a string to a property
1664 * @fdt: pointer to the device tree blob
1665 * @nodeoffset: offset of the node whose property to change
1666 * @name: name of the property to change
1667 * @str: string value to append to the property
1668 *
1669 * fdt_appendprop_string() appends the given string to the value of
1670 * the named property in the given node, or creates a new property
1671 * with that value if it does not already exist.
1672 *
1673 * This function may insert data into the blob, and will therefore
1674 * change the offsets of some existing nodes.
1675 *
1676 * returns:
1677 * 0, on success
1678 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to
1679 * contain the new property value
1680 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1681 * -FDT_ERR_BADLAYOUT,
1682 * -FDT_ERR_BADMAGIC,
1683 * -FDT_ERR_BADVERSION,
1684 * -FDT_ERR_BADSTATE,
1685 * -FDT_ERR_BADSTRUCTURE,
1686 * -FDT_ERR_BADLAYOUT,
1687 * -FDT_ERR_TRUNCATED, standard meanings
1688 */
1689#define fdt_appendprop_string(fdt, nodeoffset, name, str) \
1690 fdt_appendprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)
1691
1692/**
David Gibsonaec71352007-12-17 14:42:07 +11001693 * fdt_delprop - delete a property
1694 * @fdt: pointer to the device tree blob
1695 * @nodeoffset: offset of the node whose property to nop
1696 * @name: name of the property to nop
1697 *
1698 * fdt_del_property() will delete the given property.
1699 *
1700 * This function will delete data from the blob, and will therefore
1701 * change the offsets of some existing nodes.
1702 *
1703 * returns:
1704 * 0, on success
1705 * -FDT_ERR_NOTFOUND, node does not have the named property
1706 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1707 * -FDT_ERR_BADLAYOUT,
1708 * -FDT_ERR_BADMAGIC,
1709 * -FDT_ERR_BADVERSION,
1710 * -FDT_ERR_BADSTATE,
1711 * -FDT_ERR_BADSTRUCTURE,
1712 * -FDT_ERR_TRUNCATED, standard meanings
1713 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001714int fdt_delprop(void *fdt, int nodeoffset, const char *name);
David Gibsonaec71352007-12-17 14:42:07 +11001715
1716/**
1717 * fdt_add_subnode_namelen - creates a new node based on substring
1718 * @fdt: pointer to the device tree blob
1719 * @parentoffset: structure block offset of a node
1720 * @name: name of the subnode to locate
1721 * @namelen: number of characters of name to consider
1722 *
1723 * Identical to fdt_add_subnode(), but use only the first namelen
1724 * characters of name as the name of the new node. This is useful for
1725 * creating subnodes based on a portion of a larger string, such as a
1726 * full path.
1727 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001728int fdt_add_subnode_namelen(void *fdt, int parentoffset,
1729 const char *name, int namelen);
David Gibsonaec71352007-12-17 14:42:07 +11001730
1731/**
1732 * fdt_add_subnode - creates a new node
1733 * @fdt: pointer to the device tree blob
1734 * @parentoffset: structure block offset of a node
1735 * @name: name of the subnode to locate
1736 *
1737 * fdt_add_subnode() creates a new node as a subnode of the node at
1738 * structure block offset parentoffset, with the given name (which
1739 * should include the unit address, if any).
1740 *
1741 * This function will insert data into the blob, and will therefore
1742 * change the offsets of some existing nodes.
1743
1744 * returns:
Simon Glass9c07b982016-10-02 17:59:27 -06001745 * structure block offset of the created nodeequested subnode (>=0), on
1746 * success
David Gibsonaec71352007-12-17 14:42:07 +11001747 * -FDT_ERR_NOTFOUND, if the requested subnode does not exist
Simon Glass9c07b982016-10-02 17:59:27 -06001748 * -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE
1749 * tag
David Gibsonaec71352007-12-17 14:42:07 +11001750 * -FDT_ERR_EXISTS, if the node at parentoffset already has a subnode of
1751 * the given name
1752 * -FDT_ERR_NOSPACE, if there is insufficient free space in the
1753 * blob to contain the new node
1754 * -FDT_ERR_NOSPACE
1755 * -FDT_ERR_BADLAYOUT
1756 * -FDT_ERR_BADMAGIC,
1757 * -FDT_ERR_BADVERSION,
1758 * -FDT_ERR_BADSTATE,
1759 * -FDT_ERR_BADSTRUCTURE,
1760 * -FDT_ERR_TRUNCATED, standard meanings.
1761 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001762int fdt_add_subnode(void *fdt, int parentoffset, const char *name);
David Gibsonaec71352007-12-17 14:42:07 +11001763
1764/**
1765 * fdt_del_node - delete a node (subtree)
1766 * @fdt: pointer to the device tree blob
1767 * @nodeoffset: offset of the node to nop
1768 *
1769 * fdt_del_node() will remove the given node, including all its
1770 * subnodes if any, from the blob.
1771 *
1772 * This function will delete data from the blob, and will therefore
1773 * change the offsets of some existing nodes.
1774 *
1775 * returns:
1776 * 0, on success
1777 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag
1778 * -FDT_ERR_BADLAYOUT,
1779 * -FDT_ERR_BADMAGIC,
1780 * -FDT_ERR_BADVERSION,
1781 * -FDT_ERR_BADSTATE,
1782 * -FDT_ERR_BADSTRUCTURE,
1783 * -FDT_ERR_TRUNCATED, standard meanings
1784 */
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001785int fdt_del_node(void *fdt, int nodeoffset);
1786
Maxime Ripardddf67f72016-07-05 10:26:44 +02001787/**
1788 * fdt_overlay_apply - Applies a DT overlay on a base DT
1789 * @fdt: pointer to the base device tree blob
1790 * @fdto: pointer to the device tree overlay blob
1791 *
1792 * fdt_overlay_apply() will apply the given device tree overlay on the
1793 * given base device tree.
1794 *
1795 * Expect the base device tree to be modified, even if the function
1796 * returns an error.
1797 *
1798 * returns:
1799 * 0, on success
1800 * -FDT_ERR_NOSPACE, there's not enough space in the base device tree
1801 * -FDT_ERR_NOTFOUND, the overlay points to some inexistant nodes or
1802 * properties in the base DT
Maxime Ripard610db702016-10-17 22:50:18 +02001803 * -FDT_ERR_BADPHANDLE,
1804 * -FDT_ERR_BADOVERLAY,
1805 * -FDT_ERR_NOPHANDLES,
Maxime Ripardddf67f72016-07-05 10:26:44 +02001806 * -FDT_ERR_INTERNAL,
1807 * -FDT_ERR_BADLAYOUT,
1808 * -FDT_ERR_BADMAGIC,
1809 * -FDT_ERR_BADOFFSET,
1810 * -FDT_ERR_BADPATH,
1811 * -FDT_ERR_BADVERSION,
1812 * -FDT_ERR_BADSTRUCTURE,
1813 * -FDT_ERR_BADSTATE,
1814 * -FDT_ERR_TRUNCATED, standard meanings
1815 */
1816int fdt_overlay_apply(void *fdt, void *fdto);
1817
Kumar Gala8d04f022007-10-24 11:04:22 -05001818/**********************************************************************/
1819/* Debugging / informational functions */
1820/**********************************************************************/
1821
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04001822const char *fdt_strerror(int errval);
1823
Simon Glass8f6e2e12015-06-23 15:38:26 -06001824/**
1825 * fdt_remove_unused_strings() - Remove any unused strings from an FDT
1826 *
1827 * This creates a new device tree in @new with unused strings removed. The
1828 * called can then use fdt_pack() to minimise the space consumed.
1829 *
1830 * @old: Old device tree blog
1831 * @new: Place to put new device tree blob, which must be as large as
1832 * @old
1833 * @return
1834 * 0, on success
1835 * -FDT_ERR_BADOFFSET, corrupt device tree
1836 * -FDT_ERR_NOSPACE, out of space, which should not happen unless there
1837 * is something very wrong with the device tree input
1838 */
1839int fdt_remove_unused_strings(const void *old, void *new);
1840
Simon Glass3e06cd12013-06-13 15:10:08 -07001841struct fdt_region {
1842 int offset;
1843 int size;
1844};
1845
Simon Glassc3c4c002015-06-23 15:38:27 -06001846/*
1847 * Flags for fdt_find_regions()
1848 *
1849 * Add a region for the string table (always the last region)
1850 */
1851#define FDT_REG_ADD_STRING_TAB (1 << 0)
1852
1853/*
1854 * Add all supernodes of a matching node/property, useful for creating a
1855 * valid subset tree
1856 */
1857#define FDT_REG_SUPERNODES (1 << 1)
1858
1859/* Add the FDT_BEGIN_NODE tags of subnodes, including their names */
1860#define FDT_REG_DIRECT_SUBNODES (1 << 2)
1861
1862/* Add all subnodes of a matching node */
1863#define FDT_REG_ALL_SUBNODES (1 << 3)
1864
1865/* Add a region for the mem_rsvmap table (always the first region) */
1866#define FDT_REG_ADD_MEM_RSVMAP (1 << 4)
1867
1868/* Indicates what an fdt part is (node, property, value) */
1869#define FDT_IS_NODE (1 << 0)
1870#define FDT_IS_PROP (1 << 1)
1871#define FDT_IS_VALUE (1 << 2) /* not supported */
1872#define FDT_IS_COMPAT (1 << 3) /* used internally */
1873#define FDT_NODE_HAS_PROP (1 << 4) /* node contains prop */
1874
1875#define FDT_ANY_GLOBAL (FDT_IS_NODE | FDT_IS_PROP | FDT_IS_VALUE | \
1876 FDT_IS_COMPAT)
1877#define FDT_IS_ANY 0x1f /* all the above */
1878
1879/* We set a reasonable limit on the number of nested nodes */
1880#define FDT_MAX_DEPTH 32
1881
1882/* Decribes what we want to include from the current tag */
1883enum want_t {
1884 WANT_NOTHING,
1885 WANT_NODES_ONLY, /* No properties */
1886 WANT_NODES_AND_PROPS, /* Everything for one level */
1887 WANT_ALL_NODES_AND_PROPS /* Everything for all levels */
1888};
1889
1890/* Keeps track of the state at parent nodes */
1891struct fdt_subnode_stack {
1892 int offset; /* Offset of node */
1893 enum want_t want; /* The 'want' value here */
1894 int included; /* 1 if we included this node, 0 if not */
1895};
1896
1897struct fdt_region_ptrs {
1898 int depth; /* Current tree depth */
1899 int done; /* What we have completed scanning */
1900 enum want_t want; /* What we are currently including */
1901 char *end; /* Pointer to end of full node path */
1902 int nextoffset; /* Next node offset to check */
1903};
1904
1905/* The state of our finding algortihm */
1906struct fdt_region_state {
1907 struct fdt_subnode_stack stack[FDT_MAX_DEPTH]; /* node stack */
1908 struct fdt_region *region; /* Contains list of regions found */
1909 int count; /* Numnber of regions found */
1910 const void *fdt; /* FDT blob */
1911 int max_regions; /* Maximum regions to find */
1912 int can_merge; /* 1 if we can merge with previous region */
1913 int start; /* Start position of current region */
1914 struct fdt_region_ptrs ptrs; /* Pointers for what we are up to */
1915};
1916
Simon Glass3e06cd12013-06-13 15:10:08 -07001917/**
1918 * fdt_find_regions() - find regions in device tree
1919 *
1920 * Given a list of nodes to include and properties to exclude, find
1921 * the regions of the device tree which describe those included parts.
1922 *
1923 * The intent is to get a list of regions which will be invariant provided
1924 * those parts are invariant. For example, if you request a list of regions
1925 * for all nodes but exclude the property "data", then you will get the
1926 * same region contents regardless of any change to "data" properties.
1927 *
1928 * This function can be used to produce a byte-stream to send to a hashing
1929 * function to verify that critical parts of the FDT have not changed.
1930 *
1931 * Nodes which are given in 'inc' are included in the region list, as
1932 * are the names of the immediate subnodes nodes (but not the properties
1933 * or subnodes of those subnodes).
1934 *
1935 * For eaxample "/" means to include the root node, all root properties
1936 * and the FDT_BEGIN_NODE and FDT_END_NODE of all subnodes of /. The latter
1937 * ensures that we capture the names of the subnodes. In a hashing situation
1938 * it prevents the root node from changing at all Any change to non-excluded
1939 * properties, names of subnodes or number of subnodes would be detected.
1940 *
1941 * When used with FITs this provides the ability to hash and sign parts of
1942 * the FIT based on different configurations in the FIT. Then it is
1943 * impossible to change anything about that configuration (include images
1944 * attached to the configuration), but it may be possible to add new
1945 * configurations, new images or new signatures within the existing
1946 * framework.
1947 *
1948 * Adding new properties to a device tree may result in the string table
1949 * being extended (if the new property names are different from those
1950 * already added). This function can optionally include a region for
1951 * the string table so that this can be part of the hash too.
1952 *
1953 * The device tree header is not included in the list.
1954 *
1955 * @fdt: Device tree to check
1956 * @inc: List of node paths to included
1957 * @inc_count: Number of node paths in list
1958 * @exc_prop: List of properties names to exclude
1959 * @exc_prop_count: Number of properties in exclude list
1960 * @region: Returns list of regions
1961 * @max_region: Maximum length of region list
1962 * @path: Pointer to a temporary string for the function to use for
1963 * building path names
1964 * @path_len: Length of path, must be large enough to hold the longest
1965 * path in the tree
1966 * @add_string_tab: 1 to add a region for the string table
1967 * @return number of regions in list. If this is >max_regions then the
1968 * region array was exhausted. You should increase max_regions and try
1969 * the call again.
1970 */
1971int fdt_find_regions(const void *fdt, char * const inc[], int inc_count,
1972 char * const exc_prop[], int exc_prop_count,
1973 struct fdt_region region[], int max_regions,
1974 char *path, int path_len, int add_string_tab);
1975
Simon Glassc3c4c002015-06-23 15:38:27 -06001976/**
1977 * fdt_first_region() - find regions in device tree
1978 *
1979 * Given a nodes and properties to include and properties to exclude, find
1980 * the regions of the device tree which describe those included parts.
1981 *
1982 * The use for this function is twofold. Firstly it provides a convenient
1983 * way of performing a structure-aware grep of the tree. For example it is
1984 * possible to grep for a node and get all the properties associated with
1985 * that node. Trees can be subsetted easily, by specifying the nodes that
1986 * are required, and then writing out the regions returned by this function.
1987 * This is useful for small resource-constrained systems, such as boot
1988 * loaders, which want to use an FDT but do not need to know about all of
1989 * it.
1990 *
1991 * Secondly it makes it easy to hash parts of the tree and detect changes.
1992 * The intent is to get a list of regions which will be invariant provided
1993 * those parts are invariant. For example, if you request a list of regions
1994 * for all nodes but exclude the property "data", then you will get the
1995 * same region contents regardless of any change to "data" properties.
1996 *
1997 * This function can be used to produce a byte-stream to send to a hashing
1998 * function to verify that critical parts of the FDT have not changed.
1999 * Note that semantically null changes in order could still cause false
2000 * hash misses. Such reordering might happen if the tree is regenerated
2001 * from source, and nodes are reordered (the bytes-stream will be emitted
2002 * in a different order and mnay hash functions will detect this). However
2003 * if an existing tree is modified using libfdt functions, such as
2004 * fdt_add_subnode() and fdt_setprop(), then this problem is avoided.
2005 *
2006 * The nodes/properties to include/exclude are defined by a function
2007 * provided by the caller. This function is called for each node and
2008 * property, and must return:
2009 *
2010 * 0 - to exclude this part
2011 * 1 - to include this part
2012 * -1 - for FDT_IS_PROP only: no information is available, so include
2013 * if its containing node is included
2014 *
2015 * The last case is only used to deal with properties. Often a property is
2016 * included if its containing node is included - this is the case where
2017 * -1 is returned.. However if the property is specifically required to be
2018 * included/excluded, then 0 or 1 can be returned. Note that including a
2019 * property when the FDT_REG_SUPERNODES flag is given will force its
2020 * containing node to be included since it is not valid to have a property
2021 * that is not in a node.
2022 *
2023 * Using the information provided, the inclusion of a node can be controlled
2024 * either by a node name or its compatible string, or any other property
2025 * that the function can determine.
2026 *
2027 * As an example, including node "/" means to include the root node and all
2028 * root properties. A flag provides a way of also including supernodes (of
2029 * which there is none for the root node), and another flag includes
2030 * immediate subnodes, so in this case we would get the FDT_BEGIN_NODE and
2031 * FDT_END_NODE of all subnodes of /.
2032 *
2033 * The subnode feature helps in a hashing situation since it prevents the
2034 * root node from changing at all. Any change to non-excluded properties,
2035 * names of subnodes or number of subnodes would be detected.
2036 *
2037 * When used with FITs this provides the ability to hash and sign parts of
2038 * the FIT based on different configurations in the FIT. Then it is
2039 * impossible to change anything about that configuration (include images
2040 * attached to the configuration), but it may be possible to add new
2041 * configurations, new images or new signatures within the existing
2042 * framework.
2043 *
2044 * Adding new properties to a device tree may result in the string table
2045 * being extended (if the new property names are different from those
2046 * already added). This function can optionally include a region for
2047 * the string table so that this can be part of the hash too. This is always
2048 * the last region.
2049 *
2050 * The FDT also has a mem_rsvmap table which can also be included, and is
2051 * always the first region if so.
2052 *
2053 * The device tree header is not included in the region list. Since the
2054 * contents of the FDT are changing (shrinking, often), the caller will need
2055 * to regenerate the header anyway.
2056 *
2057 * @fdt: Device tree to check
2058 * @h_include: Function to call to determine whether to include a part or
2059 * not:
2060 *
2061 * @priv: Private pointer as passed to fdt_find_regions()
2062 * @fdt: Pointer to FDT blob
2063 * @offset: Offset of this node / property
2064 * @type: Type of this part, FDT_IS_...
2065 * @data: Pointer to data (node name, property name, compatible
2066 * string, value (not yet supported)
2067 * @size: Size of data, or 0 if none
2068 * @return 0 to exclude, 1 to include, -1 if no information is
2069 * available
2070 * @priv: Private pointer passed to h_include
2071 * @region: Returns list of regions, sorted by offset
2072 * @max_regions: Maximum length of region list
2073 * @path: Pointer to a temporary string for the function to use for
2074 * building path names
2075 * @path_len: Length of path, must be large enough to hold the longest
2076 * path in the tree
2077 * @flags: Various flags that control the region algortihm, see
2078 * FDT_REG_...
2079 * @return number of regions in list. If this is >max_regions then the
2080 * region array was exhausted. You should increase max_regions and try
2081 * the call again. Only the first max_regions elements are available in the
2082 * array.
2083 *
2084 * On error a -ve value is return, which can be:
2085 *
2086 * -FDT_ERR_BADSTRUCTURE (too deep or more END tags than BEGIN tags
2087 * -FDT_ERR_BADLAYOUT
2088 * -FDT_ERR_NOSPACE (path area is too small)
2089 */
2090int fdt_first_region(const void *fdt,
2091 int (*h_include)(void *priv, const void *fdt, int offset,
2092 int type, const char *data, int size),
2093 void *priv, struct fdt_region *region,
2094 char *path, int path_len, int flags,
2095 struct fdt_region_state *info);
2096
2097/** fdt_next_region() - find next region
2098 *
2099 * See fdt_first_region() for full description. This function finds the
2100 * next region according to the provided parameters, which must be the same
2101 * as passed to fdt_first_region().
2102 *
2103 * This function can additionally return -FDT_ERR_NOTFOUND when there are no
2104 * more regions
2105 */
2106int fdt_next_region(const void *fdt,
2107 int (*h_include)(void *priv, const void *fdt, int offset,
2108 int type, const char *data, int size),
2109 void *priv, struct fdt_region *region,
2110 char *path, int path_len, int flags,
2111 struct fdt_region_state *info);
2112
2113/**
2114 * fdt_add_alias_regions() - find aliases that point to existing regions
2115 *
2116 * Once a device tree grep is complete some of the nodes will be present
2117 * and some will have been dropped. This function checks all the alias nodes
2118 * to figure out which points point to nodes which are still present. These
2119 * aliases need to be kept, along with the nodes they reference.
2120 *
2121 * Given a list of regions function finds the aliases that still apply and
2122 * adds more regions to the list for these. This function is called after
2123 * fdt_next_region() has finished returning regions and requires the same
2124 * state.
2125 *
2126 * @fdt: Device tree file to reference
2127 * @region: List of regions that will be kept
2128 * @count: Number of regions
2129 * @max_regions: Number of entries that can fit in @region
2130 * @info: Region state as returned from fdt_next_region()
2131 * @return new number of regions in @region (i.e. count + the number added)
2132 * or -FDT_ERR_NOSPACE if there was not enough space.
2133 */
2134int fdt_add_alias_regions(const void *fdt, struct fdt_region *region, int count,
2135 int max_regions, struct fdt_region_state *info);
2136
Gerald Van Baren7cd5da02007-03-31 11:59:59 -04002137#endif /* _LIBFDT_H */