include/linux/property.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  * property.h - Unified device property interface.
0004  *
0005  * Copyright (C) 2014, Intel Corporation
0006  * Authors: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
0007  *          Mika Westerberg <mika.westerberg@linux.intel.com>
0008  */
0009
0010 #ifndef _LINUX_PROPERTY_H_
0011 #define _LINUX_PROPERTY_H_
0012
0013 #include <linux/bits.h>
0014 #include <linux/fwnode.h>
0015 #include <linux/types.h>
0016
0017 struct device;
0018 struct net_device;
0019
0020 enum dev_prop_type {
0021     DEV_PROP_U8,
0022     DEV_PROP_U16,
0023     DEV_PROP_U32,
0024     DEV_PROP_U64,
0025     DEV_PROP_STRING,
0026     DEV_PROP_REF,
0027 };
0028
0029 enum dev_dma_attr {
0030     DEV_DMA_NOT_SUPPORTED,
0031     DEV_DMA_NON_COHERENT,
0032     DEV_DMA_COHERENT,
0033 };
0034
0035 struct fwnode_handle *dev_fwnode(struct device *dev);
0036
0037 bool device_property_present(struct device *dev, const char *propname);
0038 int device_property_read_u8_array(struct device *dev, const char *propname,
0039                   u8 *val, size_t nval);
0040 int device_property_read_u16_array(struct device *dev, const char *propname,
0041                    u16 *val, size_t nval);
0042 int device_property_read_u32_array(struct device *dev, const char *propname,
0043                    u32 *val, size_t nval);
0044 int device_property_read_u64_array(struct device *dev, const char *propname,
0045                    u64 *val, size_t nval);
0046 int device_property_read_string_array(struct device *dev, const char *propname,
0047                       const char **val, size_t nval);
0048 int device_property_read_string(struct device *dev, const char *propname,
0049                 const char **val);
0050 int device_property_match_string(struct device *dev,
0051                  const char *propname, const char *string);
0052
0053 bool fwnode_device_is_available(const struct fwnode_handle *fwnode);
0054 bool fwnode_property_present(const struct fwnode_handle *fwnode,
0055                  const char *propname);
0056 int fwnode_property_read_u8_array(const struct fwnode_handle *fwnode,
0057                   const char *propname, u8 *val,
0058                   size_t nval);
0059 int fwnode_property_read_u16_array(const struct fwnode_handle *fwnode,
0060                    const char *propname, u16 *val,
0061                    size_t nval);
0062 int fwnode_property_read_u32_array(const struct fwnode_handle *fwnode,
0063                    const char *propname, u32 *val,
0064                    size_t nval);
0065 int fwnode_property_read_u64_array(const struct fwnode_handle *fwnode,
0066                    const char *propname, u64 *val,
0067                    size_t nval);
0068 int fwnode_property_read_string_array(const struct fwnode_handle *fwnode,
0069                       const char *propname, const char **val,
0070                       size_t nval);
0071 int fwnode_property_read_string(const struct fwnode_handle *fwnode,
0072                 const char *propname, const char **val);
0073 int fwnode_property_match_string(const struct fwnode_handle *fwnode,
0074                  const char *propname, const char *string);
0075 int fwnode_property_get_reference_args(const struct fwnode_handle *fwnode,
0076                        const char *prop, const char *nargs_prop,
0077                        unsigned int nargs, unsigned int index,
0078                        struct fwnode_reference_args *args);
0079
0080 struct fwnode_handle *fwnode_find_reference(const struct fwnode_handle *fwnode,
0081                         const char *name,
0082                         unsigned int index);
0083
0084 const char *fwnode_get_name(const struct fwnode_handle *fwnode);
0085 const char *fwnode_get_name_prefix(const struct fwnode_handle *fwnode);
0086
0087 struct fwnode_handle *fwnode_get_parent(const struct fwnode_handle *fwnode);
0088 struct fwnode_handle *fwnode_get_next_parent(struct fwnode_handle *fwnode);
0089
0090 #define fwnode_for_each_parent_node(fwnode, parent)     \
0091     for (parent = fwnode_get_parent(fwnode); parent;    \
0092          parent = fwnode_get_next_parent(parent))
0093
0094 struct device *fwnode_get_next_parent_dev(struct fwnode_handle *fwnode);
0095 unsigned int fwnode_count_parents(const struct fwnode_handle *fwn);
0096 struct fwnode_handle *fwnode_get_nth_parent(struct fwnode_handle *fwn,
0097                         unsigned int depth);
0098 bool fwnode_is_ancestor_of(struct fwnode_handle *ancestor, struct fwnode_handle *child);
0099 struct fwnode_handle *fwnode_get_next_child_node(
0100     const struct fwnode_handle *fwnode, struct fwnode_handle *child);
0101 struct fwnode_handle *fwnode_get_next_available_child_node(
0102     const struct fwnode_handle *fwnode, struct fwnode_handle *child);
0103
0104 #define fwnode_for_each_child_node(fwnode, child)           \
0105     for (child = fwnode_get_next_child_node(fwnode, NULL); child;   \
0106          child = fwnode_get_next_child_node(fwnode, child))
0107
0108 #define fwnode_for_each_available_child_node(fwnode, child)            \
0109     for (child = fwnode_get_next_available_child_node(fwnode, NULL); child;\
0110          child = fwnode_get_next_available_child_node(fwnode, child))
0111
0112 struct fwnode_handle *device_get_next_child_node(
0113     struct device *dev, struct fwnode_handle *child);
0114
0115 #define device_for_each_child_node(dev, child)              \
0116     for (child = device_get_next_child_node(dev, NULL); child;  \
0117          child = device_get_next_child_node(dev, child))
0118
0119 struct fwnode_handle *fwnode_get_named_child_node(
0120     const struct fwnode_handle *fwnode, const char *childname);
0121 struct fwnode_handle *device_get_named_child_node(struct device *dev,
0122                           const char *childname);
0123
0124 struct fwnode_handle *fwnode_handle_get(struct fwnode_handle *fwnode);
0125 void fwnode_handle_put(struct fwnode_handle *fwnode);
0126
0127 int fwnode_irq_get(const struct fwnode_handle *fwnode, unsigned int index);
0128 int fwnode_irq_get_byname(const struct fwnode_handle *fwnode, const char *name);
0129
0130 unsigned int device_get_child_node_count(struct device *dev);
0131
0132 static inline bool device_property_read_bool(struct device *dev,
0133                          const char *propname)
0134 {
0135     return device_property_present(dev, propname);
0136 }
0137
0138 static inline int device_property_read_u8(struct device *dev,
0139                       const char *propname, u8 *val)
0140 {
0141     return device_property_read_u8_array(dev, propname, val, 1);
0142 }
0143
0144 static inline int device_property_read_u16(struct device *dev,
0145                        const char *propname, u16 *val)
0146 {
0147     return device_property_read_u16_array(dev, propname, val, 1);
0148 }
0149
0150 static inline int device_property_read_u32(struct device *dev,
0151                        const char *propname, u32 *val)
0152 {
0153     return device_property_read_u32_array(dev, propname, val, 1);
0154 }
0155
0156 static inline int device_property_read_u64(struct device *dev,
0157                        const char *propname, u64 *val)
0158 {
0159     return device_property_read_u64_array(dev, propname, val, 1);
0160 }
0161
0162 static inline int device_property_count_u8(struct device *dev, const char *propname)
0163 {
0164     return device_property_read_u8_array(dev, propname, NULL, 0);
0165 }
0166
0167 static inline int device_property_count_u16(struct device *dev, const char *propname)
0168 {
0169     return device_property_read_u16_array(dev, propname, NULL, 0);
0170 }
0171
0172 static inline int device_property_count_u32(struct device *dev, const char *propname)
0173 {
0174     return device_property_read_u32_array(dev, propname, NULL, 0);
0175 }
0176
0177 static inline int device_property_count_u64(struct device *dev, const char *propname)
0178 {
0179     return device_property_read_u64_array(dev, propname, NULL, 0);
0180 }
0181
0182 static inline int device_property_string_array_count(struct device *dev,
0183                              const char *propname)
0184 {
0185     return device_property_read_string_array(dev, propname, NULL, 0);
0186 }
0187
0188 static inline bool fwnode_property_read_bool(const struct fwnode_handle *fwnode,
0189                          const char *propname)
0190 {
0191     return fwnode_property_present(fwnode, propname);
0192 }
0193
0194 static inline int fwnode_property_read_u8(const struct fwnode_handle *fwnode,
0195                       const char *propname, u8 *val)
0196 {
0197     return fwnode_property_read_u8_array(fwnode, propname, val, 1);
0198 }
0199
0200 static inline int fwnode_property_read_u16(const struct fwnode_handle *fwnode,
0201                        const char *propname, u16 *val)
0202 {
0203     return fwnode_property_read_u16_array(fwnode, propname, val, 1);
0204 }
0205
0206 static inline int fwnode_property_read_u32(const struct fwnode_handle *fwnode,
0207                        const char *propname, u32 *val)
0208 {
0209     return fwnode_property_read_u32_array(fwnode, propname, val, 1);
0210 }
0211
0212 static inline int fwnode_property_read_u64(const struct fwnode_handle *fwnode,
0213                        const char *propname, u64 *val)
0214 {
0215     return fwnode_property_read_u64_array(fwnode, propname, val, 1);
0216 }
0217
0218 static inline int fwnode_property_count_u8(const struct fwnode_handle *fwnode,
0219                        const char *propname)
0220 {
0221     return fwnode_property_read_u8_array(fwnode, propname, NULL, 0);
0222 }
0223
0224 static inline int fwnode_property_count_u16(const struct fwnode_handle *fwnode,
0225                         const char *propname)
0226 {
0227     return fwnode_property_read_u16_array(fwnode, propname, NULL, 0);
0228 }
0229
0230 static inline int fwnode_property_count_u32(const struct fwnode_handle *fwnode,
0231                         const char *propname)
0232 {
0233     return fwnode_property_read_u32_array(fwnode, propname, NULL, 0);
0234 }
0235
0236 static inline int fwnode_property_count_u64(const struct fwnode_handle *fwnode,
0237                         const char *propname)
0238 {
0239     return fwnode_property_read_u64_array(fwnode, propname, NULL, 0);
0240 }
0241
0242 static inline int
0243 fwnode_property_string_array_count(const struct fwnode_handle *fwnode,
0244                    const char *propname)
0245 {
0246     return fwnode_property_read_string_array(fwnode, propname, NULL, 0);
0247 }
0248
0249 struct software_node;
0250
0251 /**
0252  * struct software_node_ref_args - Reference property with additional arguments
0253  * @node: Reference to a software node
0254  * @nargs: Number of elements in @args array
0255  * @args: Integer arguments
0256  */
0257 struct software_node_ref_args {
0258     const struct software_node *node;
0259     unsigned int nargs;
0260     u64 args[NR_FWNODE_REFERENCE_ARGS];
0261 };
0262
0263 #define SOFTWARE_NODE_REFERENCE(_ref_, ...)         \
0264 (const struct software_node_ref_args) {             \
0265     .node = _ref_,                      \
0266     .nargs = ARRAY_SIZE(((u64[]){ 0, ##__VA_ARGS__ })) - 1, \
0267     .args = { __VA_ARGS__ },                \
0268 }
0269
0270 /**
0271  * struct property_entry - "Built-in" device property representation.
0272  * @name: Name of the property.
0273  * @length: Length of data making up the value.
0274  * @is_inline: True when the property value is stored inline.
0275  * @type: Type of the data in unions.
0276  * @pointer: Pointer to the property when it is not stored inline.
0277  * @value: Value of the property when it is stored inline.
0278  */
0279 struct property_entry {
0280     const char *name;
0281     size_t length;
0282     bool is_inline;
0283     enum dev_prop_type type;
0284     union {
0285         const void *pointer;
0286         union {
0287             u8 u8_data[sizeof(u64) / sizeof(u8)];
0288             u16 u16_data[sizeof(u64) / sizeof(u16)];
0289             u32 u32_data[sizeof(u64) / sizeof(u32)];
0290             u64 u64_data[sizeof(u64) / sizeof(u64)];
0291             const char *str[sizeof(u64) / sizeof(char *)];
0292         } value;
0293     };
0294 };
0295
0296 /*
0297  * Note: the below initializers for the anonymous union are carefully
0298  * crafted to avoid gcc-4.4.4's problems with initialization of anon unions
0299  * and structs.
0300  */
0301
0302 #define __PROPERTY_ENTRY_ELEMENT_SIZE(_elem_)               \
0303     sizeof(((struct property_entry *)NULL)->value._elem_[0])
0304
0305 #define __PROPERTY_ENTRY_ARRAY_ELSIZE_LEN(_name_, _elsize_, _Type_, \
0306                       _val_, _len_)         \
0307 (struct property_entry) {                       \
0308     .name = _name_,                         \
0309     .length = (_len_) * (_elsize_),                 \
0310     .type = DEV_PROP_##_Type_,                  \
0311     { .pointer = _val_ },                       \
0312 }
0313
0314 #define __PROPERTY_ENTRY_ARRAY_LEN(_name_, _elem_, _Type_, _val_, _len_)\
0315     __PROPERTY_ENTRY_ARRAY_ELSIZE_LEN(_name_,           \
0316                 __PROPERTY_ENTRY_ELEMENT_SIZE(_elem_),  \
0317                 _Type_, _val_, _len_)
0318
0319 #define PROPERTY_ENTRY_U8_ARRAY_LEN(_name_, _val_, _len_)       \
0320     __PROPERTY_ENTRY_ARRAY_LEN(_name_, u8_data, U8, _val_, _len_)
0321 #define PROPERTY_ENTRY_U16_ARRAY_LEN(_name_, _val_, _len_)      \
0322     __PROPERTY_ENTRY_ARRAY_LEN(_name_, u16_data, U16, _val_, _len_)
0323 #define PROPERTY_ENTRY_U32_ARRAY_LEN(_name_, _val_, _len_)      \
0324     __PROPERTY_ENTRY_ARRAY_LEN(_name_, u32_data, U32, _val_, _len_)
0325 #define PROPERTY_ENTRY_U64_ARRAY_LEN(_name_, _val_, _len_)      \
0326     __PROPERTY_ENTRY_ARRAY_LEN(_name_, u64_data, U64, _val_, _len_)
0327 #define PROPERTY_ENTRY_STRING_ARRAY_LEN(_name_, _val_, _len_)       \
0328     __PROPERTY_ENTRY_ARRAY_LEN(_name_, str, STRING, _val_, _len_)
0329 #define PROPERTY_ENTRY_REF_ARRAY_LEN(_name_, _val_, _len_)      \
0330     __PROPERTY_ENTRY_ARRAY_ELSIZE_LEN(_name_,           \
0331                 sizeof(struct software_node_ref_args),  \
0332                 REF, _val_, _len_)
0333
0334 #define PROPERTY_ENTRY_U8_ARRAY(_name_, _val_)              \
0335     PROPERTY_ENTRY_U8_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
0336 #define PROPERTY_ENTRY_U16_ARRAY(_name_, _val_)             \
0337     PROPERTY_ENTRY_U16_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
0338 #define PROPERTY_ENTRY_U32_ARRAY(_name_, _val_)             \
0339     PROPERTY_ENTRY_U32_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
0340 #define PROPERTY_ENTRY_U64_ARRAY(_name_, _val_)             \
0341     PROPERTY_ENTRY_U64_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
0342 #define PROPERTY_ENTRY_STRING_ARRAY(_name_, _val_)          \
0343     PROPERTY_ENTRY_STRING_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
0344 #define PROPERTY_ENTRY_REF_ARRAY(_name_, _val_)         \
0345     PROPERTY_ENTRY_REF_ARRAY_LEN(_name_, _val_, ARRAY_SIZE(_val_))
0346
0347 #define __PROPERTY_ENTRY_ELEMENT(_name_, _elem_, _Type_, _val_)     \
0348 (struct property_entry) {                       \
0349     .name = _name_,                         \
0350     .length = __PROPERTY_ENTRY_ELEMENT_SIZE(_elem_),        \
0351     .is_inline = true,                      \
0352     .type = DEV_PROP_##_Type_,                  \
0353     { .value = { ._elem_[0] = _val_ } },                \
0354 }
0355
0356 #define PROPERTY_ENTRY_U8(_name_, _val_)                \
0357     __PROPERTY_ENTRY_ELEMENT(_name_, u8_data, U8, _val_)
0358 #define PROPERTY_ENTRY_U16(_name_, _val_)               \
0359     __PROPERTY_ENTRY_ELEMENT(_name_, u16_data, U16, _val_)
0360 #define PROPERTY_ENTRY_U32(_name_, _val_)               \
0361     __PROPERTY_ENTRY_ELEMENT(_name_, u32_data, U32, _val_)
0362 #define PROPERTY_ENTRY_U64(_name_, _val_)               \
0363     __PROPERTY_ENTRY_ELEMENT(_name_, u64_data, U64, _val_)
0364 #define PROPERTY_ENTRY_STRING(_name_, _val_)                \
0365     __PROPERTY_ENTRY_ELEMENT(_name_, str, STRING, _val_)
0366
0367 #define PROPERTY_ENTRY_BOOL(_name_)     \
0368 (struct property_entry) {           \
0369     .name = _name_,             \
0370     .is_inline = true,          \
0371 }
0372
0373 #define PROPERTY_ENTRY_REF(_name_, _ref_, ...)              \
0374 (struct property_entry) {                       \
0375     .name = _name_,                         \
0376     .length = sizeof(struct software_node_ref_args),        \
0377     .type = DEV_PROP_REF,                       \
0378     { .pointer = &SOFTWARE_NODE_REFERENCE(_ref_, ##__VA_ARGS__), }, \
0379 }
0380
0381 struct property_entry *
0382 property_entries_dup(const struct property_entry *properties);
0383
0384 void property_entries_free(const struct property_entry *properties);
0385
0386 bool device_dma_supported(struct device *dev);
0387
0388 enum dev_dma_attr device_get_dma_attr(struct device *dev);
0389
0390 const void *device_get_match_data(struct device *dev);
0391
0392 int device_get_phy_mode(struct device *dev);
0393 int fwnode_get_phy_mode(struct fwnode_handle *fwnode);
0394
0395 void __iomem *fwnode_iomap(struct fwnode_handle *fwnode, int index);
0396
0397 struct fwnode_handle *fwnode_graph_get_next_endpoint(
0398     const struct fwnode_handle *fwnode, struct fwnode_handle *prev);
0399 struct fwnode_handle *
0400 fwnode_graph_get_port_parent(const struct fwnode_handle *fwnode);
0401 struct fwnode_handle *fwnode_graph_get_remote_port_parent(
0402     const struct fwnode_handle *fwnode);
0403 struct fwnode_handle *fwnode_graph_get_remote_port(
0404     const struct fwnode_handle *fwnode);
0405 struct fwnode_handle *fwnode_graph_get_remote_endpoint(
0406     const struct fwnode_handle *fwnode);
0407
0408 static inline bool fwnode_graph_is_endpoint(struct fwnode_handle *fwnode)
0409 {
0410     return fwnode_property_present(fwnode, "remote-endpoint");
0411 }
0412
0413 /*
0414  * Fwnode lookup flags
0415  *
0416  * @FWNODE_GRAPH_ENDPOINT_NEXT: In the case of no exact match, look for the
0417  *              closest endpoint ID greater than the specified
0418  *              one.
0419  * @FWNODE_GRAPH_DEVICE_DISABLED: That the device to which the remote
0420  *                endpoint of the given endpoint belongs to,
0421  *                may be disabled, or that the endpoint is not
0422  *                connected.
0423  */
0424 #define FWNODE_GRAPH_ENDPOINT_NEXT  BIT(0)
0425 #define FWNODE_GRAPH_DEVICE_DISABLED    BIT(1)
0426
0427 struct fwnode_handle *
0428 fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode,
0429                 u32 port, u32 endpoint, unsigned long flags);
0430 unsigned int fwnode_graph_get_endpoint_count(struct fwnode_handle *fwnode,
0431                          unsigned long flags);
0432
0433 #define fwnode_graph_for_each_endpoint(fwnode, child)           \
0434     for (child = NULL;                      \
0435          (child = fwnode_graph_get_next_endpoint(fwnode, child)); )
0436
0437 int fwnode_graph_parse_endpoint(const struct fwnode_handle *fwnode,
0438                 struct fwnode_endpoint *endpoint);
0439
0440 typedef void *(*devcon_match_fn_t)(struct fwnode_handle *fwnode, const char *id,
0441                    void *data);
0442
0443 void *fwnode_connection_find_match(struct fwnode_handle *fwnode,
0444                    const char *con_id, void *data,
0445                    devcon_match_fn_t match);
0446
0447 static inline void *device_connection_find_match(struct device *dev,
0448                          const char *con_id, void *data,
0449                          devcon_match_fn_t match)
0450 {
0451     return fwnode_connection_find_match(dev_fwnode(dev), con_id, data, match);
0452 }
0453
0454 int fwnode_connection_find_matches(struct fwnode_handle *fwnode,
0455                    const char *con_id, void *data,
0456                    devcon_match_fn_t match,
0457                    void **matches, unsigned int matches_len);
0458
0459 /* -------------------------------------------------------------------------- */
0460 /* Software fwnode support - when HW description is incomplete or missing */
0461
0462 /**
0463  * struct software_node - Software node description
0464  * @name: Name of the software node
0465  * @parent: Parent of the software node
0466  * @properties: Array of device properties
0467  */
0468 struct software_node {
0469     const char *name;
0470     const struct software_node *parent;
0471     const struct property_entry *properties;
0472 };
0473
0474 bool is_software_node(const struct fwnode_handle *fwnode);
0475 const struct software_node *
0476 to_software_node(const struct fwnode_handle *fwnode);
0477 struct fwnode_handle *software_node_fwnode(const struct software_node *node);
0478
0479 const struct software_node *
0480 software_node_find_by_name(const struct software_node *parent,
0481                const char *name);
0482
0483 int software_node_register_nodes(const struct software_node *nodes);
0484 void software_node_unregister_nodes(const struct software_node *nodes);
0485
0486 int software_node_register_node_group(const struct software_node **node_group);
0487 void software_node_unregister_node_group(const struct software_node **node_group);
0488
0489 int software_node_register(const struct software_node *node);
0490 void software_node_unregister(const struct software_node *node);
0491
0492 struct fwnode_handle *
0493 fwnode_create_software_node(const struct property_entry *properties,
0494                 const struct fwnode_handle *parent);
0495 void fwnode_remove_software_node(struct fwnode_handle *fwnode);
0496
0497 int device_add_software_node(struct device *dev, const struct software_node *node);
0498 void device_remove_software_node(struct device *dev);
0499
0500 int device_create_managed_software_node(struct device *dev,
0501                     const struct property_entry *properties,
0502                     const struct software_node *parent);
0503
0504 #endif /* _LINUX_PROPERTY_H_ */