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