include/dm/read.h

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