1/* SPDX-License-Identifier: GPL-2.0+ */ 2/* 3 * Copyright (c) 2013 Google, Inc 4 * 5 * (C) Copyright 2012 6 * Pavel Herrmann <morpheus.ibis@gmail.com> 7 * Marek Vasut <marex@denx.de> 8 */ 9 10#ifndef _DM_DEVICE_H 11#define _DM_DEVICE_H 12 13#include <dm/ofnode.h> 14#include <dm/uclass-id.h> 15#include <fdtdec.h> 16#include <linker_lists.h> 17#include <linux/kernel.h> 18#include <linux/list.h> 19#include <linux/printk.h> 20 21struct driver_info; 22 23/* Driver is active (probed). Cleared when it is removed */ 24#define DM_FLAG_ACTIVATED (1 << 0) 25 26/* DM is responsible for allocating and freeing plat */ 27#define DM_FLAG_ALLOC_PDATA (1 << 1) 28 29/* DM should init this device prior to relocation */ 30#define DM_FLAG_PRE_RELOC (1 << 2) 31 32/* DM is responsible for allocating and freeing parent_plat */ 33#define DM_FLAG_ALLOC_PARENT_PDATA (1 << 3) 34 35/* DM is responsible for allocating and freeing uclass_plat */ 36#define DM_FLAG_ALLOC_UCLASS_PDATA (1 << 4) 37 38/* Allocate driver private data on a DMA boundary */ 39#define DM_FLAG_ALLOC_PRIV_DMA (1 << 5) 40 41/* Device is bound */ 42#define DM_FLAG_BOUND (1 << 6) 43 44/* Device name is allocated and should be freed on unbind() */ 45#define DM_FLAG_NAME_ALLOCED (1 << 7) 46 47/* Device has platform data provided by of-platdata */ 48#define DM_FLAG_OF_PLATDATA (1 << 8) 49 50/* 51 * Call driver remove function to stop currently active DMA transfers or 52 * give DMA buffers back to the HW / controller. This may be needed for 53 * some drivers to do some final stage cleanup before the OS is called 54 * (U-Boot exit) 55 */ 56#define DM_FLAG_ACTIVE_DMA (1 << 9) 57 58/* 59 * Call driver remove function to do some final configuration, before 60 * U-Boot exits and the OS is started 61 */ 62#define DM_FLAG_OS_PREPARE (1 << 10) 63 64/* DM does not enable/disable the power domains corresponding to this device */ 65#define DM_FLAG_DEFAULT_PD_CTRL_OFF (1 << 11) 66 67/* Driver plat has been read. Cleared when the device is removed */ 68#define DM_FLAG_PLATDATA_VALID (1 << 12) 69 70/* 71 * Device is removed without switching off its power domain. This might 72 * be required, i. e. for serial console (debug) output when booting OS. 73 */ 74#define DM_FLAG_LEAVE_PD_ON (1 << 13) 75 76/* 77 * Device is vital to the operation of other devices. It is possible to remove 78 * removed this device after all regular devices are removed. This is useful 79 * e.g. for clock, which need to be active during the device-removal phase. 80 */ 81#define DM_FLAG_VITAL (1 << 14) 82 83/* 84 * One or multiple of these flags are passed to device_remove() so that 85 * a selective device removal as specified by the remove-stage and the 86 * driver flags can be done. 87 * 88 * DO NOT use these flags in your driver's @flags value... 89 * use the above DM_FLAG_... values instead 90 */ 91enum { 92 /* Normal remove, remove all devices */ 93 DM_REMOVE_NORMAL = 1 << 0, 94 95 /* Remove devices with active DMA */ 96 DM_REMOVE_ACTIVE_DMA = DM_FLAG_ACTIVE_DMA, 97 98 /* Remove devices which need some final OS preparation steps */ 99 DM_REMOVE_OS_PREPARE = DM_FLAG_OS_PREPARE, 100 101 /* Remove only devices that are not marked vital */ 102 DM_REMOVE_NON_VITAL = DM_FLAG_VITAL, 103 104 /* Remove devices with any active flag */ 105 DM_REMOVE_ACTIVE_ALL = DM_REMOVE_ACTIVE_DMA | DM_REMOVE_OS_PREPARE, 106 107 /* Don't power down any attached power domains */ 108 DM_REMOVE_NO_PD = 1 << 1, 109}; 110 111/** 112 * struct udevice - An instance of a driver 113 * 114 * This holds information about a device, which is a driver bound to a 115 * particular port or peripheral (essentially a driver instance). 116 * 117 * A device will come into existence through a 'bind' call, either due to 118 * a U_BOOT_DRVINFO() macro (in which case plat is non-NULL) or a node 119 * in the device tree (in which case of_offset is >= 0). In the latter case 120 * we translate the device tree information into plat in a function 121 * implemented by the driver of_to_plat method (called just before the 122 * probe method if the device has a device tree node. 123 * 124 * All three of plat, priv and uclass_priv can be allocated by the 125 * driver, or you can use the auto members of struct driver and 126 * struct uclass_driver to have driver model do this automatically. 127 * 128 * @driver: The driver used by this device 129 * @name: Name of device, typically the FDT node name 130 * @plat_: Configuration data for this device (do not access outside driver 131 * model) 132 * @parent_plat_: The parent bus's configuration data for this device (do not 133 * access outside driver model) 134 * @uclass_plat_: The uclass's configuration data for this device (do not access 135 * outside driver model) 136 * @driver_data: Driver data word for the entry that matched this device with 137 * its driver 138 * @parent: Parent of this device, or NULL for the top level device 139 * @priv_: Private data for this device (do not access outside driver model) 140 * @uclass: Pointer to uclass for this device 141 * @uclass_priv_: The uclass's private data for this device (do not access 142 * outside driver model) 143 * @parent_priv_: The parent's private data for this device (do not access 144 * outside driver model) 145 * @uclass_node: Used by uclass to link its devices 146 * @child_head: List of children of this device 147 * @sibling_node: Next device in list of all devices 148 * @flags_: Flags for this device DM_FLAG_... (do not access outside driver 149 * model) 150 * @seq_: Allocated sequence number for this device (-1 = none). This is set up 151 * when the device is bound and is unique within the device's uclass. If the 152 * device has an alias in the devicetree then that is used to set the sequence 153 * number. Otherwise, the next available number is used. Sequence numbers are 154 * used by certain commands that need device to be numbered (e.g. 'mmc dev'). 155 * (do not access outside driver model) 156 * @node_: Reference to device tree node for this device (do not access outside 157 * driver model) 158 * @devres_head: List of memory allocations associated with this device. 159 * When CONFIG_DEVRES is enabled, devm_kmalloc() and friends will 160 * add to this list. Memory so-allocated will be freed 161 * automatically when the device is removed / unbound 162 * @dma_offset: Offset between the physical address space (CPU's) and the 163 * device's bus address space 164 */ 165struct udevice { 166 const struct driver *driver; 167 const char *name; 168 void *plat_; 169 void *parent_plat_; 170 void *uclass_plat_; 171 ulong driver_data; 172 struct udevice *parent; 173 void *priv_; 174 struct uclass *uclass; 175 void *uclass_priv_; 176 void *parent_priv_; 177 struct list_head uclass_node; 178 struct list_head child_head; 179 struct list_head sibling_node; 180#if !CONFIG_IS_ENABLED(OF_PLATDATA_RT) 181 u32 flags_; 182#endif 183 int seq_; 184#if CONFIG_IS_ENABLED(OF_REAL) 185 ofnode node_; 186#endif 187#ifdef CONFIG_DEVRES 188 struct list_head devres_head; 189#endif 190#if CONFIG_IS_ENABLED(DM_DMA) 191 ulong dma_offset; 192#endif 193}; 194 195/** 196 * udevice_rt - runtime information set up by U-Boot 197 * 198 * This is only used with OF_PLATDATA_RT 199 * 200 * There is one of these for every udevice in the linker list, indexed by 201 * the udevice_info idx value. 202 * 203 * @flags_: Flags for this device DM_FLAG_... (do not access outside driver 204 * model) 205 */ 206struct udevice_rt { 207 u32 flags_; 208}; 209 210/* Maximum sequence number supported and associated string length */ 211#define DM_MAX_SEQ 999 212#define DM_MAX_SEQ_STR 3 213 214/* Returns the operations for a device */ 215#define device_get_ops(dev) (dev->driver->ops) 216 217#if CONFIG_IS_ENABLED(OF_PLATDATA_RT) 218u32 dev_get_flags(const struct udevice *dev); 219void dev_or_flags(const struct udevice *dev, u32 or); 220void dev_bic_flags(const struct udevice *dev, u32 bic); 221#else 222static inline u32 dev_get_flags(const struct udevice *dev) 223{ 224 return dev->flags_; 225} 226 227static inline void dev_or_flags(struct udevice *dev, u32 or) 228{ 229 dev->flags_ |= or; 230} 231 232static inline void dev_bic_flags(struct udevice *dev, u32 bic) 233{ 234 dev->flags_ &= ~bic; 235} 236#endif /* OF_PLATDATA_RT */ 237 238/** 239 * dev_ofnode() - get the DT node reference associated with a udevice 240 * 241 * @dev: device to check 242 * @return reference of the the device's DT node 243 */ 244static inline ofnode dev_ofnode(const struct udevice *dev) 245{ 246#if CONFIG_IS_ENABLED(OF_REAL) 247 return dev->node_; 248#else 249 return ofnode_null(); 250#endif 251} 252 253/* Returns non-zero if the device is active (probed and not removed) */ 254#define device_active(dev) (dev_get_flags(dev) & DM_FLAG_ACTIVATED) 255 256#if CONFIG_IS_ENABLED(DM_DMA) 257#define dev_set_dma_offset(_dev, _offset) _dev->dma_offset = _offset 258#define dev_get_dma_offset(_dev) _dev->dma_offset 259#else 260#define dev_set_dma_offset(_dev, _offset) 261#define dev_get_dma_offset(_dev) 0 262#endif 263 264static inline int dev_of_offset(const struct udevice *dev) 265{ 266#if CONFIG_IS_ENABLED(OF_REAL) 267 return ofnode_to_offset(dev_ofnode(dev)); 268#else 269 return -1; 270#endif 271} 272 273static inline bool dev_has_ofnode(const struct udevice *dev) 274{ 275#if CONFIG_IS_ENABLED(OF_REAL) 276 return ofnode_valid(dev_ofnode(dev)); 277#else 278 return false; 279#endif 280} 281 282static inline void dev_set_ofnode(struct udevice *dev, ofnode node) 283{ 284#if CONFIG_IS_ENABLED(OF_REAL) 285 dev->node_ = node; 286#endif 287} 288 289static inline int dev_seq(const struct udevice *dev) 290{ 291 return dev->seq_; 292} 293 294/** 295 * struct udevice_id - Lists the compatible strings supported by a driver 296 * @compatible: Compatible string 297 * @data: Data for this compatible string 298 */ 299struct udevice_id { 300 const char *compatible; 301 ulong data; 302}; 303 304#if CONFIG_IS_ENABLED(OF_REAL) 305#define of_match_ptr(_ptr) (_ptr) 306#else 307#define of_match_ptr(_ptr) NULL 308#endif /* CONFIG_IS_ENABLED(OF_CONTROL) */ 309 310/** 311 * struct driver - A driver for a feature or peripheral 312 * 313 * This holds methods for setting up a new device, and also removing it. 314 * The device needs information to set itself up - this is provided either 315 * by plat or a device tree node (which we find by looking up 316 * matching compatible strings with of_match). 317 * 318 * Drivers all belong to a uclass, representing a class of devices of the 319 * same type. Common elements of the drivers can be implemented in the uclass, 320 * or the uclass can provide a consistent interface to the drivers within 321 * it. 322 * 323 * @name: Device name 324 * @id: Identifies the uclass we belong to 325 * @of_match: List of compatible strings to match, and any identifying data 326 * for each. 327 * @bind: Called to bind a device to its driver 328 * @probe: Called to probe a device, i.e. activate it 329 * @remove: Called to remove a device, i.e. de-activate it 330 * @unbind: Called to unbind a device from its driver 331 * @of_to_plat: Called before probe to decode device tree data 332 * @child_post_bind: Called after a new child has been bound 333 * @child_pre_probe: Called before a child device is probed. The device has 334 * memory allocated but it has not yet been probed. 335 * @child_post_remove: Called after a child device is removed. The device 336 * has memory allocated but its device_remove() method has been called. 337 * @priv_auto: If non-zero this is the size of the private data 338 * to be allocated in the device's ->priv pointer. If zero, then the driver 339 * is responsible for allocating any data required. 340 * @plat_auto: If non-zero this is the size of the 341 * platform data to be allocated in the device's ->plat pointer. 342 * This is typically only useful for device-tree-aware drivers (those with 343 * an of_match), since drivers which use plat will have the data 344 * provided in the U_BOOT_DRVINFO() instantiation. 345 * @per_child_auto: Each device can hold private data owned by 346 * its parent. If required this will be automatically allocated if this 347 * value is non-zero. 348 * @per_child_plat_auto: A bus likes to store information about 349 * its children. If non-zero this is the size of this data, to be allocated 350 * in the child's parent_plat pointer. 351 * @ops: Driver-specific operations. This is typically a list of function 352 * pointers defined by the driver, to implement driver functions required by 353 * the uclass. 354 * @flags: driver flags - see DM_FLAGS_... 355 * @acpi_ops: Advanced Configuration and Power Interface (ACPI) operations, 356 * allowing the device to add things to the ACPI tables passed to Linux 357 */ 358struct driver { 359 char *name; 360 enum uclass_id id; 361 const struct udevice_id *of_match; 362 int (*bind)(struct udevice *dev); 363 int (*probe)(struct udevice *dev); 364 int (*remove)(struct udevice *dev); 365 int (*unbind)(struct udevice *dev); 366 int (*of_to_plat)(struct udevice *dev); 367 int (*child_post_bind)(struct udevice *dev); 368 int (*child_pre_probe)(struct udevice *dev); 369 int (*child_post_remove)(struct udevice *dev); 370 int priv_auto; 371 int plat_auto; 372 int per_child_auto; 373 int per_child_plat_auto; 374 const void *ops; /* driver-specific operations */ 375 uint32_t flags; 376#if CONFIG_IS_ENABLED(ACPIGEN) 377 struct acpi_ops *acpi_ops; 378#endif 379}; 380 381/* Declare a new U-Boot driver */ 382#define U_BOOT_DRIVER(__name) \ 383 ll_entry_declare(struct driver, __name, driver) 384 385/* Get a pointer to a given driver */ 386#define DM_DRIVER_GET(__name) \ 387 ll_entry_get(struct driver, __name, driver) 388 389/** 390 * DM_DRIVER_REF() - Get a reference to a driver 391 * 392 * This is useful in data structures and code for referencing a driver at 393 * build time. Before this is used, an extern U_BOOT_DRIVER() must have been 394 * declared. 395 * 396 * For example: 397 * 398 * extern U_BOOT_DRIVER(sandbox_fixed_clock); 399 * 400 * struct driver *drvs[] = { 401 * DM_DRIVER_REF(sandbox_fixed_clock), 402 * }; 403 * 404 * @_name: Name of the driver. This must be a valid C identifier, used by the 405 * linker_list 406 * @returns struct driver * for the driver 407 */ 408#define DM_DRIVER_REF(_name) \ 409 ll_entry_ref(struct driver, _name, driver) 410 411/** 412 * Declare a macro to state a alias for a driver name. This macro will 413 * produce no code but its information will be parsed by tools like 414 * dtoc 415 */ 416#define DM_DRIVER_ALIAS(__name, __alias) 417 418/** 419 * Declare a macro to indicate which phase of U-Boot this driver is fore. 420 * 421 * 422 * This macro produces no code but its information will be parsed by dtoc. The 423 * macro can be only be used once in a driver. Put it within the U_BOOT_DRIVER() 424 * declaration, e.g.: 425 * 426 * U_BOOT_DRIVER(cpu) = { 427 * .name = ... 428 * ... 429 * DM_PHASE(tpl) 430 * }; 431 */ 432#define DM_PHASE(_phase) 433 434/** 435 * Declare a macro to declare a header needed for a driver. Often the correct 436 * header can be found automatically, but only for struct declarations. For 437 * enums and #defines used in the driver declaration and declared in a different 438 * header from the structs, this macro must be used. 439 * 440 * This macro produces no code but its information will be parsed by dtoc. The 441 * macro can be used multiple times with different headers, for the same driver. 442 * Put it within the U_BOOT_DRIVER() declaration, e.g.: 443 * 444 * U_BOOT_DRIVER(cpu) = { 445 * .name = ... 446 * ... 447 * DM_HEADER(<asm/cpu.h>) 448 * }; 449 */ 450#define DM_HEADER(_hdr) 451 452/** 453 * dev_get_plat() - Get the platform data for a device 454 * 455 * This checks that dev is not NULL, but no other checks for now 456 * 457 * @dev Device to check 458 * @return platform data, or NULL if none 459 */ 460void *dev_get_plat(const struct udevice *dev); 461 462/** 463 * dev_get_parent_plat() - Get the parent platform data for a device 464 * 465 * This checks that dev is not NULL, but no other checks for now 466 * 467 * @dev Device to check 468 * @return parent's platform data, or NULL if none 469 */ 470void *dev_get_parent_plat(const struct udevice *dev); 471 472/** 473 * dev_get_uclass_plat() - Get the uclass platform data for a device 474 * 475 * This checks that dev is not NULL, but no other checks for now 476 * 477 * @dev Device to check 478 * @return uclass's platform data, or NULL if none 479 */ 480void *dev_get_uclass_plat(const struct udevice *dev); 481 482/** 483 * dev_get_priv() - Get the private data for a device 484 * 485 * This checks that dev is not NULL, but no other checks for now 486 * 487 * @dev Device to check 488 * @return private data, or NULL if none 489 */ 490void *dev_get_priv(const struct udevice *dev); 491 492/** 493 * dev_get_parent_priv() - Get the parent private data for a device 494 * 495 * The parent private data is data stored in the device but owned by the 496 * parent. For example, a USB device may have parent data which contains 497 * information about how to talk to the device over USB. 498 * 499 * This checks that dev is not NULL, but no other checks for now 500 * 501 * @dev Device to check 502 * @return parent data, or NULL if none 503 */ 504void *dev_get_parent_priv(const struct udevice *dev); 505 506/** 507 * dev_get_uclass_priv() - Get the private uclass data for a device 508 * 509 * This checks that dev is not NULL, but no other checks for now 510 * 511 * @dev Device to check 512 * @return private uclass data for this device, or NULL if none 513 */ 514void *dev_get_uclass_priv(const struct udevice *dev); 515 516/** 517 * struct dev_get_parent() - Get the parent of a device 518 * 519 * @child: Child to check 520 * @return parent of child, or NULL if this is the root device 521 */ 522struct udevice *dev_get_parent(const struct udevice *child); 523 524/** 525 * dev_get_driver_data() - get the driver data used to bind a device 526 * 527 * When a device is bound using a device tree node, it matches a 528 * particular compatible string in struct udevice_id. This function 529 * returns the associated data value for that compatible string. This is 530 * the 'data' field in struct udevice_id. 531 * 532 * As an example, consider this structure: 533 * static const struct udevice_id tegra_i2c_ids[] = { 534 * { .compatible = "nvidia,tegra114-i2c", .data = TYPE_114 }, 535 * { .compatible = "nvidia,tegra20-i2c", .data = TYPE_STD }, 536 * { .compatible = "nvidia,tegra20-i2c-dvc", .data = TYPE_DVC }, 537 * { } 538 * }; 539 * 540 * When driver model finds a driver for this it will store the 'data' value 541 * corresponding to the compatible string it matches. This function returns 542 * that value. This allows the driver to handle several variants of a device. 543 * 544 * For USB devices, this is the driver_info field in struct usb_device_id. 545 * 546 * @dev: Device to check 547 * @return driver data (0 if none is provided) 548 */ 549ulong dev_get_driver_data(const struct udevice *dev); 550 551/** 552 * dev_get_driver_ops() - get the device's driver's operations 553 * 554 * This checks that dev is not NULL, and returns the pointer to device's 555 * driver's operations. 556 * 557 * @dev: Device to check 558 * @return void pointer to driver's operations or NULL for NULL-dev or NULL-ops 559 */ 560const void *dev_get_driver_ops(const struct udevice *dev); 561 562/** 563 * device_get_uclass_id() - return the uclass ID of a device 564 * 565 * @dev: Device to check 566 * @return uclass ID for the device 567 */ 568enum uclass_id device_get_uclass_id(const struct udevice *dev); 569 570/** 571 * dev_get_uclass_name() - return the uclass name of a device 572 * 573 * This checks that dev is not NULL. 574 * 575 * @dev: Device to check 576 * @return pointer to the uclass name for the device 577 */ 578const char *dev_get_uclass_name(const struct udevice *dev); 579 580/** 581 * device_get_child() - Get the child of a device by index 582 * 583 * Returns the numbered child, 0 being the first. This does not use 584 * sequence numbers, only the natural order. 585 * 586 * @dev: Parent device to check 587 * @index: Child index 588 * @devp: Returns pointer to device 589 * @return 0 if OK, -ENODEV if no such device, other error if the device fails 590 * to probe 591 */ 592int device_get_child(const struct udevice *parent, int index, 593 struct udevice **devp); 594 595/** 596 * device_get_child_count() - Get the available child count of a device 597 * 598 * Returns the number of children to a device. 599 * 600 * @parent: Parent device to check 601 */ 602int device_get_child_count(const struct udevice *parent); 603 604/** 605 * device_find_child_by_seq() - Find a child device based on a sequence 606 * 607 * This searches for a device with the given seq. 608 * 609 * @parent: Parent device 610 * @seq: Sequence number to find (0=first) 611 * @devp: Returns pointer to device (there is only one per for each seq). 612 * Set to NULL if none is found 613 * @return 0 if OK, -ENODEV if not found 614 */ 615int device_find_child_by_seq(const struct udevice *parent, int seq, 616 struct udevice **devp); 617 618/** 619 * device_get_child_by_seq() - Get a child device based on a sequence 620 * 621 * If an active device has this sequence it will be returned. If there is no 622 * such device then this will check for a device that is requesting this 623 * sequence. 624 * 625 * The device is probed to activate it ready for use. 626 * 627 * @parent: Parent device 628 * @seq: Sequence number to find (0=first) 629 * @devp: Returns pointer to device (there is only one per for each seq) 630 * Set to NULL if none is found 631 * @return 0 if OK, -ve on error 632 */ 633int device_get_child_by_seq(const struct udevice *parent, int seq, 634 struct udevice **devp); 635 636/** 637 * device_find_child_by_of_offset() - Find a child device based on FDT offset 638 * 639 * Locates a child device by its device tree offset. 640 * 641 * @parent: Parent device 642 * @of_offset: Device tree offset to find 643 * @devp: Returns pointer to device if found, otherwise this is set to NULL 644 * @return 0 if OK, -ve on error 645 */ 646int device_find_child_by_of_offset(const struct udevice *parent, int of_offset, 647 struct udevice **devp); 648 649/** 650 * device_get_child_by_of_offset() - Get a child device based on FDT offset 651 * 652 * Locates a child device by its device tree offset. 653 * 654 * The device is probed to activate it ready for use. 655 * 656 * @parent: Parent device 657 * @of_offset: Device tree offset to find 658 * @devp: Returns pointer to device if found, otherwise this is set to NULL 659 * @return 0 if OK, -ve on error 660 */ 661int device_get_child_by_of_offset(const struct udevice *parent, int of_offset, 662 struct udevice **devp); 663 664/** 665 * device_find_global_by_ofnode() - Get a device based on ofnode 666 * 667 * Locates a device by its device tree ofnode, searching globally throughout 668 * the all driver model devices. 669 * 670 * The device is NOT probed 671 * 672 * @node: Device tree ofnode to find 673 * @devp: Returns pointer to device if found, otherwise this is set to NULL 674 * @return 0 if OK, -ve on error 675 */ 676 677int device_find_global_by_ofnode(ofnode node, struct udevice **devp); 678 679/** 680 * device_get_global_by_ofnode() - Get a device based on ofnode 681 * 682 * Locates a device by its device tree ofnode, searching globally throughout 683 * the all driver model devices. 684 * 685 * The device is probed to activate it ready for use. 686 * 687 * @node: Device tree ofnode to find 688 * @devp: Returns pointer to device if found, otherwise this is set to NULL 689 * @return 0 if OK, -ve on error 690 */ 691int device_get_global_by_ofnode(ofnode node, struct udevice **devp); 692 693/** 694 * device_get_by_ofplat_idx() - Get a device based on of-platdata index 695 * 696 * Locates a device by either its struct driver_info index, or its 697 * struct udevice index. The latter is used with OF_PLATDATA_INST, since we have 698 * a list of build-time instantiated struct udevice records, The former is used 699 * with !OF_PLATDATA_INST since in that case we have a list of 700 * struct driver_info records. 701 * 702 * The index number is written into the idx field of struct phandle_1_arg, etc. 703 * It is the position of this driver_info/udevice in its linker list. 704 * 705 * The device is probed to activate it ready for use. 706 * 707 * @idx: Index number of the driver_info/udevice structure (0=first) 708 * @devp: Returns pointer to device if found, otherwise this is set to NULL 709 * @return 0 if OK, -ve on error 710 */ 711int device_get_by_ofplat_idx(uint idx, struct udevice **devp); 712 713/** 714 * device_find_first_child() - Find the first child of a device 715 * 716 * @parent: Parent device to search 717 * @devp: Returns first child device, or NULL if none 718 * @return 0 719 */ 720int device_find_first_child(const struct udevice *parent, 721 struct udevice **devp); 722 723/** 724 * device_find_next_child() - Find the next child of a device 725 * 726 * @devp: Pointer to previous child device on entry. Returns pointer to next 727 * child device, or NULL if none 728 * @return 0 729 */ 730int device_find_next_child(struct udevice **devp); 731 732/** 733 * device_find_first_inactive_child() - Find the first inactive child 734 * 735 * This is used to locate an existing child of a device which is of a given 736 * uclass. 737 * 738 * The device is NOT probed 739 * 740 * @parent: Parent device to search 741 * @uclass_id: Uclass to look for 742 * @devp: Returns device found, if any, else NULL 743 * @return 0 if found, else -ENODEV 744 */ 745int device_find_first_inactive_child(const struct udevice *parent, 746 enum uclass_id uclass_id, 747 struct udevice **devp); 748 749/** 750 * device_find_first_child_by_uclass() - Find the first child of a device in uc 751 * 752 * @parent: Parent device to search 753 * @uclass_id: Uclass to look for 754 * @devp: Returns first child device in that uclass, if any, else NULL 755 * @return 0 if found, else -ENODEV 756 */ 757int device_find_first_child_by_uclass(const struct udevice *parent, 758 enum uclass_id uclass_id, 759 struct udevice **devp); 760 761/** 762 * device_find_child_by_name() - Find a child by device name 763 * 764 * @parent: Parent device to search 765 * @name: Name to look for 766 * @devp: Returns device found, if any 767 * @return 0 if found, else -ENODEV 768 */ 769int device_find_child_by_name(const struct udevice *parent, const char *name, 770 struct udevice **devp); 771 772/** 773 * device_first_child_ofdata_err() - Find the first child and reads its plat 774 * 775 * The of_to_plat() method is called on the child before it is returned, 776 * but the child is not probed. 777 * 778 * @parent: Parent to check 779 * @devp: Returns child that was found, if any 780 * @return 0 on success, -ENODEV if no children, other -ve on error 781 */ 782int device_first_child_ofdata_err(struct udevice *parent, 783 struct udevice **devp); 784 785/* 786 * device_next_child_ofdata_err() - Find the next child and read its plat 787 * 788 * The of_to_plat() method is called on the child before it is returned, 789 * but the child is not probed. 790 * 791 * @devp: On entry, points to the previous child; on exit returns the child that 792 * was found, if any 793 * @return 0 on success, -ENODEV if no children, other -ve on error 794 */ 795int device_next_child_ofdata_err(struct udevice **devp); 796 797/** 798 * device_first_child_err() - Get the first child of a device 799 * 800 * The device returned is probed if necessary, and ready for use 801 * 802 * @parent: Parent device to search 803 * @devp: Returns device found, if any 804 * @return 0 if found, -ENODEV if not, -ve error if device failed to probe 805 */ 806int device_first_child_err(struct udevice *parent, struct udevice **devp); 807 808/** 809 * device_next_child_err() - Get the next child of a parent device 810 * 811 * The device returned is probed if necessary, and ready for use 812 * 813 * @devp: On entry, pointer to device to lookup. On exit, returns pointer 814 * to the next sibling if no error occurred 815 * @return 0 if found, -ENODEV if not, -ve error if device failed to probe 816 */ 817int device_next_child_err(struct udevice **devp); 818 819/** 820 * device_has_children() - check if a device has any children 821 * 822 * @dev: Device to check 823 * @return true if the device has one or more children 824 */ 825bool device_has_children(const struct udevice *dev); 826 827/** 828 * device_has_active_children() - check if a device has any active children 829 * 830 * @dev: Device to check 831 * @return true if the device has one or more children and at least one of 832 * them is active (probed). 833 */ 834bool device_has_active_children(const struct udevice *dev); 835 836/** 837 * device_is_last_sibling() - check if a device is the last sibling 838 * 839 * This function can be useful for display purposes, when special action needs 840 * to be taken when displaying the last sibling. This can happen when a tree 841 * view of devices is being displayed. 842 * 843 * @dev: Device to check 844 * @return true if there are no more siblings after this one - i.e. is it 845 * last in the list. 846 */ 847bool device_is_last_sibling(const struct udevice *dev); 848 849/** 850 * device_set_name() - set the name of a device 851 * 852 * This must be called in the device's bind() method and no later. Normally 853 * this is unnecessary but for probed devices which don't get a useful name 854 * this function can be helpful. 855 * 856 * The name is allocated and will be freed automatically when the device is 857 * unbound. 858 * 859 * @dev: Device to update 860 * @name: New name (this string is allocated new memory and attached to 861 * the device) 862 * @return 0 if OK, -ENOMEM if there is not enough memory to allocate the 863 * string 864 */ 865int device_set_name(struct udevice *dev, const char *name); 866 867/** 868 * device_set_name_alloced() - note that a device name is allocated 869 * 870 * This sets the DM_FLAG_NAME_ALLOCED flag for the device, so that when it is 871 * unbound the name will be freed. This avoids memory leaks. 872 * 873 * @dev: Device to update 874 */ 875void device_set_name_alloced(struct udevice *dev); 876 877/** 878 * device_is_compatible() - check if the device is compatible with the compat 879 * 880 * This allows to check whether the device is comaptible with the compat. 881 * 882 * @dev: udevice pointer for which compatible needs to be verified. 883 * @compat: Compatible string which needs to verified in the given 884 * device 885 * @return true if OK, false if the compatible is not found 886 */ 887bool device_is_compatible(const struct udevice *dev, const char *compat); 888 889/** 890 * of_machine_is_compatible() - check if the machine is compatible with 891 * the compat 892 * 893 * This allows to check whether the machine is comaptible with the compat. 894 * 895 * @compat: Compatible string which needs to verified 896 * @return true if OK, false if the compatible is not found 897 */ 898bool of_machine_is_compatible(const char *compat); 899 900/** 901 * dev_disable_by_path() - Disable a device given its device tree path 902 * 903 * @path: The device tree path identifying the device to be disabled 904 * @return 0 on success, -ve on error 905 */ 906int dev_disable_by_path(const char *path); 907 908/** 909 * dev_enable_by_path() - Enable a device given its device tree path 910 * 911 * @path: The device tree path identifying the device to be enabled 912 * @return 0 on success, -ve on error 913 */ 914int dev_enable_by_path(const char *path); 915 916/** 917 * device_is_on_pci_bus - Test if a device is on a PCI bus 918 * 919 * @dev: device to test 920 * @return: true if it is on a PCI bus, false otherwise 921 */ 922static inline bool device_is_on_pci_bus(const struct udevice *dev) 923{ 924 return dev->parent && device_get_uclass_id(dev->parent) == UCLASS_PCI; 925} 926 927/** 928 * device_foreach_child_safe() - iterate through child devices safely 929 * 930 * This allows the @pos child to be removed in the loop if required. 931 * 932 * @pos: struct udevice * for the current device 933 * @next: struct udevice * for the next device 934 * @parent: parent device to scan 935 */ 936#define device_foreach_child_safe(pos, next, parent) \ 937 list_for_each_entry_safe(pos, next, &parent->child_head, sibling_node) 938 939/** 940 * device_foreach_child() - iterate through child devices 941 * 942 * @pos: struct udevice * for the current device 943 * @parent: parent device to scan 944 */ 945#define device_foreach_child(pos, parent) \ 946 list_for_each_entry(pos, &parent->child_head, sibling_node) 947 948/** 949 * device_foreach_child_of_to_plat() - iterate through children 950 * 951 * This stops when it gets an error, with @pos set to the device that failed to 952 * read ofdata. 953 954 * This creates a for() loop which works through the available children of 955 * a device in order from start to end. Device ofdata is read by calling 956 * device_of_to_plat() on each one. The devices are not probed. 957 * 958 * @pos: struct udevice * for the current device 959 * @parent: parent device to scan 960 */ 961#define device_foreach_child_of_to_plat(pos, parent) \ 962 for (int _ret = device_first_child_ofdata_err(parent, &pos); !_ret; \ 963 _ret = device_next_child_ofdata_err(&pos)) 964 965/** 966 * device_foreach_child_probe() - iterate through children, probing them 967 * 968 * This creates a for() loop which works through the available children of 969 * a device in order from start to end. Devices are probed if necessary, 970 * and ready for use. 971 * 972 * This stops when it gets an error, with @pos set to the device that failed to 973 * probe 974 * 975 * @pos: struct udevice * for the current device 976 * @parent: parent device to scan 977 */ 978#define device_foreach_child_probe(pos, parent) \ 979 for (int _ret = device_first_child_err(parent, &pos); !_ret; \ 980 _ret = device_next_child_err(&pos)) 981 982/** 983 * dm_scan_fdt_dev() - Bind child device in the device tree 984 * 985 * This handles device which have sub-nodes in the device tree. It scans all 986 * sub-nodes and binds drivers for each node where a driver can be found. 987 * 988 * If this is called prior to relocation, only pre-relocation devices will be 989 * bound (those marked with u-boot,dm-pre-reloc in the device tree, or where 990 * the driver has the DM_FLAG_PRE_RELOC flag set). Otherwise, all devices will 991 * be bound. 992 * 993 * @dev: Device to scan 994 * @return 0 if OK, -ve on error 995 */ 996int dm_scan_fdt_dev(struct udevice *dev); 997 998#endif 999