Merge tag 'for-linus' of git://github.com/openrisc/linux
[linux-2.6-microblaze.git] / include / linux / property.h
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 static inline bool device_property_read_bool(struct device *dev,
127                                              const char *propname)
128 {
129         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 static inline int device_property_read_u32(struct device *dev,
145                                            const char *propname, u32 *val)
146 {
147         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 #endif /* _LINUX_PROPERTY_H_ */