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