include/dm/device-internal.h

   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_INTERNAL_H
  11 #define _DM_DEVICE_INTERNAL_H
  12
  13 #include <dm/ofnode.h>
  14
  15 struct device_node;
  16 struct udevice;
  17
  18 /**
  19  * device_bind() - Create a device and bind it to a driver
  20  *
  21  * Called to set up a new device attached to a driver. The device will either
  22  * have platdata, or a device tree node which can be used to create the
  23  * platdata.
  24  *
  25  * Once bound a device exists but is not yet active until device_probe() is
  26  * called.
  27  *
  28  * @parent: Pointer to device's parent, under which this driver will exist
  29  * @drv: Device's driver
  30  * @name: Name of device (e.g. device tree node name)
  31  * @platdata: Pointer to data for this device - the structure is device-
  32  * specific but may include the device's I/O address, etc.. This is NULL for
  33  * devices which use device tree.
  34  * @of_offset: Offset of device tree node for this device. This is -1 for
  35  * devices which don't use device tree.
  36  * @devp: if non-NULL, returns a pointer to the bound device
  37  * @return 0 if OK, -ve on error
  38  */
  39 int device_bind(struct udevice *parent, const struct driver *drv,
  40                 const char *name, void *platdata, int of_offset,
  41                 struct udevice **devp);
  42
  43 int device_bind_ofnode(struct udevice *parent, const struct driver *drv,
  44                        const char *name, void *platdata, ofnode node,
  45                        struct udevice **devp);
  46
  47 /**
  48  * device_bind_with_driver_data() - Create a device and bind it to a driver
  49  *
  50  * Called to set up a new device attached to a driver, in the case where the
  51  * driver was matched to the device by means of a match table that provides
  52  * driver_data.
  53  *
  54  * Once bound a device exists but is not yet active until device_probe() is
  55  * called.
  56  *
  57  * @parent: Pointer to device's parent, under which this driver will exist
  58  * @drv: Device's driver
  59  * @name: Name of device (e.g. device tree node name)
  60  * @driver_data: The driver_data field from the driver's match table.
  61  * @node: Device tree node for this device. This is invalid for devices which
  62  * don't use device tree.
  63  * @devp: if non-NULL, returns a pointer to the bound device
  64  * @return 0 if OK, -ve on error
  65  */
  66 int device_bind_with_driver_data(struct udevice *parent,
  67                                  const struct driver *drv, const char *name,
  68                                  ulong driver_data, ofnode node,
  69                                  struct udevice **devp);
  70 /**
  71  * device_bind_by_name: Create a device and bind it to a driver
  72  *
  73  * This is a helper function used to bind devices which do not use device
  74  * tree.
  75  *
  76  * @parent: Pointer to device's parent
  77  * @pre_reloc_only: If true, bind the driver only if its DM_FLAG_PRE_RELOC flag
  78  * is set. If false bind the driver always.
  79  * @info: Name and platdata for this device
  80  * @devp: if non-NULL, returns a pointer to the bound device
  81  * @return 0 if OK, -ve on error
  82  */
  83 int device_bind_by_name(struct udevice *parent, bool pre_reloc_only,
  84                         const struct driver_info *info, struct udevice **devp);
  85
  86 /**
  87  * device_probe() - Probe a device, activating it
  88  *
  89  * Activate a device so that it is ready for use. All its parents are probed
  90  * first.
  91  *
  92  * @dev: Pointer to device to probe
  93  * @return 0 if OK, -ve on error
  94  */
  95 int device_probe(struct udevice *dev);
  96
  97 /**
  98  * device_remove() - Remove a device, de-activating it
  99  *
 100  * De-activate a device so that it is no longer ready for use. All its
 101  * children are deactivated first.
 102  *
 103  * @dev: Pointer to device to remove
 104  * @flags: Flags for selective device removal (DM_REMOVE_...)
 105  * @return 0 if OK, -ve on error (an error here is normally a very bad thing)
 106  */
 107 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 108 int device_remove(struct udevice *dev, uint flags);
 109 #else
 110 static inline int device_remove(struct udevice *dev, uint flags) { return 0; }
 111 #endif
 112
 113 /**
 114  * device_unbind() - Unbind a device, destroying it
 115  *
 116  * Unbind a device and remove all memory used by it
 117  *
 118  * @dev: Pointer to device to unbind
 119  * @return 0 if OK, -ve on error
 120  */
 121 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 122 int device_unbind(struct udevice *dev);
 123 #else
 124 static inline int device_unbind(struct udevice *dev) { return 0; }
 125 #endif
 126
 127 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 128 void device_free(struct udevice *dev);
 129 #else
 130 static inline void device_free(struct udevice *dev) {}
 131 #endif
 132
 133 /**
 134  * device_chld_unbind() - Unbind all device's children from the device if bound
 135  *                        to drv
 136  *
 137  * On error, the function continues to unbind all children, and reports the
 138  * first error.
 139  *
 140  * @dev:        The device that is to be stripped of its children
 141  * @drv:        The targeted driver
 142  * @return 0 on success, -ve on error
 143  */
 144 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 145 int device_chld_unbind(struct udevice *dev, struct driver *drv);
 146 #else
 147 static inline int device_chld_unbind(struct udevice *dev, struct driver *drv)
 148 {
 149         return 0;
 150 }
 151 #endif
 152
 153 /**
 154  * device_chld_remove() - Stop all device's children
 155  * @dev:        The device whose children are to be removed
 156  * @drv:        The targeted driver
 157  * @flags:      Flag, if this functions is called in the pre-OS stage
 158  * @return 0 on success, -ve on error
 159  */
 160 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 161 int device_chld_remove(struct udevice *dev, struct driver *drv,
 162                        uint flags);
 163 #else
 164 static inline int device_chld_remove(struct udevice *dev, struct driver *drv,
 165                                      uint flags)
 166 {
 167         return 0;
 168 }
 169 #endif
 170
 171 /**
 172  * simple_bus_translate() - translate a bus address to a system address
 173  *
 174  * This handles the 'ranges' property in a simple bus. It translates the
 175  * device address @addr to a system address using this property.
 176  *
 177  * @dev:        Simple bus device (parent of target device)
 178  * @addr:       Address to translate
 179  * @return new address
 180  */
 181 fdt_addr_t simple_bus_translate(struct udevice *dev, fdt_addr_t addr);
 182
 183 /* Cast away any volatile pointer */
 184 #define DM_ROOT_NON_CONST               (((gd_t *)gd)->dm_root)
 185 #define DM_UCLASS_ROOT_NON_CONST        (((gd_t *)gd)->uclass_root)
 186
 187 /* device resource management */
 188 #ifdef CONFIG_DEVRES
 189
 190 /**
 191  * devres_release_probe - Release managed resources allocated after probing
 192  * @dev: Device to release resources for
 193  *
 194  * Release all resources allocated for @dev when it was probed or later.
 195  * This function is called on driver removal.
 196  */
 197 void devres_release_probe(struct udevice *dev);
 198
 199 /**
 200  * devres_release_all - Release all managed resources
 201  * @dev: Device to release resources for
 202  *
 203  * Release all resources associated with @dev.  This function is
 204  * called on driver unbinding.
 205  */
 206 void devres_release_all(struct udevice *dev);
 207
 208 #else /* ! CONFIG_DEVRES */
 209
 210 static inline void devres_release_probe(struct udevice *dev)
 211 {
 212 }
 213
 214 static inline void devres_release_all(struct udevice *dev)
 215 {
 216 }
 217
 218 #endif /* ! CONFIG_DEVRES */
 219 #endif