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