include/dm/device.h

   1 /*
   2  * Copyright (c) 2013 Google, Inc
   3  *
   4  * (C) Copyright 2012
   5  * Pavel Herrmann <[email protected]>
   6  * Marek Vasut <[email protected]>
   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 /**
  45  * struct udevice - An instance of a driver
  46  *
  47  * This holds information about a device, which is a driver bound to a
  48  * particular port or peripheral (essentially a driver instance).
  49  *
  50  * A device will come into existence through a 'bind' call, either due to
  51  * a U_BOOT_DEVICE() macro (in which case platdata is non-NULL) or a node
  52  * in the device tree (in which case of_offset is >= 0). In the latter case
  53  * we translate the device tree information into platdata in a function
  54  * implemented by the driver ofdata_to_platdata method (called just before the
  55  * probe method if the device has a device tree node.
  56  *
  57  * All three of platdata, priv and uclass_priv can be allocated by the
  58  * driver, or you can use the auto_alloc_size members of struct driver and
  59  * struct uclass_driver to have driver model do this automatically.
  60  *
  61  * @driver: The driver used by this device
  62  * @name: Name of device, typically the FDT node name
  63  * @platdata: Configuration data for this device
  64  * @parent_platdata: The parent bus's configuration data for this device
  65  * @uclass_platdata: The uclass's configuration data for this device
  66  * @of_offset: Device tree node offset for this device (- for none)
  67  * @driver_data: Driver data word for the entry that matched this device with
  68  *              its driver
  69  * @parent: Parent of this device, or NULL for the top level device
  70  * @priv: Private data for this device
  71  * @uclass: Pointer to uclass for this device
  72  * @uclass_priv: The uclass's private data for this device
  73  * @parent_priv: The parent's private data for this device
  74  * @uclass_node: Used by uclass to link its devices
  75  * @child_head: List of children of this device
  76  * @sibling_node: Next device in list of all devices
  77  * @flags: Flags for this device DM_FLAG_...
  78  * @req_seq: Requested sequence number for this device (-1 = any)
  79  * @seq: Allocated sequence number for this device (-1 = none). This is set up
  80  * when the device is probed and will be unique within the device's uclass.
  81  */
  82 struct udevice {
  83         const struct driver *driver;
  84         const char *name;
  85         void *platdata;
  86         void *parent_platdata;
  87         void *uclass_platdata;
  88         int of_offset;
  89         ulong driver_data;
  90         struct udevice *parent;
  91         void *priv;
  92         struct uclass *uclass;
  93         void *uclass_priv;
  94         void *parent_priv;
  95         struct list_head uclass_node;
  96         struct list_head child_head;
  97         struct list_head sibling_node;
  98         uint32_t flags;
  99         int req_seq;
 100         int seq;
 101         struct list_head devres_head;
 102 };
 103
 104 /* Maximum sequence number supported */
 105 #define DM_MAX_SEQ      999
 106
 107 /* Returns the operations for a device */
 108 #define device_get_ops(dev)     (dev->driver->ops)
 109
 110 /* Returns non-zero if the device is active (probed and not removed) */
 111 #define device_active(dev)      ((dev)->flags & DM_FLAG_ACTIVATED)
 112
 113 /**
 114  * struct udevice_id - Lists the compatible strings supported by a driver
 115  * @compatible: Compatible string
 116  * @data: Data for this compatible string
 117  */
 118 struct udevice_id {
 119         const char *compatible;
 120         ulong data;
 121 };
 122
 123 #ifdef CONFIG_OF_CONTROL
 124 #define of_match_ptr(_ptr)      (_ptr)
 125 #else
 126 #define of_match_ptr(_ptr)      NULL
 127 #endif /* CONFIG_OF_CONTROL */
 128
 129 /**
 130  * struct driver - A driver for a feature or peripheral
 131  *
 132  * This holds methods for setting up a new device, and also removing it.
 133  * The device needs information to set itself up - this is provided either
 134  * by platdata or a device tree node (which we find by looking up
 135  * matching compatible strings with of_match).
 136  *
 137  * Drivers all belong to a uclass, representing a class of devices of the
 138  * same type. Common elements of the drivers can be implemented in the uclass,
 139  * or the uclass can provide a consistent interface to the drivers within
 140  * it.
 141  *
 142  * @name: Device name
 143  * @id: Identiies the uclass we belong to
 144  * @of_match: List of compatible strings to match, and any identifying data
 145  * for each.
 146  * @bind: Called to bind a device to its driver
 147  * @probe: Called to probe a device, i.e. activate it
 148  * @remove: Called to remove a device, i.e. de-activate it
 149  * @unbind: Called to unbind a device from its driver
 150  * @ofdata_to_platdata: Called before probe to decode device tree data
 151  * @child_post_bind: Called after a new child has been bound
 152  * @child_pre_probe: Called before a child device is probed. The device has
 153  * memory allocated but it has not yet been probed.
 154  * @child_post_remove: Called after a child device is removed. The device
 155  * has memory allocated but its device_remove() method has been called.
 156  * @priv_auto_alloc_size: If non-zero this is the size of the private data
 157  * to be allocated in the device's ->priv pointer. If zero, then the driver
 158  * is responsible for allocating any data required.
 159  * @platdata_auto_alloc_size: If non-zero this is the size of the
 160  * platform data to be allocated in the device's ->platdata pointer.
 161  * This is typically only useful for device-tree-aware drivers (those with
 162  * an of_match), since drivers which use platdata will have the data
 163  * provided in the U_BOOT_DEVICE() instantiation.
 164  * @per_child_auto_alloc_size: Each device can hold private data owned by
 165  * its parent. If required this will be automatically allocated if this
 166  * value is non-zero.
 167  * TODO([email protected]): I'm considering dropping this, and just having
 168  * device_probe_child() pass it in. So far the use case for allocating it
 169  * is SPI, but I found that unsatisfactory. Since it is here I will leave it
 170  * until things are clearer.
 171  * @per_child_platdata_auto_alloc_size: A bus likes to store information about
 172  * its children. If non-zero this is the size of this data, to be allocated
 173  * in the child's parent_platdata pointer.
 174  * @ops: Driver-specific operations. This is typically a list of function
 175  * pointers defined by the driver, to implement driver functions required by
 176  * the uclass.
 177  * @flags: driver flags - see DM_FLAGS_...
 178  */
 179 struct driver {
 180         char *name;
 181         enum uclass_id id;
 182         const struct udevice_id *of_match;
 183         int (*bind)(struct udevice *dev);
 184         int (*probe)(struct udevice *dev);
 185         int (*remove)(struct udevice *dev);
 186         int (*unbind)(struct udevice *dev);
 187         int (*ofdata_to_platdata)(struct udevice *dev);
 188         int (*child_post_bind)(struct udevice *dev);
 189         int (*child_pre_probe)(struct udevice *dev);
 190         int (*child_post_remove)(struct udevice *dev);
 191         int priv_auto_alloc_size;
 192         int platdata_auto_alloc_size;
 193         int per_child_auto_alloc_size;
 194         int per_child_platdata_auto_alloc_size;
 195         const void *ops;        /* driver-specific operations */
 196         uint32_t flags;
 197 };
 198
 199 /* Declare a new U-Boot driver */
 200 #define U_BOOT_DRIVER(__name)                                           \
 201         ll_entry_declare(struct driver, __name, driver)
 202
 203 /**
 204  * dev_get_platdata() - Get the platform data for a device
 205  *
 206  * This checks that dev is not NULL, but no other checks for now
 207  *
 208  * @dev         Device to check
 209  * @return platform data, or NULL if none
 210  */
 211 void *dev_get_platdata(struct udevice *dev);
 212
 213 /**
 214  * dev_get_parent_platdata() - Get the parent platform data for a device
 215  *
 216  * This checks that dev is not NULL, but no other checks for now
 217  *
 218  * @dev         Device to check
 219  * @return parent's platform data, or NULL if none
 220  */
 221 void *dev_get_parent_platdata(struct udevice *dev);
 222
 223 /**
 224  * dev_get_uclass_platdata() - Get the uclass platform data for a device
 225  *
 226  * This checks that dev is not NULL, but no other checks for now
 227  *
 228  * @dev         Device to check
 229  * @return uclass's platform data, or NULL if none
 230  */
 231 void *dev_get_uclass_platdata(struct udevice *dev);
 232
 233 /**
 234  * dev_get_parentdata() - Get the parent data for a device
 235  *
 236  * The parent data is data stored in the device but owned by the parent.
 237  * For example, a USB device may have parent data which contains information
 238  * about how to talk to the device over USB.
 239  *
 240  * This checks that dev is not NULL, but no other checks for now
 241  *
 242  * @dev         Device to check
 243  * @return parent data, or NULL if none
 244  */
 245 void *dev_get_parentdata(struct udevice *dev);
 246
 247 /**
 248  * dev_get_priv() - Get the private data for a device
 249  *
 250  * This checks that dev is not NULL, but no other checks for now
 251  *
 252  * @dev         Device to check
 253  * @return private data, or NULL if none
 254  */
 255 void *dev_get_priv(struct udevice *dev);
 256
 257 /**
 258  * struct dev_get_parent() - Get the parent of a device
 259  *
 260  * @child:      Child to check
 261  * @return parent of child, or NULL if this is the root device
 262  */
 263 struct udevice *dev_get_parent(struct udevice *child);
 264
 265 /**
 266  * dev_get_uclass_priv() - Get the private uclass data for a device
 267  *
 268  * This checks that dev is not NULL, but no other checks for now
 269  *
 270  * @dev         Device to check
 271  * @return private uclass data for this device, or NULL if none
 272  */
 273 void *dev_get_uclass_priv(struct udevice *dev);
 274
 275 /**
 276  * dev_get_driver_data() - get the driver data used to bind a device
 277  *
 278  * When a device is bound using a device tree node, it matches a
 279  * particular compatible string as in struct udevice_id. This function
 280  * returns the associated data value for that compatible string. This is
 281  * the 'data' field in struct udevice_id.
 282  *
 283  * For USB devices, this is the driver_info field in struct usb_device_id.
 284  *
 285  * @dev:        Device to check
 286  */
 287 ulong dev_get_driver_data(struct udevice *dev);
 288
 289 /**
 290  * dev_get_driver_ops() - get the device's driver's operations
 291  *
 292  * This checks that dev is not NULL, and returns the pointer to device's
 293  * driver's operations.
 294  *
 295  * @dev:        Device to check
 296  * @return void pointer to driver's operations or NULL for NULL-dev or NULL-ops
 297  */
 298 const void *dev_get_driver_ops(struct udevice *dev);
 299
 300 /*
 301  * device_get_uclass_id() - return the uclass ID of a device
 302  *
 303  * @dev:        Device to check
 304  * @return uclass ID for the device
 305  */
 306 enum uclass_id device_get_uclass_id(struct udevice *dev);
 307
 308 /*
 309  * dev_get_uclass_name() - return the uclass name of a device
 310  *
 311  * This checks that dev is not NULL.
 312  *
 313  * @dev:        Device to check
 314  * @return  pointer to the uclass name for the device
 315  */
 316 const char *dev_get_uclass_name(struct udevice *dev);
 317
 318 /**
 319  * device_get_child() - Get the child of a device by index
 320  *
 321  * Returns the numbered child, 0 being the first. This does not use
 322  * sequence numbers, only the natural order.
 323  *
 324  * @dev:        Parent device to check
 325  * @index:      Child index
 326  * @devp:       Returns pointer to device
 327  * @return 0 if OK, -ENODEV if no such device, other error if the device fails
 328  *         to probe
 329  */
 330 int device_get_child(struct udevice *parent, int index, struct udevice **devp);
 331
 332 /**
 333  * device_find_child_by_seq() - Find a child device based on a sequence
 334  *
 335  * This searches for a device with the given seq or req_seq.
 336  *
 337  * For seq, if an active device has this sequence it will be returned.
 338  * If there is no such device then this will return -ENODEV.
 339  *
 340  * For req_seq, if a device (whether activated or not) has this req_seq
 341  * value, that device will be returned. This is a strong indication that
 342  * the device will receive that sequence when activated.
 343  *
 344  * @parent: Parent device
 345  * @seq_or_req_seq: Sequence number to find (0=first)
 346  * @find_req_seq: true to find req_seq, false to find seq
 347  * @devp: Returns pointer to device (there is only one per for each seq).
 348  * Set to NULL if none is found
 349  * @return 0 if OK, -ve on error
 350  */
 351 int device_find_child_by_seq(struct udevice *parent, int seq_or_req_seq,
 352                              bool find_req_seq, struct udevice **devp);
 353
 354 /**
 355  * device_get_child_by_seq() - Get a child device based on a sequence
 356  *
 357  * If an active device has this sequence it will be returned. If there is no
 358  * such device then this will check for a device that is requesting this
 359  * sequence.
 360  *
 361  * The device is probed to activate it ready for use.
 362  *
 363  * @parent: Parent device
 364  * @seq: Sequence number to find (0=first)
 365  * @devp: Returns pointer to device (there is only one per for each seq)
 366  * Set to NULL if none is found
 367  * @return 0 if OK, -ve on error
 368  */
 369 int device_get_child_by_seq(struct udevice *parent, int seq,
 370                             struct udevice **devp);
 371
 372 /**
 373  * device_find_child_by_of_offset() - Find a child device based on FDT offset
 374  *
 375  * Locates a child device by its device tree offset.
 376  *
 377  * @parent: Parent device
 378  * @of_offset: Device tree offset to find
 379  * @devp: Returns pointer to device if found, otherwise this is set to NULL
 380  * @return 0 if OK, -ve on error
 381  */
 382 int device_find_child_by_of_offset(struct udevice *parent, int of_offset,
 383                                    struct udevice **devp);
 384
 385 /**
 386  * device_get_child_by_of_offset() - Get a child device based on FDT offset
 387  *
 388  * Locates a child device by its device tree offset.
 389  *
 390  * The device is probed to activate it ready for use.
 391  *
 392  * @parent: Parent device
 393  * @of_offset: Device tree offset to find
 394  * @devp: Returns pointer to device if found, otherwise this is set to NULL
 395  * @return 0 if OK, -ve on error
 396  */
 397 int device_get_child_by_of_offset(struct udevice *parent, int of_offset,
 398                                   struct udevice **devp);
 399
 400 /**
 401  * device_get_global_by_of_offset() - Get a device based on FDT offset
 402  *
 403  * Locates a device by its device tree offset, searching globally throughout
 404  * the all driver model devices.
 405  *
 406  * The device is probed to activate it ready for use.
 407  *
 408  * @of_offset: Device tree offset to find
 409  * @devp: Returns pointer to device if found, otherwise this is set to NULL
 410  * @return 0 if OK, -ve on error
 411  */
 412 int device_get_global_by_of_offset(int of_offset, struct udevice **devp);
 413
 414 /**
 415  * device_find_first_child() - Find the first child of a device
 416  *
 417  * @parent: Parent device to search
 418  * @devp: Returns first child device, or NULL if none
 419  * @return 0
 420  */
 421 int device_find_first_child(struct udevice *parent, struct udevice **devp);
 422
 423 /**
 424  * device_find_next_child() - Find the next child of a device
 425  *
 426  * @devp: Pointer to previous child device on entry. Returns pointer to next
 427  *              child device, or NULL if none
 428  * @return 0
 429  */
 430 int device_find_next_child(struct udevice **devp);
 431
 432 /**
 433  * dev_get_addr() - Get the reg property of a device
 434  *
 435  * @dev: Pointer to a device
 436  *
 437  * @return addr
 438  */
 439 fdt_addr_t dev_get_addr(struct udevice *dev);
 440
 441 /**
 442  * device_has_children() - check if a device has any children
 443  *
 444  * @dev:        Device to check
 445  * @return true if the device has one or more children
 446  */
 447 bool device_has_children(struct udevice *dev);
 448
 449 /**
 450  * device_has_active_children() - check if a device has any active children
 451  *
 452  * @dev:        Device to check
 453  * @return true if the device has one or more children and at least one of
 454  * them is active (probed).
 455  */
 456 bool device_has_active_children(struct udevice *dev);
 457
 458 /**
 459  * device_is_last_sibling() - check if a device is the last sibling
 460  *
 461  * This function can be useful for display purposes, when special action needs
 462  * to be taken when displaying the last sibling. This can happen when a tree
 463  * view of devices is being displayed.
 464  *
 465  * @dev:        Device to check
 466  * @return true if there are no more siblings after this one - i.e. is it
 467  * last in the list.
 468  */
 469 bool device_is_last_sibling(struct udevice *dev);
 470
 471 /* device resource management */
 472 typedef void (*dr_release_t)(struct udevice *dev, void *res);
 473 typedef int (*dr_match_t)(struct udevice *dev, void *res, void *match_data);
 474
 475 #ifdef CONFIG_DEBUG_DEVRES
 476 void *__devres_alloc(dr_release_t release, size_t size, gfp_t gfp,
 477                      const char *name);
 478 #define _devres_alloc(release, size, gfp) \
 479         __devres_alloc(release, size, gfp, #release)
 480 #else
 481 void *_devres_alloc(dr_release_t release, size_t size, gfp_t gfp);
 482 #endif
 483
 484 /**
 485  * devres_alloc - Allocate device resource data
 486  * @release: Release function devres will be associated with
 487  * @size: Allocation size
 488  * @gfp: Allocation flags
 489  *
 490  * Allocate devres of @size bytes.  The allocated area is associated
 491  * with @release.  The returned pointer can be passed to
 492  * other devres_*() functions.
 493  *
 494  * RETURNS:
 495  * Pointer to allocated devres on success, NULL on failure.
 496  */
 497 #define devres_alloc(release, size, gfp) \
 498         _devres_alloc(release, size, gfp | __GFP_ZERO)
 499
 500 /**
 501  * devres_free - Free device resource data
 502  * @res: Pointer to devres data to free
 503  *
 504  * Free devres created with devres_alloc().
 505  */
 506 void devres_free(void *res);
 507
 508 /**
 509  * devres_add - Register device resource
 510  * @dev: Device to add resource to
 511  * @res: Resource to register
 512  *
 513  * Register devres @res to @dev.  @res should have been allocated
 514  * using devres_alloc().  On driver detach, the associated release
 515  * function will be invoked and devres will be freed automatically.
 516  */
 517 void devres_add(struct udevice *dev, void *res);
 518
 519 /**
 520  * devres_find - Find device resource
 521  * @dev: Device to lookup resource from
 522  * @release: Look for resources associated with this release function
 523  * @match: Match function (optional)
 524  * @match_data: Data for the match function
 525  *
 526  * Find the latest devres of @dev which is associated with @release
 527  * and for which @match returns 1.  If @match is NULL, it's considered
 528  * to match all.
 529  *
 530  * RETURNS:
 531  * Pointer to found devres, NULL if not found.
 532  */
 533 void *devres_find(struct udevice *dev, dr_release_t release,
 534                   dr_match_t match, void *match_data);
 535
 536 /**
 537  * devres_get - Find devres, if non-existent, add one atomically
 538  * @dev: Device to lookup or add devres for
 539  * @new_res: Pointer to new initialized devres to add if not found
 540  * @match: Match function (optional)
 541  * @match_data: Data for the match function
 542  *
 543  * Find the latest devres of @dev which has the same release function
 544  * as @new_res and for which @match return 1.  If found, @new_res is
 545  * freed; otherwise, @new_res is added atomically.
 546  *
 547  * RETURNS:
 548  * Pointer to found or added devres.
 549  */
 550 void *devres_get(struct udevice *dev, void *new_res,
 551                  dr_match_t match, void *match_data);
 552
 553 /**
 554  * devres_remove - Find a device resource and remove it
 555  * @dev: Device to find resource from
 556  * @release: Look for resources associated with this release function
 557  * @match: Match function (optional)
 558  * @match_data: Data for the match function
 559  *
 560  * Find the latest devres of @dev associated with @release and for
 561  * which @match returns 1.  If @match is NULL, it's considered to
 562  * match all.  If found, the resource is removed atomically and
 563  * returned.
 564  *
 565  * RETURNS:
 566  * Pointer to removed devres on success, NULL if not found.
 567  */
 568 void *devres_remove(struct udevice *dev, dr_release_t release,
 569                     dr_match_t match, void *match_data);
 570
 571 /**
 572  * devres_destroy - Find a device resource and destroy it
 573  * @dev: Device to find resource from
 574  * @release: Look for resources associated with this release function
 575  * @match: Match function (optional)
 576  * @match_data: Data for the match function
 577  *
 578  * Find the latest devres of @dev associated with @release and for
 579  * which @match returns 1.  If @match is NULL, it's considered to
 580  * match all.  If found, the resource is removed atomically and freed.
 581  *
 582  * Note that the release function for the resource will not be called,
 583  * only the devres-allocated data will be freed.  The caller becomes
 584  * responsible for freeing any other data.
 585  *
 586  * RETURNS:
 587  * 0 if devres is found and freed, -ENOENT if not found.
 588  */
 589 int devres_destroy(struct udevice *dev, dr_release_t release,
 590                    dr_match_t match, void *match_data);
 591
 592 /**
 593  * devres_release - Find a device resource and destroy it, calling release
 594  * @dev: Device to find resource from
 595  * @release: Look for resources associated with this release function
 596  * @match: Match function (optional)
 597  * @match_data: Data for the match function
 598  *
 599  * Find the latest devres of @dev associated with @release and for
 600  * which @match returns 1.  If @match is NULL, it's considered to
 601  * match all.  If found, the resource is removed atomically, the
 602  * release function called and the resource freed.
 603  *
 604  * RETURNS:
 605  * 0 if devres is found and freed, -ENOENT if not found.
 606  */
 607 int devres_release(struct udevice *dev, dr_release_t release,
 608                    dr_match_t match, void *match_data);
 609
 610 /* managed devm_k.alloc/kfree for device drivers */
 611 /**
 612  * devm_kmalloc - Resource-managed kmalloc
 613  * @dev: Device to allocate memory for
 614  * @size: Allocation size
 615  * @gfp: Allocation gfp flags
 616  *
 617  * Managed kmalloc.  Memory allocated with this function is
 618  * automatically freed on driver detach.  Like all other devres
 619  * resources, guaranteed alignment is unsigned long long.
 620  *
 621  * RETURNS:
 622  * Pointer to allocated memory on success, NULL on failure.
 623  */
 624 void *devm_kmalloc(struct udevice *dev, size_t size, gfp_t gfp);
 625 static inline void *devm_kzalloc(struct udevice *dev, size_t size, gfp_t gfp)
 626 {
 627         return devm_kmalloc(dev, size, gfp | __GFP_ZERO);
 628 }
 629 static inline void *devm_kmalloc_array(struct udevice *dev,
 630                                        size_t n, size_t size, gfp_t flags)
 631 {
 632         if (size != 0 && n > SIZE_MAX / size)
 633                 return NULL;
 634         return devm_kmalloc(dev, n * size, flags);
 635 }
 636 static inline void *devm_kcalloc(struct udevice *dev,
 637                                  size_t n, size_t size, gfp_t flags)
 638 {
 639         return devm_kmalloc_array(dev, n, size, flags | __GFP_ZERO);
 640 }
 641
 642 /**
 643  * devm_kfree - Resource-managed kfree
 644  * @dev: Device this memory belongs to
 645  * @p: Memory to free
 646  *
 647  * Free memory allocated with devm_kmalloc().
 648  */
 649 void devm_kfree(struct udevice *dev, void *p);
 650
 651
 652 #endif