include/dm/uclass-internal.h

   1 /*
   2  * Copyright (c) 2013 Google, Inc
   3  *
   4  * (C) Copyright 2012
   5  * Pavel Herrmann <morpheus.ibis@gmail.com>
   6  *
   7  * SPDX-License-Identifier:     GPL-2.0+
   8  */
   9
  10 #ifndef _DM_UCLASS_INTERNAL_H
  11 #define _DM_UCLASS_INTERNAL_H
  12
  13 #include <dm/ofnode.h>
  14
  15 /**
  16  * uclass_get_device_tail() - handle the end of a get_device call
  17  *
  18  * This handles returning an error or probing a device as needed.
  19  *
  20  * @dev: Device that needs to be probed
  21  * @ret: Error to return. If non-zero then the device is not probed
  22  * @devp: Returns the value of 'dev' if there is no error
  23  * @return ret, if non-zero, else the result of the device_probe() call
  24  */
  25 int uclass_get_device_tail(struct udevice *dev, int ret, struct udevice **devp);
  26
  27 /**
  28  * uclass_find_device() - Return n-th child of uclass
  29  * @id:         Id number of the uclass
  30  * @index:      Position of the child in uclass's list
  31  * #devp:       Returns pointer to device, or NULL on error
  32  *
  33  * The device is not prepared for use - this is an internal function.
  34  * The function uclass_get_device_tail() can be used to probe the device.
  35  *
  36  * @return the uclass pointer of a child at the given index or
  37  * return NULL on error.
  38  */
  39 int uclass_find_device(enum uclass_id id, int index, struct udevice **devp);
  40
  41 /**
  42  * uclass_find_first_device() - Return the first device in a uclass
  43  * @id:         Id number of the uclass
  44  * #devp:       Returns pointer to device, or NULL on error
  45  *
  46  * The device is not prepared for use - this is an internal function.
  47  * The function uclass_get_device_tail() can be used to probe the device.
  48  *
  49  * @return 0 if OK (found or not found), -1 on error
  50  */
  51 int uclass_find_first_device(enum uclass_id id, struct udevice **devp);
  52
  53 /**
  54  * uclass_find_next_device() - Return the next device in a uclass
  55  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
  56  * to the next device in the same uclass, or NULL if none
  57  *
  58  * The device is not prepared for use - this is an internal function.
  59  * The function uclass_get_device_tail() can be used to probe the device.
  60  *
  61  * @return 0 if OK (found or not found), -1 on error
  62  */
  63 int uclass_find_next_device(struct udevice **devp);
  64
  65 /**
  66  * uclass_find_device_by_name() - Find uclass device based on ID and name
  67  *
  68  * This searches for a device with the exactly given name.
  69  *
  70  * The device is NOT probed, it is merely returned.
  71  *
  72  * @id: ID to look up
  73  * @name: name of a device to find
  74  * @devp: Returns pointer to device (the first one with the name)
  75  * @return 0 if OK, -ve on error
  76  */
  77 int uclass_find_device_by_name(enum uclass_id id, const char *name,
  78                                struct udevice **devp);
  79
  80 /**
  81  * uclass_find_device_by_seq() - Find uclass device based on ID and sequence
  82  *
  83  * This searches for a device with the given seq or req_seq.
  84  *
  85  * For seq, if an active device has this sequence it will be returned.
  86  * If there is no such device then this will return -ENODEV.
  87  *
  88  * For req_seq, if a device (whether activated or not) has this req_seq
  89  * value, that device will be returned. This is a strong indication that
  90  * the device will receive that sequence when activated.
  91  *
  92  * The device is NOT probed, it is merely returned.
  93  *
  94  * @id: ID to look up
  95  * @seq_or_req_seq: Sequence number to find (0=first)
  96  * @find_req_seq: true to find req_seq, false to find seq
  97  * @devp: Returns pointer to device (there is only one per for each seq)
  98  * @return 0 if OK, -ve on error
  99  */
 100 int uclass_find_device_by_seq(enum uclass_id id, int seq_or_req_seq,
 101                               bool find_req_seq, struct udevice **devp);
 102
 103 /**
 104  * uclass_find_device_by_of_offset() - Find a uclass device by device tree node
 105  *
 106  * This searches the devices in the uclass for one attached to the given
 107  * device tree node.
 108  *
 109  * The device is NOT probed, it is merely returned.
 110  *
 111  * @id: ID to look up
 112  * @node: Device tree offset to search for (if -ve then -ENODEV is returned)
 113  * @devp: Returns pointer to device (there is only one for each node)
 114  * @return 0 if OK, -ve on error
 115  */
 116 int uclass_find_device_by_of_offset(enum uclass_id id, int node,
 117                                     struct udevice **devp);
 118
 119 /**
 120  * uclass_find_device_by_of_node() - Find a uclass device by device tree node
 121  *
 122  * This searches the devices in the uclass for one attached to the given
 123  * device tree node.
 124  *
 125  * The device is NOT probed, it is merely returned.
 126  *
 127  * @id: ID to look up
 128  * @node: Device tree offset to search for (if NULL then -ENODEV is returned)
 129  * @devp: Returns pointer to device (there is only one for each node)
 130  * @return 0 if OK, -ve on error
 131  */
 132 int uclass_find_device_by_ofnode(enum uclass_id id, ofnode node,
 133                                  struct udevice **devp);
 134
 135 /**
 136  * uclass_bind_device() - Associate device with a uclass
 137  *
 138  * Connect the device into uclass's list of devices.
 139  *
 140  * @dev:        Pointer to the device
 141  * #return 0 on success, -ve on error
 142  */
 143 int uclass_bind_device(struct udevice *dev);
 144
 145 /**
 146  * uclass_unbind_device() - Deassociate device with a uclass
 147  *
 148  * Disconnect the device from uclass's list of devices.
 149  *
 150  * @dev:        Pointer to the device
 151  * #return 0 on success, -ve on error
 152  */
 153 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 154 int uclass_unbind_device(struct udevice *dev);
 155 #else
 156 static inline int uclass_unbind_device(struct udevice *dev) { return 0; }
 157 #endif
 158
 159 /**
 160  * uclass_pre_probe_device() - Deal with a device that is about to be probed
 161  *
 162  * Perform any pre-processing that is needed by the uclass before it can be
 163  * probed. This includes the uclass' pre-probe() method and the parent
 164  * uclass' child_pre_probe() method.
 165  *
 166  * @dev:        Pointer to the device
 167  * #return 0 on success, -ve on error
 168  */
 169 int uclass_pre_probe_device(struct udevice *dev);
 170
 171 /**
 172  * uclass_post_probe_device() - Deal with a device that has just been probed
 173  *
 174  * Perform any post-processing of a probed device that is needed by the
 175  * uclass.
 176  *
 177  * @dev:        Pointer to the device
 178  * #return 0 on success, -ve on error
 179  */
 180 int uclass_post_probe_device(struct udevice *dev);
 181
 182 /**
 183  * uclass_pre_remove_device() - Handle a device which is about to be removed
 184  *
 185  * Perform any pre-processing of a device that is about to be removed.
 186  *
 187  * @dev:        Pointer to the device
 188  * #return 0 on success, -ve on error
 189  */
 190 #if CONFIG_IS_ENABLED(DM_DEVICE_REMOVE)
 191 int uclass_pre_remove_device(struct udevice *dev);
 192 #else
 193 static inline int uclass_pre_remove_device(struct udevice *dev) { return 0; }
 194 #endif
 195
 196 /**
 197  * uclass_find() - Find uclass by its id
 198  *
 199  * @id:         Id to serach for
 200  * @return pointer to uclass, or NULL if not found
 201  */
 202 struct uclass *uclass_find(enum uclass_id key);
 203
 204 /**
 205  * uclass_destroy() - Destroy a uclass
 206  *
 207  * Destroy a uclass and all its devices
 208  *
 209  * @uc: uclass to destroy
 210  * @return 0 on success, -ve on error
 211  */
 212 int uclass_destroy(struct uclass *uc);
 213
 214 #endif