uclass.h 8.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234
  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. #ifndef _DM_UCLASS_H
  10. #define _DM_UCLASS_H
  11. #include <dm/uclass-id.h>
  12. #include <linker_lists.h>
  13. #include <linux/list.h>
  14. /**
  15. * struct uclass - a U-Boot drive class, collecting together similar drivers
  16. *
  17. * A uclass provides an interface to a particular function, which is
  18. * implemented by one or more drivers. Every driver belongs to a uclass even
  19. * if it is the only driver in that uclass. An example uclass is GPIO, which
  20. * provides the ability to change read inputs, set and clear outputs, etc.
  21. * There may be drivers for on-chip SoC GPIO banks, I2C GPIO expanders and
  22. * PMIC IO lines, all made available in a unified way through the uclass.
  23. *
  24. * @priv: Private data for this uclass
  25. * @uc_drv: The driver for the uclass itself, not to be confused with a
  26. * 'struct driver'
  27. * @dev_head: List of devices in this uclass (devices are attached to their
  28. * uclass when their bind method is called)
  29. * @sibling_node: Next uclass in the linked list of uclasses
  30. */
  31. struct uclass {
  32. void *priv;
  33. struct uclass_driver *uc_drv;
  34. struct list_head dev_head;
  35. struct list_head sibling_node;
  36. };
  37. struct udevice;
  38. /* Members of this uclass sequence themselves with aliases */
  39. #define DM_UC_FLAG_SEQ_ALIAS (1 << 0)
  40. /**
  41. * struct uclass_driver - Driver for the uclass
  42. *
  43. * A uclass_driver provides a consistent interface to a set of related
  44. * drivers.
  45. *
  46. * @name: Name of uclass driver
  47. * @id: ID number of this uclass
  48. * @post_bind: Called after a new device is bound to this uclass
  49. * @pre_unbind: Called before a device is unbound from this uclass
  50. * @pre_probe: Called before a new device is probed
  51. * @post_probe: Called after a new device is probed
  52. * @pre_remove: Called before a device is removed
  53. * @child_post_bind: Called after a child is bound to a device in this uclass
  54. * @init: Called to set up the uclass
  55. * @destroy: Called to destroy the uclass
  56. * @priv_auto_alloc_size: If non-zero this is the size of the private data
  57. * to be allocated in the uclass's ->priv pointer. If zero, then the uclass
  58. * driver is responsible for allocating any data required.
  59. * @per_device_auto_alloc_size: Each device can hold private data owned
  60. * by the uclass. If required this will be automatically allocated if this
  61. * value is non-zero.
  62. * @per_device_platdata_auto_alloc_size: Each device can hold platform data
  63. * owned by the uclass as 'dev->uclass_platdata'. If the value is non-zero,
  64. * then this will be automatically allocated.
  65. * @per_child_auto_alloc_size: Each child device (of a parent in this
  66. * uclass) can hold parent data for the device/uclass. This value is only
  67. * used as a falback if this member is 0 in the driver.
  68. * @per_child_platdata_auto_alloc_size: A bus likes to store information about
  69. * its children. If non-zero this is the size of this data, to be allocated
  70. * in the child device's parent_platdata pointer. This value is only used as
  71. * a falback if this member is 0 in the driver.
  72. * @ops: Uclass operations, providing the consistent interface to devices
  73. * within the uclass.
  74. * @flags: Flags for this uclass (DM_UC_...)
  75. */
  76. struct uclass_driver {
  77. const char *name;
  78. enum uclass_id id;
  79. int (*post_bind)(struct udevice *dev);
  80. int (*pre_unbind)(struct udevice *dev);
  81. int (*pre_probe)(struct udevice *dev);
  82. int (*post_probe)(struct udevice *dev);
  83. int (*pre_remove)(struct udevice *dev);
  84. int (*child_post_bind)(struct udevice *dev);
  85. int (*child_pre_probe)(struct udevice *dev);
  86. int (*init)(struct uclass *class);
  87. int (*destroy)(struct uclass *class);
  88. int priv_auto_alloc_size;
  89. int per_device_auto_alloc_size;
  90. int per_device_platdata_auto_alloc_size;
  91. int per_child_auto_alloc_size;
  92. int per_child_platdata_auto_alloc_size;
  93. const void *ops;
  94. uint32_t flags;
  95. };
  96. /* Declare a new uclass_driver */
  97. #define UCLASS_DRIVER(__name) \
  98. ll_entry_declare(struct uclass_driver, __name, uclass)
  99. /**
  100. * uclass_get() - Get a uclass based on an ID, creating it if needed
  101. *
  102. * Every uclass is identified by an ID, a number from 0 to n-1 where n is
  103. * the number of uclasses. This function allows looking up a uclass by its
  104. * ID.
  105. *
  106. * @key: ID to look up
  107. * @ucp: Returns pointer to uclass (there is only one per ID)
  108. * @return 0 if OK, -ve on error
  109. */
  110. int uclass_get(enum uclass_id key, struct uclass **ucp);
  111. /**
  112. * uclass_get_device() - Get a uclass device based on an ID and index
  113. *
  114. * The device is probed to activate it ready for use.
  115. *
  116. * @id: ID to look up
  117. * @index: Device number within that uclass (0=first)
  118. * @devp: Returns pointer to device (there is only one per for each ID)
  119. * @return 0 if OK, -ve on error
  120. */
  121. int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
  122. /**
  123. * uclass_get_device_by_name() - Get a uclass device by it's name
  124. *
  125. * This searches the devices in the uclass for one with the given name.
  126. *
  127. * The device is probed to activate it ready for use.
  128. *
  129. * @id: ID to look up
  130. * @name: name of a device to get
  131. * @devp: Returns pointer to device (the first one with the name)
  132. * @return 0 if OK, -ve on error
  133. */
  134. int uclass_get_device_by_name(enum uclass_id id, const char *name,
  135. struct udevice **devp);
  136. /**
  137. * uclass_get_device_by_seq() - Get a uclass device based on an ID and sequence
  138. *
  139. * If an active device has this sequence it will be returned. If there is no
  140. * such device then this will check for a device that is requesting this
  141. * sequence.
  142. *
  143. * The device is probed to activate it ready for use.
  144. *
  145. * @id: ID to look up
  146. * @seq: Sequence number to find (0=first)
  147. * @devp: Returns pointer to device (there is only one for each seq)
  148. * @return 0 if OK, -ve on error
  149. */
  150. int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp);
  151. /**
  152. * uclass_get_device_by_of_offset() - Get 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 probed to activate it ready for use.
  158. *
  159. * @id: ID to look up
  160. * @node: Device tree offset to search for (if -ve 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_get_device_by_of_offset(enum uclass_id id, int node,
  165. struct udevice **devp);
  166. /**
  167. * uclass_first_device() - Get the first device in a uclass
  168. *
  169. * The device returned is probed if necessary, and ready for use
  170. *
  171. * @id: Uclass ID to look up
  172. * @devp: Returns pointer to the first device in that uclass, or NULL if none
  173. * @return 0 if OK (found or not found), -1 on error
  174. */
  175. int uclass_first_device(enum uclass_id id, struct udevice **devp);
  176. /**
  177. * uclass_next_device() - Get the next device in a uclass
  178. *
  179. * The device returned is probed if necessary, and ready for use
  180. *
  181. * @devp: On entry, pointer to device to lookup. On exit, returns pointer
  182. * to the next device in the same uclass, or NULL if none
  183. * @return 0 if OK (found or not found), -1 on error
  184. */
  185. int uclass_next_device(struct udevice **devp);
  186. /**
  187. * uclass_resolve_seq() - Resolve a device's sequence number
  188. *
  189. * On entry dev->seq is -1, and dev->req_seq may be -1 (to allocate a
  190. * sequence number automatically, or >= 0 to select a particular number.
  191. * If the requested sequence number is in use, then this device will
  192. * be allocated another one.
  193. *
  194. * Note that the device's seq value is not changed by this function.
  195. *
  196. * @dev: Device for which to allocate sequence number
  197. * @return sequence number allocated, or -ve on error
  198. */
  199. int uclass_resolve_seq(struct udevice *dev);
  200. /**
  201. * uclass_foreach_dev() - Helper function to iteration through devices
  202. *
  203. * This creates a for() loop which works through the available devices in
  204. * a uclass in order from start to end.
  205. *
  206. * @pos: struct udevice * to hold the current device. Set to NULL when there
  207. * are no more devices.
  208. * @uc: uclass to scan
  209. */
  210. #define uclass_foreach_dev(pos, uc) \
  211. for (pos = list_entry((&(uc)->dev_head)->next, typeof(*pos), \
  212. uclass_node); \
  213. prefetch(pos->uclass_node.next), \
  214. &pos->uclass_node != (&(uc)->dev_head); \
  215. pos = list_entry(pos->uclass_node.next, typeof(*pos), \
  216. uclass_node))
  217. #endif