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