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