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 /**
  44  * device_bind_with_driver_data() - Create a device and bind it to a driver
  45  *
  46  * Called to set up a new device attached to a driver, in the case where the
  47  * driver was matched to the device by means of a match table that provides
  48  * driver_data.
  49  *
  50  * Once bound a device exists but is not yet active until device_probe() is
  51  * called.
  52  *
  53  * @parent: Pointer to device's parent, under which this driver will exist
  54  * @drv: Device's driver
  55  * @name: Name of device (e.g. device tree node name)
  56  * @driver_data: The driver_data field from the driver's match table.
  57  * @node: Device tree node for this device. This is invalid for devices which
  58  * don't use device tree.
  59  * @devp: if non-NULL, returns a pointer to the bound device
  60  * @return 0 if OK, -ve on error
  61  */
  62 int device_bind_with_driver_data(struct udevice *parent,
  63                                  const struct driver *drv, const char *name,
  64                                  ulong driver_data, ofnode node,
  65                                  struct udevice **devp);
  66 /**
  67  * device_bind_by_name: Create a device and bind it to a driver
  68  *
  69  * This is a helper function used to bind devices which do not use device
  70  * tree.
  71  *
  72  * @parent: Pointer to device's parent
  73  * @pre_reloc_only: If true, bind the driver only if its DM_INIT_F flag is set.
  74  * If false bind the driver always.
  75  * @info: Name and platdata for this device
  76  * @devp: if non-NULL, returns a pointer to the bound device
  77  * @return 0 if OK, -ve on error
  78  */
  79 int device_bind_by_name(struct udevice *parent, bool pre_reloc_only,
  80                         const struct driver_info *info, struct udevice **devp);
  81
  82 /**
  83  * device_probe() - Probe a device, activating it
  84  *
  85  * Activate a device so that it is ready for use. All its parents are probed
  86  * first.
  87  *
  88  * @dev: Pointer to device to probe
  89  * @return 0 if OK, -ve on error
  90  */
  91 int device_probe(struct udevice *dev);
  92
  93 /**
  94  * device_remove() - Remove a device, de-activating it
  95  *
  96  * De-activate a device so that it is no longer ready for use. All its
  97  * children are deactivated first.
  98  *
  99  * @dev: Pointer to device to remove
 100  * @flags: Flags for selective device removal (DM_REMOVE_...)
 101  * @return 0 if OK, -ve on error (an error here is normally a very bad thing)
 102  */
 103 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 104 int device_remove(struct udevice *dev, uint flags);
 105 #else
 106 static inline int device_remove(struct udevice *dev, uint flags) { return 0; }
 107 #endif
 108
 109 /**
 110  * device_unbind() - Unbind a device, destroying it
 111  *
 112  * Unbind a device and remove all memory used by it
 113  *
 114  * @dev: Pointer to device to unbind
 115  * @return 0 if OK, -ve on error
 116  */
 117 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 118 int device_unbind(struct udevice *dev);
 119 #else
 120 static inline int device_unbind(struct udevice *dev) { return 0; }
 121 #endif
 122
 123 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 124 void device_free(struct udevice *dev);
 125 #else
 126 static inline void device_free(struct udevice *dev) {}
 127 #endif
 128
 129 /**
 130  * simple_bus_translate() - translate a bus address to a system address
 131  *
 132  * This handles the 'ranges' property in a simple bus. It translates the
 133  * device address @addr to a system address using this property.
 134  *
 135  * @dev:        Simple bus device (parent of target device)
 136  * @addr:       Address to translate
 137  * @return new address
 138  */
 139 fdt_addr_t simple_bus_translate(struct udevice *dev, fdt_addr_t addr);
 140
 141 /* Cast away any volatile pointer */
 142 #define DM_ROOT_NON_CONST               (((gd_t *)gd)->dm_root)
 143 #define DM_UCLASS_ROOT_NON_CONST        (((gd_t *)gd)->uclass_root)
 144
 145 /* device resource management */
 146 #ifdef CONFIG_DEVRES
 147
 148 /**
 149  * devres_release_probe - Release managed resources allocated after probing
 150  * @dev: Device to release resources for
 151  *
 152  * Release all resources allocated for @dev when it was probed or later.
 153  * This function is called on driver removal.
 154  */
 155 void devres_release_probe(struct udevice *dev);
 156
 157 /**
 158  * devres_release_all - Release all managed resources
 159  * @dev: Device to release resources for
 160  *
 161  * Release all resources associated with @dev.  This function is
 162  * called on driver unbinding.
 163  */
 164 void devres_release_all(struct udevice *dev);
 165
 166 #else /* ! CONFIG_DEVRES */
 167
 168 static inline void devres_release_probe(struct udevice *dev)
 169 {
 170 }
 171
 172 static inline void devres_release_all(struct udevice *dev)
 173 {
 174 }
 175
 176 #endif /* ! CONFIG_DEVRES */
 177 #endif