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