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