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