1/* SPDX-License-Identifier: GPL-2.0+ */ 2/* 3 * Originally from Linux v4.9 4 * Copyright (C) 1996-2005 Paul Mackerras. 5 * 6 * Updates for PPC64 by Peter Bergner & David Engebretsen, IBM Corp. 7 * Updates for SPARC64 by David S. Miller 8 * Derived from PowerPC and Sparc prom.h files by Stephen Rothwell, IBM Corp. 9 * 10 * Copyright (c) 2017 Google, Inc 11 * Written by Simon Glass <sjg@chromium.org> 12 * 13 * Modified for U-Boot 14 * Copyright (c) 2017 Google, Inc 15 */ 16 17#ifndef _DM_OF_ACCESS_H 18#define _DM_OF_ACCESS_H 19 20#include <dm/of.h> 21 22/** 23 * of_find_all_nodes - Get next node in global list 24 * @prev: Previous node or NULL to start iteration 25 * of_node_put() will be called on it 26 * 27 * Returns a node pointer with refcount incremented, use 28 * of_node_put() on it when done. 29 */ 30struct device_node *of_find_all_nodes(struct device_node *prev); 31 32#define for_each_of_allnodes_from(from, dn) \ 33 for (dn = of_find_all_nodes(from); dn; dn = of_find_all_nodes(dn)) 34#define for_each_of_allnodes(dn) for_each_of_allnodes_from(NULL, dn) 35 36/* Dummy functions to mirror Linux. These are not used in U-Boot */ 37#define of_node_get(x) (x) 38static inline void of_node_put(const struct device_node *np) { } 39 40/** 41 * of_n_addr_cells() - Get the number of address cells for a node 42 * 43 * This walks back up the tree to find the closest #address-cells property 44 * which controls the given node. 45 * 46 * @np: Node pointer to check 47 * Return: number of address cells this node uses 48 */ 49int of_n_addr_cells(const struct device_node *np); 50 51/** 52 * of_n_size_cells() - Get the number of size cells for a node 53 * 54 * This walks back up the tree to find the closest #size-cells property 55 * which controls the given node. 56 * 57 * @np: Node pointer to check 58 * Return: number of size cells this node uses 59 */ 60int of_n_size_cells(const struct device_node *np); 61 62/** 63 * of_simple_addr_cells() - Get the address cells property in a node 64 * 65 * This function matches fdt_address_cells(). 66 * 67 * @np: Node pointer to check 68 * Return: value of #address-cells property in this node, or 2 if none 69 */ 70int of_simple_addr_cells(const struct device_node *np); 71 72/** 73 * of_simple_size_cells() - Get the size cells property in a node 74 * 75 * This function matches fdt_size_cells(). 76 * 77 * @np: Node pointer to check 78 * Return: value of #size-cells property in this node, or 2 if none 79 */ 80int of_simple_size_cells(const struct device_node *np); 81 82/** 83 * of_find_property() - find a property in a node 84 * 85 * @np: Pointer to device node holding property 86 * @name: Name of property 87 * @lenp: If non-NULL, returns length of property 88 * Return: pointer to property, or NULL if not found 89 */ 90struct property *of_find_property(const struct device_node *np, 91 const char *name, int *lenp); 92 93/** 94 * of_get_property() - get a property value 95 * 96 * Find a property with a given name for a given node and return the value. 97 * 98 * @np: Pointer to device node holding property 99 * @name: Name of property 100 * @lenp: If non-NULL, returns length of property 101 * Return: pointer to property value, or NULL if not found 102 */ 103const void *of_get_property(const struct device_node *np, const char *name, 104 int *lenp); 105 106/** 107 * of_get_first_property()- get to the pointer of the first property 108 * 109 * Get pointer to the first property of the node, it is used to iterate 110 * and read all the property with of_get_next_property_by_prop(). 111 * 112 * @np: Pointer to device node 113 * Return: pointer to property or NULL if not found 114 */ 115const struct property *of_get_first_property(const struct device_node *np); 116 117/** 118 * of_get_next_property() - get to the pointer of the next property 119 * 120 * Get pointer to the next property of the node, it is used to iterate 121 * and read all the property with of_get_property_by_prop(). 122 * 123 * @np: Pointer to device node 124 * @property: pointer of the current property 125 * Return: pointer to next property or NULL if not found 126 */ 127const struct property *of_get_next_property(const struct device_node *np, 128 const struct property *property); 129 130/** 131 * of_get_property_by_prop() - get a property value of a node property 132 * 133 * Get value for the property identified by node and property pointer. 134 * 135 * @np: Pointer to device node 136 * @property: pointer of the property to read 137 * @name: place to property name on success 138 * @lenp: place to put length on success 139 * Return: pointer to property value or NULL if error 140 */ 141const void *of_get_property_by_prop(const struct device_node *np, 142 const struct property *property, 143 const char **name, 144 int *lenp); 145 146/** 147 * of_device_is_compatible() - Check if the node matches given constraints 148 * @np: Pointer to device node 149 * @compat: required compatible string, NULL or "" for any match 150 * @type: required device_type value, NULL or "" for any match 151 * @name: required node name, NULL or "" for any match 152 * 153 * Checks if the given @compat, @type and @name strings match the 154 * properties of the given @device. A constraints can be skipped by 155 * passing NULL or an empty string as the constraint. 156 * 157 * Return: 0 for no match, and a positive integer on match. The return 158 * value is a relative score with larger values indicating better 159 * matches. The score is weighted for the most specific compatible value 160 * to get the highest score. Matching type is next, followed by matching 161 * name. Practically speaking, this results in the following priority 162 * order for matches: 163 * 164 * 1. specific compatible && type && name 165 * 2. specific compatible && type 166 * 3. specific compatible && name 167 * 4. specific compatible 168 * 5. general compatible && type && name 169 * 6. general compatible && type 170 * 7. general compatible && name 171 * 8. general compatible 172 * 9. type && name 173 * 10. type 174 * 11. name 175 */ 176int of_device_is_compatible(const struct device_node *np, const char *compat, 177 const char *type, const char *name); 178 179/** 180 * of_device_is_available() - check if a device is available for use 181 * 182 * @np: Pointer to device node to check for availability 183 * 184 * Return: true if the status property is absent or set to "okay", false 185 * otherwise 186 */ 187bool of_device_is_available(const struct device_node *np); 188 189/** 190 * of_get_parent() - Get a node's parent, if any 191 * 192 * @np: Pointer to device node to check 193 * Return: a node pointer, or NULL if none 194 */ 195struct device_node *of_get_parent(const struct device_node *np); 196 197/** 198 * of_find_node_opts_by_path() - Find a node matching a full OF path 199 * 200 * Note that alias processing is only available on the control FDT (gd->of_root). 201 * For other trees it is skipped, so any attempt to obtain an alias will result 202 * in returning NULL. 203 * 204 * @root: Root node of the tree to use. If this is NULL, then gd->of_root is used 205 * @path: Either the full path to match, or if the path does not start with 206 * '/', the name of a property of the /aliases node (an alias). In the 207 * case of an alias, the node matching the alias' value will be returned. 208 * @opts: Address of a pointer into which to store the start of an options 209 * string appended to the end of the path with a ':' separator. Can be NULL 210 * 211 * Valid paths: 212 * /foo/bar Full path 213 * foo Valid alias 214 * foo/bar Valid alias + relative path 215 * 216 * Return: a node pointer or NULL if not found 217 */ 218struct device_node *of_find_node_opts_by_path(struct device_node *root, 219 const char *path, 220 const char **opts); 221 222static inline struct device_node *of_find_node_by_path(const char *path) 223{ 224 return of_find_node_opts_by_path(NULL, path, NULL); 225} 226 227/** 228 * of_find_compatible_node() - find a node based on its compatible string 229 * 230 * Find a node based on type and one of the tokens in its "compatible" property 231 * @from: Node to start searching from or NULL. the node you pass will not be 232 * searched, only the next one will; typically, you pass what the previous 233 * call returned. 234 * @type: The type string to match "device_type" or NULL to ignore 235 * @compatible: The string to match to one of the tokens in the device 236 * "compatible" list. 237 * Return: node pointer or NULL if not found 238 */ 239struct device_node *of_find_compatible_node(struct device_node *from, 240 const char *type, const char *compatible); 241 242/** 243 * of_find_node_by_prop_value() - find a node with a given property value 244 * 245 * Find a node based on a property value. 246 * @from: Node to start searching from or NULL. the node you pass will not be 247 * searched, only the next one will; typically, you pass what the previous 248 * call returned. 249 * @propname: property name to check 250 * @propval: property value to search for 251 * @proplen: length of the value in propval 252 * Return: node pointer or NULL if not found 253 */ 254struct device_node *of_find_node_by_prop_value(struct device_node *from, 255 const char *propname, 256 const void *propval, 257 int proplen); 258/** 259 * of_find_node_by_phandle() - Find a node given a phandle 260 * 261 * @root: root node to start from (NULL for default device tree) 262 * @handle: phandle of the node to find 263 * 264 * Return: node pointer, or NULL if not found 265 */ 266struct device_node *of_find_node_by_phandle(struct device_node *root, 267 phandle handle); 268 269/** 270 * of_read_u8() - Find and read a 8-bit integer from a property 271 * 272 * Search for a property in a device node and read a 8-bit value from 273 * it. 274 * 275 * @np: device node from which the property value is to be read. 276 * @propname: name of the property to be searched. 277 * @outp: pointer to return value, modified only if return value is 0. 278 * 279 * Return: 0 on success, -EINVAL if the property does not exist, 280 * -ENODATA if property does not have a value, and -EOVERFLOW if the 281 * property data isn't large enough. 282 */ 283int of_read_u8(const struct device_node *np, const char *propname, u8 *outp); 284 285/** 286 * of_read_u16() - Find and read a 16-bit integer from a property 287 * 288 * Search for a property in a device node and read a 16-bit value from 289 * it. 290 * 291 * @np: device node from which the property value is to be read. 292 * @propname: name of the property to be searched. 293 * @outp: pointer to return value, modified only if return value is 0. 294 * 295 * Return: 0 on success, -EINVAL if the property does not exist, 296 * -ENODATA if property does not have a value, and -EOVERFLOW if the 297 * property data isn't large enough. 298 */ 299int of_read_u16(const struct device_node *np, const char *propname, u16 *outp); 300 301/** 302 * of_read_u32() - Find and read a 32-bit integer from a property 303 * 304 * Search for a property in a device node and read a 32-bit value from 305 * it. 306 * 307 * @np: device node from which the property value is to be read. 308 * @propname: name of the property to be searched. 309 * @outp: pointer to return value, modified only if return value is 0. 310 * 311 * Return: 0 on success, -EINVAL if the property does not exist, 312 * -ENODATA if property does not have a value, and -EOVERFLOW if the 313 * property data isn't large enough. 314 */ 315int of_read_u32(const struct device_node *np, const char *propname, u32 *outp); 316 317/** 318 * of_read_u32_index() - Find and read a 32-bit value from a multi-value 319 * property 320 * 321 * Search for a property in a device node and read a 32-bit value from 322 * it. 323 * 324 * @np: device node from which the property value is to be read. 325 * @propname: name of the property to be searched. 326 * @index: index of the u32 in the list of values 327 * @outp: pointer to return value, modified only if return value is 0. 328 * 329 * Return: 330 * 0 on success, -EINVAL if the property does not exist, or -EOVERFLOW if the 331 * property data isn't large enough. 332 */ 333int of_read_u32_index(const struct device_node *np, const char *propname, 334 int index, u32 *outp); 335 336/** 337 * of_read_u64_index() - Find and read a 64-bit value from a multi-value 338 * property 339 * 340 * @np: device node from which the property value is to be read. 341 * @propname: name of the property to be searched. 342 * @index: index of the u32 in the list of values 343 * @outp: pointer to return value, modified only if return value is 0. 344 * 345 * Search for a property in a device node and read a 64-bit value from 346 * it. 347 * 348 * Return: 349 * 0 on success, -EINVAL if the property does not exist, or -EOVERFLOW if the 350 * property data isn't large enough. 351 */ 352int of_read_u64_index(const struct device_node *np, const char *propname, 353 int index, u64 *outp); 354 355/** 356 * of_read_u64() - Find and read a 64-bit integer from a property 357 * 358 * Search for a property in a device node and read a 64-bit value from 359 * it. 360 * 361 * @np: device node from which the property value is to be read. 362 * @propname: name of the property to be searched. 363 * @outp: pointer to return value, modified only if return value is 0. 364 * 365 * Return: 366 * 0 on success, -EINVAL if the property does not exist, or -EOVERFLOW if the 367 * property data isn't large enough. 368 */ 369int of_read_u64(const struct device_node *np, const char *propname, u64 *outp); 370 371/** 372 * of_read_u32_array() - Find and read an array of 32 bit integers 373 * 374 * Search for a property in a device node and read 32-bit value(s) from 375 * it. 376 * 377 * @np: device node from which the property value is to be read. 378 * @propname: name of the property to be searched. 379 * @out_values: pointer to return value, modified only if return value is 0. 380 * @sz: number of array elements to read 381 * Return: 382 * 0 on success, -EINVAL if the property does not exist, or -EOVERFLOW if 383 * longer than sz. 384 */ 385int of_read_u32_array(const struct device_node *np, const char *propname, 386 u32 *out_values, size_t sz); 387 388/** 389 * of_property_match_string() - Find string in a list and return index 390 * 391 * This function searches a string list property and returns the index 392 * of a specific string value. 393 * 394 * @np: pointer to node containing string list property 395 * @propname: string list property name 396 * @string: pointer to string to search for in string list 397 * Return: 398 * 0 on success, -EINVAL if the property does not exist, -ENODATA 399 * if property does not have a value, and -EOVERFLOW is longer than sz. 400 */ 401int of_property_match_string(const struct device_node *np, const char *propname, 402 const char *string); 403 404int of_property_read_string_helper(const struct device_node *np, 405 const char *propname, const char **out_strs, 406 size_t sz, int index); 407 408/** 409 * of_property_read_string_index() - Find and read a string from a multiple 410 * strings property. 411 * @np: device node from which the property value is to be read. 412 * @propname: name of the property to be searched. 413 * @index: index of the string in the list of strings 414 * @output: pointer to null terminated return string, modified only if 415 * return value is 0. 416 * 417 * Search for a property in a device tree node and retrieve a null 418 * terminated string value (pointer to data, not a copy) in the list of strings 419 * contained in that property. 420 * 421 * Return: 422 * 0 on success, -EINVAL if the property does not exist, -ENODATA if 423 * property does not have a value, and -EILSEQ if the string is not 424 * null-terminated within the length of the property data. 425 * 426 * The out_string pointer is modified only if a valid string can be decoded. 427 */ 428static inline int of_property_read_string_index(const struct device_node *np, 429 const char *propname, 430 int index, const char **output) 431{ 432 int rc = of_property_read_string_helper(np, propname, output, 1, index); 433 return rc < 0 ? rc : 0; 434} 435 436/** 437 * of_property_count_strings() - Find and return the number of strings from a 438 * multiple strings property. 439 * @np: device node from which the property value is to be read. 440 * @propname: name of the property to be searched. 441 * 442 * Search for a property in a device tree node and retrieve the number of null 443 * terminated string contain in it. 444 * 445 * Return: 446 * the number of strings on success, -EINVAL if the property does not exist, 447 * -ENODATA if property does not have a value, and -EILSEQ if the string is 448 * not null-terminated within the length of the property data. 449 */ 450static inline int of_property_count_strings(const struct device_node *np, 451 const char *propname) 452{ 453 return of_property_read_string_helper(np, propname, NULL, 0, 0); 454} 455 456/** 457 * of_parse_phandle - Resolve a phandle property to a device_node pointer 458 * @np: Pointer to device node holding phandle property 459 * @phandle_name: Name of property holding a phandle value 460 * @index: For properties holding a table of phandles, this is the index into 461 * the table 462 * 463 * Return: 464 * the device_node pointer with refcount incremented. Use 465 * of_node_put() on it when done. 466 */ 467struct device_node *of_parse_phandle(const struct device_node *np, 468 const char *phandle_name, int index); 469 470/** 471 * of_parse_phandle_with_args() - Find a node pointed by phandle in a list 472 * 473 * @np: pointer to a device tree node containing a list 474 * @list_name: property name that contains a list 475 * @cells_name: property name that specifies phandles' arguments count 476 * @cells_count: Cell count to use if @cells_name is NULL 477 * @index: index of a phandle to parse out 478 * @out_args: optional pointer to output arguments structure (will be filled) 479 * Return: 480 * 0 on success (with @out_args filled out if not NULL), -ENOENT if 481 * @list_name does not exist, -EINVAL if a phandle was not found, 482 * @cells_name could not be found, the arguments were truncated or there 483 * were too many arguments. 484 * 485 * This function is useful to parse lists of phandles and their arguments. 486 * Returns 0 on success and fills out_args, on error returns appropriate 487 * errno value. 488 * 489 * Caller is responsible to call of_node_put() on the returned out_args->np 490 * pointer. 491 * 492 * Example: 493 * 494 * .. code-block:: 495 * 496 * phandle1: node1 { 497 * #list-cells = <2>; 498 * }; 499 * phandle2: node2 { 500 * #list-cells = <1>; 501 * }; 502 * node3 { 503 * list = <&phandle1 1 2 &phandle2 3>; 504 * }; 505 * 506 * To get a device_node of the `node2' node you may call this: 507 * of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args); 508 */ 509int of_parse_phandle_with_args(const struct device_node *np, 510 const char *list_name, const char *cells_name, 511 int cells_count, int index, 512 struct of_phandle_args *out_args); 513 514/** 515 * of_count_phandle_with_args() - Count the number of phandle in a list 516 * 517 * @np: pointer to a device tree node containing a list 518 * @list_name: property name that contains a list 519 * @cells_name: property name that specifies phandles' arguments count 520 * @cells_count: Cell count to use if @cells_name is NULL 521 * Return: 522 * number of phandle found, -ENOENT if @list_name does not exist, 523 * -EINVAL if a phandle was not found, @cells_name could not be found, 524 * the arguments were truncated or there were too many arguments. 525 * 526 * Returns number of phandle found on success, on error returns appropriate 527 * errno value. 528 */ 529int of_count_phandle_with_args(const struct device_node *np, 530 const char *list_name, const char *cells_name, 531 int cells_count); 532 533/** 534 * of_alias_scan() - Scan all properties of the 'aliases' node 535 * 536 * The function scans all the properties of the 'aliases' node and populates 537 * the lookup table with the properties. It returns the number of alias 538 * properties found, or an error code in case of failure. 539 * 540 * Return: 9 if OK, -ENOMEM if not enough memory 541 */ 542int of_alias_scan(void); 543 544/** 545 * of_alias_get_id - Get alias id for the given device_node 546 * 547 * Travels the lookup table to get the alias id for the given device_node and 548 * alias stem. 549 * 550 * @np: Pointer to the given device_node 551 * @stem: Alias stem of the given device_node 552 * Return: alias ID, if found, else -ENODEV 553 */ 554int of_alias_get_id(const struct device_node *np, const char *stem); 555 556/** 557 * of_alias_get_highest_id - Get highest alias id for the given stem 558 * @stem: Alias stem to be examined 559 * 560 * The function travels the lookup table to get the highest alias id for the 561 * given alias stem. 562 * Return: alias ID, if found, else -1 563 */ 564int of_alias_get_highest_id(const char *stem); 565 566/** 567 * of_get_stdout() - Get node to use for stdout 568 * 569 * Return: node referred to by stdout-path alias, or NULL if none 570 */ 571struct device_node *of_get_stdout(void); 572 573/** 574 * of_write_prop() - Write a property to the device tree 575 * 576 * @np: device node to which the property value is to be written 577 * @propname: name of the property to write 578 * @value: value of the property 579 * @len: length of the property in bytes 580 * Returns: 0 if OK, -ve on error 581 */ 582int of_write_prop(struct device_node *np, const char *propname, int len, 583 const void *value); 584 585/** 586 * of_add_subnode() - add a new subnode to a node 587 * 588 * @node: parent node to add to 589 * @name: name of subnode 590 * @len: length of name (so the caller does not need to nul-terminate a 591 * partial string), or -1 for strlen(@name) 592 * @subnodep: returns pointer to new subnode (valid if the function returns 0 593 * or -EEXIST) 594 * Returns 0 if OK, -EEXIST if already exists, -ENOMEM if out of memory, other 595 * -ve on other error 596 */ 597int of_add_subnode(struct device_node *node, const char *name, int len, 598 struct device_node **subnodep); 599 600/** 601 * of_remove_property() - Remove a property from a node 602 * 603 * @np: Node to remove from 604 * @prop: Pointer to property to remove 605 * Return 0 if OK, -ENODEV if the property could not be found in the node 606 */ 607int of_remove_property(struct device_node *np, struct property *prop); 608 609/** 610 * of_remove_node() - Remove a node from the tree 611 * 612 * @to_remove: Node to remove 613 * Return: 0 if OK, -EPERM if it is the root node (wWhich cannot be removed), 614 * -ENOENT if the tree is broken (to_remove is not a child of its parent) 615 */ 616int of_remove_node(struct device_node *to_remove); 617 618#endif 619