1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3 * property.h - 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 #ifndef _LINUX_PROPERTY_H_
11 #define _LINUX_PROPERTY_H_
12
13 #include <linux/args.h>
14 #include <linux/array_size.h>
15 #include <linux/bits.h>
16 #include <linux/cleanup.h>
17 #include <linux/fwnode.h>
18 #include <linux/stddef.h>
19 #include <linux/types.h>
20
21 struct device;
22
23 enum dev_prop_type {
24 DEV_PROP_U8,
25 DEV_PROP_U16,
26 DEV_PROP_U32,
27 DEV_PROP_U64,
28 DEV_PROP_STRING,
29 DEV_PROP_REF,
30 };
31
32 const struct fwnode_handle *__dev_fwnode_const(const struct device *dev);
33 struct fwnode_handle *__dev_fwnode(struct device *dev);
34 #define dev_fwnode(dev) \
35 _Generic((dev), \
36 const struct device *: __dev_fwnode_const, \
37 struct device *: __dev_fwnode)(dev)
38
39 bool device_property_present(const struct device *dev, const char *propname);
40 int device_property_read_u8_array(const struct device *dev, const char *propname,
41 u8 *val, size_t nval);
42 int device_property_read_u16_array(const struct device *dev, const char *propname,
43 u16 *val, size_t nval);
44 int device_property_read_u32_array(const struct device *dev, const char *propname,
45 u32 *val, size_t nval);
46 int device_property_read_u64_array(const struct device *dev, const char *propname,
47 u64 *val, size_t nval);
48 int device_property_read_string_array(const struct device *dev, const char *propname,
49 const char **val, size_t nval);
50 int device_property_read_string(const struct device *dev, const char *propname,
51 const char **val);
52 int device_property_match_string(const struct device *dev,
53 const char *propname, const char *string);
54
55 bool fwnode_property_present(const struct fwnode_handle *fwnode,
56 const char *propname);
57 int fwnode_property_read_u8_array(const struct fwnode_handle *fwnode,
58 const char *propname, u8 *val,
59 size_t nval);
60 int fwnode_property_read_u16_array(const struct fwnode_handle *fwnode,
61 const char *propname, u16 *val,
62 size_t nval);
63 int fwnode_property_read_u32_array(const struct fwnode_handle *fwnode,
64 const char *propname, u32 *val,
65 size_t nval);
66 int fwnode_property_read_u64_array(const struct fwnode_handle *fwnode,
67 const char *propname, u64 *val,
68 size_t nval);
69 int fwnode_property_read_string_array(const struct fwnode_handle *fwnode,
70 const char *propname, const char **val,
71 size_t nval);
72 int fwnode_property_read_string(const struct fwnode_handle *fwnode,
73 const char *propname, const char **val);
74 int fwnode_property_match_string(const struct fwnode_handle *fwnode,
75 const char *propname, const char *string);
76
77 bool fwnode_device_is_available(const struct fwnode_handle *fwnode);
78
79 static inline bool fwnode_device_is_big_endian(const struct fwnode_handle *fwnode)
80 {
81 if (fwnode_property_present(fwnode, "big-endian"))
82 return true;
83 if (IS_ENABLED(CONFIG_CPU_BIG_ENDIAN) &&
84 fwnode_property_present(fwnode, "native-endian"))
85 return true;
86 return false;
87 }
88
89 static inline
90 bool fwnode_device_is_compatible(const struct fwnode_handle *fwnode, const char *compat)
91 {
92 return fwnode_property_match_string(fwnode, "compatible", compat) >= 0;
93 }
94
95 /**
96 * device_is_big_endian - check if a device has BE registers
97 * @dev: Pointer to the struct device
98 *
99 * Returns: true if the device has a "big-endian" property, or if the kernel
100 * was compiled for BE *and* the device has a "native-endian" property.
101 * Returns false otherwise.
102 *
103 * Callers would nominally use ioread32be/iowrite32be if
104 * device_is_big_endian() == true, or readl/writel otherwise.
105 */
106 static inline bool device_is_big_endian(const struct device *dev)
107 {
108 return fwnode_device_is_big_endian(dev_fwnode(dev));
109 }
110
111 /**
112 * device_is_compatible - match 'compatible' property of the device with a given string
113 * @dev: Pointer to the struct device
114 * @compat: The string to match 'compatible' property with
115 *
116 * Returns: true if matches, otherwise false.
117 */
118 static inline bool device_is_compatible(const struct device *dev, const char *compat)
119 {
120 return fwnode_device_is_compatible(dev_fwnode(dev), compat);
121 }
122
123 int fwnode_property_match_property_string(const struct fwnode_handle *fwnode,
124 const char *propname,
125 const char * const *array, size_t n);
126
127 static inline
128 int device_property_match_property_string(const struct device *dev,
129 const char *propname,
130 const char * const *array, size_t n)
131 {
132 return fwnode_property_match_property_string(dev_fwnode(dev), propname, array, n);
133 }
134
135 int fwnode_property_get_reference_args(const struct fwnode_handle *fwnode,
136 const char *prop, const char *nargs_prop,
137 unsigned int nargs, unsigned int index,
138 struct fwnode_reference_args *args);
139
140 struct fwnode_handle *fwnode_find_reference(const struct fwnode_handle *fwnode,
141 const char *name,
142 unsigned int index);
143
144 const char *fwnode_get_name(const struct fwnode_handle *fwnode);
145 const char *fwnode_get_name_prefix(const struct fwnode_handle *fwnode);
146 bool fwnode_name_eq(const struct fwnode_handle *fwnode, const char *name);
147
148 struct fwnode_handle *fwnode_get_parent(const struct fwnode_handle *fwnode);
149 struct fwnode_handle *fwnode_get_next_parent(struct fwnode_handle *fwnode);
150
151 #define fwnode_for_each_parent_node(fwnode, parent) \
152 for (parent = fwnode_get_parent(fwnode); parent; \
153 parent = fwnode_get_next_parent(parent))
154
155 unsigned int fwnode_count_parents(const struct fwnode_handle *fwn);
156 struct fwnode_handle *fwnode_get_nth_parent(struct fwnode_handle *fwn,
157 unsigned int depth);
158 struct fwnode_handle *fwnode_get_next_child_node(
159 const struct fwnode_handle *fwnode, struct fwnode_handle *child);
160 struct fwnode_handle *fwnode_get_next_available_child_node(
161 const struct fwnode_handle *fwnode, struct fwnode_handle *child);
162
163 #define fwnode_for_each_child_node(fwnode, child) \
164 for (child = fwnode_get_next_child_node(fwnode, NULL); child; \
165 child = fwnode_get_next_child_node(fwnode, child))
166
167 #define fwnode_for_each_available_child_node(fwnode, child) \
168 for (child = fwnode_get_next_available_child_node(fwnode, NULL); child;\
169 child = fwnode_get_next_available_child_node(fwnode, child))
170
171 struct fwnode_handle *device_get_next_child_node(const struct device *dev,
172 struct fwnode_handle *child);
173
174 #define device_for_each_child_node(dev, child) \
175 for (child = device_get_next_child_node(dev, NULL); child; \
176 child = device_get_next_child_node(dev, child))
177
178 #define device_for_each_child_node_scoped(dev, child) \
179 for (struct fwnode_handle *child __free(fwnode_handle) = \
180 device_get_next_child_node(dev, NULL); \
181 child; child = device_get_next_child_node(dev, child))
182
183 struct fwnode_handle *fwnode_get_named_child_node(const struct fwnode_handle *fwnode,
184 const char *childname);
185 struct fwnode_handle *device_get_named_child_node(const struct device *dev,
186 const char *childname);
187
188 struct fwnode_handle *fwnode_handle_get(struct fwnode_handle *fwnode);
189
190 /**
191 * fwnode_handle_put - Drop reference to a device node
192 * @fwnode: Pointer to the device node to drop the reference to.
193 *
194 * This has to be used when terminating device_for_each_child_node() iteration
195 * with break or return to prevent stale device node references from being left
196 * behind.
197 */
198 static inline void fwnode_handle_put(struct fwnode_handle *fwnode)
199 {
200 fwnode_call_void_op(fwnode, put);
201 }
202
203 DEFINE_FREE(fwnode_handle, struct fwnode_handle *, fwnode_handle_put(_T))
204
205 int fwnode_irq_get(const struct fwnode_handle *fwnode, unsigned int index);
206 int fwnode_irq_get_byname(const struct fwnode_handle *fwnode, const char *name);
207
208 unsigned int device_get_child_node_count(const struct device *dev);
209
210 static inline bool device_property_read_bool(const struct device *dev,
211 const char *propname)
212 {
213 return device_property_present(dev, propname);
214 }
215
216 static inline int device_property_read_u8(const struct device *dev,
217 const char *propname, u8 *val)
218 {
219 return device_property_read_u8_array(dev, propname, val, 1);
220 }
221
222 static inline int device_property_read_u16(const struct device *dev,
223 const char *propname, u16 *val)
224 {
225 return device_property_read_u16_array(dev, propname, val, 1);
226 }
227
228 static inline int device_property_read_u32(const struct device *dev,
229 const char *propname, u32 *val)
230 {
231 return device_property_read_u32_array(dev, propname, val, 1);
232 }
233
234 static inline int device_property_read_u64(const struct device *dev,
235 const char *propname, u64 *val)
236 {
237 return device_property_read_u64_array(dev, propname, val, 1);
238 }
239
240 static inline int device_property_count_u8(const struct device *dev, const char *propname)
241 {
242 return device_property_read_u8_array(dev, propname, NULL, 0);
243 }
244
245 static inline int device_property_count_u16(const struct device *dev, const char *propname)
246 {
247 return device_property_read_u16_array(dev, propname, NULL, 0);
248 }
249
250 static inline int device_property_count_u32(const struct device *dev, const char *propname)
251 {
252 return device_property_read_u32_array(dev, propname, NULL, 0);
253 }
254
255 static inline int device_property_count_u64(const struct device *dev, const char *propname)
256 {
257 return device_property_read_u64_array(dev, propname, NULL, 0);
258 }
259
260 static inline int device_property_string_array_count(const struct device *dev,
261 const char *propname)
262 {
263 return device_property_read_string_array(dev, propname, NULL, 0);
264 }
265
266 static inline bool fwnode_property_read_bool(const struct fwnode_handle *fwnode,
267 const char *propname)
268 {
269 return fwnode_property_present(fwnode, propname);
270 }
271
272 static inline int fwnode_property_read_u8(const struct fwnode_handle *fwnode,
273 const char *propname, u8 *val)
274 {
275 return fwnode_property_read_u8_array(fwnode, propname, val, 1);
276 }
277
278 static inline int fwnode_property_read_u16(const struct fwnode_handle *fwnode,
279 const char *propname, u16 *val)
280 {
281 return fwnode_property_read_u16_array(fwnode, propname, val, 1);
282 }
283
284 static inline int fwnode_property_read_u32(const struct fwnode_handle *fwnode,
285 const char *propname, u32 *val)
286 {
287 return fwnode_property_read_u32_array(fwnode, propname, val, 1);
288 }
289
290 static inline int fwnode_property_read_u64(const struct fwnode_handle *fwnode,
291 const char *propname, u64 *val)
292 {
293 return fwnode_property_read_u64_array(fwnode, propname, val, 1);
294 }
295
296 static inline int fwnode_property_count_u8(const struct fwnode_handle *fwnode,
297 const char *propname)
298 {
299 return fwnode_property_read_u8_array(fwnode, propname, NULL, 0);
300 }
301
302 static inline int fwnode_property_count_u16(const struct fwnode_handle *fwnode,
303 const char *propname)
304 {
305 return fwnode_property_read_u16_array(fwnode, propname, NULL, 0);
306 }
307
308 static inline int fwnode_property_count_u32(const struct fwnode_handle *fwnode,
309 const char *propname)
310 {
311 return fwnode_property_read_u32_array(fwnode, propname, NULL, 0);
312 }
313
314 static inline int fwnode_property_count_u64(const struct fwnode_handle *fwnode,
315 const char *propname)
316 {
317 return fwnode_property_read_u64_array(fwnode, propname, NULL, 0);
318 }
319
320 static inline int
321 fwnode_property_string_array_count(const struct fwnode_handle *fwnode,
322 const char *propname)
323 {
324 return fwnode_property_read_string_array(fwnode, propname, NULL, 0);
325 }
326
327 struct software_node;
328
329 /**
330 * struct software_node_ref_args - Reference property with additional arguments
331 * @node: Reference to a software node
332 * @nargs: Number of elements in @args array
333 * @args: Integer arguments
334 */
335 struct software_node_ref_args {
336 const struct software_node *node;
337 unsigned int nargs;
338 u64 args[NR_FWNODE_REFERENCE_ARGS];
339 };
340
341 #define SOFTWARE_NODE_REFERENCE(_ref_, ...) \
342 (const struct software_node_ref_args) { \
343 .node = _ref_, \
344 .nargs = COUNT_ARGS(__VA_ARGS__), \
345 .args = { __VA_ARGS__ }, \
346 }
347
348 /**
349 * struct property_entry - "Built-in" device property representation.
350 * @name: Name of the property.
351 * @length: Length of data making up the value.
352 * @is_inline: True when the property value is stored inline.
353 * @type: Type of the data in unions.
354 * @pointer: Pointer to the property when it is not stored inline.
355 * @value: Value of the property when it is stored inline.
356 */
357 struct property_entry {
358 const char *name;
359 size_t length;
360 bool is_inline;
361 enum dev_prop_type type;
362 union {
363 const void *pointer;
364 union {
365 u8 u8_data[sizeof(u64) / sizeof(u8)];
366 u16 u16_data[sizeof(u64) / sizeof(u16)];
367 u32 u32_data[sizeof(u64) / sizeof(u32)];
368 u64 u64_data[sizeof(u64) / sizeof(u64)];
369 const char *str[sizeof(u64) / sizeof(char *)];
370 } value;
371 };
372 };
373
374 /*
375 * Note: the below initializers for the anonymous union are carefully
376 * crafted to avoid gcc-4.4.4's problems with initialization of anon unions
377 * and structs.
378 */
379 #define __PROPERTY_ENTRY_ARRAY_LEN(_name_, _elem_, _Type_, _val_, _len_) \
380 (struct property_entry) { \
381 .name = _name_, \
382 .length = (_len_) * sizeof_field(struct property_entry, value._elem_[0]), \
383 .type = DEV_PROP_##_Type_, \
384 { .pointer = _val_ }, \
385 }
386
387 #define PROPERTY_ENTRY_U8_ARRAY_LEN(_name_, _val_, _len_) \
388 __PROPERTY_ENTRY_ARRAY_LEN(_name_, u8_data, U8, _val_, _len_)
389 #define PROPERTY_ENTRY_U16_ARRAY_LEN(_name_, _val_, _len_) \
390 __PROPERTY_ENTRY_ARRAY_LEN(_name_, u16_data, U16, _val_, _len_)
391 #define PROPERTY_ENTRY_U32_ARRAY_LEN(_name_, _val_, _len_) \
392 __PROPERTY_ENTRY_ARRAY_LEN(_name_, u32_data, U32, _val_, _len_)
393 #define PROPERTY_ENTRY_U64_ARRAY_LEN(_name_, _val_, _len_) \
394 __PROPERTY_ENTRY_ARRAY_LEN(_name_, u64_data, U64, _val_, _len_)
395 #define PROPERTY_ENTRY_STRING_ARRAY_LEN(_name_, _val_, _len_) \
396 __PROPERTY_ENTRY_ARRAY_LEN(_name_, str, STRING, _val_, _len_)
397
398 #define PROPERTY_ENTRY_REF_ARRAY_LEN(_name_, _val_, _len_) \
399 (struct property_entry) { \
400 .name = _name_, \
401 .length = (_len_) * sizeof(struct software_node_ref_args), \
402 .type = DEV_PROP_REF, \
403 { .pointer = _val_ }, \
404 }
405
406 #define PROPERTY_ENTRY_U8_ARRAY(_name_, _val_) \
407 PROPERTY_ENTRY_U8_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
408 #define PROPERTY_ENTRY_U16_ARRAY(_name_, _val_) \
409 PROPERTY_ENTRY_U16_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
410 #define PROPERTY_ENTRY_U32_ARRAY(_name_, _val_) \
411 PROPERTY_ENTRY_U32_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
412 #define PROPERTY_ENTRY_U64_ARRAY(_name_, _val_) \
413 PROPERTY_ENTRY_U64_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
414 #define PROPERTY_ENTRY_STRING_ARRAY(_name_, _val_) \
415 PROPERTY_ENTRY_STRING_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
416 #define PROPERTY_ENTRY_REF_ARRAY(_name_, _val_) \
417 PROPERTY_ENTRY_REF_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
418
419 #define __PROPERTY_ENTRY_ELEMENT(_name_, _elem_, _Type_, _val_) \
420 (struct property_entry) { \
421 .name = _name_, \
422 .length = sizeof_field(struct property_entry, value._elem_[0]), \
423 .is_inline = true, \
424 .type = DEV_PROP_##_Type_, \
425 { .value = { ._elem_[0] = _val_ } }, \
426 }
427
428 #define PROPERTY_ENTRY_U8(_name_, _val_) \
429 __PROPERTY_ENTRY_ELEMENT(_name_, u8_data, U8, _val_)
430 #define PROPERTY_ENTRY_U16(_name_, _val_) \
431 __PROPERTY_ENTRY_ELEMENT(_name_, u16_data, U16, _val_)
432 #define PROPERTY_ENTRY_U32(_name_, _val_) \
433 __PROPERTY_ENTRY_ELEMENT(_name_, u32_data, U32, _val_)
434 #define PROPERTY_ENTRY_U64(_name_, _val_) \
435 __PROPERTY_ENTRY_ELEMENT(_name_, u64_data, U64, _val_)
436 #define PROPERTY_ENTRY_STRING(_name_, _val_) \
437 __PROPERTY_ENTRY_ELEMENT(_name_, str, STRING, _val_)
438
439 #define PROPERTY_ENTRY_REF(_name_, _ref_, ...) \
440 (struct property_entry) { \
441 .name = _name_, \
442 .length = sizeof(struct software_node_ref_args), \
443 .type = DEV_PROP_REF, \
444 { .pointer = &SOFTWARE_NODE_REFERENCE(_ref_, ##__VA_ARGS__), }, \
445 }
446
447 #define PROPERTY_ENTRY_BOOL(_name_) \
448 (struct property_entry) { \
449 .name = _name_, \
450 .is_inline = true, \
451 }
452
453 struct property_entry *
454 property_entries_dup(const struct property_entry *properties);
455 void property_entries_free(const struct property_entry *properties);
456
457 bool device_dma_supported(const struct device *dev);
458 enum dev_dma_attr device_get_dma_attr(const struct device *dev);
459
460 const void *device_get_match_data(const struct device *dev);
461
462 int device_get_phy_mode(struct device *dev);
463 int fwnode_get_phy_mode(const struct fwnode_handle *fwnode);
464
465 void __iomem *fwnode_iomap(struct fwnode_handle *fwnode, int index);
466
467 struct fwnode_handle *fwnode_graph_get_next_endpoint(
468 const struct fwnode_handle *fwnode, struct fwnode_handle *prev);
469 struct fwnode_handle *
470 fwnode_graph_get_port_parent(const struct fwnode_handle *fwnode);
471 struct fwnode_handle *fwnode_graph_get_remote_port_parent(
472 const struct fwnode_handle *fwnode);
473 struct fwnode_handle *fwnode_graph_get_remote_port(
474 const struct fwnode_handle *fwnode);
475 struct fwnode_handle *fwnode_graph_get_remote_endpoint(
476 const struct fwnode_handle *fwnode);
477
478 static inline bool fwnode_graph_is_endpoint(const struct fwnode_handle *fwnode)
479 {
480 return fwnode_property_present(fwnode, "remote-endpoint");
481 }
482
483 /*
484 * Fwnode lookup flags
485 *
486 * @FWNODE_GRAPH_ENDPOINT_NEXT: In the case of no exact match, look for the
487 * closest endpoint ID greater than the specified
488 * one.
489 * @FWNODE_GRAPH_DEVICE_DISABLED: That the device to which the remote
490 * endpoint of the given endpoint belongs to,
491 * may be disabled, or that the endpoint is not
492 * connected.
493 */
494 #define FWNODE_GRAPH_ENDPOINT_NEXT BIT(0)
495 #define FWNODE_GRAPH_DEVICE_DISABLED BIT(1)
496
497 struct fwnode_handle *
498 fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode,
499 u32 port, u32 endpoint, unsigned long flags);
500 unsigned int fwnode_graph_get_endpoint_count(const struct fwnode_handle *fwnode,
501 unsigned long flags);
502
503 #define fwnode_graph_for_each_endpoint(fwnode, child) \
504 for (child = fwnode_graph_get_next_endpoint(fwnode, NULL); child; \
505 child = fwnode_graph_get_next_endpoint(fwnode, child))
506
507 int fwnode_graph_parse_endpoint(const struct fwnode_handle *fwnode,
508 struct fwnode_endpoint *endpoint);
509
510 typedef void *(*devcon_match_fn_t)(const struct fwnode_handle *fwnode, const char *id,
511 void *data);
512
513 void *fwnode_connection_find_match(const struct fwnode_handle *fwnode,
514 const char *con_id, void *data,
515 devcon_match_fn_t match);
516
517 static inline void *device_connection_find_match(const struct device *dev,
518 const char *con_id, void *data,
519 devcon_match_fn_t match)
520 {
521 return fwnode_connection_find_match(dev_fwnode(dev), con_id, data, match);
522 }
523
524 int fwnode_connection_find_matches(const struct fwnode_handle *fwnode,
525 const char *con_id, void *data,
526 devcon_match_fn_t match,
527 void **matches, unsigned int matches_len);
528
529 /* -------------------------------------------------------------------------- */
530 /* Software fwnode support - when HW description is incomplete or missing */
531
532 /**
533 * struct software_node - Software node description
534 * @name: Name of the software node
535 * @parent: Parent of the software node
536 * @properties: Array of device properties
537 */
538 struct software_node {
539 const char *name;
540 const struct software_node *parent;
541 const struct property_entry *properties;
542 };
543
544 #define SOFTWARE_NODE(_name_, _properties_, _parent_) \
545 (struct software_node) { \
546 .name = _name_, \
547 .properties = _properties_, \
548 .parent = _parent_, \
549 }
550
551 bool is_software_node(const struct fwnode_handle *fwnode);
552 const struct software_node *
553 to_software_node(const struct fwnode_handle *fwnode);
554 struct fwnode_handle *software_node_fwnode(const struct software_node *node);
555
556 const struct software_node *
557 software_node_find_by_name(const struct software_node *parent,
558 const char *name);
559
560 int software_node_register_node_group(const struct software_node **node_group);
561 void software_node_unregister_node_group(const struct software_node **node_group);
562
563 int software_node_register(const struct software_node *node);
564 void software_node_unregister(const struct software_node *node);
565
566 struct fwnode_handle *
567 fwnode_create_software_node(const struct property_entry *properties,
568 const struct fwnode_handle *parent);
569 void fwnode_remove_software_node(struct fwnode_handle *fwnode);
570
571 int device_add_software_node(struct device *dev, const struct software_node *node);
572 void device_remove_software_node(struct device *dev);
573
574 int device_create_managed_software_node(struct device *dev,
575 const struct property_entry *properties,
576 const struct software_node *parent);
577
578 #endif /* _LINUX_PROPERTY_H_ */
579
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.