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