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