1 /* 2 * Copyright (c) 2013 Google, Inc 3 * 4 * (C) Copyright 2012 5 * Pavel Herrmann <morpheus.ibis@gmail.com> 6 * Marek Vasut <marex@denx.de> 7 * 8 * SPDX-License-Identifier: GPL-2.0+ 9 */ 10 11 #ifndef _DM_DEVICE_H 12 #define _DM_DEVICE_H 13 14 #include <dm/uclass-id.h> 15 #include <fdtdec.h> 16 #include <linker_lists.h> 17 #include <linux/compat.h> 18 #include <linux/kernel.h> 19 #include <linux/list.h> 20 21 struct 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 platdata */ 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_platdata */ 33 #define DM_FLAG_ALLOC_PARENT_PDATA (1 << 3) 34 35 /* DM is responsible for allocating and freeing uclass_platdata */ 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 #define DM_FLAG_OF_PLATDATA (1 << 8) 48 49 /* 50 * Call driver remove function to stop currently active DMA transfers or 51 * give DMA buffers back to the HW / controller. This may be needed for 52 * some drivers to do some final stage cleanup before the OS is called 53 * (U-Boot exit) 54 */ 55 #define DM_FLAG_ACTIVE_DMA (1 << 9) 56 57 /* 58 * One or multiple of these flags are passed to device_remove() so that 59 * a selective device removal as specified by the remove-stage and the 60 * driver flags can be done. 61 */ 62 enum { 63 /* Normal remove, remove all devices */ 64 DM_REMOVE_NORMAL = 1 << 0, 65 66 /* Remove devices with active DMA */ 67 DM_REMOVE_ACTIVE_DMA = DM_FLAG_ACTIVE_DMA, 68 69 /* Add more use cases here */ 70 71 /* Remove devices with any active flag */ 72 DM_REMOVE_ACTIVE_ALL = DM_REMOVE_ACTIVE_DMA, 73 }; 74 75 /** 76 * struct udevice - An instance of a driver 77 * 78 * This holds information about a device, which is a driver bound to a 79 * particular port or peripheral (essentially a driver instance). 80 * 81 * A device will come into existence through a 'bind' call, either due to 82 * a U_BOOT_DEVICE() macro (in which case platdata is non-NULL) or a node 83 * in the device tree (in which case of_offset is >= 0). In the latter case 84 * we translate the device tree information into platdata in a function 85 * implemented by the driver ofdata_to_platdata method (called just before the 86 * probe method if the device has a device tree node. 87 * 88 * All three of platdata, priv and uclass_priv can be allocated by the 89 * driver, or you can use the auto_alloc_size members of struct driver and 90 * struct uclass_driver to have driver model do this automatically. 91 * 92 * @driver: The driver used by this device 93 * @name: Name of device, typically the FDT node name 94 * @platdata: Configuration data for this device 95 * @parent_platdata: The parent bus's configuration data for this device 96 * @uclass_platdata: The uclass's configuration data for this device 97 * @of_offset: Device tree node offset for this device (- for none) 98 * @driver_data: Driver data word for the entry that matched this device with 99 * its driver 100 * @parent: Parent of this device, or NULL for the top level device 101 * @priv: Private data for this device 102 * @uclass: Pointer to uclass for this device 103 * @uclass_priv: The uclass's private data for this device 104 * @parent_priv: The parent's private data for this device 105 * @uclass_node: Used by uclass to link its devices 106 * @child_head: List of children of this device 107 * @sibling_node: Next device in list of all devices 108 * @flags: Flags for this device DM_FLAG_... 109 * @req_seq: Requested sequence number for this device (-1 = any) 110 * @seq: Allocated sequence number for this device (-1 = none). This is set up 111 * when the device is probed and will be unique within the device's uclass. 112 * @devres_head: List of memory allocations associated with this device. 113 * When CONFIG_DEVRES is enabled, devm_kmalloc() and friends will 114 * add to this list. Memory so-allocated will be freed 115 * automatically when the device is removed / unbound 116 */ 117 struct udevice { 118 const struct driver *driver; 119 const char *name; 120 void *platdata; 121 void *parent_platdata; 122 void *uclass_platdata; 123 int of_offset; 124 ulong driver_data; 125 struct udevice *parent; 126 void *priv; 127 struct uclass *uclass; 128 void *uclass_priv; 129 void *parent_priv; 130 struct list_head uclass_node; 131 struct list_head child_head; 132 struct list_head sibling_node; 133 uint32_t flags; 134 int req_seq; 135 int seq; 136 #ifdef CONFIG_DEVRES 137 struct list_head devres_head; 138 #endif 139 }; 140 141 /* Maximum sequence number supported */ 142 #define DM_MAX_SEQ 999 143 144 /* Returns the operations for a device */ 145 #define device_get_ops(dev) (dev->driver->ops) 146 147 /* Returns non-zero if the device is active (probed and not removed) */ 148 #define device_active(dev) ((dev)->flags & DM_FLAG_ACTIVATED) 149 150 static inline int dev_of_offset(const struct udevice *dev) 151 { 152 return dev->of_offset; 153 } 154 155 static inline void dev_set_of_offset(struct udevice *dev, int of_offset) 156 { 157 dev->of_offset = of_offset; 158 } 159 160 /** 161 * struct udevice_id - Lists the compatible strings supported by a driver 162 * @compatible: Compatible string 163 * @data: Data for this compatible string 164 */ 165 struct udevice_id { 166 const char *compatible; 167 ulong data; 168 }; 169 170 #if CONFIG_IS_ENABLED(OF_CONTROL) 171 #define of_match_ptr(_ptr) (_ptr) 172 #else 173 #define of_match_ptr(_ptr) NULL 174 #endif /* CONFIG_IS_ENABLED(OF_CONTROL) */ 175 176 /** 177 * struct driver - A driver for a feature or peripheral 178 * 179 * This holds methods for setting up a new device, and also removing it. 180 * The device needs information to set itself up - this is provided either 181 * by platdata or a device tree node (which we find by looking up 182 * matching compatible strings with of_match). 183 * 184 * Drivers all belong to a uclass, representing a class of devices of the 185 * same type. Common elements of the drivers can be implemented in the uclass, 186 * or the uclass can provide a consistent interface to the drivers within 187 * it. 188 * 189 * @name: Device name 190 * @id: Identiies the uclass we belong to 191 * @of_match: List of compatible strings to match, and any identifying data 192 * for each. 193 * @bind: Called to bind a device to its driver 194 * @probe: Called to probe a device, i.e. activate it 195 * @remove: Called to remove a device, i.e. de-activate it 196 * @unbind: Called to unbind a device from its driver 197 * @ofdata_to_platdata: Called before probe to decode device tree data 198 * @child_post_bind: Called after a new child has been bound 199 * @child_pre_probe: Called before a child device is probed. The device has 200 * memory allocated but it has not yet been probed. 201 * @child_post_remove: Called after a child device is removed. The device 202 * has memory allocated but its device_remove() method has been called. 203 * @priv_auto_alloc_size: If non-zero this is the size of the private data 204 * to be allocated in the device's ->priv pointer. If zero, then the driver 205 * is responsible for allocating any data required. 206 * @platdata_auto_alloc_size: If non-zero this is the size of the 207 * platform data to be allocated in the device's ->platdata pointer. 208 * This is typically only useful for device-tree-aware drivers (those with 209 * an of_match), since drivers which use platdata will have the data 210 * provided in the U_BOOT_DEVICE() instantiation. 211 * @per_child_auto_alloc_size: Each device can hold private data owned by 212 * its parent. If required this will be automatically allocated if this 213 * value is non-zero. 214 * @per_child_platdata_auto_alloc_size: A bus likes to store information about 215 * its children. If non-zero this is the size of this data, to be allocated 216 * in the child's parent_platdata pointer. 217 * @ops: Driver-specific operations. This is typically a list of function 218 * pointers defined by the driver, to implement driver functions required by 219 * the uclass. 220 * @flags: driver flags - see DM_FLAGS_... 221 */ 222 struct driver { 223 char *name; 224 enum uclass_id id; 225 const struct udevice_id *of_match; 226 int (*bind)(struct udevice *dev); 227 int (*probe)(struct udevice *dev); 228 int (*remove)(struct udevice *dev); 229 int (*unbind)(struct udevice *dev); 230 int (*ofdata_to_platdata)(struct udevice *dev); 231 int (*child_post_bind)(struct udevice *dev); 232 int (*child_pre_probe)(struct udevice *dev); 233 int (*child_post_remove)(struct udevice *dev); 234 int priv_auto_alloc_size; 235 int platdata_auto_alloc_size; 236 int per_child_auto_alloc_size; 237 int per_child_platdata_auto_alloc_size; 238 const void *ops; /* driver-specific operations */ 239 uint32_t flags; 240 }; 241 242 /* Declare a new U-Boot driver */ 243 #define U_BOOT_DRIVER(__name) \ 244 ll_entry_declare(struct driver, __name, driver) 245 246 /* Get a pointer to a given driver */ 247 #define DM_GET_DRIVER(__name) \ 248 ll_entry_get(struct driver, __name, driver) 249 250 /** 251 * dev_get_platdata() - Get the platform data for a device 252 * 253 * This checks that dev is not NULL, but no other checks for now 254 * 255 * @dev Device to check 256 * @return platform data, or NULL if none 257 */ 258 void *dev_get_platdata(struct udevice *dev); 259 260 /** 261 * dev_get_parent_platdata() - Get the parent platform data for a device 262 * 263 * This checks that dev is not NULL, but no other checks for now 264 * 265 * @dev Device to check 266 * @return parent's platform data, or NULL if none 267 */ 268 void *dev_get_parent_platdata(struct udevice *dev); 269 270 /** 271 * dev_get_uclass_platdata() - Get the uclass platform data for a device 272 * 273 * This checks that dev is not NULL, but no other checks for now 274 * 275 * @dev Device to check 276 * @return uclass's platform data, or NULL if none 277 */ 278 void *dev_get_uclass_platdata(struct udevice *dev); 279 280 /** 281 * dev_get_priv() - Get the private data for a device 282 * 283 * This checks that dev is not NULL, but no other checks for now 284 * 285 * @dev Device to check 286 * @return private data, or NULL if none 287 */ 288 void *dev_get_priv(struct udevice *dev); 289 290 /** 291 * dev_get_parent_priv() - Get the parent private data for a device 292 * 293 * The parent private data is data stored in the device but owned by the 294 * parent. For example, a USB device may have parent data which contains 295 * information about how to talk to the device over USB. 296 * 297 * This checks that dev is not NULL, but no other checks for now 298 * 299 * @dev Device to check 300 * @return parent data, or NULL if none 301 */ 302 void *dev_get_parent_priv(struct udevice *dev); 303 304 /** 305 * dev_get_uclass_priv() - Get the private uclass data for a device 306 * 307 * This checks that dev is not NULL, but no other checks for now 308 * 309 * @dev Device to check 310 * @return private uclass data for this device, or NULL if none 311 */ 312 void *dev_get_uclass_priv(struct udevice *dev); 313 314 /** 315 * struct dev_get_parent() - Get the parent of a device 316 * 317 * @child: Child to check 318 * @return parent of child, or NULL if this is the root device 319 */ 320 struct udevice *dev_get_parent(struct udevice *child); 321 322 /** 323 * dev_get_driver_data() - get the driver data used to bind a device 324 * 325 * When a device is bound using a device tree node, it matches a 326 * particular compatible string in struct udevice_id. This function 327 * returns the associated data value for that compatible string. This is 328 * the 'data' field in struct udevice_id. 329 * 330 * As an example, consider this structure: 331 * static const struct udevice_id tegra_i2c_ids[] = { 332 * { .compatible = "nvidia,tegra114-i2c", .data = TYPE_114 }, 333 * { .compatible = "nvidia,tegra20-i2c", .data = TYPE_STD }, 334 * { .compatible = "nvidia,tegra20-i2c-dvc", .data = TYPE_DVC }, 335 * { } 336 * }; 337 * 338 * When driver model finds a driver for this it will store the 'data' value 339 * corresponding to the compatible string it matches. This function returns 340 * that value. This allows the driver to handle several variants of a device. 341 * 342 * For USB devices, this is the driver_info field in struct usb_device_id. 343 * 344 * @dev: Device to check 345 * @return driver data (0 if none is provided) 346 */ 347 ulong dev_get_driver_data(struct udevice *dev); 348 349 /** 350 * dev_get_driver_ops() - get the device's driver's operations 351 * 352 * This checks that dev is not NULL, and returns the pointer to device's 353 * driver's operations. 354 * 355 * @dev: Device to check 356 * @return void pointer to driver's operations or NULL for NULL-dev or NULL-ops 357 */ 358 const void *dev_get_driver_ops(struct udevice *dev); 359 360 /** 361 * device_get_uclass_id() - return the uclass ID of a device 362 * 363 * @dev: Device to check 364 * @return uclass ID for the device 365 */ 366 enum uclass_id device_get_uclass_id(struct udevice *dev); 367 368 /** 369 * dev_get_uclass_name() - return the uclass name of a device 370 * 371 * This checks that dev is not NULL. 372 * 373 * @dev: Device to check 374 * @return pointer to the uclass name for the device 375 */ 376 const char *dev_get_uclass_name(struct udevice *dev); 377 378 /** 379 * device_get_child() - Get the child of a device by index 380 * 381 * Returns the numbered child, 0 being the first. This does not use 382 * sequence numbers, only the natural order. 383 * 384 * @dev: Parent device to check 385 * @index: Child index 386 * @devp: Returns pointer to device 387 * @return 0 if OK, -ENODEV if no such device, other error if the device fails 388 * to probe 389 */ 390 int device_get_child(struct udevice *parent, int index, struct udevice **devp); 391 392 /** 393 * device_find_child_by_seq() - Find a child device based on a sequence 394 * 395 * This searches for a device with the given seq or req_seq. 396 * 397 * For seq, if an active device has this sequence it will be returned. 398 * If there is no such device then this will return -ENODEV. 399 * 400 * For req_seq, if a device (whether activated or not) has this req_seq 401 * value, that device will be returned. This is a strong indication that 402 * the device will receive that sequence when activated. 403 * 404 * @parent: Parent device 405 * @seq_or_req_seq: Sequence number to find (0=first) 406 * @find_req_seq: true to find req_seq, false to find seq 407 * @devp: Returns pointer to device (there is only one per for each seq). 408 * Set to NULL if none is found 409 * @return 0 if OK, -ve on error 410 */ 411 int device_find_child_by_seq(struct udevice *parent, int seq_or_req_seq, 412 bool find_req_seq, struct udevice **devp); 413 414 /** 415 * device_get_child_by_seq() - Get a child device based on a sequence 416 * 417 * If an active device has this sequence it will be returned. If there is no 418 * such device then this will check for a device that is requesting this 419 * sequence. 420 * 421 * The device is probed to activate it ready for use. 422 * 423 * @parent: Parent device 424 * @seq: Sequence number to find (0=first) 425 * @devp: Returns pointer to device (there is only one per for each seq) 426 * Set to NULL if none is found 427 * @return 0 if OK, -ve on error 428 */ 429 int device_get_child_by_seq(struct udevice *parent, int seq, 430 struct udevice **devp); 431 432 /** 433 * device_find_child_by_of_offset() - Find a child device based on FDT offset 434 * 435 * Locates a child device by its device tree offset. 436 * 437 * @parent: Parent device 438 * @of_offset: Device tree offset to find 439 * @devp: Returns pointer to device if found, otherwise this is set to NULL 440 * @return 0 if OK, -ve on error 441 */ 442 int device_find_child_by_of_offset(struct udevice *parent, int of_offset, 443 struct udevice **devp); 444 445 /** 446 * device_get_child_by_of_offset() - Get a child device based on FDT offset 447 * 448 * Locates a child device by its device tree offset. 449 * 450 * The device is probed to activate it ready for use. 451 * 452 * @parent: Parent device 453 * @of_offset: Device tree offset to find 454 * @devp: Returns pointer to device if found, otherwise this is set to NULL 455 * @return 0 if OK, -ve on error 456 */ 457 int device_get_child_by_of_offset(struct udevice *parent, int of_offset, 458 struct udevice **devp); 459 460 /** 461 * device_get_global_by_of_offset() - Get a device based on FDT offset 462 * 463 * Locates a device by its device tree offset, searching globally throughout 464 * the all driver model devices. 465 * 466 * The device is probed to activate it ready for use. 467 * 468 * @of_offset: Device tree offset to find 469 * @devp: Returns pointer to device if found, otherwise this is set to NULL 470 * @return 0 if OK, -ve on error 471 */ 472 int device_get_global_by_of_offset(int of_offset, struct udevice **devp); 473 474 /** 475 * device_find_first_child() - Find the first child of a device 476 * 477 * @parent: Parent device to search 478 * @devp: Returns first child device, or NULL if none 479 * @return 0 480 */ 481 int device_find_first_child(struct udevice *parent, struct udevice **devp); 482 483 /** 484 * device_find_next_child() - Find the next child of a device 485 * 486 * @devp: Pointer to previous child device on entry. Returns pointer to next 487 * child device, or NULL if none 488 * @return 0 489 */ 490 int device_find_next_child(struct udevice **devp); 491 492 /** 493 * dev_get_addr() - Get the reg property of a device 494 * 495 * @dev: Pointer to a device 496 * 497 * @return addr 498 */ 499 fdt_addr_t dev_get_addr(struct udevice *dev); 500 501 /** 502 * dev_get_addr_ptr() - Return pointer to the address of the reg property 503 * of a device 504 * 505 * @dev: Pointer to a device 506 * 507 * @return Pointer to addr, or NULL if there is no such property 508 */ 509 void *dev_get_addr_ptr(struct udevice *dev); 510 511 /** 512 * dev_map_physmem() - Read device address from reg property of the 513 * device node and map the address into CPU address 514 * space. 515 * 516 * @dev: Pointer to device 517 * @size: size of the memory to map 518 * 519 * @return mapped address, or NULL if the device does not have reg 520 * property. 521 */ 522 void *dev_map_physmem(struct udevice *dev, unsigned long size); 523 524 /** 525 * dev_get_addr_index() - Get the indexed reg property of a device 526 * 527 * @dev: Pointer to a device 528 * @index: the 'reg' property can hold a list of <addr, size> pairs 529 * and @index is used to select which one is required 530 * 531 * @return addr 532 */ 533 fdt_addr_t dev_get_addr_index(struct udevice *dev, int index); 534 535 /** 536 * dev_get_addr_size_index() - Get the indexed reg property of a device 537 * 538 * Returns the address and size specified in the 'reg' property of a device. 539 * 540 * @dev: Pointer to a device 541 * @index: the 'reg' property can hold a list of <addr, size> pairs 542 * and @index is used to select which one is required 543 * @size: Pointer to size varible - this function returns the size 544 * specified in the 'reg' property here 545 * 546 * @return addr 547 */ 548 fdt_addr_t dev_get_addr_size_index(struct udevice *dev, int index, 549 fdt_size_t *size); 550 551 /** 552 * dev_get_addr_name() - Get the reg property of a device, indexed by name 553 * 554 * @dev: Pointer to a device 555 * @name: the 'reg' property can hold a list of <addr, size> pairs, with the 556 * 'reg-names' property providing named-based identification. @index 557 * indicates the value to search for in 'reg-names'. 558 * 559 * @return addr 560 */ 561 fdt_addr_t dev_get_addr_name(struct udevice *dev, const char *name); 562 563 /** 564 * device_has_children() - check if a device has any children 565 * 566 * @dev: Device to check 567 * @return true if the device has one or more children 568 */ 569 bool device_has_children(struct udevice *dev); 570 571 /** 572 * device_has_active_children() - check if a device has any active children 573 * 574 * @dev: Device to check 575 * @return true if the device has one or more children and at least one of 576 * them is active (probed). 577 */ 578 bool device_has_active_children(struct udevice *dev); 579 580 /** 581 * device_is_last_sibling() - check if a device is the last sibling 582 * 583 * This function can be useful for display purposes, when special action needs 584 * to be taken when displaying the last sibling. This can happen when a tree 585 * view of devices is being displayed. 586 * 587 * @dev: Device to check 588 * @return true if there are no more siblings after this one - i.e. is it 589 * last in the list. 590 */ 591 bool device_is_last_sibling(struct udevice *dev); 592 593 /** 594 * device_set_name() - set the name of a device 595 * 596 * This must be called in the device's bind() method and no later. Normally 597 * this is unnecessary but for probed devices which don't get a useful name 598 * this function can be helpful. 599 * 600 * The name is allocated and will be freed automatically when the device is 601 * unbound. 602 * 603 * @dev: Device to update 604 * @name: New name (this string is allocated new memory and attached to 605 * the device) 606 * @return 0 if OK, -ENOMEM if there is not enough memory to allocate the 607 * string 608 */ 609 int device_set_name(struct udevice *dev, const char *name); 610 611 /** 612 * device_set_name_alloced() - note that a device name is allocated 613 * 614 * This sets the DM_FLAG_NAME_ALLOCED flag for the device, so that when it is 615 * unbound the name will be freed. This avoids memory leaks. 616 * 617 * @dev: Device to update 618 */ 619 void device_set_name_alloced(struct udevice *dev); 620 621 /** 622 * of_device_is_compatible() - check if the device is compatible with the compat 623 * 624 * This allows to check whether the device is comaptible with the compat. 625 * 626 * @dev: udevice pointer for which compatible needs to be verified. 627 * @compat: Compatible string which needs to verified in the given 628 * device 629 * @return true if OK, false if the compatible is not found 630 */ 631 bool of_device_is_compatible(struct udevice *dev, const char *compat); 632 633 /** 634 * of_machine_is_compatible() - check if the machine is compatible with 635 * the compat 636 * 637 * This allows to check whether the machine is comaptible with the compat. 638 * 639 * @compat: Compatible string which needs to verified 640 * @return true if OK, false if the compatible is not found 641 */ 642 bool of_machine_is_compatible(const char *compat); 643 644 /** 645 * device_is_on_pci_bus - Test if a device is on a PCI bus 646 * 647 * @dev: device to test 648 * @return: true if it is on a PCI bus, false otherwise 649 */ 650 static inline bool device_is_on_pci_bus(struct udevice *dev) 651 { 652 return device_get_uclass_id(dev->parent) == UCLASS_PCI; 653 } 654 655 /** 656 * device_foreach_child_safe() - iterate through child devices safely 657 * 658 * This allows the @pos child to be removed in the loop if required. 659 * 660 * @pos: struct udevice * for the current device 661 * @next: struct udevice * for the next device 662 * @parent: parent device to scan 663 */ 664 #define device_foreach_child_safe(pos, next, parent) \ 665 list_for_each_entry_safe(pos, next, &parent->child_head, sibling_node) 666 667 /** 668 * dm_scan_fdt_dev() - Bind child device in a the device tree 669 * 670 * This handles device which have sub-nodes in the device tree. It scans all 671 * sub-nodes and binds drivers for each node where a driver can be found. 672 * 673 * If this is called prior to relocation, only pre-relocation devices will be 674 * bound (those marked with u-boot,dm-pre-reloc in the device tree, or where 675 * the driver has the DM_FLAG_PRE_RELOC flag set). Otherwise, all devices will 676 * be bound. 677 * 678 * @dev: Device to scan 679 * @return 0 if OK, -ve on error 680 */ 681 int dm_scan_fdt_dev(struct udevice *dev); 682 683 /* device resource management */ 684 typedef void (*dr_release_t)(struct udevice *dev, void *res); 685 typedef int (*dr_match_t)(struct udevice *dev, void *res, void *match_data); 686 687 #ifdef CONFIG_DEVRES 688 689 #ifdef CONFIG_DEBUG_DEVRES 690 void *__devres_alloc(dr_release_t release, size_t size, gfp_t gfp, 691 const char *name); 692 #define _devres_alloc(release, size, gfp) \ 693 __devres_alloc(release, size, gfp, #release) 694 #else 695 void *_devres_alloc(dr_release_t release, size_t size, gfp_t gfp); 696 #endif 697 698 /** 699 * devres_alloc() - Allocate device resource data 700 * @release: Release function devres will be associated with 701 * @size: Allocation size 702 * @gfp: Allocation flags 703 * 704 * Allocate devres of @size bytes. The allocated area is associated 705 * with @release. The returned pointer can be passed to 706 * other devres_*() functions. 707 * 708 * RETURNS: 709 * Pointer to allocated devres on success, NULL on failure. 710 */ 711 #define devres_alloc(release, size, gfp) \ 712 _devres_alloc(release, size, gfp | __GFP_ZERO) 713 714 /** 715 * devres_free() - Free device resource data 716 * @res: Pointer to devres data to free 717 * 718 * Free devres created with devres_alloc(). 719 */ 720 void devres_free(void *res); 721 722 /** 723 * devres_add() - Register device resource 724 * @dev: Device to add resource to 725 * @res: Resource to register 726 * 727 * Register devres @res to @dev. @res should have been allocated 728 * using devres_alloc(). On driver detach, the associated release 729 * function will be invoked and devres will be freed automatically. 730 */ 731 void devres_add(struct udevice *dev, void *res); 732 733 /** 734 * devres_find() - Find device resource 735 * @dev: Device to lookup resource from 736 * @release: Look for resources associated with this release function 737 * @match: Match function (optional) 738 * @match_data: Data for the match function 739 * 740 * Find the latest devres of @dev which is associated with @release 741 * and for which @match returns 1. If @match is NULL, it's considered 742 * to match all. 743 * 744 * @return pointer to found devres, NULL if not found. 745 */ 746 void *devres_find(struct udevice *dev, dr_release_t release, 747 dr_match_t match, void *match_data); 748 749 /** 750 * devres_get() - Find devres, if non-existent, add one atomically 751 * @dev: Device to lookup or add devres for 752 * @new_res: Pointer to new initialized devres to add if not found 753 * @match: Match function (optional) 754 * @match_data: Data for the match function 755 * 756 * Find the latest devres of @dev which has the same release function 757 * as @new_res and for which @match return 1. If found, @new_res is 758 * freed; otherwise, @new_res is added atomically. 759 * 760 * @return ointer to found or added devres. 761 */ 762 void *devres_get(struct udevice *dev, void *new_res, 763 dr_match_t match, void *match_data); 764 765 /** 766 * devres_remove() - Find a device resource and remove it 767 * @dev: Device to find resource from 768 * @release: Look for resources associated with this release function 769 * @match: Match function (optional) 770 * @match_data: Data for the match function 771 * 772 * Find the latest devres of @dev associated with @release and for 773 * which @match returns 1. If @match is NULL, it's considered to 774 * match all. If found, the resource is removed atomically and 775 * returned. 776 * 777 * @return ointer to removed devres on success, NULL if not found. 778 */ 779 void *devres_remove(struct udevice *dev, dr_release_t release, 780 dr_match_t match, void *match_data); 781 782 /** 783 * devres_destroy() - Find a device resource and destroy it 784 * @dev: Device to find resource from 785 * @release: Look for resources associated with this release function 786 * @match: Match function (optional) 787 * @match_data: Data for the match function 788 * 789 * Find the latest devres of @dev associated with @release and for 790 * which @match returns 1. If @match is NULL, it's considered to 791 * match all. If found, the resource is removed atomically and freed. 792 * 793 * Note that the release function for the resource will not be called, 794 * only the devres-allocated data will be freed. The caller becomes 795 * responsible for freeing any other data. 796 * 797 * @return 0 if devres is found and freed, -ENOENT if not found. 798 */ 799 int devres_destroy(struct udevice *dev, dr_release_t release, 800 dr_match_t match, void *match_data); 801 802 /** 803 * devres_release() - Find a device resource and destroy it, calling release 804 * @dev: Device to find resource from 805 * @release: Look for resources associated with this release function 806 * @match: Match function (optional) 807 * @match_data: Data for the match function 808 * 809 * Find the latest devres of @dev associated with @release and for 810 * which @match returns 1. If @match is NULL, it's considered to 811 * match all. If found, the resource is removed atomically, the 812 * release function called and the resource freed. 813 * 814 * @return 0 if devres is found and freed, -ENOENT if not found. 815 */ 816 int devres_release(struct udevice *dev, dr_release_t release, 817 dr_match_t match, void *match_data); 818 819 /* managed devm_k.alloc/kfree for device drivers */ 820 /** 821 * devm_kmalloc() - Resource-managed kmalloc 822 * @dev: Device to allocate memory for 823 * @size: Allocation size 824 * @gfp: Allocation gfp flags 825 * 826 * Managed kmalloc. Memory allocated with this function is 827 * automatically freed on driver detach. Like all other devres 828 * resources, guaranteed alignment is unsigned long long. 829 * 830 * @return pointer to allocated memory on success, NULL on failure. 831 */ 832 void *devm_kmalloc(struct udevice *dev, size_t size, gfp_t gfp); 833 static inline void *devm_kzalloc(struct udevice *dev, size_t size, gfp_t gfp) 834 { 835 return devm_kmalloc(dev, size, gfp | __GFP_ZERO); 836 } 837 static inline void *devm_kmalloc_array(struct udevice *dev, 838 size_t n, size_t size, gfp_t flags) 839 { 840 if (size != 0 && n > SIZE_MAX / size) 841 return NULL; 842 return devm_kmalloc(dev, n * size, flags); 843 } 844 static inline void *devm_kcalloc(struct udevice *dev, 845 size_t n, size_t size, gfp_t flags) 846 { 847 return devm_kmalloc_array(dev, n, size, flags | __GFP_ZERO); 848 } 849 850 /** 851 * devm_kfree() - Resource-managed kfree 852 * @dev: Device this memory belongs to 853 * @ptr: Memory to free 854 * 855 * Free memory allocated with devm_kmalloc(). 856 */ 857 void devm_kfree(struct udevice *dev, void *ptr); 858 859 #else /* ! CONFIG_DEVRES */ 860 861 static inline void *devres_alloc(dr_release_t release, size_t size, gfp_t gfp) 862 { 863 return kzalloc(size, gfp); 864 } 865 866 static inline void devres_free(void *res) 867 { 868 kfree(res); 869 } 870 871 static inline void devres_add(struct udevice *dev, void *res) 872 { 873 } 874 875 static inline void *devres_find(struct udevice *dev, dr_release_t release, 876 dr_match_t match, void *match_data) 877 { 878 return NULL; 879 } 880 881 static inline void *devres_get(struct udevice *dev, void *new_res, 882 dr_match_t match, void *match_data) 883 { 884 return NULL; 885 } 886 887 static inline void *devres_remove(struct udevice *dev, dr_release_t release, 888 dr_match_t match, void *match_data) 889 { 890 return NULL; 891 } 892 893 static inline int devres_destroy(struct udevice *dev, dr_release_t release, 894 dr_match_t match, void *match_data) 895 { 896 return 0; 897 } 898 899 static inline int devres_release(struct udevice *dev, dr_release_t release, 900 dr_match_t match, void *match_data) 901 { 902 return 0; 903 } 904 905 static inline void *devm_kmalloc(struct udevice *dev, size_t size, gfp_t gfp) 906 { 907 return kmalloc(size, gfp); 908 } 909 910 static inline void *devm_kzalloc(struct udevice *dev, size_t size, gfp_t gfp) 911 { 912 return kzalloc(size, gfp); 913 } 914 915 static inline void *devm_kmaloc_array(struct udevice *dev, 916 size_t n, size_t size, gfp_t flags) 917 { 918 /* TODO: add kmalloc_array() to linux/compat.h */ 919 if (size != 0 && n > SIZE_MAX / size) 920 return NULL; 921 return kmalloc(n * size, flags); 922 } 923 924 static inline void *devm_kcalloc(struct udevice *dev, 925 size_t n, size_t size, gfp_t flags) 926 { 927 /* TODO: add kcalloc() to linux/compat.h */ 928 return kmalloc(n * size, flags | __GFP_ZERO); 929 } 930 931 static inline void devm_kfree(struct udevice *dev, void *ptr) 932 { 933 kfree(ptr); 934 } 935 936 #endif /* ! CONFIG_DEVRES */ 937 938 /** 939 * dm_set_translation_offset() - Set translation offset 940 * @offs: Translation offset 941 * 942 * Some platforms need a special address translation. Those 943 * platforms (e.g. mvebu in SPL) can configure a translation 944 * offset in the DM by calling this function. It will be 945 * added to all addresses returned in dev_get_addr(). 946 */ 947 void dm_set_translation_offset(fdt_addr_t offs); 948 949 /** 950 * dm_get_translation_offset() - Get translation offset 951 * 952 * This function returns the translation offset that can 953 * be configured by calling dm_set_translation_offset(). 954 * 955 * @return translation offset for the device address (0 as default). 956 */ 957 fdt_addr_t dm_get_translation_offset(void); 958 959 #endif 960