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