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