1 // SPDX-License-Identifier: GPL-2.0 2 /* 3 * property.c - Unified device property interface. 4 * 5 * Copyright (C) 2014, Intel Corporation 6 * Authors: Rafael J. Wysocki <rafael.j.wysocki@intel.com> 7 * Mika Westerberg <mika.westerberg@linux.intel.com> 8 */ 9 10 #include <linux/acpi.h> 11 #include <linux/export.h> 12 #include <linux/kernel.h> 13 #include <linux/of.h> 14 #include <linux/of_address.h> 15 #include <linux/of_graph.h> 16 #include <linux/of_irq.h> 17 #include <linux/property.h> 18 #include <linux/phy.h> 19 20 struct fwnode_handle *dev_fwnode(struct device *dev) 21 { 22 return IS_ENABLED(CONFIG_OF) && dev->of_node ? 23 of_fwnode_handle(dev->of_node) : dev->fwnode; 24 } 25 EXPORT_SYMBOL_GPL(dev_fwnode); 26 27 /** 28 * device_property_present - check if a property of a device is present 29 * @dev: Device whose property is being checked 30 * @propname: Name of the property 31 * 32 * Check if property @propname is present in the device firmware description. 33 */ 34 bool device_property_present(struct device *dev, const char *propname) 35 { 36 return fwnode_property_present(dev_fwnode(dev), propname); 37 } 38 EXPORT_SYMBOL_GPL(device_property_present); 39 40 /** 41 * fwnode_property_present - check if a property of a firmware node is present 42 * @fwnode: Firmware node whose property to check 43 * @propname: Name of the property 44 */ 45 bool fwnode_property_present(const struct fwnode_handle *fwnode, 46 const char *propname) 47 { 48 bool ret; 49 50 ret = fwnode_call_bool_op(fwnode, property_present, propname); 51 if (ret == false && !IS_ERR_OR_NULL(fwnode) && 52 !IS_ERR_OR_NULL(fwnode->secondary)) 53 ret = fwnode_call_bool_op(fwnode->secondary, property_present, 54 propname); 55 return ret; 56 } 57 EXPORT_SYMBOL_GPL(fwnode_property_present); 58 59 /** 60 * device_property_read_u8_array - return a u8 array property of a device 61 * @dev: Device to get the property of 62 * @propname: Name of the property 63 * @val: The values are stored here or %NULL to return the number of values 64 * @nval: Size of the @val array 65 * 66 * Function reads an array of u8 properties with @propname from the device 67 * firmware description and stores them to @val if found. 68 * 69 * Return: number of values if @val was %NULL, 70 * %0 if the property was found (success), 71 * %-EINVAL if given arguments are not valid, 72 * %-ENODATA if the property does not have a value, 73 * %-EPROTO if the property is not an array of numbers, 74 * %-EOVERFLOW if the size of the property is not as expected. 75 * %-ENXIO if no suitable firmware interface is present. 76 */ 77 int device_property_read_u8_array(struct device *dev, const char *propname, 78 u8 *val, size_t nval) 79 { 80 return fwnode_property_read_u8_array(dev_fwnode(dev), propname, val, nval); 81 } 82 EXPORT_SYMBOL_GPL(device_property_read_u8_array); 83 84 /** 85 * device_property_read_u16_array - return a u16 array property of a device 86 * @dev: Device to get the property of 87 * @propname: Name of the property 88 * @val: The values are stored here or %NULL to return the number of values 89 * @nval: Size of the @val array 90 * 91 * Function reads an array of u16 properties with @propname from the device 92 * firmware description and stores them to @val if found. 93 * 94 * Return: number of values if @val was %NULL, 95 * %0 if the property was found (success), 96 * %-EINVAL if given arguments are not valid, 97 * %-ENODATA if the property does not have a value, 98 * %-EPROTO if the property is not an array of numbers, 99 * %-EOVERFLOW if the size of the property is not as expected. 100 * %-ENXIO if no suitable firmware interface is present. 101 */ 102 int device_property_read_u16_array(struct device *dev, const char *propname, 103 u16 *val, size_t nval) 104 { 105 return fwnode_property_read_u16_array(dev_fwnode(dev), propname, val, nval); 106 } 107 EXPORT_SYMBOL_GPL(device_property_read_u16_array); 108 109 /** 110 * device_property_read_u32_array - return a u32 array property of a device 111 * @dev: Device to get the property of 112 * @propname: Name of the property 113 * @val: The values are stored here or %NULL to return the number of values 114 * @nval: Size of the @val array 115 * 116 * Function reads an array of u32 properties with @propname from the device 117 * firmware description and stores them to @val if found. 118 * 119 * Return: number of values if @val was %NULL, 120 * %0 if the property was found (success), 121 * %-EINVAL if given arguments are not valid, 122 * %-ENODATA if the property does not have a value, 123 * %-EPROTO if the property is not an array of numbers, 124 * %-EOVERFLOW if the size of the property is not as expected. 125 * %-ENXIO if no suitable firmware interface is present. 126 */ 127 int device_property_read_u32_array(struct device *dev, const char *propname, 128 u32 *val, size_t nval) 129 { 130 return fwnode_property_read_u32_array(dev_fwnode(dev), propname, val, nval); 131 } 132 EXPORT_SYMBOL_GPL(device_property_read_u32_array); 133 134 /** 135 * device_property_read_u64_array - return a u64 array property of a device 136 * @dev: Device to get the property of 137 * @propname: Name of the property 138 * @val: The values are stored here or %NULL to return the number of values 139 * @nval: Size of the @val array 140 * 141 * Function reads an array of u64 properties with @propname from the device 142 * firmware description and stores them to @val if found. 143 * 144 * Return: number of values if @val was %NULL, 145 * %0 if the property was found (success), 146 * %-EINVAL if given arguments are not valid, 147 * %-ENODATA if the property does not have a value, 148 * %-EPROTO if the property is not an array of numbers, 149 * %-EOVERFLOW if the size of the property is not as expected. 150 * %-ENXIO if no suitable firmware interface is present. 151 */ 152 int device_property_read_u64_array(struct device *dev, const char *propname, 153 u64 *val, size_t nval) 154 { 155 return fwnode_property_read_u64_array(dev_fwnode(dev), propname, val, nval); 156 } 157 EXPORT_SYMBOL_GPL(device_property_read_u64_array); 158 159 /** 160 * device_property_read_string_array - return a string array property of device 161 * @dev: Device to get the property of 162 * @propname: Name of the property 163 * @val: The values are stored here or %NULL to return the number of values 164 * @nval: Size of the @val array 165 * 166 * Function reads an array of string properties with @propname from the device 167 * firmware description and stores them to @val if found. 168 * 169 * Return: number of values read on success if @val is non-NULL, 170 * number of values available on success if @val is NULL, 171 * %-EINVAL if given arguments are not valid, 172 * %-ENODATA if the property does not have a value, 173 * %-EPROTO or %-EILSEQ if the property is not an array of strings, 174 * %-EOVERFLOW if the size of the property is not as expected. 175 * %-ENXIO if no suitable firmware interface is present. 176 */ 177 int device_property_read_string_array(struct device *dev, const char *propname, 178 const char **val, size_t nval) 179 { 180 return fwnode_property_read_string_array(dev_fwnode(dev), propname, val, nval); 181 } 182 EXPORT_SYMBOL_GPL(device_property_read_string_array); 183 184 /** 185 * device_property_read_string - return a string property of a device 186 * @dev: Device to get the property of 187 * @propname: Name of the property 188 * @val: The value is stored here 189 * 190 * Function reads property @propname from the device firmware description and 191 * stores the value into @val if found. The value is checked to be a string. 192 * 193 * Return: %0 if the property was found (success), 194 * %-EINVAL if given arguments are not valid, 195 * %-ENODATA if the property does not have a value, 196 * %-EPROTO or %-EILSEQ if the property type is not a string. 197 * %-ENXIO if no suitable firmware interface is present. 198 */ 199 int device_property_read_string(struct device *dev, const char *propname, 200 const char **val) 201 { 202 return fwnode_property_read_string(dev_fwnode(dev), propname, val); 203 } 204 EXPORT_SYMBOL_GPL(device_property_read_string); 205 206 /** 207 * device_property_match_string - find a string in an array and return index 208 * @dev: Device to get the property of 209 * @propname: Name of the property holding the array 210 * @string: String to look for 211 * 212 * Find a given string in a string array and if it is found return the 213 * index back. 214 * 215 * Return: %0 if the property was found (success), 216 * %-EINVAL if given arguments are not valid, 217 * %-ENODATA if the property does not have a value, 218 * %-EPROTO if the property is not an array of strings, 219 * %-ENXIO if no suitable firmware interface is present. 220 */ 221 int device_property_match_string(struct device *dev, const char *propname, 222 const char *string) 223 { 224 return fwnode_property_match_string(dev_fwnode(dev), propname, string); 225 } 226 EXPORT_SYMBOL_GPL(device_property_match_string); 227 228 static int fwnode_property_read_int_array(const struct fwnode_handle *fwnode, 229 const char *propname, 230 unsigned int elem_size, void *val, 231 size_t nval) 232 { 233 int ret; 234 235 ret = fwnode_call_int_op(fwnode, property_read_int_array, propname, 236 elem_size, val, nval); 237 if (ret == -EINVAL && !IS_ERR_OR_NULL(fwnode) && 238 !IS_ERR_OR_NULL(fwnode->secondary)) 239 ret = fwnode_call_int_op( 240 fwnode->secondary, property_read_int_array, propname, 241 elem_size, val, nval); 242 243 return ret; 244 } 245 246 /** 247 * fwnode_property_read_u8_array - return a u8 array property of firmware node 248 * @fwnode: Firmware node to get the property of 249 * @propname: Name of the property 250 * @val: The values are stored here or %NULL to return the number of values 251 * @nval: Size of the @val array 252 * 253 * Read an array of u8 properties with @propname from @fwnode and stores them to 254 * @val if found. 255 * 256 * Return: number of values if @val was %NULL, 257 * %0 if the property was found (success), 258 * %-EINVAL if given arguments are not valid, 259 * %-ENODATA if the property does not have a value, 260 * %-EPROTO if the property is not an array of numbers, 261 * %-EOVERFLOW if the size of the property is not as expected, 262 * %-ENXIO if no suitable firmware interface is present. 263 */ 264 int fwnode_property_read_u8_array(const struct fwnode_handle *fwnode, 265 const char *propname, u8 *val, size_t nval) 266 { 267 return fwnode_property_read_int_array(fwnode, propname, sizeof(u8), 268 val, nval); 269 } 270 EXPORT_SYMBOL_GPL(fwnode_property_read_u8_array); 271 272 /** 273 * fwnode_property_read_u16_array - return a u16 array property of firmware node 274 * @fwnode: Firmware node to get the property of 275 * @propname: Name of the property 276 * @val: The values are stored here or %NULL to return the number of values 277 * @nval: Size of the @val array 278 * 279 * Read an array of u16 properties with @propname from @fwnode and store them to 280 * @val if found. 281 * 282 * Return: number of values if @val was %NULL, 283 * %0 if the property was found (success), 284 * %-EINVAL if given arguments are not valid, 285 * %-ENODATA if the property does not have a value, 286 * %-EPROTO if the property is not an array of numbers, 287 * %-EOVERFLOW if the size of the property is not as expected, 288 * %-ENXIO if no suitable firmware interface is present. 289 */ 290 int fwnode_property_read_u16_array(const struct fwnode_handle *fwnode, 291 const char *propname, u16 *val, size_t nval) 292 { 293 return fwnode_property_read_int_array(fwnode, propname, sizeof(u16), 294 val, nval); 295 } 296 EXPORT_SYMBOL_GPL(fwnode_property_read_u16_array); 297 298 /** 299 * fwnode_property_read_u32_array - return a u32 array property of firmware node 300 * @fwnode: Firmware node to get the property of 301 * @propname: Name of the property 302 * @val: The values are stored here or %NULL to return the number of values 303 * @nval: Size of the @val array 304 * 305 * Read an array of u32 properties with @propname from @fwnode store them to 306 * @val if found. 307 * 308 * Return: number of values if @val was %NULL, 309 * %0 if the property was found (success), 310 * %-EINVAL if given arguments are not valid, 311 * %-ENODATA if the property does not have a value, 312 * %-EPROTO if the property is not an array of numbers, 313 * %-EOVERFLOW if the size of the property is not as expected, 314 * %-ENXIO if no suitable firmware interface is present. 315 */ 316 int fwnode_property_read_u32_array(const struct fwnode_handle *fwnode, 317 const char *propname, u32 *val, size_t nval) 318 { 319 return fwnode_property_read_int_array(fwnode, propname, sizeof(u32), 320 val, nval); 321 } 322 EXPORT_SYMBOL_GPL(fwnode_property_read_u32_array); 323 324 /** 325 * fwnode_property_read_u64_array - return a u64 array property firmware node 326 * @fwnode: Firmware node to get the property of 327 * @propname: Name of the property 328 * @val: The values are stored here or %NULL to return the number of values 329 * @nval: Size of the @val array 330 * 331 * Read an array of u64 properties with @propname from @fwnode and store them to 332 * @val if found. 333 * 334 * Return: number of values if @val was %NULL, 335 * %0 if the property was found (success), 336 * %-EINVAL if given arguments are not valid, 337 * %-ENODATA if the property does not have a value, 338 * %-EPROTO if the property is not an array of numbers, 339 * %-EOVERFLOW if the size of the property is not as expected, 340 * %-ENXIO if no suitable firmware interface is present. 341 */ 342 int fwnode_property_read_u64_array(const struct fwnode_handle *fwnode, 343 const char *propname, u64 *val, size_t nval) 344 { 345 return fwnode_property_read_int_array(fwnode, propname, sizeof(u64), 346 val, nval); 347 } 348 EXPORT_SYMBOL_GPL(fwnode_property_read_u64_array); 349 350 /** 351 * fwnode_property_read_string_array - return string array property of a node 352 * @fwnode: Firmware node to get the property of 353 * @propname: Name of the property 354 * @val: The values are stored here or %NULL to return the number of values 355 * @nval: Size of the @val array 356 * 357 * Read an string list property @propname from the given firmware node and store 358 * them to @val if found. 359 * 360 * Return: number of values read on success if @val is non-NULL, 361 * number of values available on success if @val is NULL, 362 * %-EINVAL if given arguments are not valid, 363 * %-ENODATA if the property does not have a value, 364 * %-EPROTO or %-EILSEQ if the property is not an array of strings, 365 * %-EOVERFLOW if the size of the property is not as expected, 366 * %-ENXIO if no suitable firmware interface is present. 367 */ 368 int fwnode_property_read_string_array(const struct fwnode_handle *fwnode, 369 const char *propname, const char **val, 370 size_t nval) 371 { 372 int ret; 373 374 ret = fwnode_call_int_op(fwnode, property_read_string_array, propname, 375 val, nval); 376 if (ret == -EINVAL && !IS_ERR_OR_NULL(fwnode) && 377 !IS_ERR_OR_NULL(fwnode->secondary)) 378 ret = fwnode_call_int_op(fwnode->secondary, 379 property_read_string_array, propname, 380 val, nval); 381 return ret; 382 } 383 EXPORT_SYMBOL_GPL(fwnode_property_read_string_array); 384 385 /** 386 * fwnode_property_read_string - return a string property of a firmware node 387 * @fwnode: Firmware node to get the property of 388 * @propname: Name of the property 389 * @val: The value is stored here 390 * 391 * Read property @propname from the given firmware node and store the value into 392 * @val if found. The value is checked to be a string. 393 * 394 * Return: %0 if the property was found (success), 395 * %-EINVAL if given arguments are not valid, 396 * %-ENODATA if the property does not have a value, 397 * %-EPROTO or %-EILSEQ if the property is not a string, 398 * %-ENXIO if no suitable firmware interface is present. 399 */ 400 int fwnode_property_read_string(const struct fwnode_handle *fwnode, 401 const char *propname, const char **val) 402 { 403 int ret = fwnode_property_read_string_array(fwnode, propname, val, 1); 404 405 return ret < 0 ? ret : 0; 406 } 407 EXPORT_SYMBOL_GPL(fwnode_property_read_string); 408 409 /** 410 * fwnode_property_match_string - find a string in an array and return index 411 * @fwnode: Firmware node to get the property of 412 * @propname: Name of the property holding the array 413 * @string: String to look for 414 * 415 * Find a given string in a string array and if it is found return the 416 * index back. 417 * 418 * Return: %0 if the property was found (success), 419 * %-EINVAL if given arguments are not valid, 420 * %-ENODATA if the property does not have a value, 421 * %-EPROTO if the property is not an array of strings, 422 * %-ENXIO if no suitable firmware interface is present. 423 */ 424 int fwnode_property_match_string(const struct fwnode_handle *fwnode, 425 const char *propname, const char *string) 426 { 427 const char **values; 428 int nval, ret; 429 430 nval = fwnode_property_read_string_array(fwnode, propname, NULL, 0); 431 if (nval < 0) 432 return nval; 433 434 if (nval == 0) 435 return -ENODATA; 436 437 values = kcalloc(nval, sizeof(*values), GFP_KERNEL); 438 if (!values) 439 return -ENOMEM; 440 441 ret = fwnode_property_read_string_array(fwnode, propname, values, nval); 442 if (ret < 0) 443 goto out; 444 445 ret = match_string(values, nval, string); 446 if (ret < 0) 447 ret = -ENODATA; 448 out: 449 kfree(values); 450 return ret; 451 } 452 EXPORT_SYMBOL_GPL(fwnode_property_match_string); 453 454 /** 455 * fwnode_property_get_reference_args() - Find a reference with arguments 456 * @fwnode: Firmware node where to look for the reference 457 * @prop: The name of the property 458 * @nargs_prop: The name of the property telling the number of 459 * arguments in the referred node. NULL if @nargs is known, 460 * otherwise @nargs is ignored. Only relevant on OF. 461 * @nargs: Number of arguments. Ignored if @nargs_prop is non-NULL. 462 * @index: Index of the reference, from zero onwards. 463 * @args: Result structure with reference and integer arguments. 464 * 465 * Obtain a reference based on a named property in an fwnode, with 466 * integer arguments. 467 * 468 * Caller is responsible to call fwnode_handle_put() on the returned 469 * args->fwnode pointer. 470 * 471 * Returns: %0 on success 472 * %-ENOENT when the index is out of bounds, the index has an empty 473 * reference or the property was not found 474 * %-EINVAL on parse error 475 */ 476 int fwnode_property_get_reference_args(const struct fwnode_handle *fwnode, 477 const char *prop, const char *nargs_prop, 478 unsigned int nargs, unsigned int index, 479 struct fwnode_reference_args *args) 480 { 481 return fwnode_call_int_op(fwnode, get_reference_args, prop, nargs_prop, 482 nargs, index, args); 483 } 484 EXPORT_SYMBOL_GPL(fwnode_property_get_reference_args); 485 486 /** 487 * fwnode_find_reference - Find named reference to a fwnode_handle 488 * @fwnode: Firmware node where to look for the reference 489 * @name: The name of the reference 490 * @index: Index of the reference 491 * 492 * @index can be used when the named reference holds a table of references. 493 * 494 * Returns pointer to the reference fwnode, or ERR_PTR. Caller is responsible to 495 * call fwnode_handle_put() on the returned fwnode pointer. 496 */ 497 struct fwnode_handle *fwnode_find_reference(const struct fwnode_handle *fwnode, 498 const char *name, 499 unsigned int index) 500 { 501 struct fwnode_reference_args args; 502 int ret; 503 504 ret = fwnode_property_get_reference_args(fwnode, name, NULL, 0, index, 505 &args); 506 return ret ? ERR_PTR(ret) : args.fwnode; 507 } 508 EXPORT_SYMBOL_GPL(fwnode_find_reference); 509 510 /** 511 * device_remove_properties - Remove properties from a device object. 512 * @dev: Device whose properties to remove. 513 * 514 * The function removes properties previously associated to the device 515 * firmware node with device_add_properties(). Memory allocated to the 516 * properties will also be released. 517 */ 518 void device_remove_properties(struct device *dev) 519 { 520 struct fwnode_handle *fwnode = dev_fwnode(dev); 521 522 if (!fwnode) 523 return; 524 525 if (is_software_node(fwnode->secondary)) { 526 fwnode_remove_software_node(fwnode->secondary); 527 set_secondary_fwnode(dev, NULL); 528 } 529 } 530 EXPORT_SYMBOL_GPL(device_remove_properties); 531 532 /** 533 * device_add_properties - Add a collection of properties to a device object. 534 * @dev: Device to add properties to. 535 * @properties: Collection of properties to add. 536 * 537 * Associate a collection of device properties represented by @properties with 538 * @dev. The function takes a copy of @properties. 539 * 540 * WARNING: The callers should not use this function if it is known that there 541 * is no real firmware node associated with @dev! In that case the callers 542 * should create a software node and assign it to @dev directly. 543 */ 544 int device_add_properties(struct device *dev, 545 const struct property_entry *properties) 546 { 547 struct fwnode_handle *fwnode; 548 549 fwnode = fwnode_create_software_node(properties, NULL); 550 if (IS_ERR(fwnode)) 551 return PTR_ERR(fwnode); 552 553 set_secondary_fwnode(dev, fwnode); 554 return 0; 555 } 556 EXPORT_SYMBOL_GPL(device_add_properties); 557 558 /** 559 * fwnode_get_name - Return the name of a node 560 * @fwnode: The firmware node 561 * 562 * Returns a pointer to the node name. 563 */ 564 const char *fwnode_get_name(const struct fwnode_handle *fwnode) 565 { 566 return fwnode_call_ptr_op(fwnode, get_name); 567 } 568 EXPORT_SYMBOL_GPL(fwnode_get_name); 569 570 /** 571 * fwnode_get_name_prefix - Return the prefix of node for printing purposes 572 * @fwnode: The firmware node 573 * 574 * Returns the prefix of a node, intended to be printed right before the node. 575 * The prefix works also as a separator between the nodes. 576 */ 577 const char *fwnode_get_name_prefix(const struct fwnode_handle *fwnode) 578 { 579 return fwnode_call_ptr_op(fwnode, get_name_prefix); 580 } 581 582 /** 583 * fwnode_get_parent - Return parent firwmare node 584 * @fwnode: Firmware whose parent is retrieved 585 * 586 * Return parent firmware node of the given node if possible or %NULL if no 587 * parent was available. 588 */ 589 struct fwnode_handle *fwnode_get_parent(const struct fwnode_handle *fwnode) 590 { 591 return fwnode_call_ptr_op(fwnode, get_parent); 592 } 593 EXPORT_SYMBOL_GPL(fwnode_get_parent); 594 595 /** 596 * fwnode_get_next_parent - Iterate to the node's parent 597 * @fwnode: Firmware whose parent is retrieved 598 * 599 * This is like fwnode_get_parent() except that it drops the refcount 600 * on the passed node, making it suitable for iterating through a 601 * node's parents. 602 * 603 * Returns a node pointer with refcount incremented, use 604 * fwnode_handle_node() on it when done. 605 */ 606 struct fwnode_handle *fwnode_get_next_parent(struct fwnode_handle *fwnode) 607 { 608 struct fwnode_handle *parent = fwnode_get_parent(fwnode); 609 610 fwnode_handle_put(fwnode); 611 612 return parent; 613 } 614 EXPORT_SYMBOL_GPL(fwnode_get_next_parent); 615 616 /** 617 * fwnode_get_next_parent_dev - Find device of closest ancestor fwnode 618 * @fwnode: firmware node 619 * 620 * Given a firmware node (@fwnode), this function finds its closest ancestor 621 * firmware node that has a corresponding struct device and returns that struct 622 * device. 623 * 624 * The caller of this function is expected to call put_device() on the returned 625 * device when they are done. 626 */ 627 struct device *fwnode_get_next_parent_dev(struct fwnode_handle *fwnode) 628 { 629 struct device *dev; 630 631 fwnode_handle_get(fwnode); 632 do { 633 fwnode = fwnode_get_next_parent(fwnode); 634 if (!fwnode) 635 return NULL; 636 dev = get_dev_from_fwnode(fwnode); 637 } while (!dev); 638 fwnode_handle_put(fwnode); 639 return dev; 640 } 641 642 /** 643 * fwnode_count_parents - Return the number of parents a node has 644 * @fwnode: The node the parents of which are to be counted 645 * 646 * Returns the number of parents a node has. 647 */ 648 unsigned int fwnode_count_parents(const struct fwnode_handle *fwnode) 649 { 650 struct fwnode_handle *__fwnode; 651 unsigned int count; 652 653 __fwnode = fwnode_get_parent(fwnode); 654 655 for (count = 0; __fwnode; count++) 656 __fwnode = fwnode_get_next_parent(__fwnode); 657 658 return count; 659 } 660 EXPORT_SYMBOL_GPL(fwnode_count_parents); 661 662 /** 663 * fwnode_get_nth_parent - Return an nth parent of a node 664 * @fwnode: The node the parent of which is requested 665 * @depth: Distance of the parent from the node 666 * 667 * Returns the nth parent of a node. If there is no parent at the requested 668 * @depth, %NULL is returned. If @depth is 0, the functionality is equivalent to 669 * fwnode_handle_get(). For @depth == 1, it is fwnode_get_parent() and so on. 670 * 671 * The caller is responsible for calling fwnode_handle_put() for the returned 672 * node. 673 */ 674 struct fwnode_handle *fwnode_get_nth_parent(struct fwnode_handle *fwnode, 675 unsigned int depth) 676 { 677 unsigned int i; 678 679 fwnode_handle_get(fwnode); 680 681 for (i = 0; i < depth && fwnode; i++) 682 fwnode = fwnode_get_next_parent(fwnode); 683 684 return fwnode; 685 } 686 EXPORT_SYMBOL_GPL(fwnode_get_nth_parent); 687 688 /** 689 * fwnode_is_ancestor_of - Test if @test_ancestor is ancestor of @test_child 690 * @test_ancestor: Firmware which is tested for being an ancestor 691 * @test_child: Firmware which is tested for being the child 692 * 693 * A node is considered an ancestor of itself too. 694 * 695 * Returns true if @test_ancestor is an ancestor of @test_child. 696 * Otherwise, returns false. 697 */ 698 bool fwnode_is_ancestor_of(struct fwnode_handle *test_ancestor, 699 struct fwnode_handle *test_child) 700 { 701 if (!test_ancestor) 702 return false; 703 704 fwnode_handle_get(test_child); 705 while (test_child) { 706 if (test_child == test_ancestor) { 707 fwnode_handle_put(test_child); 708 return true; 709 } 710 test_child = fwnode_get_next_parent(test_child); 711 } 712 return false; 713 } 714 715 /** 716 * fwnode_get_next_child_node - Return the next child node handle for a node 717 * @fwnode: Firmware node to find the next child node for. 718 * @child: Handle to one of the node's child nodes or a %NULL handle. 719 */ 720 struct fwnode_handle * 721 fwnode_get_next_child_node(const struct fwnode_handle *fwnode, 722 struct fwnode_handle *child) 723 { 724 return fwnode_call_ptr_op(fwnode, get_next_child_node, child); 725 } 726 EXPORT_SYMBOL_GPL(fwnode_get_next_child_node); 727 728 /** 729 * fwnode_get_next_available_child_node - Return the next 730 * available child node handle for a node 731 * @fwnode: Firmware node to find the next child node for. 732 * @child: Handle to one of the node's child nodes or a %NULL handle. 733 */ 734 struct fwnode_handle * 735 fwnode_get_next_available_child_node(const struct fwnode_handle *fwnode, 736 struct fwnode_handle *child) 737 { 738 struct fwnode_handle *next_child = child; 739 740 if (!fwnode) 741 return NULL; 742 743 do { 744 next_child = fwnode_get_next_child_node(fwnode, next_child); 745 if (!next_child) 746 return NULL; 747 } while (!fwnode_device_is_available(next_child)); 748 749 return next_child; 750 } 751 EXPORT_SYMBOL_GPL(fwnode_get_next_available_child_node); 752 753 /** 754 * device_get_next_child_node - Return the next child node handle for a device 755 * @dev: Device to find the next child node for. 756 * @child: Handle to one of the device's child nodes or a null handle. 757 */ 758 struct fwnode_handle *device_get_next_child_node(struct device *dev, 759 struct fwnode_handle *child) 760 { 761 const struct fwnode_handle *fwnode = dev_fwnode(dev); 762 struct fwnode_handle *next; 763 764 /* Try to find a child in primary fwnode */ 765 next = fwnode_get_next_child_node(fwnode, child); 766 if (next) 767 return next; 768 769 /* When no more children in primary, continue with secondary */ 770 if (fwnode && !IS_ERR_OR_NULL(fwnode->secondary)) 771 next = fwnode_get_next_child_node(fwnode->secondary, child); 772 773 return next; 774 } 775 EXPORT_SYMBOL_GPL(device_get_next_child_node); 776 777 /** 778 * fwnode_get_named_child_node - Return first matching named child node handle 779 * @fwnode: Firmware node to find the named child node for. 780 * @childname: String to match child node name against. 781 */ 782 struct fwnode_handle * 783 fwnode_get_named_child_node(const struct fwnode_handle *fwnode, 784 const char *childname) 785 { 786 return fwnode_call_ptr_op(fwnode, get_named_child_node, childname); 787 } 788 EXPORT_SYMBOL_GPL(fwnode_get_named_child_node); 789 790 /** 791 * device_get_named_child_node - Return first matching named child node handle 792 * @dev: Device to find the named child node for. 793 * @childname: String to match child node name against. 794 */ 795 struct fwnode_handle *device_get_named_child_node(struct device *dev, 796 const char *childname) 797 { 798 return fwnode_get_named_child_node(dev_fwnode(dev), childname); 799 } 800 EXPORT_SYMBOL_GPL(device_get_named_child_node); 801 802 /** 803 * fwnode_handle_get - Obtain a reference to a device node 804 * @fwnode: Pointer to the device node to obtain the reference to. 805 * 806 * Returns the fwnode handle. 807 */ 808 struct fwnode_handle *fwnode_handle_get(struct fwnode_handle *fwnode) 809 { 810 if (!fwnode_has_op(fwnode, get)) 811 return fwnode; 812 813 return fwnode_call_ptr_op(fwnode, get); 814 } 815 EXPORT_SYMBOL_GPL(fwnode_handle_get); 816 817 /** 818 * fwnode_handle_put - Drop reference to a device node 819 * @fwnode: Pointer to the device node to drop the reference to. 820 * 821 * This has to be used when terminating device_for_each_child_node() iteration 822 * with break or return to prevent stale device node references from being left 823 * behind. 824 */ 825 void fwnode_handle_put(struct fwnode_handle *fwnode) 826 { 827 fwnode_call_void_op(fwnode, put); 828 } 829 EXPORT_SYMBOL_GPL(fwnode_handle_put); 830 831 /** 832 * fwnode_device_is_available - check if a device is available for use 833 * @fwnode: Pointer to the fwnode of the device. 834 * 835 * For fwnode node types that don't implement the .device_is_available() 836 * operation, this function returns true. 837 */ 838 bool fwnode_device_is_available(const struct fwnode_handle *fwnode) 839 { 840 if (!fwnode_has_op(fwnode, device_is_available)) 841 return true; 842 843 return fwnode_call_bool_op(fwnode, device_is_available); 844 } 845 EXPORT_SYMBOL_GPL(fwnode_device_is_available); 846 847 /** 848 * device_get_child_node_count - return the number of child nodes for device 849 * @dev: Device to cound the child nodes for 850 */ 851 unsigned int device_get_child_node_count(struct device *dev) 852 { 853 struct fwnode_handle *child; 854 unsigned int count = 0; 855 856 device_for_each_child_node(dev, child) 857 count++; 858 859 return count; 860 } 861 EXPORT_SYMBOL_GPL(device_get_child_node_count); 862 863 bool device_dma_supported(struct device *dev) 864 { 865 const struct fwnode_handle *fwnode = dev_fwnode(dev); 866 867 /* For DT, this is always supported. 868 * For ACPI, this depends on CCA, which 869 * is determined by the acpi_dma_supported(). 870 */ 871 if (is_of_node(fwnode)) 872 return true; 873 874 return acpi_dma_supported(to_acpi_device_node(fwnode)); 875 } 876 EXPORT_SYMBOL_GPL(device_dma_supported); 877 878 enum dev_dma_attr device_get_dma_attr(struct device *dev) 879 { 880 const struct fwnode_handle *fwnode = dev_fwnode(dev); 881 enum dev_dma_attr attr = DEV_DMA_NOT_SUPPORTED; 882 883 if (is_of_node(fwnode)) { 884 if (of_dma_is_coherent(to_of_node(fwnode))) 885 attr = DEV_DMA_COHERENT; 886 else 887 attr = DEV_DMA_NON_COHERENT; 888 } else 889 attr = acpi_get_dma_attr(to_acpi_device_node(fwnode)); 890 891 return attr; 892 } 893 EXPORT_SYMBOL_GPL(device_get_dma_attr); 894 895 /** 896 * fwnode_get_phy_mode - Get phy mode for given firmware node 897 * @fwnode: Pointer to the given node 898 * 899 * The function gets phy interface string from property 'phy-mode' or 900 * 'phy-connection-type', and return its index in phy_modes table, or errno in 901 * error case. 902 */ 903 int fwnode_get_phy_mode(struct fwnode_handle *fwnode) 904 { 905 const char *pm; 906 int err, i; 907 908 err = fwnode_property_read_string(fwnode, "phy-mode", &pm); 909 if (err < 0) 910 err = fwnode_property_read_string(fwnode, 911 "phy-connection-type", &pm); 912 if (err < 0) 913 return err; 914 915 for (i = 0; i < PHY_INTERFACE_MODE_MAX; i++) 916 if (!strcasecmp(pm, phy_modes(i))) 917 return i; 918 919 return -ENODEV; 920 } 921 EXPORT_SYMBOL_GPL(fwnode_get_phy_mode); 922 923 /** 924 * device_get_phy_mode - Get phy mode for given device 925 * @dev: Pointer to the given device 926 * 927 * The function gets phy interface string from property 'phy-mode' or 928 * 'phy-connection-type', and return its index in phy_modes table, or errno in 929 * error case. 930 */ 931 int device_get_phy_mode(struct device *dev) 932 { 933 return fwnode_get_phy_mode(dev_fwnode(dev)); 934 } 935 EXPORT_SYMBOL_GPL(device_get_phy_mode); 936 937 /** 938 * fwnode_irq_get - Get IRQ directly from a fwnode 939 * @fwnode: Pointer to the firmware node 940 * @index: Zero-based index of the IRQ 941 * 942 * Returns Linux IRQ number on success. Other values are determined 943 * accordingly to acpi_/of_ irq_get() operation. 944 */ 945 int fwnode_irq_get(const struct fwnode_handle *fwnode, unsigned int index) 946 { 947 struct resource res; 948 int ret; 949 950 if (is_of_node(fwnode)) 951 return of_irq_get(to_of_node(fwnode), index); 952 953 ret = acpi_irq_get(ACPI_HANDLE_FWNODE(fwnode), index, &res); 954 if (ret) 955 return ret; 956 957 return res.start; 958 } 959 EXPORT_SYMBOL(fwnode_irq_get); 960 961 /** 962 * fwnode_graph_get_next_endpoint - Get next endpoint firmware node 963 * @fwnode: Pointer to the parent firmware node 964 * @prev: Previous endpoint node or %NULL to get the first 965 * 966 * Returns an endpoint firmware node pointer or %NULL if no more endpoints 967 * are available. 968 */ 969 struct fwnode_handle * 970 fwnode_graph_get_next_endpoint(const struct fwnode_handle *fwnode, 971 struct fwnode_handle *prev) 972 { 973 const struct fwnode_handle *parent; 974 struct fwnode_handle *ep; 975 976 /* 977 * If this function is in a loop and the previous iteration returned 978 * an endpoint from fwnode->secondary, then we need to use the secondary 979 * as parent rather than @fwnode. 980 */ 981 if (prev) 982 parent = fwnode_graph_get_port_parent(prev); 983 else 984 parent = fwnode; 985 986 ep = fwnode_call_ptr_op(parent, graph_get_next_endpoint, prev); 987 988 if (IS_ERR_OR_NULL(ep) && 989 !IS_ERR_OR_NULL(parent) && !IS_ERR_OR_NULL(parent->secondary)) 990 ep = fwnode_graph_get_next_endpoint(parent->secondary, NULL); 991 992 return ep; 993 } 994 EXPORT_SYMBOL_GPL(fwnode_graph_get_next_endpoint); 995 996 /** 997 * fwnode_graph_get_port_parent - Return the device fwnode of a port endpoint 998 * @endpoint: Endpoint firmware node of the port 999 * 1000 * Return: the firmware node of the device the @endpoint belongs to. 1001 */ 1002 struct fwnode_handle * 1003 fwnode_graph_get_port_parent(const struct fwnode_handle *endpoint) 1004 { 1005 struct fwnode_handle *port, *parent; 1006 1007 port = fwnode_get_parent(endpoint); 1008 parent = fwnode_call_ptr_op(port, graph_get_port_parent); 1009 1010 fwnode_handle_put(port); 1011 1012 return parent; 1013 } 1014 EXPORT_SYMBOL_GPL(fwnode_graph_get_port_parent); 1015 1016 /** 1017 * fwnode_graph_get_remote_port_parent - Return fwnode of a remote device 1018 * @fwnode: Endpoint firmware node pointing to the remote endpoint 1019 * 1020 * Extracts firmware node of a remote device the @fwnode points to. 1021 */ 1022 struct fwnode_handle * 1023 fwnode_graph_get_remote_port_parent(const struct fwnode_handle *fwnode) 1024 { 1025 struct fwnode_handle *endpoint, *parent; 1026 1027 endpoint = fwnode_graph_get_remote_endpoint(fwnode); 1028 parent = fwnode_graph_get_port_parent(endpoint); 1029 1030 fwnode_handle_put(endpoint); 1031 1032 return parent; 1033 } 1034 EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_port_parent); 1035 1036 /** 1037 * fwnode_graph_get_remote_port - Return fwnode of a remote port 1038 * @fwnode: Endpoint firmware node pointing to the remote endpoint 1039 * 1040 * Extracts firmware node of a remote port the @fwnode points to. 1041 */ 1042 struct fwnode_handle * 1043 fwnode_graph_get_remote_port(const struct fwnode_handle *fwnode) 1044 { 1045 return fwnode_get_next_parent(fwnode_graph_get_remote_endpoint(fwnode)); 1046 } 1047 EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_port); 1048 1049 /** 1050 * fwnode_graph_get_remote_endpoint - Return fwnode of a remote endpoint 1051 * @fwnode: Endpoint firmware node pointing to the remote endpoint 1052 * 1053 * Extracts firmware node of a remote endpoint the @fwnode points to. 1054 */ 1055 struct fwnode_handle * 1056 fwnode_graph_get_remote_endpoint(const struct fwnode_handle *fwnode) 1057 { 1058 return fwnode_call_ptr_op(fwnode, graph_get_remote_endpoint); 1059 } 1060 EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_endpoint); 1061 1062 /** 1063 * fwnode_graph_get_remote_node - get remote parent node for given port/endpoint 1064 * @fwnode: pointer to parent fwnode_handle containing graph port/endpoint 1065 * @port_id: identifier of the parent port node 1066 * @endpoint_id: identifier of the endpoint node 1067 * 1068 * Return: Remote fwnode handle associated with remote endpoint node linked 1069 * to @node. Use fwnode_node_put() on it when done. 1070 */ 1071 struct fwnode_handle * 1072 fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, 1073 u32 endpoint_id) 1074 { 1075 struct fwnode_handle *endpoint = NULL; 1076 1077 while ((endpoint = fwnode_graph_get_next_endpoint(fwnode, endpoint))) { 1078 struct fwnode_endpoint fwnode_ep; 1079 struct fwnode_handle *remote; 1080 int ret; 1081 1082 ret = fwnode_graph_parse_endpoint(endpoint, &fwnode_ep); 1083 if (ret < 0) 1084 continue; 1085 1086 if (fwnode_ep.port != port_id || fwnode_ep.id != endpoint_id) 1087 continue; 1088 1089 remote = fwnode_graph_get_remote_port_parent(endpoint); 1090 if (!remote) 1091 return NULL; 1092 1093 return fwnode_device_is_available(remote) ? remote : NULL; 1094 } 1095 1096 return NULL; 1097 } 1098 EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_node); 1099 1100 /** 1101 * fwnode_graph_get_endpoint_by_id - get endpoint by port and endpoint numbers 1102 * @fwnode: parent fwnode_handle containing the graph 1103 * @port: identifier of the port node 1104 * @endpoint: identifier of the endpoint node under the port node 1105 * @flags: fwnode lookup flags 1106 * 1107 * Return the fwnode handle of the local endpoint corresponding the port and 1108 * endpoint IDs or NULL if not found. 1109 * 1110 * If FWNODE_GRAPH_ENDPOINT_NEXT is passed in @flags and the specified endpoint 1111 * has not been found, look for the closest endpoint ID greater than the 1112 * specified one and return the endpoint that corresponds to it, if present. 1113 * 1114 * Do not return endpoints that belong to disabled devices, unless 1115 * FWNODE_GRAPH_DEVICE_DISABLED is passed in @flags. 1116 * 1117 * The returned endpoint needs to be released by calling fwnode_handle_put() on 1118 * it when it is not needed any more. 1119 */ 1120 struct fwnode_handle * 1121 fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode, 1122 u32 port, u32 endpoint, unsigned long flags) 1123 { 1124 struct fwnode_handle *ep = NULL, *best_ep = NULL; 1125 unsigned int best_ep_id = 0; 1126 bool endpoint_next = flags & FWNODE_GRAPH_ENDPOINT_NEXT; 1127 bool enabled_only = !(flags & FWNODE_GRAPH_DEVICE_DISABLED); 1128 1129 while ((ep = fwnode_graph_get_next_endpoint(fwnode, ep))) { 1130 struct fwnode_endpoint fwnode_ep = { 0 }; 1131 int ret; 1132 1133 if (enabled_only) { 1134 struct fwnode_handle *dev_node; 1135 bool available; 1136 1137 dev_node = fwnode_graph_get_remote_port_parent(ep); 1138 available = fwnode_device_is_available(dev_node); 1139 fwnode_handle_put(dev_node); 1140 if (!available) 1141 continue; 1142 } 1143 1144 ret = fwnode_graph_parse_endpoint(ep, &fwnode_ep); 1145 if (ret < 0) 1146 continue; 1147 1148 if (fwnode_ep.port != port) 1149 continue; 1150 1151 if (fwnode_ep.id == endpoint) 1152 return ep; 1153 1154 if (!endpoint_next) 1155 continue; 1156 1157 /* 1158 * If the endpoint that has just been found is not the first 1159 * matching one and the ID of the one found previously is closer 1160 * to the requested endpoint ID, skip it. 1161 */ 1162 if (fwnode_ep.id < endpoint || 1163 (best_ep && best_ep_id < fwnode_ep.id)) 1164 continue; 1165 1166 fwnode_handle_put(best_ep); 1167 best_ep = fwnode_handle_get(ep); 1168 best_ep_id = fwnode_ep.id; 1169 } 1170 1171 return best_ep; 1172 } 1173 EXPORT_SYMBOL_GPL(fwnode_graph_get_endpoint_by_id); 1174 1175 /** 1176 * fwnode_graph_parse_endpoint - parse common endpoint node properties 1177 * @fwnode: pointer to endpoint fwnode_handle 1178 * @endpoint: pointer to the fwnode endpoint data structure 1179 * 1180 * Parse @fwnode representing a graph endpoint node and store the 1181 * information in @endpoint. The caller must hold a reference to 1182 * @fwnode. 1183 */ 1184 int fwnode_graph_parse_endpoint(const struct fwnode_handle *fwnode, 1185 struct fwnode_endpoint *endpoint) 1186 { 1187 memset(endpoint, 0, sizeof(*endpoint)); 1188 1189 return fwnode_call_int_op(fwnode, graph_parse_endpoint, endpoint); 1190 } 1191 EXPORT_SYMBOL(fwnode_graph_parse_endpoint); 1192 1193 const void *device_get_match_data(struct device *dev) 1194 { 1195 return fwnode_call_ptr_op(dev_fwnode(dev), device_get_match_data, dev); 1196 } 1197 EXPORT_SYMBOL_GPL(device_get_match_data); 1198 1199 static void * 1200 fwnode_graph_devcon_match(struct fwnode_handle *fwnode, const char *con_id, 1201 void *data, devcon_match_fn_t match) 1202 { 1203 struct fwnode_handle *node; 1204 struct fwnode_handle *ep; 1205 void *ret; 1206 1207 fwnode_graph_for_each_endpoint(fwnode, ep) { 1208 node = fwnode_graph_get_remote_port_parent(ep); 1209 if (!fwnode_device_is_available(node)) 1210 continue; 1211 1212 ret = match(node, con_id, data); 1213 fwnode_handle_put(node); 1214 if (ret) { 1215 fwnode_handle_put(ep); 1216 return ret; 1217 } 1218 } 1219 return NULL; 1220 } 1221 1222 static void * 1223 fwnode_devcon_match(struct fwnode_handle *fwnode, const char *con_id, 1224 void *data, devcon_match_fn_t match) 1225 { 1226 struct fwnode_handle *node; 1227 void *ret; 1228 int i; 1229 1230 for (i = 0; ; i++) { 1231 node = fwnode_find_reference(fwnode, con_id, i); 1232 if (IS_ERR(node)) 1233 break; 1234 1235 ret = match(node, NULL, data); 1236 fwnode_handle_put(node); 1237 if (ret) 1238 return ret; 1239 } 1240 1241 return NULL; 1242 } 1243 1244 /** 1245 * fwnode_connection_find_match - Find connection from a device node 1246 * @fwnode: Device node with the connection 1247 * @con_id: Identifier for the connection 1248 * @data: Data for the match function 1249 * @match: Function to check and convert the connection description 1250 * 1251 * Find a connection with unique identifier @con_id between @fwnode and another 1252 * device node. @match will be used to convert the connection description to 1253 * data the caller is expecting to be returned. 1254 */ 1255 void *fwnode_connection_find_match(struct fwnode_handle *fwnode, 1256 const char *con_id, void *data, 1257 devcon_match_fn_t match) 1258 { 1259 void *ret; 1260 1261 if (!fwnode || !match) 1262 return NULL; 1263 1264 ret = fwnode_graph_devcon_match(fwnode, con_id, data, match); 1265 if (ret) 1266 return ret; 1267 1268 return fwnode_devcon_match(fwnode, con_id, data, match); 1269 } 1270 EXPORT_SYMBOL_GPL(fwnode_connection_find_match); 1271