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