include/dm/uclass-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  */
   8
   9 #ifndef _DM_UCLASS_INTERNAL_H
  10 #define _DM_UCLASS_INTERNAL_H
  11
  12 #include <dm/ofnode.h>
  13
  14 /**
  15  * uclass_set_priv() - Set the private data for a uclass
  16  *
  17  * This is normally handled by driver model, which automatically allocates
  18  * private data when an 'auto' size if provided by the uclass driver.
  19  *
  20  * Use this function to override normal operation for special situations, such
  21  * as needing to allocate a variable amount of data.
  22  *
  23  * @uc          Uclass to update
  24  * @priv        New private-data pointer
  25  */
  26 void uclass_set_priv(struct uclass *uc, void *priv);
  27
  28 /**
  29  * uclass_find_next_free_seq() - Get the next free sequence number
  30  *
  31  * This returns the next free sequence number. This is useful only if
  32  * OF_CONTROL is not used. The next free sequence number is simply the
  33  * maximum sequence number used by all devices in the uclass + 1. The value
  34  * returned is always greater than the largest alias, if DM_SEQ_ALIAS is enabled
  35  * and the uclass has the DM_UC_FLAG_SEQ_ALIAS flag.
  36  *
  37  * This allows assigning the sequence number in the binding order.
  38  *
  39  * @uc:         uclass to check
  40  * @return      The next free sequence number
  41  */
  42 int uclass_find_next_free_seq(struct uclass *uc);
  43
  44 /**
  45  * uclass_get_device_tail() - handle the end of a get_device call
  46  *
  47  * This handles returning an error or probing a device as needed.
  48  *
  49  * @dev: Device that needs to be probed
  50  * @ret: Error to return. If non-zero then the device is not probed
  51  * @devp: Returns the value of 'dev' if there is no error
  52  * @return ret, if non-zero, else the result of the device_probe() call
  53  */
  54 int uclass_get_device_tail(struct udevice *dev, int ret, struct udevice **devp);
  55
  56 /**
  57  * dev_get_uclass_index() - Get uclass and index of device
  58  * @dev:        - in - Device that we want the uclass/index of
  59  * @ucp:        - out - A pointer to the uclass the device belongs to
  60  *
  61  * The device is not prepared for use - this is an internal function.
  62  *
  63  * @return the index of the device in the uclass list or -ENODEV if not found.
  64  */
  65 int dev_get_uclass_index(struct udevice *dev, struct uclass **ucp);
  66
  67 /**
  68  * uclass_find_device() - Return n-th child of uclass
  69  * @id:         Id number of the uclass
  70  * @index:      Position of the child in uclass's list
  71  * #devp:       Returns pointer to device, or NULL on error
  72  *
  73  * The device is not prepared for use - this is an internal function.
  74  * The function uclass_get_device_tail() can be used to probe the device.
  75  *
  76  * @return the uclass pointer of a child at the given index or
  77  * return NULL on error.
  78  */
  79 int uclass_find_device(enum uclass_id id, int index, struct udevice **devp);
  80
  81 /**
  82  * uclass_find_first_device() - Return the first device in a uclass
  83  * @id:         Id number of the uclass
  84  * #devp:       Returns pointer to device, or NULL on error
  85  *
  86  * The device is not prepared for use - this is an internal function.
  87  * The function uclass_get_device_tail() can be used to probe the device.
  88  *
  89  * @return 0 if OK (found or not found), -ve on error
  90  */
  91 int uclass_find_first_device(enum uclass_id id, struct udevice **devp);
  92
  93 /**
  94  * uclass_find_next_device() - Return the next device in a uclass
  95  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
  96  * to the next device in the same uclass, or NULL if none
  97  *
  98  * The device is not prepared for use - this is an internal function.
  99  * The function uclass_get_device_tail() can be used to probe the device.
 100  *
 101  * @return 0 if OK (found or not found), -ve on error
 102  */
 103 int uclass_find_next_device(struct udevice **devp);
 104
 105 /**
 106  * uclass_find_device_by_name() - Find uclass device based on ID and name
 107  *
 108  * This searches for a device with the exactly given name.
 109  *
 110  * The device is NOT probed, it is merely returned.
 111  *
 112  * @id: ID to look up
 113  * @name: name of a device to find
 114  * @devp: Returns pointer to device (the first one with the name)
 115  * @return 0 if OK, -ve on error
 116  */
 117 int uclass_find_device_by_name(enum uclass_id id, const char *name,
 118                                struct udevice **devp);
 119
 120 /**
 121  * uclass_find_device_by_seq() - Find uclass device based on ID and sequence
 122  *
 123  * This searches for a device with the given seq.
 124  *
 125  * The device is NOT probed, it is merely returned.
 126  *
 127  * @id: ID to look up
 128  * @seq: Sequence number to find (0=first)
 129  * @devp: Returns pointer to device (there is only one per for each seq)
 130  * @return 0 if OK, -ENODEV if not found
 131  */
 132 int uclass_find_device_by_seq(enum uclass_id id, int seq,
 133                               struct udevice **devp);
 134
 135 /**
 136  * uclass_find_device_by_of_offset() - Find a uclass device by device tree node
 137  *
 138  * This searches the devices in the uclass for one attached to the given
 139  * device tree node.
 140  *
 141  * The device is NOT probed, it is merely returned.
 142  *
 143  * @id: ID to look up
 144  * @node: Device tree offset to search for (if -ve then -ENODEV is returned)
 145  * @devp: Returns pointer to device (there is only one for each node)
 146  * @return 0 if OK, -ve on error
 147  */
 148 int uclass_find_device_by_of_offset(enum uclass_id id, int node,
 149                                     struct udevice **devp);
 150
 151 /**
 152  * uclass_find_device_by_of_node() - Find a uclass device by device tree node
 153  *
 154  * This searches the devices in the uclass for one attached to the given
 155  * device tree node.
 156  *
 157  * The device is NOT probed, it is merely returned.
 158  *
 159  * @id: ID to look up
 160  * @node: Device tree offset to search for (if NULL then -ENODEV is returned)
 161  * @devp: Returns pointer to device (there is only one for each node)
 162  * @return 0 if OK, -ve on error
 163  */
 164 int uclass_find_device_by_ofnode(enum uclass_id id, ofnode node,
 165                                  struct udevice **devp);
 166
 167 /**
 168  * uclass_find_device_by_phandle() - Find a uclass device by phandle
 169  *
 170  * This searches the devices in the uclass for one with the given phandle.
 171  *
 172  * The device is NOT probed, it is merely returned.
 173  *
 174  * @id: ID to look up
 175  * @parent: Parent device containing the phandle pointer
 176  * @name: Name of property in the parent device node
 177  * @devp: Returns pointer to device (there is only one for each node)
 178  * @return 0 if OK, -ENOENT if there is no @name present in the node, other
 179  *      -ve on error
 180  */
 181 int uclass_find_device_by_phandle(enum uclass_id id, struct udevice *parent,
 182                                   const char *name, struct udevice **devp);
 183
 184 /**
 185  * uclass_bind_device() - Associate device with a uclass
 186  *
 187  * Connect the device into uclass's list of devices.
 188  *
 189  * @dev:        Pointer to the device
 190  * #return 0 on success, -ve on error
 191  */
 192 int uclass_bind_device(struct udevice *dev);
 193
 194 /**
 195  * uclass_unbind_device() - Deassociate device with a uclass
 196  *
 197  * Disconnect the device from uclass's list of devices.
 198  *
 199  * @dev:        Pointer to the device
 200  * #return 0 on success, -ve on error
 201  */
 202 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 203 int uclass_unbind_device(struct udevice *dev);
 204 #else
 205 static inline int uclass_unbind_device(struct udevice *dev) { return 0; }
 206 #endif
 207
 208 /**
 209  * uclass_pre_probe_device() - Deal with a device that is about to be probed
 210  *
 211  * Perform any pre-processing that is needed by the uclass before it can be
 212  * probed. This includes the uclass' pre-probe() method and the parent
 213  * uclass' child_pre_probe() method.
 214  *
 215  * @dev:        Pointer to the device
 216  * #return 0 on success, -ve on error
 217  */
 218 int uclass_pre_probe_device(struct udevice *dev);
 219
 220 /**
 221  * uclass_post_probe_device() - Deal with a device that has just been probed
 222  *
 223  * Perform any post-processing of a probed device that is needed by the
 224  * uclass.
 225  *
 226  * @dev:        Pointer to the device
 227  * #return 0 on success, -ve on error
 228  */
 229 int uclass_post_probe_device(struct udevice *dev);
 230
 231 /**
 232  * uclass_pre_remove_device() - Handle a device which is about to be removed
 233  *
 234  * Perform any pre-processing of a device that is about to be removed.
 235  *
 236  * @dev:        Pointer to the device
 237  * #return 0 on success, -ve on error
 238  */
 239 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 240 int uclass_pre_remove_device(struct udevice *dev);
 241 #else
 242 static inline int uclass_pre_remove_device(struct udevice *dev) { return 0; }
 243 #endif
 244
 245 /**
 246  * uclass_find() - Find uclass by its id
 247  *
 248  * @id:         Id to serach for
 249  * @return pointer to uclass, or NULL if not found
 250  */
 251 struct uclass *uclass_find(enum uclass_id key);
 252
 253 /**
 254  * uclass_destroy() - Destroy a uclass
 255  *
 256  * Destroy a uclass and all its devices
 257  *
 258  * @uc: uclass to destroy
 259  * @return 0 on success, -ve on error
 260  */
 261 int uclass_destroy(struct uclass *uc);
 262
 263 #endif