IntelSiliconPkg IntelVTdDxe: Support early SetAttributes()
[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
64 /* FDT_ERR_EXISTS: Attemped to create a node or property which\r
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
82 /* FDT_ERR_BADPHANDLE: Function was passed an invalid phandle\r
83 * value. phandle values of 0 and -1 are not permitted. */\r
84#define FDT_ERR_BADSTATE 7\r
85 /* FDT_ERR_BADSTATE: Function was passed an incomplete device\r
86 * tree created by the sequential-write functions, which is\r
87 * not sufficiently complete for the requested operation. */\r
88\r
89/* Error codes: codes for bad device tree blobs */\r
90#define FDT_ERR_TRUNCATED 8\r
91 /* FDT_ERR_TRUNCATED: Structure block of the given device tree\r
92 * ends without an FDT_END tag. */\r
93#define FDT_ERR_BADMAGIC 9\r
94 /* FDT_ERR_BADMAGIC: Given "device tree" appears not to be a\r
95 * device tree at all - it is missing the flattened device\r
96 * tree magic number. */\r
97#define FDT_ERR_BADVERSION 10\r
98 /* FDT_ERR_BADVERSION: Given device tree has a version which\r
99 * can't be handled by the requested operation. For\r
100 * read-write functions, this may mean that fdt_open_into() is\r
101 * required to convert the tree to the expected version. */\r
102#define FDT_ERR_BADSTRUCTURE 11\r
103 /* FDT_ERR_BADSTRUCTURE: Given device tree has a corrupt\r
104 * structure block or other serious error (e.g. misnested\r
105 * nodes, or subnodes preceding properties). */\r
106#define FDT_ERR_BADLAYOUT 12\r
107 /* FDT_ERR_BADLAYOUT: For read-write functions, the given\r
108 * device tree has it's sub-blocks in an order that the\r
109 * function can't handle (memory reserve map, then structure,\r
110 * then strings). Use fdt_open_into() to reorganize the tree\r
111 * into a form suitable for the read-write operations. */\r
112\r
113/* "Can't happen" error indicating a bug in libfdt */\r
114#define FDT_ERR_INTERNAL 13\r
115 /* FDT_ERR_INTERNAL: libfdt has failed an internal assertion.\r
116 * Should never be returned, if it is, it indicates a bug in\r
117 * libfdt itself. */\r
118\r
119#define FDT_ERR_MAX 13\r
120\r
121/**********************************************************************/\r
122/* Low-level functions (you probably don't need these) */\r
123/**********************************************************************/\r
124\r
125const void *fdt_offset_ptr(const void *fdt, int offset, unsigned int checklen);\r
126static inline void *fdt_offset_ptr_w(void *fdt, int offset, int checklen)\r
127{\r
128 return (void *)(uintptr_t)fdt_offset_ptr(fdt, offset, checklen);\r
129}\r
130\r
131uint32_t fdt_next_tag(const void *fdt, int offset, int *nextoffset);\r
132\r
133/**********************************************************************/\r
134/* Traversal functions */\r
135/**********************************************************************/\r
136\r
137int fdt_next_node(const void *fdt, int offset, int *depth);\r
138\r
3e8576dd
OM
139/**\r
140 * fdt_first_subnode() - get offset of first direct subnode\r
141 *\r
142 * @fdt: FDT blob\r
143 * @offset: Offset of node to check\r
144 * @return offset of first subnode, or -FDT_ERR_NOTFOUND if there is none\r
145 */\r
146int fdt_first_subnode(const void *fdt, int offset);\r
147\r
148/**\r
149 * fdt_next_subnode() - get offset of next direct subnode\r
150 *\r
151 * After first calling fdt_first_subnode(), call this function repeatedly to\r
152 * get direct subnodes of a parent node.\r
153 *\r
154 * @fdt: FDT blob\r
155 * @offset: Offset of previous subnode\r
156 * @return offset of next subnode, or -FDT_ERR_NOTFOUND if there are no more\r
157 * subnodes\r
158 */\r
159int fdt_next_subnode(const void *fdt, int offset);\r
160\r
1e57a462 161/**********************************************************************/\r
162/* General functions */\r
163/**********************************************************************/\r
164\r
165#define fdt_get_header(fdt, field) \\r
166 (fdt32_to_cpu(((const struct fdt_header *)(fdt))->field))\r
167#define fdt_magic(fdt) (fdt_get_header(fdt, magic))\r
168#define fdt_totalsize(fdt) (fdt_get_header(fdt, totalsize))\r
169#define fdt_off_dt_struct(fdt) (fdt_get_header(fdt, off_dt_struct))\r
170#define fdt_off_dt_strings(fdt) (fdt_get_header(fdt, off_dt_strings))\r
171#define fdt_off_mem_rsvmap(fdt) (fdt_get_header(fdt, off_mem_rsvmap))\r
172#define fdt_version(fdt) (fdt_get_header(fdt, version))\r
173#define fdt_last_comp_version(fdt) (fdt_get_header(fdt, last_comp_version))\r
174#define fdt_boot_cpuid_phys(fdt) (fdt_get_header(fdt, boot_cpuid_phys))\r
175#define fdt_size_dt_strings(fdt) (fdt_get_header(fdt, size_dt_strings))\r
176#define fdt_size_dt_struct(fdt) (fdt_get_header(fdt, size_dt_struct))\r
177\r
178#define __fdt_set_hdr(name) \\r
179 static inline void fdt_set_##name(void *fdt, uint32_t val) \\r
180 { \\r
181 struct fdt_header *fdth = (struct fdt_header*)fdt; \\r
182 fdth->name = cpu_to_fdt32(val); \\r
183 }\r
184__fdt_set_hdr(magic);\r
185__fdt_set_hdr(totalsize);\r
186__fdt_set_hdr(off_dt_struct);\r
187__fdt_set_hdr(off_dt_strings);\r
188__fdt_set_hdr(off_mem_rsvmap);\r
189__fdt_set_hdr(version);\r
190__fdt_set_hdr(last_comp_version);\r
191__fdt_set_hdr(boot_cpuid_phys);\r
192__fdt_set_hdr(size_dt_strings);\r
193__fdt_set_hdr(size_dt_struct);\r
194#undef __fdt_set_hdr\r
195\r
196/**\r
197 * fdt_check_header - sanity check a device tree or possible device tree\r
198 * @fdt: pointer to data which might be a flattened device tree\r
199 *\r
200 * fdt_check_header() checks that the given buffer contains what\r
201 * appears to be a flattened device tree with sane information in its\r
202 * header.\r
203 *\r
204 * returns:\r
205 * 0, if the buffer appears to contain a valid device tree\r
206 * -FDT_ERR_BADMAGIC,\r
207 * -FDT_ERR_BADVERSION,\r
208 * -FDT_ERR_BADSTATE, standard meanings, as above\r
209 */\r
210int fdt_check_header(const void *fdt);\r
211\r
212/**\r
213 * fdt_move - move a device tree around in memory\r
214 * @fdt: pointer to the device tree to move\r
215 * @buf: pointer to memory where the device is to be moved\r
216 * @bufsize: size of the memory space at buf\r
217 *\r
218 * fdt_move() relocates, if possible, the device tree blob located at\r
219 * fdt to the buffer at buf of size bufsize. The buffer may overlap\r
220 * with the existing device tree blob at fdt. Therefore,\r
221 * fdt_move(fdt, fdt, fdt_totalsize(fdt))\r
222 * should always succeed.\r
223 *\r
224 * returns:\r
225 * 0, on success\r
226 * -FDT_ERR_NOSPACE, bufsize is insufficient to contain the device tree\r
227 * -FDT_ERR_BADMAGIC,\r
228 * -FDT_ERR_BADVERSION,\r
229 * -FDT_ERR_BADSTATE, standard meanings\r
230 */\r
231int fdt_move(const void *fdt, void *buf, int bufsize);\r
232\r
233/**********************************************************************/\r
234/* Read-only functions */\r
235/**********************************************************************/\r
236\r
237/**\r
238 * fdt_string - retrieve a string from the strings block of a device tree\r
239 * @fdt: pointer to the device tree blob\r
240 * @stroffset: offset of the string within the strings block (native endian)\r
241 *\r
242 * fdt_string() retrieves a pointer to a single string from the\r
243 * strings block of the device tree blob at fdt.\r
244 *\r
245 * returns:\r
246 * a pointer to the string, on success\r
247 * NULL, if stroffset is out of bounds\r
248 */\r
249const char *fdt_string(const void *fdt, int stroffset);\r
250\r
251/**\r
252 * fdt_num_mem_rsv - retrieve the number of memory reserve map entries\r
253 * @fdt: pointer to the device tree blob\r
254 *\r
255 * Returns the number of entries in the device tree blob's memory\r
256 * reservation map. This does not include the terminating 0,0 entry\r
257 * or any other (0,0) entries reserved for expansion.\r
258 *\r
259 * returns:\r
260 * the number of entries\r
261 */\r
262int fdt_num_mem_rsv(const void *fdt);\r
263\r
264/**\r
265 * fdt_get_mem_rsv - retrieve one memory reserve map entry\r
266 * @fdt: pointer to the device tree blob\r
267 * @address, @size: pointers to 64-bit variables\r
268 *\r
269 * On success, *address and *size will contain the address and size of\r
270 * the n-th reserve map entry from the device tree blob, in\r
271 * native-endian format.\r
272 *\r
273 * returns:\r
274 * 0, on success\r
275 * -FDT_ERR_BADMAGIC,\r
276 * -FDT_ERR_BADVERSION,\r
277 * -FDT_ERR_BADSTATE, standard meanings\r
278 */\r
279int fdt_get_mem_rsv(const void *fdt, int n, uint64_t *address, uint64_t *size);\r
280\r
281/**\r
282 * fdt_subnode_offset_namelen - find a subnode based on substring\r
283 * @fdt: pointer to the device tree blob\r
284 * @parentoffset: structure block offset of a node\r
285 * @name: name of the subnode to locate\r
286 * @namelen: number of characters of name to consider\r
287 *\r
288 * Identical to fdt_subnode_offset(), but only examine the first\r
289 * namelen characters of name for matching the subnode name. This is\r
290 * useful for finding subnodes based on a portion of a larger string,\r
291 * such as a full path.\r
292 */\r
293int fdt_subnode_offset_namelen(const void *fdt, int parentoffset,\r
294 const char *name, int namelen);\r
295/**\r
296 * fdt_subnode_offset - find a subnode of a given node\r
297 * @fdt: pointer to the device tree blob\r
298 * @parentoffset: structure block offset of a node\r
299 * @name: name of the subnode to locate\r
300 *\r
301 * fdt_subnode_offset() finds a subnode of the node at structure block\r
302 * offset parentoffset with the given name. name may include a unit\r
303 * address, in which case fdt_subnode_offset() will find the subnode\r
304 * with that unit address, or the unit address may be omitted, in\r
305 * which case fdt_subnode_offset() will find an arbitrary subnode\r
306 * whose name excluding unit address matches the given name.\r
307 *\r
308 * returns:\r
309 * structure block offset of the requested subnode (>=0), on success\r
310 * -FDT_ERR_NOTFOUND, if the requested subnode does not exist\r
311 * -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE tag\r
312 * -FDT_ERR_BADMAGIC,\r
313 * -FDT_ERR_BADVERSION,\r
314 * -FDT_ERR_BADSTATE,\r
315 * -FDT_ERR_BADSTRUCTURE,\r
316 * -FDT_ERR_TRUNCATED, standard meanings.\r
317 */\r
318int fdt_subnode_offset(const void *fdt, int parentoffset, const char *name);\r
319\r
320/**\r
321 * fdt_path_offset - find a tree node by its full path\r
322 * @fdt: pointer to the device tree blob\r
323 * @path: full path of the node to locate\r
324 *\r
325 * fdt_path_offset() finds a node of a given path in the device tree.\r
326 * Each path component may omit the unit address portion, but the\r
327 * results of this are undefined if any such path component is\r
328 * ambiguous (that is if there are multiple nodes at the relevant\r
329 * level matching the given component, differentiated only by unit\r
330 * address).\r
331 *\r
332 * returns:\r
333 * structure block offset of the node with the requested path (>=0), on success\r
334 * -FDT_ERR_BADPATH, given path does not begin with '/' or is invalid\r
335 * -FDT_ERR_NOTFOUND, if the requested node does not exist\r
336 * -FDT_ERR_BADMAGIC,\r
337 * -FDT_ERR_BADVERSION,\r
338 * -FDT_ERR_BADSTATE,\r
339 * -FDT_ERR_BADSTRUCTURE,\r
340 * -FDT_ERR_TRUNCATED, standard meanings.\r
341 */\r
342int fdt_path_offset(const void *fdt, const char *path);\r
343\r
344/**\r
345 * fdt_get_name - retrieve the name of a given node\r
346 * @fdt: pointer to the device tree blob\r
347 * @nodeoffset: structure block offset of the starting node\r
348 * @lenp: pointer to an integer variable (will be overwritten) or NULL\r
349 *\r
350 * fdt_get_name() retrieves the name (including unit address) of the\r
351 * device tree node at structure block offset nodeoffset. If lenp is\r
352 * non-NULL, the length of this name is also returned, in the integer\r
353 * pointed to by lenp.\r
354 *\r
355 * returns:\r
356 * pointer to the node's name, on success\r
357 * If lenp is non-NULL, *lenp contains the length of that name (>=0)\r
358 * NULL, on error\r
359 * if lenp is non-NULL *lenp contains an error code (<0):\r
360 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
361 * -FDT_ERR_BADMAGIC,\r
362 * -FDT_ERR_BADVERSION,\r
363 * -FDT_ERR_BADSTATE, standard meanings\r
364 */\r
365const char *fdt_get_name(const void *fdt, int nodeoffset, int *lenp);\r
366\r
367/**\r
368 * fdt_first_property_offset - find the offset of a node's first property\r
369 * @fdt: pointer to the device tree blob\r
370 * @nodeoffset: structure block offset of a node\r
371 *\r
372 * fdt_first_property_offset() finds the first property of the node at\r
373 * the given structure block offset.\r
374 *\r
375 * returns:\r
376 * structure block offset of the property (>=0), on success\r
377 * -FDT_ERR_NOTFOUND, if the requested node has no properties\r
378 * -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_BEGIN_NODE tag\r
379 * -FDT_ERR_BADMAGIC,\r
380 * -FDT_ERR_BADVERSION,\r
381 * -FDT_ERR_BADSTATE,\r
382 * -FDT_ERR_BADSTRUCTURE,\r
383 * -FDT_ERR_TRUNCATED, standard meanings.\r
384 */\r
385int fdt_first_property_offset(const void *fdt, int nodeoffset);\r
386\r
387/**\r
388 * fdt_next_property_offset - step through a node's properties\r
389 * @fdt: pointer to the device tree blob\r
390 * @offset: structure block offset of a property\r
391 *\r
392 * fdt_next_property_offset() finds the property immediately after the\r
393 * one at the given structure block offset. This will be a property\r
394 * of the same node as the given property.\r
395 *\r
396 * returns:\r
397 * structure block offset of the next property (>=0), on success\r
398 * -FDT_ERR_NOTFOUND, if the given property is the last in its node\r
399 * -FDT_ERR_BADOFFSET, if nodeoffset did not point to an FDT_PROP tag\r
400 * -FDT_ERR_BADMAGIC,\r
401 * -FDT_ERR_BADVERSION,\r
402 * -FDT_ERR_BADSTATE,\r
403 * -FDT_ERR_BADSTRUCTURE,\r
404 * -FDT_ERR_TRUNCATED, standard meanings.\r
405 */\r
406int fdt_next_property_offset(const void *fdt, int offset);\r
407\r
408/**\r
409 * fdt_get_property_by_offset - retrieve the property at a given offset\r
410 * @fdt: pointer to the device tree blob\r
411 * @offset: offset of the property to retrieve\r
412 * @lenp: pointer to an integer variable (will be overwritten) or NULL\r
413 *\r
414 * fdt_get_property_by_offset() retrieves a pointer to the\r
415 * fdt_property structure within the device tree blob at the given\r
416 * offset. If lenp is non-NULL, the length of the property value is\r
417 * also returned, in the integer pointed to by lenp.\r
418 *\r
419 * returns:\r
420 * pointer to the structure representing the property\r
421 * if lenp is non-NULL, *lenp contains the length of the property\r
422 * value (>=0)\r
423 * NULL, on error\r
424 * if lenp is non-NULL, *lenp contains an error code (<0):\r
425 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag\r
426 * -FDT_ERR_BADMAGIC,\r
427 * -FDT_ERR_BADVERSION,\r
428 * -FDT_ERR_BADSTATE,\r
429 * -FDT_ERR_BADSTRUCTURE,\r
430 * -FDT_ERR_TRUNCATED, standard meanings\r
431 */\r
432const struct fdt_property *fdt_get_property_by_offset(const void *fdt,\r
433 int offset,\r
434 int *lenp);\r
435\r
436/**\r
437 * fdt_get_property_namelen - find a property based on substring\r
438 * @fdt: pointer to the device tree blob\r
439 * @nodeoffset: offset of the node whose property to find\r
440 * @name: name of the property to find\r
441 * @namelen: number of characters of name to consider\r
442 * @lenp: pointer to an integer variable (will be overwritten) or NULL\r
443 *\r
444 * Identical to fdt_get_property_namelen(), but only examine the first\r
445 * namelen characters of name for matching the property name.\r
446 */\r
447const struct fdt_property *fdt_get_property_namelen(const void *fdt,\r
448 int nodeoffset,\r
449 const char *name,\r
450 int namelen, int *lenp);\r
451\r
452/**\r
453 * fdt_get_property - find a given property in a given node\r
454 * @fdt: pointer to the device tree blob\r
455 * @nodeoffset: offset of the node whose property to find\r
456 * @name: name of the property to find\r
457 * @lenp: pointer to an integer variable (will be overwritten) or NULL\r
458 *\r
459 * fdt_get_property() retrieves a pointer to the fdt_property\r
460 * structure within the device tree blob corresponding to the property\r
461 * named 'name' of the node at offset nodeoffset. If lenp is\r
462 * non-NULL, the length of the property value is also returned, in the\r
463 * integer pointed to by lenp.\r
464 *\r
465 * returns:\r
466 * pointer to the structure representing the property\r
467 * if lenp is non-NULL, *lenp contains the length of the property\r
468 * value (>=0)\r
469 * NULL, on error\r
470 * if lenp is non-NULL, *lenp contains an error code (<0):\r
471 * -FDT_ERR_NOTFOUND, node does not have named property\r
472 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
473 * -FDT_ERR_BADMAGIC,\r
474 * -FDT_ERR_BADVERSION,\r
475 * -FDT_ERR_BADSTATE,\r
476 * -FDT_ERR_BADSTRUCTURE,\r
477 * -FDT_ERR_TRUNCATED, standard meanings\r
478 */\r
479const struct fdt_property *fdt_get_property(const void *fdt, int nodeoffset,\r
480 const char *name, int *lenp);\r
481static inline struct fdt_property *fdt_get_property_w(void *fdt, int nodeoffset,\r
482 const char *name,\r
483 int *lenp)\r
484{\r
485 return (struct fdt_property *)(uintptr_t)\r
486 fdt_get_property(fdt, nodeoffset, name, lenp);\r
487}\r
488\r
489/**\r
490 * fdt_getprop_by_offset - retrieve the value of a property at a given offset\r
491 * @fdt: pointer to the device tree blob\r
492 * @ffset: offset of the property to read\r
493 * @namep: pointer to a string variable (will be overwritten) or NULL\r
494 * @lenp: pointer to an integer variable (will be overwritten) or NULL\r
495 *\r
496 * fdt_getprop_by_offset() retrieves a pointer to the value of the\r
497 * property at structure block offset 'offset' (this will be a pointer\r
498 * to within the device blob itself, not a copy of the value). If\r
499 * lenp is non-NULL, the length of the property value is also\r
500 * returned, in the integer pointed to by lenp. If namep is non-NULL,\r
501 * the property's namne will also be returned in the char * pointed to\r
502 * by namep (this will be a pointer to within the device tree's string\r
503 * block, not a new copy of the name).\r
504 *\r
505 * returns:\r
506 * pointer to the property's value\r
507 * if lenp is non-NULL, *lenp contains the length of the property\r
508 * value (>=0)\r
509 * if namep is non-NULL *namep contiains a pointer to the property\r
510 * name.\r
511 * NULL, on error\r
512 * if lenp is non-NULL, *lenp contains an error code (<0):\r
513 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_PROP tag\r
514 * -FDT_ERR_BADMAGIC,\r
515 * -FDT_ERR_BADVERSION,\r
516 * -FDT_ERR_BADSTATE,\r
517 * -FDT_ERR_BADSTRUCTURE,\r
518 * -FDT_ERR_TRUNCATED, standard meanings\r
519 */\r
520const void *fdt_getprop_by_offset(const void *fdt, int offset,\r
521 const char **namep, int *lenp);\r
522\r
523/**\r
524 * fdt_getprop_namelen - get property value based on substring\r
525 * @fdt: pointer to the device tree blob\r
526 * @nodeoffset: offset of the node whose property to find\r
527 * @name: name of the property to find\r
528 * @namelen: number of characters of name to consider\r
529 * @lenp: pointer to an integer variable (will be overwritten) or NULL\r
530 *\r
531 * Identical to fdt_getprop(), but only examine the first namelen\r
532 * characters of name for matching the property name.\r
533 */\r
534const void *fdt_getprop_namelen(const void *fdt, int nodeoffset,\r
535 const char *name, int namelen, int *lenp);\r
536\r
537/**\r
538 * fdt_getprop - retrieve the value of a given property\r
539 * @fdt: pointer to the device tree blob\r
540 * @nodeoffset: offset of the node whose property to find\r
541 * @name: name of the property to find\r
542 * @lenp: pointer to an integer variable (will be overwritten) or NULL\r
543 *\r
544 * fdt_getprop() retrieves a pointer to the value of the property\r
545 * named 'name' of the node at offset nodeoffset (this will be a\r
546 * pointer to within the device blob itself, not a copy of the value).\r
547 * If lenp is non-NULL, the length of the property value is also\r
548 * returned, in the integer pointed to by lenp.\r
549 *\r
550 * returns:\r
551 * pointer to the property's value\r
552 * if lenp is non-NULL, *lenp contains the length of the property\r
553 * value (>=0)\r
554 * NULL, on error\r
555 * if lenp is non-NULL, *lenp contains an error code (<0):\r
556 * -FDT_ERR_NOTFOUND, node does not have named property\r
557 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
558 * -FDT_ERR_BADMAGIC,\r
559 * -FDT_ERR_BADVERSION,\r
560 * -FDT_ERR_BADSTATE,\r
561 * -FDT_ERR_BADSTRUCTURE,\r
562 * -FDT_ERR_TRUNCATED, standard meanings\r
563 */\r
564const void *fdt_getprop(const void *fdt, int nodeoffset,\r
565 const char *name, int *lenp);\r
566static inline void *fdt_getprop_w(void *fdt, int nodeoffset,\r
567 const char *name, int *lenp)\r
568{\r
569 return (void *)(uintptr_t)fdt_getprop(fdt, nodeoffset, name, lenp);\r
570}\r
571\r
572/**\r
573 * fdt_get_phandle - retrieve the phandle of a given node\r
574 * @fdt: pointer to the device tree blob\r
575 * @nodeoffset: structure block offset of the node\r
576 *\r
577 * fdt_get_phandle() retrieves the phandle of the device tree node at\r
578 * structure block offset nodeoffset.\r
579 *\r
580 * returns:\r
581 * the phandle of the node at nodeoffset, on success (!= 0, != -1)\r
582 * 0, if the node has no phandle, or another error occurs\r
583 */\r
584uint32_t fdt_get_phandle(const void *fdt, int nodeoffset);\r
585\r
586/**\r
587 * fdt_get_alias_namelen - get alias based on substring\r
588 * @fdt: pointer to the device tree blob\r
589 * @name: name of the alias th look up\r
590 * @namelen: number of characters of name to consider\r
591 *\r
592 * Identical to fdt_get_alias(), but only examine the first namelen\r
593 * characters of name for matching the alias name.\r
594 */\r
595const char *fdt_get_alias_namelen(const void *fdt,\r
596 const char *name, int namelen);\r
597\r
598/**\r
599 * fdt_get_alias - retreive the path referenced by a given alias\r
600 * @fdt: pointer to the device tree blob\r
601 * @name: name of the alias th look up\r
602 *\r
603 * fdt_get_alias() retrieves the value of a given alias. That is, the\r
604 * value of the property named 'name' in the node /aliases.\r
605 *\r
606 * returns:\r
3e8576dd 607 * a pointer to the expansion of the alias named 'name', if it exists\r
1e57a462 608 * NULL, if the given alias or the /aliases node does not exist\r
609 */\r
610const char *fdt_get_alias(const void *fdt, const char *name);\r
611\r
612/**\r
613 * fdt_get_path - determine the full path of a node\r
614 * @fdt: pointer to the device tree blob\r
615 * @nodeoffset: offset of the node whose path to find\r
616 * @buf: character buffer to contain the returned path (will be overwritten)\r
617 * @buflen: size of the character buffer at buf\r
618 *\r
619 * fdt_get_path() computes the full path of the node at offset\r
620 * nodeoffset, and records that path in the buffer at buf.\r
621 *\r
622 * NOTE: This function is expensive, as it must scan the device tree\r
623 * structure from the start to nodeoffset.\r
624 *\r
625 * returns:\r
626 * 0, on success\r
627 * buf contains the absolute path of the node at\r
628 * nodeoffset, as a NUL-terminated string.\r
629 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag\r
630 * -FDT_ERR_NOSPACE, the path of the given node is longer than (bufsize-1)\r
631 * characters and will not fit in the given buffer.\r
632 * -FDT_ERR_BADMAGIC,\r
633 * -FDT_ERR_BADVERSION,\r
634 * -FDT_ERR_BADSTATE,\r
635 * -FDT_ERR_BADSTRUCTURE, standard meanings\r
636 */\r
637int fdt_get_path(const void *fdt, int nodeoffset, char *buf, int buflen);\r
638\r
639/**\r
640 * fdt_supernode_atdepth_offset - find a specific ancestor of a node\r
641 * @fdt: pointer to the device tree blob\r
642 * @nodeoffset: offset of the node whose parent to find\r
643 * @supernodedepth: depth of the ancestor to find\r
644 * @nodedepth: pointer to an integer variable (will be overwritten) or NULL\r
645 *\r
646 * fdt_supernode_atdepth_offset() finds an ancestor of the given node\r
647 * at a specific depth from the root (where the root itself has depth\r
648 * 0, its immediate subnodes depth 1 and so forth). So\r
649 * fdt_supernode_atdepth_offset(fdt, nodeoffset, 0, NULL);\r
650 * will always return 0, the offset of the root node. If the node at\r
651 * nodeoffset has depth D, then:\r
652 * fdt_supernode_atdepth_offset(fdt, nodeoffset, D, NULL);\r
653 * will return nodeoffset itself.\r
654 *\r
655 * NOTE: This function is expensive, as it must scan the device tree\r
656 * structure from the start to nodeoffset.\r
657 *\r
658 * returns:\r
659\r
660 * structure block offset of the node at node offset's ancestor\r
661 * of depth supernodedepth (>=0), on success\r
662 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag\r
663* -FDT_ERR_NOTFOUND, supernodedepth was greater than the depth of nodeoffset\r
664 * -FDT_ERR_BADMAGIC,\r
665 * -FDT_ERR_BADVERSION,\r
666 * -FDT_ERR_BADSTATE,\r
667 * -FDT_ERR_BADSTRUCTURE, standard meanings\r
668 */\r
669int fdt_supernode_atdepth_offset(const void *fdt, int nodeoffset,\r
670 int supernodedepth, int *nodedepth);\r
671\r
672/**\r
673 * fdt_node_depth - find the depth of a given node\r
674 * @fdt: pointer to the device tree blob\r
675 * @nodeoffset: offset of the node whose parent to find\r
676 *\r
677 * fdt_node_depth() finds the depth of a given node. The root node\r
678 * has depth 0, its immediate subnodes depth 1 and so forth.\r
679 *\r
680 * NOTE: This function is expensive, as it must scan the device tree\r
681 * structure from the start to nodeoffset.\r
682 *\r
683 * returns:\r
684 * depth of the node at nodeoffset (>=0), on success\r
685 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag\r
686 * -FDT_ERR_BADMAGIC,\r
687 * -FDT_ERR_BADVERSION,\r
688 * -FDT_ERR_BADSTATE,\r
689 * -FDT_ERR_BADSTRUCTURE, standard meanings\r
690 */\r
691int fdt_node_depth(const void *fdt, int nodeoffset);\r
692\r
693/**\r
694 * fdt_parent_offset - find the parent of a given node\r
695 * @fdt: pointer to the device tree blob\r
696 * @nodeoffset: offset of the node whose parent to find\r
697 *\r
698 * fdt_parent_offset() locates the parent node of a given node (that\r
699 * is, it finds the offset of the node which contains the node at\r
700 * nodeoffset as a subnode).\r
701 *\r
702 * NOTE: This function is expensive, as it must scan the device tree\r
703 * structure from the start to nodeoffset, *twice*.\r
704 *\r
705 * returns:\r
706 * structure block offset of the parent of the node at nodeoffset\r
707 * (>=0), on success\r
708 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag\r
709 * -FDT_ERR_BADMAGIC,\r
710 * -FDT_ERR_BADVERSION,\r
711 * -FDT_ERR_BADSTATE,\r
712 * -FDT_ERR_BADSTRUCTURE, standard meanings\r
713 */\r
714int fdt_parent_offset(const void *fdt, int nodeoffset);\r
715\r
716/**\r
717 * fdt_node_offset_by_prop_value - find nodes with a given property value\r
718 * @fdt: pointer to the device tree blob\r
719 * @startoffset: only find nodes after this offset\r
720 * @propname: property name to check\r
721 * @propval: property value to search for\r
722 * @proplen: length of the value in propval\r
723 *\r
724 * fdt_node_offset_by_prop_value() returns the offset of the first\r
725 * node after startoffset, which has a property named propname whose\r
726 * value is of length proplen and has value equal to propval; or if\r
727 * startoffset is -1, the very first such node in the tree.\r
728 *\r
729 * To iterate through all nodes matching the criterion, the following\r
730 * idiom can be used:\r
731 * offset = fdt_node_offset_by_prop_value(fdt, -1, propname,\r
732 * propval, proplen);\r
733 * while (offset != -FDT_ERR_NOTFOUND) {\r
734 * // other code here\r
735 * offset = fdt_node_offset_by_prop_value(fdt, offset, propname,\r
736 * propval, proplen);\r
737 * }\r
738 *\r
739 * Note the -1 in the first call to the function, if 0 is used here\r
740 * instead, the function will never locate the root node, even if it\r
741 * matches the criterion.\r
742 *\r
743 * returns:\r
744 * structure block offset of the located node (>= 0, >startoffset),\r
745 * on success\r
746 * -FDT_ERR_NOTFOUND, no node matching the criterion exists in the\r
747 * tree after startoffset\r
748 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag\r
749 * -FDT_ERR_BADMAGIC,\r
750 * -FDT_ERR_BADVERSION,\r
751 * -FDT_ERR_BADSTATE,\r
752 * -FDT_ERR_BADSTRUCTURE, standard meanings\r
753 */\r
754int fdt_node_offset_by_prop_value(const void *fdt, int startoffset,\r
755 const char *propname,\r
756 const void *propval, int proplen);\r
757\r
758/**\r
759 * fdt_node_offset_by_phandle - find the node with a given phandle\r
760 * @fdt: pointer to the device tree blob\r
761 * @phandle: phandle value\r
762 *\r
763 * fdt_node_offset_by_phandle() returns the offset of the node\r
764 * which has the given phandle value. If there is more than one node\r
765 * in the tree with the given phandle (an invalid tree), results are\r
766 * undefined.\r
767 *\r
768 * returns:\r
769 * structure block offset of the located node (>= 0), on success\r
770 * -FDT_ERR_NOTFOUND, no node with that phandle exists\r
771 * -FDT_ERR_BADPHANDLE, given phandle value was invalid (0 or -1)\r
772 * -FDT_ERR_BADMAGIC,\r
773 * -FDT_ERR_BADVERSION,\r
774 * -FDT_ERR_BADSTATE,\r
775 * -FDT_ERR_BADSTRUCTURE, standard meanings\r
776 */\r
777int fdt_node_offset_by_phandle(const void *fdt, uint32_t phandle);\r
778\r
779/**\r
780 * fdt_node_check_compatible: check a node's compatible property\r
781 * @fdt: pointer to the device tree blob\r
782 * @nodeoffset: offset of a tree node\r
783 * @compatible: string to match against\r
784 *\r
785 *\r
786 * fdt_node_check_compatible() returns 0 if the given node contains a\r
787 * 'compatible' property with the given string as one of its elements,\r
788 * it returns non-zero otherwise, or on error.\r
789 *\r
790 * returns:\r
791 * 0, if the node has a 'compatible' property listing the given string\r
792 * 1, if the node has a 'compatible' property, but it does not list\r
793 * the given string\r
794 * -FDT_ERR_NOTFOUND, if the given node has no 'compatible' property\r
795 * -FDT_ERR_BADOFFSET, if nodeoffset does not refer to a BEGIN_NODE tag\r
796 * -FDT_ERR_BADMAGIC,\r
797 * -FDT_ERR_BADVERSION,\r
798 * -FDT_ERR_BADSTATE,\r
799 * -FDT_ERR_BADSTRUCTURE, standard meanings\r
800 */\r
801int fdt_node_check_compatible(const void *fdt, int nodeoffset,\r
802 const char *compatible);\r
803\r
804/**\r
805 * fdt_node_offset_by_compatible - find nodes with a given 'compatible' value\r
806 * @fdt: pointer to the device tree blob\r
807 * @startoffset: only find nodes after this offset\r
808 * @compatible: 'compatible' string to match against\r
809 *\r
810 * fdt_node_offset_by_compatible() returns the offset of the first\r
811 * node after startoffset, which has a 'compatible' property which\r
812 * lists the given compatible string; or if startoffset is -1, the\r
813 * very first such node in the tree.\r
814 *\r
815 * To iterate through all nodes matching the criterion, the following\r
816 * idiom can be used:\r
817 * offset = fdt_node_offset_by_compatible(fdt, -1, compatible);\r
818 * while (offset != -FDT_ERR_NOTFOUND) {\r
819 * // other code here\r
820 * offset = fdt_node_offset_by_compatible(fdt, offset, compatible);\r
821 * }\r
822 *\r
823 * Note the -1 in the first call to the function, if 0 is used here\r
824 * instead, the function will never locate the root node, even if it\r
825 * matches the criterion.\r
826 *\r
827 * returns:\r
828 * structure block offset of the located node (>= 0, >startoffset),\r
829 * on success\r
830 * -FDT_ERR_NOTFOUND, no node matching the criterion exists in the\r
831 * tree after startoffset\r
832 * -FDT_ERR_BADOFFSET, nodeoffset does not refer to a BEGIN_NODE tag\r
833 * -FDT_ERR_BADMAGIC,\r
834 * -FDT_ERR_BADVERSION,\r
835 * -FDT_ERR_BADSTATE,\r
836 * -FDT_ERR_BADSTRUCTURE, standard meanings\r
837 */\r
838int fdt_node_offset_by_compatible(const void *fdt, int startoffset,\r
839 const char *compatible);\r
840\r
3e8576dd
OM
841/**\r
842 * fdt_stringlist_contains - check a string list property for a string\r
843 * @strlist: Property containing a list of strings to check\r
844 * @listlen: Length of property\r
845 * @str: String to search for\r
846 *\r
847 * This is a utility function provided for convenience. The list contains\r
848 * one or more strings, each terminated by \0, as is found in a device tree\r
849 * "compatible" property.\r
850 *\r
851 * @return: 1 if the string is found in the list, 0 not found, or invalid list\r
852 */\r
853int fdt_stringlist_contains(const char *strlist, int listlen, const char *str);\r
854\r
1e57a462 855/**********************************************************************/\r
856/* Write-in-place functions */\r
857/**********************************************************************/\r
858\r
859/**\r
860 * fdt_setprop_inplace - change a property's value, but not its size\r
861 * @fdt: pointer to the device tree blob\r
862 * @nodeoffset: offset of the node whose property to change\r
863 * @name: name of the property to change\r
864 * @val: pointer to data to replace the property value with\r
865 * @len: length of the property value\r
866 *\r
867 * fdt_setprop_inplace() replaces the value of a given property with\r
868 * the data in val, of length len. This function cannot change the\r
869 * size of a property, and so will only work if len is equal to the\r
870 * current length of the property.\r
871 *\r
872 * This function will alter only the bytes in the blob which contain\r
873 * the given property value, and will not alter or move any other part\r
874 * of the tree.\r
875 *\r
876 * returns:\r
877 * 0, on success\r
878 * -FDT_ERR_NOSPACE, if len is not equal to the property's current length\r
879 * -FDT_ERR_NOTFOUND, node does not have the named property\r
880 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
881 * -FDT_ERR_BADMAGIC,\r
882 * -FDT_ERR_BADVERSION,\r
883 * -FDT_ERR_BADSTATE,\r
884 * -FDT_ERR_BADSTRUCTURE,\r
885 * -FDT_ERR_TRUNCATED, standard meanings\r
886 */\r
887int fdt_setprop_inplace(void *fdt, int nodeoffset, const char *name,\r
888 const void *val, int len);\r
889\r
890/**\r
891 * fdt_setprop_inplace_u32 - change the value of a 32-bit integer property\r
892 * @fdt: pointer to the device tree blob\r
893 * @nodeoffset: offset of the node whose property to change\r
894 * @name: name of the property to change\r
895 * @val: 32-bit integer value to replace the property with\r
896 *\r
897 * fdt_setprop_inplace_u32() replaces the value of a given property\r
898 * with the 32-bit integer value in val, converting val to big-endian\r
899 * if necessary. This function cannot change the size of a property,\r
900 * and so will only work if the property already exists and has length\r
901 * 4.\r
902 *\r
903 * This function will alter only the bytes in the blob which contain\r
904 * the given property value, and will not alter or move any other part\r
905 * of the tree.\r
906 *\r
907 * returns:\r
908 * 0, on success\r
909 * -FDT_ERR_NOSPACE, if the property's length is not equal to 4\r
910 * -FDT_ERR_NOTFOUND, node does not have the named property\r
911 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
912 * -FDT_ERR_BADMAGIC,\r
913 * -FDT_ERR_BADVERSION,\r
914 * -FDT_ERR_BADSTATE,\r
915 * -FDT_ERR_BADSTRUCTURE,\r
916 * -FDT_ERR_TRUNCATED, standard meanings\r
917 */\r
918static inline int fdt_setprop_inplace_u32(void *fdt, int nodeoffset,\r
919 const char *name, uint32_t val)\r
920{\r
3e8576dd
OM
921 fdt32_t tmp = cpu_to_fdt32(val);\r
922 return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));\r
1e57a462 923}\r
924\r
925/**\r
926 * fdt_setprop_inplace_u64 - change the value of a 64-bit integer property\r
927 * @fdt: pointer to the device tree blob\r
928 * @nodeoffset: offset of the node whose property to change\r
929 * @name: name of the property to change\r
930 * @val: 64-bit integer value to replace the property with\r
931 *\r
932 * fdt_setprop_inplace_u64() replaces the value of a given property\r
933 * with the 64-bit integer value in val, converting val to big-endian\r
934 * if necessary. This function cannot change the size of a property,\r
935 * and so will only work if the property already exists and has length\r
936 * 8.\r
937 *\r
938 * This function will alter only the bytes in the blob which contain\r
939 * the given property value, and will not alter or move any other part\r
940 * of the tree.\r
941 *\r
942 * returns:\r
943 * 0, on success\r
944 * -FDT_ERR_NOSPACE, if the property's length is not equal to 8\r
945 * -FDT_ERR_NOTFOUND, node does not have the named property\r
946 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
947 * -FDT_ERR_BADMAGIC,\r
948 * -FDT_ERR_BADVERSION,\r
949 * -FDT_ERR_BADSTATE,\r
950 * -FDT_ERR_BADSTRUCTURE,\r
951 * -FDT_ERR_TRUNCATED, standard meanings\r
952 */\r
953static inline int fdt_setprop_inplace_u64(void *fdt, int nodeoffset,\r
954 const char *name, uint64_t val)\r
955{\r
3e8576dd
OM
956 fdt64_t tmp = cpu_to_fdt64(val);\r
957 return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));\r
1e57a462 958}\r
959\r
960/**\r
961 * fdt_setprop_inplace_cell - change the value of a single-cell property\r
962 *\r
963 * This is an alternative name for fdt_setprop_inplace_u32()\r
964 */\r
965static inline int fdt_setprop_inplace_cell(void *fdt, int nodeoffset,\r
966 const char *name, uint32_t val)\r
967{\r
968 return fdt_setprop_inplace_u32(fdt, nodeoffset, name, val);\r
969}\r
970\r
971/**\r
972 * fdt_nop_property - replace a property with nop tags\r
973 * @fdt: pointer to the device tree blob\r
974 * @nodeoffset: offset of the node whose property to nop\r
975 * @name: name of the property to nop\r
976 *\r
977 * fdt_nop_property() will replace a given property's representation\r
978 * in the blob with FDT_NOP tags, effectively removing it from the\r
979 * tree.\r
980 *\r
981 * This function will alter only the bytes in the blob which contain\r
982 * the property, and will not alter or move any other part of the\r
983 * tree.\r
984 *\r
985 * returns:\r
986 * 0, on success\r
987 * -FDT_ERR_NOTFOUND, node does not have the named property\r
988 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
989 * -FDT_ERR_BADMAGIC,\r
990 * -FDT_ERR_BADVERSION,\r
991 * -FDT_ERR_BADSTATE,\r
992 * -FDT_ERR_BADSTRUCTURE,\r
993 * -FDT_ERR_TRUNCATED, standard meanings\r
994 */\r
995int fdt_nop_property(void *fdt, int nodeoffset, const char *name);\r
996\r
997/**\r
998 * fdt_nop_node - replace a node (subtree) with nop tags\r
999 * @fdt: pointer to the device tree blob\r
1000 * @nodeoffset: offset of the node to nop\r
1001 *\r
1002 * fdt_nop_node() will replace a given node's representation in the\r
1003 * blob, including all its subnodes, if any, with FDT_NOP tags,\r
1004 * effectively removing it from the tree.\r
1005 *\r
1006 * This function will alter only the bytes in the blob which contain\r
1007 * the node and its properties and subnodes, and will not alter or\r
1008 * move any other part of the tree.\r
1009 *\r
1010 * returns:\r
1011 * 0, on success\r
1012 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1013 * -FDT_ERR_BADMAGIC,\r
1014 * -FDT_ERR_BADVERSION,\r
1015 * -FDT_ERR_BADSTATE,\r
1016 * -FDT_ERR_BADSTRUCTURE,\r
1017 * -FDT_ERR_TRUNCATED, standard meanings\r
1018 */\r
1019int fdt_nop_node(void *fdt, int nodeoffset);\r
1020\r
1021/**********************************************************************/\r
1022/* Sequential write functions */\r
1023/**********************************************************************/\r
1024\r
1025int fdt_create(void *buf, int bufsize);\r
1026int fdt_add_reservemap_entry(void *fdt, uint64_t addr, uint64_t size);\r
1027int fdt_finish_reservemap(void *fdt);\r
1028int fdt_begin_node(void *fdt, const char *name);\r
1029int fdt_property(void *fdt, const char *name, const void *val, int len);\r
1030static inline int fdt_property_u32(void *fdt, const char *name, uint32_t val)\r
1031{\r
3e8576dd
OM
1032 fdt32_t tmp = cpu_to_fdt32(val);\r
1033 return fdt_property(fdt, name, &tmp, sizeof(tmp));\r
1e57a462 1034}\r
1035static inline int fdt_property_u64(void *fdt, const char *name, uint64_t val)\r
1036{\r
3e8576dd
OM
1037 fdt64_t tmp = cpu_to_fdt64(val);\r
1038 return fdt_property(fdt, name, &tmp, sizeof(tmp));\r
1e57a462 1039}\r
1040static inline int fdt_property_cell(void *fdt, const char *name, uint32_t val)\r
1041{\r
1042 return fdt_property_u32(fdt, name, val);\r
1043}\r
1044#define fdt_property_string(fdt, name, str) \\r
1045 fdt_property(fdt, name, str, strlen(str)+1)\r
1046int fdt_end_node(void *fdt);\r
1047int fdt_finish(void *fdt);\r
1048\r
1049/**********************************************************************/\r
1050/* Read-write functions */\r
1051/**********************************************************************/\r
1052\r
1053int fdt_create_empty_tree(void *buf, int bufsize);\r
1054int fdt_open_into(const void *fdt, void *buf, int bufsize);\r
1055int fdt_pack(void *fdt);\r
1056\r
1057/**\r
1058 * fdt_add_mem_rsv - add one memory reserve map entry\r
1059 * @fdt: pointer to the device tree blob\r
1060 * @address, @size: 64-bit values (native endian)\r
1061 *\r
1062 * Adds a reserve map entry to the given blob reserving a region at\r
1063 * address address of length size.\r
1064 *\r
1065 * This function will insert data into the reserve map and will\r
1066 * therefore change the indexes of some entries in the table.\r
1067 *\r
1068 * returns:\r
1069 * 0, on success\r
1070 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to\r
1071 * contain the new reservation entry\r
1072 * -FDT_ERR_BADMAGIC,\r
1073 * -FDT_ERR_BADVERSION,\r
1074 * -FDT_ERR_BADSTATE,\r
1075 * -FDT_ERR_BADSTRUCTURE,\r
1076 * -FDT_ERR_BADLAYOUT,\r
1077 * -FDT_ERR_TRUNCATED, standard meanings\r
1078 */\r
1079int fdt_add_mem_rsv(void *fdt, uint64_t address, uint64_t size);\r
1080\r
1081/**\r
1082 * fdt_del_mem_rsv - remove a memory reserve map entry\r
1083 * @fdt: pointer to the device tree blob\r
1084 * @n: entry to remove\r
1085 *\r
1086 * fdt_del_mem_rsv() removes the n-th memory reserve map entry from\r
1087 * the blob.\r
1088 *\r
1089 * This function will delete data from the reservation table and will\r
1090 * therefore change the indexes of some entries in the table.\r
1091 *\r
1092 * returns:\r
1093 * 0, on success\r
1094 * -FDT_ERR_NOTFOUND, there is no entry of the given index (i.e. there\r
1095 * are less than n+1 reserve map entries)\r
1096 * -FDT_ERR_BADMAGIC,\r
1097 * -FDT_ERR_BADVERSION,\r
1098 * -FDT_ERR_BADSTATE,\r
1099 * -FDT_ERR_BADSTRUCTURE,\r
1100 * -FDT_ERR_BADLAYOUT,\r
1101 * -FDT_ERR_TRUNCATED, standard meanings\r
1102 */\r
1103int fdt_del_mem_rsv(void *fdt, int n);\r
1104\r
1105/**\r
1106 * fdt_set_name - change the name of a given node\r
1107 * @fdt: pointer to the device tree blob\r
1108 * @nodeoffset: structure block offset of a node\r
1109 * @name: name to give the node\r
1110 *\r
1111 * fdt_set_name() replaces the name (including unit address, if any)\r
1112 * of the given node with the given string. NOTE: this function can't\r
1113 * efficiently check if the new name is unique amongst the given\r
1114 * node's siblings; results are undefined if this function is invoked\r
1115 * with a name equal to one of the given node's siblings.\r
1116 *\r
1117 * This function may insert or delete data from the blob, and will\r
1118 * therefore change the offsets of some existing nodes.\r
1119 *\r
1120 * returns:\r
1121 * 0, on success\r
1122 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob\r
1123 * to contain the new name\r
1124 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1125 * -FDT_ERR_BADMAGIC,\r
1126 * -FDT_ERR_BADVERSION,\r
1127 * -FDT_ERR_BADSTATE, standard meanings\r
1128 */\r
1129int fdt_set_name(void *fdt, int nodeoffset, const char *name);\r
1130\r
1131/**\r
1132 * fdt_setprop - create or change a property\r
1133 * @fdt: pointer to the device tree blob\r
1134 * @nodeoffset: offset of the node whose property to change\r
1135 * @name: name of the property to change\r
1136 * @val: pointer to data to set the property value to\r
1137 * @len: length of the property value\r
1138 *\r
1139 * fdt_setprop() sets the value of the named property in the given\r
1140 * node to the given value and length, creating the property if it\r
1141 * does not already exist.\r
1142 *\r
1143 * This function may insert or delete data from the blob, and will\r
1144 * therefore change the offsets of some existing nodes.\r
1145 *\r
1146 * returns:\r
1147 * 0, on success\r
1148 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to\r
1149 * contain the new property value\r
1150 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1151 * -FDT_ERR_BADLAYOUT,\r
1152 * -FDT_ERR_BADMAGIC,\r
1153 * -FDT_ERR_BADVERSION,\r
1154 * -FDT_ERR_BADSTATE,\r
1155 * -FDT_ERR_BADSTRUCTURE,\r
1156 * -FDT_ERR_BADLAYOUT,\r
1157 * -FDT_ERR_TRUNCATED, standard meanings\r
1158 */\r
1159int fdt_setprop(void *fdt, int nodeoffset, const char *name,\r
1160 const void *val, int len);\r
1161\r
1162/**\r
1163 * fdt_setprop_u32 - set a property to a 32-bit integer\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 for the property (native endian)\r
1168 *\r
1169 * fdt_setprop_u32() sets the value of the named property in the given\r
1170 * node to the given 32-bit integer value (converting to big-endian if\r
1171 * necessary), or creates a new property with that value if it does\r
1172 * not already exist.\r
1173 *\r
1174 * This function may insert or delete data from the blob, and will\r
1175 * therefore change the offsets of some existing nodes.\r
1176 *\r
1177 * returns:\r
1178 * 0, on success\r
1179 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to\r
1180 * contain the new property value\r
1181 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1182 * -FDT_ERR_BADLAYOUT,\r
1183 * -FDT_ERR_BADMAGIC,\r
1184 * -FDT_ERR_BADVERSION,\r
1185 * -FDT_ERR_BADSTATE,\r
1186 * -FDT_ERR_BADSTRUCTURE,\r
1187 * -FDT_ERR_BADLAYOUT,\r
1188 * -FDT_ERR_TRUNCATED, standard meanings\r
1189 */\r
1190static inline int fdt_setprop_u32(void *fdt, int nodeoffset, const char *name,\r
1191 uint32_t val)\r
1192{\r
3e8576dd
OM
1193 fdt32_t tmp = cpu_to_fdt32(val);\r
1194 return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));\r
1e57a462 1195}\r
1196\r
1197/**\r
1198 * fdt_setprop_u64 - set a property to a 64-bit integer\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 for the property (native endian)\r
1203 *\r
1204 * fdt_setprop_u64() sets the value of the named property in the given\r
1205 * node to the given 64-bit integer value (converting to big-endian if\r
1206 * necessary), or creates a new property with that value if it does\r
1207 * not already exist.\r
1208 *\r
1209 * This function may insert or delete data from the blob, and will\r
1210 * therefore change the offsets of some existing nodes.\r
1211 *\r
1212 * returns:\r
1213 * 0, on success\r
1214 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to\r
1215 * contain the new property value\r
1216 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1217 * -FDT_ERR_BADLAYOUT,\r
1218 * -FDT_ERR_BADMAGIC,\r
1219 * -FDT_ERR_BADVERSION,\r
1220 * -FDT_ERR_BADSTATE,\r
1221 * -FDT_ERR_BADSTRUCTURE,\r
1222 * -FDT_ERR_BADLAYOUT,\r
1223 * -FDT_ERR_TRUNCATED, standard meanings\r
1224 */\r
1225static inline int fdt_setprop_u64(void *fdt, int nodeoffset, const char *name,\r
1226 uint64_t val)\r
1227{\r
3e8576dd
OM
1228 fdt64_t tmp = cpu_to_fdt64(val);\r
1229 return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));\r
1e57a462 1230}\r
1231\r
1232/**\r
1233 * fdt_setprop_cell - set a property to a single cell value\r
1234 *\r
1235 * This is an alternative name for fdt_setprop_u32()\r
1236 */\r
1237static inline int fdt_setprop_cell(void *fdt, int nodeoffset, const char *name,\r
1238 uint32_t val)\r
1239{\r
1240 return fdt_setprop_u32(fdt, nodeoffset, name, val);\r
1241}\r
1242\r
1243/**\r
1244 * fdt_setprop_string - set a property to a string value\r
1245 * @fdt: pointer to the device tree blob\r
1246 * @nodeoffset: offset of the node whose property to change\r
1247 * @name: name of the property to change\r
1248 * @str: string value for the property\r
1249 *\r
1250 * fdt_setprop_string() sets the value of the named property in the\r
1251 * given node to the given string value (using the length of the\r
1252 * string to determine the new length of the property), or creates a\r
1253 * new property with that value if it does not already exist.\r
1254 *\r
1255 * This function may insert or delete data from the blob, and will\r
1256 * therefore change the offsets of some existing nodes.\r
1257 *\r
1258 * returns:\r
1259 * 0, on success\r
1260 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to\r
1261 * contain the new property value\r
1262 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1263 * -FDT_ERR_BADLAYOUT,\r
1264 * -FDT_ERR_BADMAGIC,\r
1265 * -FDT_ERR_BADVERSION,\r
1266 * -FDT_ERR_BADSTATE,\r
1267 * -FDT_ERR_BADSTRUCTURE,\r
1268 * -FDT_ERR_BADLAYOUT,\r
1269 * -FDT_ERR_TRUNCATED, standard meanings\r
1270 */\r
1271#define fdt_setprop_string(fdt, nodeoffset, name, str) \\r
1272 fdt_setprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)\r
1273\r
1274/**\r
1275 * fdt_appendprop - append to or create a property\r
1276 * @fdt: pointer to the device tree blob\r
1277 * @nodeoffset: offset of the node whose property to change\r
1278 * @name: name of the property to append to\r
1279 * @val: pointer to data to append to the property value\r
1280 * @len: length of the data to append to the property value\r
1281 *\r
1282 * fdt_appendprop() appends the value to the named property in the\r
1283 * given node, creating the property if it does not already exist.\r
1284 *\r
1285 * This function may insert data into the blob, and will therefore\r
1286 * change the offsets of some existing nodes.\r
1287 *\r
1288 * returns:\r
1289 * 0, on success\r
1290 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to\r
1291 * contain the new property value\r
1292 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1293 * -FDT_ERR_BADLAYOUT,\r
1294 * -FDT_ERR_BADMAGIC,\r
1295 * -FDT_ERR_BADVERSION,\r
1296 * -FDT_ERR_BADSTATE,\r
1297 * -FDT_ERR_BADSTRUCTURE,\r
1298 * -FDT_ERR_BADLAYOUT,\r
1299 * -FDT_ERR_TRUNCATED, standard meanings\r
1300 */\r
1301int fdt_appendprop(void *fdt, int nodeoffset, const char *name,\r
1302 const void *val, int len);\r
1303\r
1304/**\r
1305 * fdt_appendprop_u32 - append a 32-bit integer value to a property\r
1306 * @fdt: pointer to the device tree blob\r
1307 * @nodeoffset: offset of the node whose property to change\r
1308 * @name: name of the property to change\r
1309 * @val: 32-bit integer value to append to the property (native endian)\r
1310 *\r
1311 * fdt_appendprop_u32() appends the given 32-bit integer value\r
1312 * (converting to big-endian if necessary) to the value of the named\r
1313 * property in the given node, or creates a new property with that\r
1314 * value if it does not already exist.\r
1315 *\r
1316 * This function may insert data into the blob, and will therefore\r
1317 * change the offsets of some existing nodes.\r
1318 *\r
1319 * returns:\r
1320 * 0, on success\r
1321 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to\r
1322 * contain the new property value\r
1323 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1324 * -FDT_ERR_BADLAYOUT,\r
1325 * -FDT_ERR_BADMAGIC,\r
1326 * -FDT_ERR_BADVERSION,\r
1327 * -FDT_ERR_BADSTATE,\r
1328 * -FDT_ERR_BADSTRUCTURE,\r
1329 * -FDT_ERR_BADLAYOUT,\r
1330 * -FDT_ERR_TRUNCATED, standard meanings\r
1331 */\r
1332static inline int fdt_appendprop_u32(void *fdt, int nodeoffset,\r
1333 const char *name, uint32_t val)\r
1334{\r
3e8576dd
OM
1335 fdt32_t tmp = cpu_to_fdt32(val);\r
1336 return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));\r
1e57a462 1337}\r
1338\r
1339/**\r
1340 * fdt_appendprop_u64 - append a 64-bit integer value to a property\r
1341 * @fdt: pointer to the device tree blob\r
1342 * @nodeoffset: offset of the node whose property to change\r
1343 * @name: name of the property to change\r
1344 * @val: 64-bit integer value to append to the property (native endian)\r
1345 *\r
1346 * fdt_appendprop_u64() appends the given 64-bit integer value\r
1347 * (converting to big-endian if necessary) to the value of the named\r
1348 * property in the given node, or creates a new property with that\r
1349 * value if it does not already exist.\r
1350 *\r
1351 * This function may insert data into the blob, and will therefore\r
1352 * change the offsets of some existing nodes.\r
1353 *\r
1354 * returns:\r
1355 * 0, on success\r
1356 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to\r
1357 * contain the new property value\r
1358 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1359 * -FDT_ERR_BADLAYOUT,\r
1360 * -FDT_ERR_BADMAGIC,\r
1361 * -FDT_ERR_BADVERSION,\r
1362 * -FDT_ERR_BADSTATE,\r
1363 * -FDT_ERR_BADSTRUCTURE,\r
1364 * -FDT_ERR_BADLAYOUT,\r
1365 * -FDT_ERR_TRUNCATED, standard meanings\r
1366 */\r
1367static inline int fdt_appendprop_u64(void *fdt, int nodeoffset,\r
1368 const char *name, uint64_t val)\r
1369{\r
3e8576dd
OM
1370 fdt64_t tmp = cpu_to_fdt64(val);\r
1371 return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));\r
1e57a462 1372}\r
1373\r
1374/**\r
1375 * fdt_appendprop_cell - append a single cell value to a property\r
1376 *\r
1377 * This is an alternative name for fdt_appendprop_u32()\r
1378 */\r
1379static inline int fdt_appendprop_cell(void *fdt, int nodeoffset,\r
1380 const char *name, uint32_t val)\r
1381{\r
1382 return fdt_appendprop_u32(fdt, nodeoffset, name, val);\r
1383}\r
1384\r
1385/**\r
1386 * fdt_appendprop_string - append a string to a property\r
1387 * @fdt: pointer to the device tree blob\r
1388 * @nodeoffset: offset of the node whose property to change\r
1389 * @name: name of the property to change\r
1390 * @str: string value to append to the property\r
1391 *\r
1392 * fdt_appendprop_string() appends the given string to the value of\r
1393 * the named property in the given node, or creates a new property\r
1394 * with that value if it does not already exist.\r
1395 *\r
1396 * This function may insert data into the blob, and will therefore\r
1397 * change the offsets of some existing nodes.\r
1398 *\r
1399 * returns:\r
1400 * 0, on success\r
1401 * -FDT_ERR_NOSPACE, there is insufficient free space in the blob to\r
1402 * contain the new property value\r
1403 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1404 * -FDT_ERR_BADLAYOUT,\r
1405 * -FDT_ERR_BADMAGIC,\r
1406 * -FDT_ERR_BADVERSION,\r
1407 * -FDT_ERR_BADSTATE,\r
1408 * -FDT_ERR_BADSTRUCTURE,\r
1409 * -FDT_ERR_BADLAYOUT,\r
1410 * -FDT_ERR_TRUNCATED, standard meanings\r
1411 */\r
1412#define fdt_appendprop_string(fdt, nodeoffset, name, str) \\r
1413 fdt_appendprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)\r
1414\r
1415/**\r
1416 * fdt_delprop - delete a property\r
1417 * @fdt: pointer to the device tree blob\r
1418 * @nodeoffset: offset of the node whose property to nop\r
1419 * @name: name of the property to nop\r
1420 *\r
1421 * fdt_del_property() will delete the given property.\r
1422 *\r
1423 * This function will delete data from the blob, and will therefore\r
1424 * change the offsets of some existing nodes.\r
1425 *\r
1426 * returns:\r
1427 * 0, on success\r
1428 * -FDT_ERR_NOTFOUND, node does not have the named property\r
1429 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1430 * -FDT_ERR_BADLAYOUT,\r
1431 * -FDT_ERR_BADMAGIC,\r
1432 * -FDT_ERR_BADVERSION,\r
1433 * -FDT_ERR_BADSTATE,\r
1434 * -FDT_ERR_BADSTRUCTURE,\r
1435 * -FDT_ERR_TRUNCATED, standard meanings\r
1436 */\r
1437int fdt_delprop(void *fdt, int nodeoffset, const char *name);\r
1438\r
1439/**\r
1440 * fdt_add_subnode_namelen - creates a new node based on substring\r
1441 * @fdt: pointer to the device tree blob\r
1442 * @parentoffset: structure block offset of a node\r
1443 * @name: name of the subnode to locate\r
1444 * @namelen: number of characters of name to consider\r
1445 *\r
1446 * Identical to fdt_add_subnode(), but use only the first namelen\r
1447 * characters of name as the name of the new node. This is useful for\r
1448 * creating subnodes based on a portion of a larger string, such as a\r
1449 * full path.\r
1450 */\r
1451int fdt_add_subnode_namelen(void *fdt, int parentoffset,\r
1452 const char *name, int namelen);\r
1453\r
1454/**\r
1455 * fdt_add_subnode - creates a new node\r
1456 * @fdt: pointer to the device tree blob\r
1457 * @parentoffset: structure block offset of a node\r
1458 * @name: name of the subnode to locate\r
1459 *\r
1460 * fdt_add_subnode() creates a new node as a subnode of the node at\r
1461 * structure block offset parentoffset, with the given name (which\r
1462 * should include the unit address, if any).\r
1463 *\r
1464 * This function will insert data into the blob, and will therefore\r
1465 * change the offsets of some existing nodes.\r
1466\r
1467 * returns:\r
1468 * structure block offset of the created nodeequested subnode (>=0), on success\r
1469 * -FDT_ERR_NOTFOUND, if the requested subnode does not exist\r
1470 * -FDT_ERR_BADOFFSET, if parentoffset did not point to an FDT_BEGIN_NODE tag\r
1471 * -FDT_ERR_EXISTS, if the node at parentoffset already has a subnode of\r
1472 * the given name\r
1473 * -FDT_ERR_NOSPACE, if there is insufficient free space in the\r
1474 * blob to contain the new node\r
1475 * -FDT_ERR_NOSPACE\r
1476 * -FDT_ERR_BADLAYOUT\r
1477 * -FDT_ERR_BADMAGIC,\r
1478 * -FDT_ERR_BADVERSION,\r
1479 * -FDT_ERR_BADSTATE,\r
1480 * -FDT_ERR_BADSTRUCTURE,\r
1481 * -FDT_ERR_TRUNCATED, standard meanings.\r
1482 */\r
1483int fdt_add_subnode(void *fdt, int parentoffset, const char *name);\r
1484\r
1485/**\r
1486 * fdt_del_node - delete a node (subtree)\r
1487 * @fdt: pointer to the device tree blob\r
1488 * @nodeoffset: offset of the node to nop\r
1489 *\r
1490 * fdt_del_node() will remove the given node, including all its\r
1491 * subnodes if any, from the blob.\r
1492 *\r
1493 * This function will delete data from the blob, and will therefore\r
1494 * change the offsets of some existing nodes.\r
1495 *\r
1496 * returns:\r
1497 * 0, on success\r
1498 * -FDT_ERR_BADOFFSET, nodeoffset did not point to FDT_BEGIN_NODE tag\r
1499 * -FDT_ERR_BADLAYOUT,\r
1500 * -FDT_ERR_BADMAGIC,\r
1501 * -FDT_ERR_BADVERSION,\r
1502 * -FDT_ERR_BADSTATE,\r
1503 * -FDT_ERR_BADSTRUCTURE,\r
1504 * -FDT_ERR_TRUNCATED, standard meanings\r
1505 */\r
1506int fdt_del_node(void *fdt, int nodeoffset);\r
1507\r
1508/**********************************************************************/\r
1509/* Debugging / informational functions */\r
1510/**********************************************************************/\r
1511\r
1512const char *fdt_strerror(int errval);\r
1513\r
1514#endif /* _LIBFDT_H */\r