device.h 38 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122
  1. // SPDX-License-Identifier: GPL-2.0
  2. /*
  3. * device.h - generic, centralized driver model
  4. *
  5. * Copyright (c) 2001-2003 Patrick Mochel <[email protected]>
  6. * Copyright (c) 2004-2009 Greg Kroah-Hartman <[email protected]>
  7. * Copyright (c) 2008-2009 Novell Inc.
  8. *
  9. * See Documentation/driver-api/driver-model/ for more information.
  10. */
  11. #ifndef _DEVICE_H_
  12. #define _DEVICE_H_
  13. #include <linux/dev_printk.h>
  14. #include <linux/energy_model.h>
  15. #include <linux/ioport.h>
  16. #include <linux/kobject.h>
  17. #include <linux/klist.h>
  18. #include <linux/list.h>
  19. #include <linux/lockdep.h>
  20. #include <linux/compiler.h>
  21. #include <linux/types.h>
  22. #include <linux/mutex.h>
  23. #include <linux/pm.h>
  24. #include <linux/atomic.h>
  25. #include <linux/uidgid.h>
  26. #include <linux/gfp.h>
  27. #include <linux/overflow.h>
  28. #include <linux/device/bus.h>
  29. #include <linux/device/class.h>
  30. #include <linux/device/driver.h>
  31. #include <linux/android_kabi.h>
  32. #include <asm/device.h>
  33. struct device;
  34. struct device_private;
  35. struct device_driver;
  36. struct driver_private;
  37. struct module;
  38. struct class;
  39. struct subsys_private;
  40. struct device_node;
  41. struct fwnode_handle;
  42. struct iommu_ops;
  43. struct iommu_group;
  44. struct dev_pin_info;
  45. struct dev_iommu;
  46. struct msi_device_data;
  47. /**
  48. * struct subsys_interface - interfaces to device functions
  49. * @name: name of the device function
  50. * @subsys: subsystem of the devices to attach to
  51. * @node: the list of functions registered at the subsystem
  52. * @add_dev: device hookup to device function handler
  53. * @remove_dev: device hookup to device function handler
  54. *
  55. * Simple interfaces attached to a subsystem. Multiple interfaces can
  56. * attach to a subsystem and its devices. Unlike drivers, they do not
  57. * exclusively claim or control devices. Interfaces usually represent
  58. * a specific functionality of a subsystem/class of devices.
  59. */
  60. struct subsys_interface {
  61. const char *name;
  62. struct bus_type *subsys;
  63. struct list_head node;
  64. int (*add_dev)(struct device *dev, struct subsys_interface *sif);
  65. void (*remove_dev)(struct device *dev, struct subsys_interface *sif);
  66. };
  67. int subsys_interface_register(struct subsys_interface *sif);
  68. void subsys_interface_unregister(struct subsys_interface *sif);
  69. int subsys_system_register(struct bus_type *subsys,
  70. const struct attribute_group **groups);
  71. int subsys_virtual_register(struct bus_type *subsys,
  72. const struct attribute_group **groups);
  73. /*
  74. * The type of device, "struct device" is embedded in. A class
  75. * or bus can contain devices of different types
  76. * like "partitions" and "disks", "mouse" and "event".
  77. * This identifies the device type and carries type-specific
  78. * information, equivalent to the kobj_type of a kobject.
  79. * If "name" is specified, the uevent will contain it in
  80. * the DEVTYPE variable.
  81. */
  82. struct device_type {
  83. const char *name;
  84. const struct attribute_group **groups;
  85. int (*uevent)(struct device *dev, struct kobj_uevent_env *env);
  86. char *(*devnode)(struct device *dev, umode_t *mode,
  87. kuid_t *uid, kgid_t *gid);
  88. void (*release)(struct device *dev);
  89. const struct dev_pm_ops *pm;
  90. };
  91. /* interface for exporting device attributes */
  92. struct device_attribute {
  93. struct attribute attr;
  94. ssize_t (*show)(struct device *dev, struct device_attribute *attr,
  95. char *buf);
  96. ssize_t (*store)(struct device *dev, struct device_attribute *attr,
  97. const char *buf, size_t count);
  98. };
  99. struct dev_ext_attribute {
  100. struct device_attribute attr;
  101. void *var;
  102. };
  103. ssize_t device_show_ulong(struct device *dev, struct device_attribute *attr,
  104. char *buf);
  105. ssize_t device_store_ulong(struct device *dev, struct device_attribute *attr,
  106. const char *buf, size_t count);
  107. ssize_t device_show_int(struct device *dev, struct device_attribute *attr,
  108. char *buf);
  109. ssize_t device_store_int(struct device *dev, struct device_attribute *attr,
  110. const char *buf, size_t count);
  111. ssize_t device_show_bool(struct device *dev, struct device_attribute *attr,
  112. char *buf);
  113. ssize_t device_store_bool(struct device *dev, struct device_attribute *attr,
  114. const char *buf, size_t count);
  115. #define DEVICE_ATTR(_name, _mode, _show, _store) \
  116. struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
  117. #define DEVICE_ATTR_PREALLOC(_name, _mode, _show, _store) \
  118. struct device_attribute dev_attr_##_name = \
  119. __ATTR_PREALLOC(_name, _mode, _show, _store)
  120. #define DEVICE_ATTR_RW(_name) \
  121. struct device_attribute dev_attr_##_name = __ATTR_RW(_name)
  122. #define DEVICE_ATTR_ADMIN_RW(_name) \
  123. struct device_attribute dev_attr_##_name = __ATTR_RW_MODE(_name, 0600)
  124. #define DEVICE_ATTR_RO(_name) \
  125. struct device_attribute dev_attr_##_name = __ATTR_RO(_name)
  126. #define DEVICE_ATTR_ADMIN_RO(_name) \
  127. struct device_attribute dev_attr_##_name = __ATTR_RO_MODE(_name, 0400)
  128. #define DEVICE_ATTR_WO(_name) \
  129. struct device_attribute dev_attr_##_name = __ATTR_WO(_name)
  130. #define DEVICE_ULONG_ATTR(_name, _mode, _var) \
  131. struct dev_ext_attribute dev_attr_##_name = \
  132. { __ATTR(_name, _mode, device_show_ulong, device_store_ulong), &(_var) }
  133. #define DEVICE_INT_ATTR(_name, _mode, _var) \
  134. struct dev_ext_attribute dev_attr_##_name = \
  135. { __ATTR(_name, _mode, device_show_int, device_store_int), &(_var) }
  136. #define DEVICE_BOOL_ATTR(_name, _mode, _var) \
  137. struct dev_ext_attribute dev_attr_##_name = \
  138. { __ATTR(_name, _mode, device_show_bool, device_store_bool), &(_var) }
  139. #define DEVICE_ATTR_IGNORE_LOCKDEP(_name, _mode, _show, _store) \
  140. struct device_attribute dev_attr_##_name = \
  141. __ATTR_IGNORE_LOCKDEP(_name, _mode, _show, _store)
  142. int device_create_file(struct device *device,
  143. const struct device_attribute *entry);
  144. void device_remove_file(struct device *dev,
  145. const struct device_attribute *attr);
  146. bool device_remove_file_self(struct device *dev,
  147. const struct device_attribute *attr);
  148. int __must_check device_create_bin_file(struct device *dev,
  149. const struct bin_attribute *attr);
  150. void device_remove_bin_file(struct device *dev,
  151. const struct bin_attribute *attr);
  152. /* device resource management */
  153. typedef void (*dr_release_t)(struct device *dev, void *res);
  154. typedef int (*dr_match_t)(struct device *dev, void *res, void *match_data);
  155. void *__devres_alloc_node(dr_release_t release, size_t size, gfp_t gfp,
  156. int nid, const char *name) __malloc;
  157. #define devres_alloc(release, size, gfp) \
  158. __devres_alloc_node(release, size, gfp, NUMA_NO_NODE, #release)
  159. #define devres_alloc_node(release, size, gfp, nid) \
  160. __devres_alloc_node(release, size, gfp, nid, #release)
  161. void devres_for_each_res(struct device *dev, dr_release_t release,
  162. dr_match_t match, void *match_data,
  163. void (*fn)(struct device *, void *, void *),
  164. void *data);
  165. void devres_free(void *res);
  166. void devres_add(struct device *dev, void *res);
  167. void *devres_find(struct device *dev, dr_release_t release,
  168. dr_match_t match, void *match_data);
  169. void *devres_get(struct device *dev, void *new_res,
  170. dr_match_t match, void *match_data);
  171. void *devres_remove(struct device *dev, dr_release_t release,
  172. dr_match_t match, void *match_data);
  173. int devres_destroy(struct device *dev, dr_release_t release,
  174. dr_match_t match, void *match_data);
  175. int devres_release(struct device *dev, dr_release_t release,
  176. dr_match_t match, void *match_data);
  177. /* devres group */
  178. void * __must_check devres_open_group(struct device *dev, void *id, gfp_t gfp);
  179. void devres_close_group(struct device *dev, void *id);
  180. void devres_remove_group(struct device *dev, void *id);
  181. int devres_release_group(struct device *dev, void *id);
  182. /* managed devm_k.alloc/kfree for device drivers */
  183. void *devm_kmalloc(struct device *dev, size_t size, gfp_t gfp) __malloc;
  184. void *devm_krealloc(struct device *dev, void *ptr, size_t size,
  185. gfp_t gfp) __must_check;
  186. __printf(3, 0) char *devm_kvasprintf(struct device *dev, gfp_t gfp,
  187. const char *fmt, va_list ap) __malloc;
  188. __printf(3, 4) char *devm_kasprintf(struct device *dev, gfp_t gfp,
  189. const char *fmt, ...) __malloc;
  190. static inline void *devm_kzalloc(struct device *dev, size_t size, gfp_t gfp)
  191. {
  192. return devm_kmalloc(dev, size, gfp | __GFP_ZERO);
  193. }
  194. static inline void *devm_kmalloc_array(struct device *dev,
  195. size_t n, size_t size, gfp_t flags)
  196. {
  197. size_t bytes;
  198. if (unlikely(check_mul_overflow(n, size, &bytes)))
  199. return NULL;
  200. return devm_kmalloc(dev, bytes, flags);
  201. }
  202. static inline void *devm_kcalloc(struct device *dev,
  203. size_t n, size_t size, gfp_t flags)
  204. {
  205. return devm_kmalloc_array(dev, n, size, flags | __GFP_ZERO);
  206. }
  207. void devm_kfree(struct device *dev, const void *p);
  208. char *devm_kstrdup(struct device *dev, const char *s, gfp_t gfp) __malloc;
  209. const char *devm_kstrdup_const(struct device *dev, const char *s, gfp_t gfp);
  210. void *devm_kmemdup(struct device *dev, const void *src, size_t len, gfp_t gfp);
  211. unsigned long devm_get_free_pages(struct device *dev,
  212. gfp_t gfp_mask, unsigned int order);
  213. void devm_free_pages(struct device *dev, unsigned long addr);
  214. void __iomem *devm_ioremap_resource(struct device *dev,
  215. const struct resource *res);
  216. void __iomem *devm_ioremap_resource_wc(struct device *dev,
  217. const struct resource *res);
  218. void __iomem *devm_of_iomap(struct device *dev,
  219. struct device_node *node, int index,
  220. resource_size_t *size);
  221. /* allows to add/remove a custom action to devres stack */
  222. int devm_add_action(struct device *dev, void (*action)(void *), void *data);
  223. void devm_remove_action(struct device *dev, void (*action)(void *), void *data);
  224. void devm_release_action(struct device *dev, void (*action)(void *), void *data);
  225. static inline int devm_add_action_or_reset(struct device *dev,
  226. void (*action)(void *), void *data)
  227. {
  228. int ret;
  229. ret = devm_add_action(dev, action, data);
  230. if (ret)
  231. action(data);
  232. return ret;
  233. }
  234. /**
  235. * devm_alloc_percpu - Resource-managed alloc_percpu
  236. * @dev: Device to allocate per-cpu memory for
  237. * @type: Type to allocate per-cpu memory for
  238. *
  239. * Managed alloc_percpu. Per-cpu memory allocated with this function is
  240. * automatically freed on driver detach.
  241. *
  242. * RETURNS:
  243. * Pointer to allocated memory on success, NULL on failure.
  244. */
  245. #define devm_alloc_percpu(dev, type) \
  246. ((typeof(type) __percpu *)__devm_alloc_percpu((dev), sizeof(type), \
  247. __alignof__(type)))
  248. void __percpu *__devm_alloc_percpu(struct device *dev, size_t size,
  249. size_t align);
  250. void devm_free_percpu(struct device *dev, void __percpu *pdata);
  251. struct device_dma_parameters {
  252. /*
  253. * a low level driver may set these to teach IOMMU code about
  254. * sg limitations.
  255. */
  256. unsigned int max_segment_size;
  257. unsigned int min_align_mask;
  258. unsigned long segment_boundary_mask;
  259. };
  260. /**
  261. * enum device_link_state - Device link states.
  262. * @DL_STATE_NONE: The presence of the drivers is not being tracked.
  263. * @DL_STATE_DORMANT: None of the supplier/consumer drivers is present.
  264. * @DL_STATE_AVAILABLE: The supplier driver is present, but the consumer is not.
  265. * @DL_STATE_CONSUMER_PROBE: The consumer is probing (supplier driver present).
  266. * @DL_STATE_ACTIVE: Both the supplier and consumer drivers are present.
  267. * @DL_STATE_SUPPLIER_UNBIND: The supplier driver is unbinding.
  268. */
  269. enum device_link_state {
  270. DL_STATE_NONE = -1,
  271. DL_STATE_DORMANT = 0,
  272. DL_STATE_AVAILABLE,
  273. DL_STATE_CONSUMER_PROBE,
  274. DL_STATE_ACTIVE,
  275. DL_STATE_SUPPLIER_UNBIND,
  276. };
  277. /*
  278. * Device link flags.
  279. *
  280. * STATELESS: The core will not remove this link automatically.
  281. * AUTOREMOVE_CONSUMER: Remove the link automatically on consumer driver unbind.
  282. * PM_RUNTIME: If set, the runtime PM framework will use this link.
  283. * RPM_ACTIVE: Run pm_runtime_get_sync() on the supplier during link creation.
  284. * AUTOREMOVE_SUPPLIER: Remove the link automatically on supplier driver unbind.
  285. * AUTOPROBE_CONSUMER: Probe consumer driver automatically after supplier binds.
  286. * MANAGED: The core tracks presence of supplier/consumer drivers (internal).
  287. * SYNC_STATE_ONLY: Link only affects sync_state() behavior.
  288. * INFERRED: Inferred from data (eg: firmware) and not from driver actions.
  289. */
  290. #define DL_FLAG_STATELESS BIT(0)
  291. #define DL_FLAG_AUTOREMOVE_CONSUMER BIT(1)
  292. #define DL_FLAG_PM_RUNTIME BIT(2)
  293. #define DL_FLAG_RPM_ACTIVE BIT(3)
  294. #define DL_FLAG_AUTOREMOVE_SUPPLIER BIT(4)
  295. #define DL_FLAG_AUTOPROBE_CONSUMER BIT(5)
  296. #define DL_FLAG_MANAGED BIT(6)
  297. #define DL_FLAG_SYNC_STATE_ONLY BIT(7)
  298. #define DL_FLAG_INFERRED BIT(8)
  299. #define DL_FLAG_CYCLE BIT(9)
  300. /**
  301. * enum dl_dev_state - Device driver presence tracking information.
  302. * @DL_DEV_NO_DRIVER: There is no driver attached to the device.
  303. * @DL_DEV_PROBING: A driver is probing.
  304. * @DL_DEV_DRIVER_BOUND: The driver has been bound to the device.
  305. * @DL_DEV_UNBINDING: The driver is unbinding from the device.
  306. */
  307. enum dl_dev_state {
  308. DL_DEV_NO_DRIVER = 0,
  309. DL_DEV_PROBING,
  310. DL_DEV_DRIVER_BOUND,
  311. DL_DEV_UNBINDING,
  312. };
  313. /**
  314. * enum device_removable - Whether the device is removable. The criteria for a
  315. * device to be classified as removable is determined by its subsystem or bus.
  316. * @DEVICE_REMOVABLE_NOT_SUPPORTED: This attribute is not supported for this
  317. * device (default).
  318. * @DEVICE_REMOVABLE_UNKNOWN: Device location is Unknown.
  319. * @DEVICE_FIXED: Device is not removable by the user.
  320. * @DEVICE_REMOVABLE: Device is removable by the user.
  321. */
  322. enum device_removable {
  323. DEVICE_REMOVABLE_NOT_SUPPORTED = 0, /* must be 0 */
  324. DEVICE_REMOVABLE_UNKNOWN,
  325. DEVICE_FIXED,
  326. DEVICE_REMOVABLE,
  327. };
  328. /**
  329. * struct dev_links_info - Device data related to device links.
  330. * @suppliers: List of links to supplier devices.
  331. * @consumers: List of links to consumer devices.
  332. * @defer_sync: Hook to global list of devices that have deferred sync_state.
  333. * @status: Driver status information.
  334. */
  335. struct dev_links_info {
  336. struct list_head suppliers;
  337. struct list_head consumers;
  338. struct list_head defer_sync;
  339. enum dl_dev_state status;
  340. };
  341. /**
  342. * struct dev_msi_info - Device data related to MSI
  343. * @domain: The MSI interrupt domain associated to the device
  344. * @data: Pointer to MSI device data
  345. */
  346. struct dev_msi_info {
  347. #ifdef CONFIG_GENERIC_MSI_IRQ_DOMAIN
  348. struct irq_domain *domain;
  349. #endif
  350. #ifdef CONFIG_GENERIC_MSI_IRQ
  351. struct msi_device_data *data;
  352. #endif
  353. };
  354. /**
  355. * enum device_physical_location_panel - Describes which panel surface of the
  356. * system's housing the device connection point resides on.
  357. * @DEVICE_PANEL_TOP: Device connection point is on the top panel.
  358. * @DEVICE_PANEL_BOTTOM: Device connection point is on the bottom panel.
  359. * @DEVICE_PANEL_LEFT: Device connection point is on the left panel.
  360. * @DEVICE_PANEL_RIGHT: Device connection point is on the right panel.
  361. * @DEVICE_PANEL_FRONT: Device connection point is on the front panel.
  362. * @DEVICE_PANEL_BACK: Device connection point is on the back panel.
  363. * @DEVICE_PANEL_UNKNOWN: The panel with device connection point is unknown.
  364. */
  365. enum device_physical_location_panel {
  366. DEVICE_PANEL_TOP,
  367. DEVICE_PANEL_BOTTOM,
  368. DEVICE_PANEL_LEFT,
  369. DEVICE_PANEL_RIGHT,
  370. DEVICE_PANEL_FRONT,
  371. DEVICE_PANEL_BACK,
  372. DEVICE_PANEL_UNKNOWN,
  373. };
  374. /**
  375. * enum device_physical_location_vertical_position - Describes vertical
  376. * position of the device connection point on the panel surface.
  377. * @DEVICE_VERT_POS_UPPER: Device connection point is at upper part of panel.
  378. * @DEVICE_VERT_POS_CENTER: Device connection point is at center part of panel.
  379. * @DEVICE_VERT_POS_LOWER: Device connection point is at lower part of panel.
  380. */
  381. enum device_physical_location_vertical_position {
  382. DEVICE_VERT_POS_UPPER,
  383. DEVICE_VERT_POS_CENTER,
  384. DEVICE_VERT_POS_LOWER,
  385. };
  386. /**
  387. * enum device_physical_location_horizontal_position - Describes horizontal
  388. * position of the device connection point on the panel surface.
  389. * @DEVICE_HORI_POS_LEFT: Device connection point is at left part of panel.
  390. * @DEVICE_HORI_POS_CENTER: Device connection point is at center part of panel.
  391. * @DEVICE_HORI_POS_RIGHT: Device connection point is at right part of panel.
  392. */
  393. enum device_physical_location_horizontal_position {
  394. DEVICE_HORI_POS_LEFT,
  395. DEVICE_HORI_POS_CENTER,
  396. DEVICE_HORI_POS_RIGHT,
  397. };
  398. /**
  399. * struct device_physical_location - Device data related to physical location
  400. * of the device connection point.
  401. * @panel: Panel surface of the system's housing that the device connection
  402. * point resides on.
  403. * @vertical_position: Vertical position of the device connection point within
  404. * the panel.
  405. * @horizontal_position: Horizontal position of the device connection point
  406. * within the panel.
  407. * @dock: Set if the device connection point resides in a docking station or
  408. * port replicator.
  409. * @lid: Set if this device connection point resides on the lid of laptop
  410. * system.
  411. */
  412. struct device_physical_location {
  413. enum device_physical_location_panel panel;
  414. enum device_physical_location_vertical_position vertical_position;
  415. enum device_physical_location_horizontal_position horizontal_position;
  416. bool dock;
  417. bool lid;
  418. };
  419. /**
  420. * struct device - The basic device structure
  421. * @parent: The device's "parent" device, the device to which it is attached.
  422. * In most cases, a parent device is some sort of bus or host
  423. * controller. If parent is NULL, the device, is a top-level device,
  424. * which is not usually what you want.
  425. * @p: Holds the private data of the driver core portions of the device.
  426. * See the comment of the struct device_private for detail.
  427. * @kobj: A top-level, abstract class from which other classes are derived.
  428. * @init_name: Initial name of the device.
  429. * @type: The type of device.
  430. * This identifies the device type and carries type-specific
  431. * information.
  432. * @mutex: Mutex to synchronize calls to its driver.
  433. * @bus: Type of bus device is on.
  434. * @driver: Which driver has allocated this
  435. * @platform_data: Platform data specific to the device.
  436. * Example: For devices on custom boards, as typical of embedded
  437. * and SOC based hardware, Linux often uses platform_data to point
  438. * to board-specific structures describing devices and how they
  439. * are wired. That can include what ports are available, chip
  440. * variants, which GPIO pins act in what additional roles, and so
  441. * on. This shrinks the "Board Support Packages" (BSPs) and
  442. * minimizes board-specific #ifdefs in drivers.
  443. * @driver_data: Private pointer for driver specific info.
  444. * @links: Links to suppliers and consumers of this device.
  445. * @power: For device power management.
  446. * See Documentation/driver-api/pm/devices.rst for details.
  447. * @pm_domain: Provide callbacks that are executed during system suspend,
  448. * hibernation, system resume and during runtime PM transitions
  449. * along with subsystem-level and driver-level callbacks.
  450. * @em_pd: device's energy model performance domain
  451. * @pins: For device pin management.
  452. * See Documentation/driver-api/pin-control.rst for details.
  453. * @msi: MSI related data
  454. * @numa_node: NUMA node this device is close to.
  455. * @dma_ops: DMA mapping operations for this device.
  456. * @dma_mask: Dma mask (if dma'ble device).
  457. * @coherent_dma_mask: Like dma_mask, but for alloc_coherent mapping as not all
  458. * hardware supports 64-bit addresses for consistent allocations
  459. * such descriptors.
  460. * @bus_dma_limit: Limit of an upstream bridge or bus which imposes a smaller
  461. * DMA limit than the device itself supports.
  462. * @dma_range_map: map for DMA memory ranges relative to that of RAM
  463. * @dma_parms: A low level driver may set these to teach IOMMU code about
  464. * segment limitations.
  465. * @dma_pools: Dma pools (if dma'ble device).
  466. * @dma_mem: Internal for coherent mem override.
  467. * @cma_area: Contiguous memory area for dma allocations
  468. * @dma_io_tlb_mem: Pointer to the swiotlb pool used. Not for driver use.
  469. * @archdata: For arch-specific additions.
  470. * @of_node: Associated device tree node.
  471. * @fwnode: Associated device node supplied by platform firmware.
  472. * @devt: For creating the sysfs "dev".
  473. * @id: device instance
  474. * @devres_lock: Spinlock to protect the resource of the device.
  475. * @devres_head: The resources list of the device.
  476. * @knode_class: The node used to add the device to the class list.
  477. * @class: The class of the device.
  478. * @groups: Optional attribute groups.
  479. * @release: Callback to free the device after all references have
  480. * gone away. This should be set by the allocator of the
  481. * device (i.e. the bus driver that discovered the device).
  482. * @iommu_group: IOMMU group the device belongs to.
  483. * @iommu: Per device generic IOMMU runtime data
  484. * @physical_location: Describes physical location of the device connection
  485. * point in the system housing.
  486. * @removable: Whether the device can be removed from the system. This
  487. * should be set by the subsystem / bus driver that discovered
  488. * the device.
  489. *
  490. * @offline_disabled: If set, the device is permanently online.
  491. * @offline: Set after successful invocation of bus type's .offline().
  492. * @of_node_reused: Set if the device-tree node is shared with an ancestor
  493. * device.
  494. * @state_synced: The hardware state of this device has been synced to match
  495. * the software state of this device by calling the driver/bus
  496. * sync_state() callback.
  497. * @can_match: The device has matched with a driver at least once or it is in
  498. * a bus (like AMBA) which can't check for matching drivers until
  499. * other devices probe successfully.
  500. * @dma_coherent: this particular device is dma coherent, even if the
  501. * architecture supports non-coherent devices.
  502. * @dma_ops_bypass: If set to %true then the dma_ops are bypassed for the
  503. * streaming DMA operations (->map_* / ->unmap_* / ->sync_*),
  504. * and optionall (if the coherent mask is large enough) also
  505. * for dma allocations. This flag is managed by the dma ops
  506. * instance from ->dma_supported.
  507. *
  508. * At the lowest level, every device in a Linux system is represented by an
  509. * instance of struct device. The device structure contains the information
  510. * that the device model core needs to model the system. Most subsystems,
  511. * however, track additional information about the devices they host. As a
  512. * result, it is rare for devices to be represented by bare device structures;
  513. * instead, that structure, like kobject structures, is usually embedded within
  514. * a higher-level representation of the device.
  515. */
  516. struct device {
  517. struct kobject kobj;
  518. struct device *parent;
  519. struct device_private *p;
  520. const char *init_name; /* initial name of the device */
  521. const struct device_type *type;
  522. struct bus_type *bus; /* type of bus device is on */
  523. struct device_driver *driver; /* which driver has allocated this
  524. device */
  525. void *platform_data; /* Platform specific data, device
  526. core doesn't touch it */
  527. void *driver_data; /* Driver data, set and get with
  528. dev_set_drvdata/dev_get_drvdata */
  529. struct mutex mutex; /* mutex to synchronize calls to
  530. * its driver.
  531. */
  532. struct dev_links_info links;
  533. struct dev_pm_info power;
  534. struct dev_pm_domain *pm_domain;
  535. #ifdef CONFIG_ENERGY_MODEL
  536. struct em_perf_domain *em_pd;
  537. #endif
  538. #ifdef CONFIG_PINCTRL
  539. struct dev_pin_info *pins;
  540. #endif
  541. struct dev_msi_info msi;
  542. #ifdef CONFIG_DMA_OPS
  543. const struct dma_map_ops *dma_ops;
  544. #endif
  545. u64 *dma_mask; /* dma mask (if dma'able device) */
  546. u64 coherent_dma_mask;/* Like dma_mask, but for
  547. alloc_coherent mappings as
  548. not all hardware supports
  549. 64 bit addresses for consistent
  550. allocations such descriptors. */
  551. u64 bus_dma_limit; /* upstream dma constraint */
  552. const struct bus_dma_region *dma_range_map;
  553. struct device_dma_parameters *dma_parms;
  554. struct list_head dma_pools; /* dma pools (if dma'ble) */
  555. #ifdef CONFIG_DMA_DECLARE_COHERENT
  556. struct dma_coherent_mem *dma_mem; /* internal for coherent mem
  557. override */
  558. #endif
  559. #ifdef CONFIG_DMA_CMA
  560. struct cma *cma_area; /* contiguous memory area for dma
  561. allocations */
  562. #endif
  563. #ifdef CONFIG_SWIOTLB
  564. struct io_tlb_mem *dma_io_tlb_mem;
  565. #endif
  566. /* arch specific additions */
  567. struct dev_archdata archdata;
  568. struct device_node *of_node; /* associated device tree node */
  569. struct fwnode_handle *fwnode; /* firmware device node */
  570. #ifdef CONFIG_NUMA
  571. int numa_node; /* NUMA node this device is close to */
  572. #endif
  573. dev_t devt; /* dev_t, creates the sysfs "dev" */
  574. u32 id; /* device instance */
  575. spinlock_t devres_lock;
  576. struct list_head devres_head;
  577. struct class *class;
  578. const struct attribute_group **groups; /* optional groups */
  579. void (*release)(struct device *dev);
  580. struct iommu_group *iommu_group;
  581. struct dev_iommu *iommu;
  582. struct device_physical_location *physical_location;
  583. enum device_removable removable;
  584. bool offline_disabled:1;
  585. bool offline:1;
  586. bool of_node_reused:1;
  587. bool state_synced:1;
  588. bool can_match:1;
  589. #if defined(CONFIG_ARCH_HAS_SYNC_DMA_FOR_DEVICE) || \
  590. defined(CONFIG_ARCH_HAS_SYNC_DMA_FOR_CPU) || \
  591. defined(CONFIG_ARCH_HAS_SYNC_DMA_FOR_CPU_ALL)
  592. bool dma_coherent:1;
  593. #endif
  594. #ifdef CONFIG_DMA_OPS_BYPASS
  595. bool dma_ops_bypass : 1;
  596. #endif
  597. ANDROID_KABI_RESERVE(1);
  598. ANDROID_KABI_RESERVE(2);
  599. ANDROID_KABI_RESERVE(3);
  600. ANDROID_KABI_RESERVE(4);
  601. ANDROID_KABI_RESERVE(5);
  602. ANDROID_KABI_RESERVE(6);
  603. ANDROID_KABI_RESERVE(7);
  604. ANDROID_KABI_RESERVE(8);
  605. };
  606. /**
  607. * struct device_link - Device link representation.
  608. * @supplier: The device on the supplier end of the link.
  609. * @s_node: Hook to the supplier device's list of links to consumers.
  610. * @consumer: The device on the consumer end of the link.
  611. * @c_node: Hook to the consumer device's list of links to suppliers.
  612. * @link_dev: device used to expose link details in sysfs
  613. * @status: The state of the link (with respect to the presence of drivers).
  614. * @flags: Link flags.
  615. * @rpm_active: Whether or not the consumer device is runtime-PM-active.
  616. * @kref: Count repeated addition of the same link.
  617. * @rm_work: Work structure used for removing the link.
  618. * @supplier_preactivated: Supplier has been made active before consumer probe.
  619. */
  620. struct device_link {
  621. struct device *supplier;
  622. struct list_head s_node;
  623. struct device *consumer;
  624. struct list_head c_node;
  625. struct device link_dev;
  626. enum device_link_state status;
  627. u32 flags;
  628. refcount_t rpm_active;
  629. struct kref kref;
  630. struct work_struct rm_work;
  631. bool supplier_preactivated; /* Owned by consumer probe. */
  632. ANDROID_KABI_RESERVE(1);
  633. ANDROID_KABI_RESERVE(2);
  634. };
  635. static inline struct device *kobj_to_dev(struct kobject *kobj)
  636. {
  637. return container_of(kobj, struct device, kobj);
  638. }
  639. /**
  640. * device_iommu_mapped - Returns true when the device DMA is translated
  641. * by an IOMMU
  642. * @dev: Device to perform the check on
  643. */
  644. static inline bool device_iommu_mapped(struct device *dev)
  645. {
  646. return (dev->iommu_group != NULL);
  647. }
  648. /* Get the wakeup routines, which depend on struct device */
  649. #include <linux/pm_wakeup.h>
  650. static inline const char *dev_name(const struct device *dev)
  651. {
  652. /* Use the init name until the kobject becomes available */
  653. if (dev->init_name)
  654. return dev->init_name;
  655. return kobject_name(&dev->kobj);
  656. }
  657. /**
  658. * dev_bus_name - Return a device's bus/class name, if at all possible
  659. * @dev: struct device to get the bus/class name of
  660. *
  661. * Will return the name of the bus/class the device is attached to. If it is
  662. * not attached to a bus/class, an empty string will be returned.
  663. */
  664. static inline const char *dev_bus_name(const struct device *dev)
  665. {
  666. return dev->bus ? dev->bus->name : (dev->class ? dev->class->name : "");
  667. }
  668. __printf(2, 3) int dev_set_name(struct device *dev, const char *name, ...);
  669. #ifdef CONFIG_NUMA
  670. static inline int dev_to_node(struct device *dev)
  671. {
  672. return dev->numa_node;
  673. }
  674. static inline void set_dev_node(struct device *dev, int node)
  675. {
  676. dev->numa_node = node;
  677. }
  678. #else
  679. static inline int dev_to_node(struct device *dev)
  680. {
  681. return NUMA_NO_NODE;
  682. }
  683. static inline void set_dev_node(struct device *dev, int node)
  684. {
  685. }
  686. #endif
  687. static inline struct irq_domain *dev_get_msi_domain(const struct device *dev)
  688. {
  689. #ifdef CONFIG_GENERIC_MSI_IRQ_DOMAIN
  690. return dev->msi.domain;
  691. #else
  692. return NULL;
  693. #endif
  694. }
  695. static inline void dev_set_msi_domain(struct device *dev, struct irq_domain *d)
  696. {
  697. #ifdef CONFIG_GENERIC_MSI_IRQ_DOMAIN
  698. dev->msi.domain = d;
  699. #endif
  700. }
  701. static inline void *dev_get_drvdata(const struct device *dev)
  702. {
  703. return dev->driver_data;
  704. }
  705. static inline void dev_set_drvdata(struct device *dev, void *data)
  706. {
  707. dev->driver_data = data;
  708. }
  709. static inline struct pm_subsys_data *dev_to_psd(struct device *dev)
  710. {
  711. return dev ? dev->power.subsys_data : NULL;
  712. }
  713. static inline unsigned int dev_get_uevent_suppress(const struct device *dev)
  714. {
  715. return dev->kobj.uevent_suppress;
  716. }
  717. static inline void dev_set_uevent_suppress(struct device *dev, int val)
  718. {
  719. dev->kobj.uevent_suppress = val;
  720. }
  721. static inline int device_is_registered(struct device *dev)
  722. {
  723. return dev->kobj.state_in_sysfs;
  724. }
  725. static inline void device_enable_async_suspend(struct device *dev)
  726. {
  727. if (!dev->power.is_prepared)
  728. dev->power.async_suspend = true;
  729. }
  730. static inline void device_disable_async_suspend(struct device *dev)
  731. {
  732. if (!dev->power.is_prepared)
  733. dev->power.async_suspend = false;
  734. }
  735. static inline bool device_async_suspend_enabled(struct device *dev)
  736. {
  737. return !!dev->power.async_suspend;
  738. }
  739. static inline bool device_pm_not_required(struct device *dev)
  740. {
  741. return dev->power.no_pm;
  742. }
  743. static inline void device_set_pm_not_required(struct device *dev)
  744. {
  745. dev->power.no_pm = true;
  746. }
  747. static inline void dev_pm_syscore_device(struct device *dev, bool val)
  748. {
  749. #ifdef CONFIG_PM_SLEEP
  750. dev->power.syscore = val;
  751. #endif
  752. }
  753. static inline void dev_pm_set_driver_flags(struct device *dev, u32 flags)
  754. {
  755. dev->power.driver_flags = flags;
  756. }
  757. static inline bool dev_pm_test_driver_flags(struct device *dev, u32 flags)
  758. {
  759. return !!(dev->power.driver_flags & flags);
  760. }
  761. static inline void device_lock(struct device *dev)
  762. {
  763. mutex_lock(&dev->mutex);
  764. }
  765. static inline int device_lock_interruptible(struct device *dev)
  766. {
  767. return mutex_lock_interruptible(&dev->mutex);
  768. }
  769. static inline int device_trylock(struct device *dev)
  770. {
  771. return mutex_trylock(&dev->mutex);
  772. }
  773. static inline void device_unlock(struct device *dev)
  774. {
  775. mutex_unlock(&dev->mutex);
  776. }
  777. static inline void device_lock_assert(struct device *dev)
  778. {
  779. lockdep_assert_held(&dev->mutex);
  780. }
  781. static inline struct device_node *dev_of_node(struct device *dev)
  782. {
  783. if (!IS_ENABLED(CONFIG_OF) || !dev)
  784. return NULL;
  785. return dev->of_node;
  786. }
  787. static inline bool dev_has_sync_state(struct device *dev)
  788. {
  789. if (!dev)
  790. return false;
  791. if (dev->driver && dev->driver->sync_state)
  792. return true;
  793. if (dev->bus && dev->bus->sync_state)
  794. return true;
  795. return false;
  796. }
  797. static inline void dev_set_removable(struct device *dev,
  798. enum device_removable removable)
  799. {
  800. dev->removable = removable;
  801. }
  802. static inline bool dev_is_removable(struct device *dev)
  803. {
  804. return dev->removable == DEVICE_REMOVABLE;
  805. }
  806. static inline bool dev_removable_is_valid(struct device *dev)
  807. {
  808. return dev->removable != DEVICE_REMOVABLE_NOT_SUPPORTED;
  809. }
  810. /*
  811. * High level routines for use by the bus drivers
  812. */
  813. int __must_check device_register(struct device *dev);
  814. void device_unregister(struct device *dev);
  815. void device_initialize(struct device *dev);
  816. int __must_check device_add(struct device *dev);
  817. void device_del(struct device *dev);
  818. int device_for_each_child(struct device *dev, void *data,
  819. int (*fn)(struct device *dev, void *data));
  820. int device_for_each_child_reverse(struct device *dev, void *data,
  821. int (*fn)(struct device *dev, void *data));
  822. struct device *device_find_child(struct device *dev, void *data,
  823. int (*match)(struct device *dev, void *data));
  824. struct device *device_find_child_by_name(struct device *parent,
  825. const char *name);
  826. struct device *device_find_any_child(struct device *parent);
  827. int device_rename(struct device *dev, const char *new_name);
  828. int device_move(struct device *dev, struct device *new_parent,
  829. enum dpm_order dpm_order);
  830. int device_change_owner(struct device *dev, kuid_t kuid, kgid_t kgid);
  831. const char *device_get_devnode(struct device *dev, umode_t *mode, kuid_t *uid,
  832. kgid_t *gid, const char **tmp);
  833. int device_is_dependent(struct device *dev, void *target);
  834. static inline bool device_supports_offline(struct device *dev)
  835. {
  836. return dev->bus && dev->bus->offline && dev->bus->online;
  837. }
  838. #define __device_lock_set_class(dev, name, key) \
  839. do { \
  840. struct device *__d2 __maybe_unused = dev; \
  841. lock_set_class(&__d2->mutex.dep_map, name, key, 0, _THIS_IP_); \
  842. } while (0)
  843. /**
  844. * device_lock_set_class - Specify a temporary lock class while a device
  845. * is attached to a driver
  846. * @dev: device to modify
  847. * @key: lock class key data
  848. *
  849. * This must be called with the device_lock() already held, for example
  850. * from driver ->probe(). Take care to only override the default
  851. * lockdep_no_validate class.
  852. */
  853. #ifdef CONFIG_LOCKDEP
  854. #define device_lock_set_class(dev, key) \
  855. do { \
  856. struct device *__d = dev; \
  857. dev_WARN_ONCE(__d, !lockdep_match_class(&__d->mutex, \
  858. &__lockdep_no_validate__), \
  859. "overriding existing custom lock class\n"); \
  860. __device_lock_set_class(__d, #key, key); \
  861. } while (0)
  862. #else
  863. #define device_lock_set_class(dev, key) __device_lock_set_class(dev, #key, key)
  864. #endif
  865. /**
  866. * device_lock_reset_class - Return a device to the default lockdep novalidate state
  867. * @dev: device to modify
  868. *
  869. * This must be called with the device_lock() already held, for example
  870. * from driver ->remove().
  871. */
  872. #define device_lock_reset_class(dev) \
  873. do { \
  874. struct device *__d __maybe_unused = dev; \
  875. lock_set_novalidate_class(&__d->mutex.dep_map, "&dev->mutex", \
  876. _THIS_IP_); \
  877. } while (0)
  878. void lock_device_hotplug(void);
  879. void unlock_device_hotplug(void);
  880. int lock_device_hotplug_sysfs(void);
  881. int device_offline(struct device *dev);
  882. int device_online(struct device *dev);
  883. void set_primary_fwnode(struct device *dev, struct fwnode_handle *fwnode);
  884. void set_secondary_fwnode(struct device *dev, struct fwnode_handle *fwnode);
  885. void device_set_of_node_from_dev(struct device *dev, const struct device *dev2);
  886. void device_set_node(struct device *dev, struct fwnode_handle *fwnode);
  887. static inline int dev_num_vf(struct device *dev)
  888. {
  889. if (dev->bus && dev->bus->num_vf)
  890. return dev->bus->num_vf(dev);
  891. return 0;
  892. }
  893. /*
  894. * Root device objects for grouping under /sys/devices
  895. */
  896. struct device *__root_device_register(const char *name, struct module *owner);
  897. /* This is a macro to avoid include problems with THIS_MODULE */
  898. #define root_device_register(name) \
  899. __root_device_register(name, THIS_MODULE)
  900. void root_device_unregister(struct device *root);
  901. static inline void *dev_get_platdata(const struct device *dev)
  902. {
  903. return dev->platform_data;
  904. }
  905. /*
  906. * Manual binding of a device to driver. See drivers/base/bus.c
  907. * for information on use.
  908. */
  909. int __must_check device_driver_attach(struct device_driver *drv,
  910. struct device *dev);
  911. int __must_check device_bind_driver(struct device *dev);
  912. void device_release_driver(struct device *dev);
  913. int __must_check device_attach(struct device *dev);
  914. int __must_check driver_attach(struct device_driver *drv);
  915. void device_initial_probe(struct device *dev);
  916. int __must_check device_reprobe(struct device *dev);
  917. bool device_is_bound(struct device *dev);
  918. /*
  919. * Easy functions for dynamically creating devices on the fly
  920. */
  921. __printf(5, 6) struct device *
  922. device_create(struct class *cls, struct device *parent, dev_t devt,
  923. void *drvdata, const char *fmt, ...);
  924. __printf(6, 7) struct device *
  925. device_create_with_groups(struct class *cls, struct device *parent, dev_t devt,
  926. void *drvdata, const struct attribute_group **groups,
  927. const char *fmt, ...);
  928. void device_destroy(struct class *cls, dev_t devt);
  929. int __must_check device_add_groups(struct device *dev,
  930. const struct attribute_group **groups);
  931. void device_remove_groups(struct device *dev,
  932. const struct attribute_group **groups);
  933. static inline int __must_check device_add_group(struct device *dev,
  934. const struct attribute_group *grp)
  935. {
  936. const struct attribute_group *groups[] = { grp, NULL };
  937. return device_add_groups(dev, groups);
  938. }
  939. static inline void device_remove_group(struct device *dev,
  940. const struct attribute_group *grp)
  941. {
  942. const struct attribute_group *groups[] = { grp, NULL };
  943. return device_remove_groups(dev, groups);
  944. }
  945. int __must_check devm_device_add_groups(struct device *dev,
  946. const struct attribute_group **groups);
  947. void devm_device_remove_groups(struct device *dev,
  948. const struct attribute_group **groups);
  949. int __must_check devm_device_add_group(struct device *dev,
  950. const struct attribute_group *grp);
  951. void devm_device_remove_group(struct device *dev,
  952. const struct attribute_group *grp);
  953. /*
  954. * Platform "fixup" functions - allow the platform to have their say
  955. * about devices and actions that the general device layer doesn't
  956. * know about.
  957. */
  958. /* Notify platform of device discovery */
  959. extern int (*platform_notify)(struct device *dev);
  960. extern int (*platform_notify_remove)(struct device *dev);
  961. /*
  962. * get_device - atomically increment the reference count for the device.
  963. *
  964. */
  965. struct device *get_device(struct device *dev);
  966. void put_device(struct device *dev);
  967. bool kill_device(struct device *dev);
  968. #ifdef CONFIG_DEVTMPFS
  969. int devtmpfs_mount(void);
  970. #else
  971. static inline int devtmpfs_mount(void) { return 0; }
  972. #endif
  973. /* drivers/base/power/shutdown.c */
  974. void device_shutdown(void);
  975. /* debugging and troubleshooting/diagnostic helpers. */
  976. const char *dev_driver_string(const struct device *dev);
  977. /* Device links interface. */
  978. struct device_link *device_link_add(struct device *consumer,
  979. struct device *supplier, u32 flags);
  980. void device_link_del(struct device_link *link);
  981. void device_link_remove(void *consumer, struct device *supplier);
  982. void device_links_supplier_sync_state_pause(void);
  983. void device_links_supplier_sync_state_resume(void);
  984. extern __printf(3, 4)
  985. int dev_err_probe(const struct device *dev, int err, const char *fmt, ...);
  986. /* Create alias, so I can be autoloaded. */
  987. #define MODULE_ALIAS_CHARDEV(major,minor) \
  988. MODULE_ALIAS("char-major-" __stringify(major) "-" __stringify(minor))
  989. #define MODULE_ALIAS_CHARDEV_MAJOR(major) \
  990. MODULE_ALIAS("char-major-" __stringify(major) "-*")
  991. #ifdef CONFIG_SYSFS_DEPRECATED
  992. extern long sysfs_deprecated;
  993. #else
  994. #define sysfs_deprecated 0
  995. #endif
  996. #endif /* _DEVICE_H_ */