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