1 /* 2 * Function to read values from the device tree node attached to a udevice. 3 * 4 * Copyright (c) 2017 Google, Inc 5 * Written by Simon Glass <sjg@chromium.org> 6 * 7 * SPDX-License-Identifier: GPL-2.0+ 8 */ 9 10 #ifndef _DM_READ_H 11 #define _DM_READ_H 12 13 #include <dm/fdtaddr.h> 14 #include <dm/ofnode.h> 15 #include <dm/uclass.h> 16 17 struct resource; 18 19 #if CONFIG_IS_ENABLED(OF_LIVE) 20 static inline const struct device_node *dev_np(struct udevice *dev) 21 { 22 return ofnode_to_np(dev->node); 23 } 24 #else 25 static inline const struct device_node *dev_np(struct udevice *dev) 26 { 27 return NULL; 28 } 29 #endif 30 31 /** 32 * dev_ofnode() - get the DT node reference associated with a udevice 33 * 34 * @dev: device to check 35 * @return reference of the the device's DT node 36 */ 37 static inline ofnode dev_ofnode(struct udevice *dev) 38 { 39 return dev->node; 40 } 41 42 static inline bool dev_of_valid(struct udevice *dev) 43 { 44 return ofnode_valid(dev_ofnode(dev)); 45 } 46 47 /** 48 * dev_read_resource() - obtain an indexed resource from a device. 49 * 50 * @dev: devuce to examine 51 * @index index of the resource to retrieve (0 = first) 52 * @res returns the resource 53 * @return 0 if ok, negative on error 54 */ 55 int dev_read_resource(struct udevice *dev, uint index, struct resource *res); 56 57 #ifndef CONFIG_DM_DEV_READ_INLINE 58 /** 59 * dev_read_u32_default() - read a 32-bit integer from a device's DT property 60 * 61 * @dev: device to read DT property from 62 * @propname: name of the property to read from 63 * @def: default value to return if the property has no value 64 * @return property value, or @def if not found 65 */ 66 int dev_read_u32_default(struct udevice *dev, const char *propname, int def); 67 68 /** 69 * dev_read_string() - Read a string from a device's DT property 70 * 71 * @dev: device to read DT property from 72 * @propname: name of the property to read 73 * @return string from property value, or NULL if there is no such property 74 */ 75 const char *dev_read_string(struct udevice *dev, const char *propname); 76 77 /** 78 * dev_read_bool() - read a boolean value from a device's DT property 79 * 80 * @dev: device to read DT property from 81 * @propname: name of property to read 82 * @return true if property is present (meaning true), false if not present 83 */ 84 bool dev_read_bool(struct udevice *dev, const char *propname); 85 86 /** 87 * dev_read_subnode() - find a named subnode of a device 88 * 89 * @dev: device whose DT node contains the subnode 90 * @subnode_name: name of subnode to find 91 * @return reference to subnode (which can be invalid if there is no such 92 * subnode) 93 */ 94 ofnode dev_read_subnode(struct udevice *dev, const char *subbnode_name); 95 96 /** 97 * dev_read_size() - read the size of a property 98 * 99 * @dev: device to check 100 * @propname: property to check 101 * @return size of property if present, or -EINVAL if not 102 */ 103 int dev_read_size(struct udevice *dev, const char *propname); 104 105 /** 106 * dev_read_addr_index() - Get the indexed reg property of a device 107 * 108 * @dev: Device to read from 109 * @index: the 'reg' property can hold a list of <addr, size> pairs 110 * and @index is used to select which one is required 111 * 112 * @return address or FDT_ADDR_T_NONE if not found 113 */ 114 fdt_addr_t dev_read_addr_index(struct udevice *dev, int index); 115 116 /** 117 * dev_read_addr() - Get the reg property of a device 118 * 119 * @dev: Device to read from 120 * 121 * @return address or FDT_ADDR_T_NONE if not found 122 */ 123 fdt_addr_t dev_read_addr(struct udevice *dev); 124 125 /** 126 * dev_read_addr_size() - get address and size from a device property 127 * 128 * This does no address translation. It simply reads an property that contains 129 * an address and a size value, one after the other. 130 * 131 * @dev: Device to read from 132 * @propname: property to read 133 * @sizep: place to put size value (on success) 134 * @return address value, or FDT_ADDR_T_NONE on error 135 */ 136 fdt_addr_t dev_read_addr_size(struct udevice *dev, const char *propname, 137 fdt_size_t *sizep); 138 139 /** 140 * dev_read_name() - get the name of a device's node 141 * 142 * @node: valid node to look up 143 * @return name of node 144 */ 145 const char *dev_read_name(struct udevice *dev); 146 147 /** 148 * dev_read_stringlist_search() - find string in a string list and return index 149 * 150 * Note that it is possible for this function to succeed on property values 151 * that are not NUL-terminated. That's because the function will stop after 152 * finding the first occurrence of @string. This can for example happen with 153 * small-valued cell properties, such as #address-cells, when searching for 154 * the empty string. 155 * 156 * @dev: device to check 157 * @propname: name of the property containing the string list 158 * @string: string to look up in the string list 159 * 160 * @return: 161 * the index of the string in the list of strings 162 * -ENODATA if the property is not found 163 * -EINVAL on some other error 164 */ 165 int dev_read_stringlist_search(struct udevice *dev, const char *property, 166 const char *string); 167 168 /** 169 * dev_read_phandle_with_args() - Find a node pointed by phandle in a list 170 * 171 * This function is useful to parse lists of phandles and their arguments. 172 * Returns 0 on success and fills out_args, on error returns appropriate 173 * errno value. 174 * 175 * Caller is responsible to call of_node_put() on the returned out_args->np 176 * pointer. 177 * 178 * Example: 179 * 180 * phandle1: node1 { 181 * #list-cells = <2>; 182 * } 183 * 184 * phandle2: node2 { 185 * #list-cells = <1>; 186 * } 187 * 188 * node3 { 189 * list = <&phandle1 1 2 &phandle2 3>; 190 * } 191 * 192 * To get a device_node of the `node2' node you may call this: 193 * dev_read_phandle_with_args(dev, "list", "#list-cells", 0, 1, &args); 194 * 195 * @dev: device whose node containing a list 196 * @list_name: property name that contains a list 197 * @cells_name: property name that specifies phandles' arguments count 198 * @cells_count: Cell count to use if @cells_name is NULL 199 * @index: index of a phandle to parse out 200 * @out_args: optional pointer to output arguments structure (will be filled) 201 * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if 202 * @list_name does not exist, -EINVAL if a phandle was not found, 203 * @cells_name could not be found, the arguments were truncated or there 204 * were too many arguments. 205 */ 206 int dev_read_phandle_with_args(struct udevice *dev, const char *list_name, 207 const char *cells_name, int cell_count, 208 int index, 209 struct ofnode_phandle_args *out_args); 210 211 /** 212 * dev_count_phandle_with_args() - Return phandle number in a list 213 * 214 * This function is usefull to get phandle number contained in a property list. 215 * For example, this allows to allocate the right amount of memory to keep 216 * clock's reference contained into the "clocks" property. 217 * 218 * 219 * @dev: device whose node containing a list 220 * @list_name: property name that contains a list 221 * @cells_name: property name that specifies phandles' arguments count 222 * @Returns number of phandle found on success, on error returns appropriate 223 * errno value. 224 */ 225 226 int dev_count_phandle_with_args(struct udevice *dev, const char *list_name, 227 const char *cells_name); 228 229 /** 230 * dev_read_addr_cells() - Get the number of address cells for a device's node 231 * 232 * This walks back up the tree to find the closest #address-cells property 233 * which controls the given node. 234 * 235 * @dev: devioe to check 236 * @return number of address cells this node uses 237 */ 238 int dev_read_addr_cells(struct udevice *dev); 239 240 /** 241 * dev_read_size_cells() - Get the number of size cells for a device's node 242 * 243 * This walks back up the tree to find the closest #size-cells property 244 * which controls the given node. 245 * 246 * @dev: devioe to check 247 * @return number of size cells this node uses 248 */ 249 int dev_read_size_cells(struct udevice *dev); 250 251 /** 252 * dev_read_addr_cells() - Get the address cells property in a node 253 * 254 * This function matches fdt_address_cells(). 255 * 256 * @dev: devioe to check 257 * @return number of address cells this node uses 258 */ 259 int dev_read_simple_addr_cells(struct udevice *dev); 260 261 /** 262 * dev_read_size_cells() - Get the size cells property in a node 263 * 264 * This function matches fdt_size_cells(). 265 * 266 * @dev: devioe to check 267 * @return number of size cells this node uses 268 */ 269 int dev_read_simple_size_cells(struct udevice *dev); 270 271 /** 272 * dev_read_phandle() - Get the phandle from a device 273 * 274 * @dev: device to check 275 * @return phandle (1 or greater), or 0 if no phandle or other error 276 */ 277 int dev_read_phandle(struct udevice *dev); 278 279 /** 280 * dev_read_prop()- - read a property from a device's node 281 * 282 * @dev: device to check 283 * @propname: property to read 284 * @lenp: place to put length on success 285 * @return pointer to property, or NULL if not found 286 */ 287 const u32 *dev_read_prop(struct udevice *dev, const char *propname, int *lenp); 288 289 /** 290 * dev_read_alias_seq() - Get the alias sequence number of a node 291 * 292 * This works out whether a node is pointed to by an alias, and if so, the 293 * sequence number of that alias. Aliases are of the form <base><num> where 294 * <num> is the sequence number. For example spi2 would be sequence number 2. 295 * 296 * @dev: device to look up 297 * @devnump: set to the sequence number if one is found 298 * @return 0 if a sequence was found, -ve if not 299 */ 300 int dev_read_alias_seq(struct udevice *dev, int *devnump); 301 302 /** 303 * dev_read_u32_array() - Find and read an array of 32 bit integers 304 * 305 * Search for a property in a device node and read 32-bit value(s) from 306 * it. 307 * 308 * The out_values is modified only if a valid u32 value can be decoded. 309 * 310 * @dev: device to look up 311 * @propname: name of the property to read 312 * @out_values: pointer to return value, modified only if return value is 0 313 * @sz: number of array elements to read 314 * @return 0 on success, -EINVAL if the property does not exist, -ENODATA if 315 * property does not have a value, and -EOVERFLOW if the property data isn't 316 * large enough. 317 */ 318 int dev_read_u32_array(struct udevice *dev, const char *propname, 319 u32 *out_values, size_t sz); 320 321 /** 322 * dev_read_first_subnode() - find the first subnode of a device's node 323 * 324 * @dev: device to look up 325 * @return reference to the first subnode (which can be invalid if the device's 326 * node has no subnodes) 327 */ 328 ofnode dev_read_first_subnode(struct udevice *dev); 329 330 /** 331 * ofnode_next_subnode() - find the next sibling of a subnode 332 * 333 * @node: valid reference to previous node (sibling) 334 * @return reference to the next subnode (which can be invalid if the node 335 * has no more siblings) 336 */ 337 ofnode dev_read_next_subnode(ofnode node); 338 339 /** 340 * dev_read_u8_array_ptr() - find an 8-bit array 341 * 342 * Look up a device's node property and return a pointer to its contents as a 343 * byte array of given length. The property must have at least enough data 344 * for the array (count bytes). It may have more, but this will be ignored. 345 * The data is not copied. 346 * 347 * @dev: device to look up 348 * @propname: name of property to find 349 * @sz: number of array elements 350 * @return pointer to byte array if found, or NULL if the property is not 351 * found or there is not enough data 352 */ 353 const uint8_t *dev_read_u8_array_ptr(struct udevice *dev, const char *propname, 354 size_t sz); 355 356 /** 357 * dev_read_enabled() - check whether a node is enabled 358 * 359 * This looks for a 'status' property. If this exists, then returns 1 if 360 * the status is 'ok' and 0 otherwise. If there is no status property, 361 * it returns 1 on the assumption that anything mentioned should be enabled 362 * by default. 363 * 364 * @dev: device to examine 365 * @return integer value 0 (not enabled) or 1 (enabled) 366 */ 367 int dev_read_enabled(struct udevice *dev); 368 369 #else /* CONFIG_DM_DEV_READ_INLINE is enabled */ 370 371 static inline int dev_read_u32_default(struct udevice *dev, 372 const char *propname, int def) 373 { 374 return ofnode_read_u32_default(dev_ofnode(dev), propname, def); 375 } 376 377 static inline const char *dev_read_string(struct udevice *dev, 378 const char *propname) 379 { 380 return ofnode_read_string(dev_ofnode(dev), propname); 381 } 382 383 static inline bool dev_read_bool(struct udevice *dev, const char *propname) 384 { 385 return ofnode_read_bool(dev_ofnode(dev), propname); 386 } 387 388 static inline ofnode dev_read_subnode(struct udevice *dev, 389 const char *subbnode_name) 390 { 391 return ofnode_find_subnode(dev_ofnode(dev), subbnode_name); 392 } 393 394 static inline int dev_read_size(struct udevice *dev, const char *propname) 395 { 396 return ofnode_read_size(dev_ofnode(dev), propname); 397 } 398 399 static inline fdt_addr_t dev_read_addr_index(struct udevice *dev, int index) 400 { 401 return devfdt_get_addr_index(dev, index); 402 } 403 404 static inline fdt_addr_t dev_read_addr(struct udevice *dev) 405 { 406 return devfdt_get_addr(dev); 407 } 408 409 static inline fdt_addr_t dev_read_addr_size(struct udevice *dev, 410 const char *propname, 411 fdt_size_t *sizep) 412 { 413 return ofnode_get_addr_size(dev_ofnode(dev), propname, sizep); 414 } 415 416 static inline const char *dev_read_name(struct udevice *dev) 417 { 418 return ofnode_get_name(dev_ofnode(dev)); 419 } 420 421 static inline int dev_read_stringlist_search(struct udevice *dev, 422 const char *propname, 423 const char *string) 424 { 425 return ofnode_stringlist_search(dev_ofnode(dev), propname, string); 426 } 427 428 static inline int dev_read_phandle_with_args(struct udevice *dev, 429 const char *list_name, const char *cells_name, int cell_count, 430 int index, struct ofnode_phandle_args *out_args) 431 { 432 return ofnode_parse_phandle_with_args(dev_ofnode(dev), list_name, 433 cells_name, cell_count, index, 434 out_args); 435 } 436 437 static inline int dev_count_phandle_with_args(struct udevice *dev, 438 const char *list_name, const char *cells_name) 439 { 440 return ofnode_count_phandle_with_args(dev_ofnode(dev), list_name, 441 cells_name); 442 } 443 444 static inline int dev_read_addr_cells(struct udevice *dev) 445 { 446 /* NOTE: this call should walk up the parent stack */ 447 return fdt_address_cells(gd->fdt_blob, dev_of_offset(dev)); 448 } 449 450 static inline int dev_read_size_cells(struct udevice *dev) 451 { 452 /* NOTE: this call should walk up the parent stack */ 453 return fdt_size_cells(gd->fdt_blob, dev_of_offset(dev)); 454 } 455 456 static inline int dev_read_simple_addr_cells(struct udevice *dev) 457 { 458 return fdt_address_cells(gd->fdt_blob, dev_of_offset(dev)); 459 } 460 461 static inline int dev_read_simple_size_cells(struct udevice *dev) 462 { 463 return fdt_size_cells(gd->fdt_blob, dev_of_offset(dev)); 464 } 465 466 static inline int dev_read_phandle(struct udevice *dev) 467 { 468 return fdt_get_phandle(gd->fdt_blob, dev_of_offset(dev)); 469 } 470 471 static inline const u32 *dev_read_prop(struct udevice *dev, 472 const char *propname, int *lenp) 473 { 474 return ofnode_get_property(dev_ofnode(dev), propname, lenp); 475 } 476 477 static inline int dev_read_alias_seq(struct udevice *dev, int *devnump) 478 { 479 return fdtdec_get_alias_seq(gd->fdt_blob, dev->uclass->uc_drv->name, 480 dev_of_offset(dev), devnump); 481 } 482 483 static inline int dev_read_u32_array(struct udevice *dev, const char *propname, 484 u32 *out_values, size_t sz) 485 { 486 return ofnode_read_u32_array(dev_ofnode(dev), propname, out_values, sz); 487 } 488 489 static inline ofnode dev_read_first_subnode(struct udevice *dev) 490 { 491 return ofnode_first_subnode(dev_ofnode(dev)); 492 } 493 494 static inline ofnode dev_read_next_subnode(ofnode node) 495 { 496 return ofnode_next_subnode(node); 497 } 498 499 static inline const uint8_t *dev_read_u8_array_ptr(struct udevice *dev, 500 const char *propname, size_t sz) 501 { 502 return ofnode_read_u8_array_ptr(dev_ofnode(dev), propname, sz); 503 } 504 505 static inline int dev_read_enabled(struct udevice *dev) 506 { 507 return fdtdec_get_is_enabled(gd->fdt_blob, dev_of_offset(dev)); 508 } 509 510 #endif /* CONFIG_DM_DEV_READ_INLINE */ 511 512 /** 513 * dev_for_each_subnode() - Helper function to iterate through subnodes 514 * 515 * This creates a for() loop which works through the subnodes in a device's 516 * device-tree node. 517 * 518 * @subnode: ofnode holding the current subnode 519 * @dev: device to use for interation (struct udevice *) 520 */ 521 #define dev_for_each_subnode(subnode, dev) \ 522 for (subnode = dev_read_first_subnode(dev); \ 523 ofnode_valid(subnode); \ 524 subnode = ofnode_next_subnode(subnode)) 525 526 #endif 527