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