1 // SPDX-License-Identifier: GPL-2.0
3  * device.h - generic, centralized driver model
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.
9  * See Documentation/driver-api/driver-model/ for more information.
51  * struct subsys_interface - interfaces to device functions
61  * a specific functionality of a subsystem/class of devices.
83  * This identifies the device type and carries type-specific
100  * struct device_attribute - Interface for exporting device attributes.
114  * struct dev_ext_attribute - Exported device attribute with extra context.
139  * DEVICE_ATTR - Define a device attribute.
149  * .. code-block:: c
161  * DEVICE_ATTR_PREALLOC - Define a preallocated device attribute.
174  * DEVICE_ATTR_RW - Define a read-write device attribute.
184  * DEVICE_ATTR_ADMIN_RW - Define an admin-only read-write device attribute.
193  * DEVICE_ATTR_RO - Define a readable device attribute.
202  * DEVICE_ATTR_ADMIN_RO - Define an admin-only readable device attribute.
211  * DEVICE_ATTR_WO - Define an admin-only writable device attribute.
220  * DEVICE_ULONG_ATTR - Define a device attribute backed by an unsigned long.
233  * DEVICE_INT_ATTR - Define a device attribute backed by an int.
245  * DEVICE_BOOL_ATTR - Define a device attribute backed by a bool.
257  * DEVICE_STRING_ATTR_RO - Define a device attribute backed by a r/o string.
263  * string allocation is unknown, the attribute must be read-only.
381 	return ERR_PTR(-EINVAL);  in devm_ioremap_resource()
388 	return ERR_PTR(-EINVAL);  in devm_ioremap_resource_wc()
396 	return ERR_PTR(-EINVAL);  in devm_of_iomap()
405  * devm_remove_action() - removes previously added custom action
440  * devm_alloc_percpu - Resource-managed alloc_percpu
441  * @dev: Device to allocate per-cpu memory for
442  * @type: Type to allocate per-cpu memory for
444  * Managed alloc_percpu. Per-cpu memory allocated with this function is
469  * enum device_link_state - Device link states.
478 	DL_STATE_NONE = -1,
511  * enum dl_dev_state - Device driver presence tracking information.
525  * enum device_removable - Whether the device is removable. The criteria for a
541  * struct dev_links_info - Device data related to device links.
555  * struct dev_msi_info - Device data related to MSI
567  * enum device_physical_location_panel - Describes which panel surface of the
569  * @DEVICE_PANEL_TOP: Device connection point is on the top panel.
570  * @DEVICE_PANEL_BOTTOM: Device connection point is on the bottom panel.
571  * @DEVICE_PANEL_LEFT: Device connection point is on the left panel.
572  * @DEVICE_PANEL_RIGHT: Device connection point is on the right panel.
573  * @DEVICE_PANEL_FRONT: Device connection point is on the front panel.
574  * @DEVICE_PANEL_BACK: Device connection point is on the back panel.
575  * @DEVICE_PANEL_UNKNOWN: The panel with device connection point is unknown.
588  * enum device_physical_location_vertical_position - Describes vertical
589  * position of the device connection point on the panel surface.
590  * @DEVICE_VERT_POS_UPPER: Device connection point is at upper part of panel.
591  * @DEVICE_VERT_POS_CENTER: Device connection point is at center part of panel.
592  * @DEVICE_VERT_POS_LOWER: Device connection point is at lower part of panel.
601  * enum device_physical_location_horizontal_position - Describes horizontal
602  * position of the device connection point on the panel surface.
603  * @DEVICE_HORI_POS_LEFT: Device connection point is at left part of panel.
604  * @DEVICE_HORI_POS_CENTER: Device connection point is at center part of panel.
605  * @DEVICE_HORI_POS_RIGHT: Device connection point is at right part of panel.
614  * struct device_physical_location - Device data related to physical location
616  * @panel: Panel surface of the system's housing that the device connection
619  *                     the panel.
621  *                       within the panel.
628 	enum device_physical_location_panel panel;  member
636  * struct device - The basic device structure
639  * 		controller. If parent is NULL, the device, is a top-level device,
643  * @kobj:	A top-level, abstract class from which other classes are derived.
646  * 		This identifies the device type and carries type-specific
651  * @platform_data: Platform data specific to the device.
654  * 		to board-specific structures describing devices and how they
658  * 		minimizes board-specific #ifdefs in drivers.
659  * @driver_data: Private pointer for driver specific info.
662  *		See Documentation/driver-api/pm/devices.rst for details.
665  * 		along with subsystem-level and driver-level callbacks.
668  *		See Documentation/driver-api/pin-control.rst for details.
674  * 		hardware supports 64-bit addresses for consistent allocations
688  * @archdata:	For arch-specific additions.
710  * @of_node_reused: Set if the device-tree node is shared with an ancestor
719  *		architecture supports non-coherent devices.
721  *		streaming DMA operations (->map_* / ->unmap_* / ->sync_*),
724  *		instance from ->dma_supported.
735  * a higher-level representation of the device.
749 	void		*platform_data;	/* Platform specific data, device
801 	/* arch specific additions */
849  * struct device_link - Device link representation.
857  * @rpm_active: Whether or not the consumer device is runtime-PM-active.
879  * device_iommu_mapped - Returns true when the device DMA is translated
885 	return (dev->iommu_group != NULL);  in device_iommu_mapped()
892  * dev_name - Return a device's name.
899 	if (dev->init_name)  in dev_name()
900 		return dev->init_name;  in dev_name()
902 	return kobject_name(&dev->kobj);  in dev_name()
906  * dev_bus_name - Return a device's bus/class name, if at all possible
914 	return dev->bus ? dev->bus->name : (dev->class ? dev->class->name : "");  in dev_bus_name()
922 	return dev->numa_node;  in dev_to_node()
926 	dev->numa_node = node;  in set_dev_node()
941 	return dev->msi.domain;  in dev_get_msi_domain()
950 	dev->msi.domain = d;  in dev_set_msi_domain()
956 	return dev->driver_data;  in dev_get_drvdata()
961 	dev->driver_data = data;  in dev_set_drvdata()
966 	return dev ? dev->power.subsys_data : NULL;  in dev_to_psd()
971 	return dev->kobj.uevent_suppress;  in dev_get_uevent_suppress()
976 	dev->kobj.uevent_suppress = val;  in dev_set_uevent_suppress()
981 	return dev->kobj.state_in_sysfs;  in device_is_registered()
986 	if (!dev->power.is_prepared)  in device_enable_async_suspend()
987 		dev->power.async_suspend = true;  in device_enable_async_suspend()
992 	if (!dev->power.is_prepared)  in device_disable_async_suspend()
993 		dev->power.async_suspend = false;  in device_disable_async_suspend()
998 	return !!dev->power.async_suspend;  in device_async_suspend_enabled()
1003 	return dev->power.no_pm;  in device_pm_not_required()
1008 	dev->power.no_pm = true;  in device_set_pm_not_required()
1014 	dev->power.syscore = val;  in dev_pm_syscore_device()
1020 	dev->power.driver_flags = flags;  in dev_pm_set_driver_flags()
1025 	return !!(dev->power.driver_flags & flags);  in dev_pm_test_driver_flags()
1030 	mutex_lock(&dev->mutex);  in device_lock()
1035 	return mutex_lock_interruptible(&dev->mutex);  in device_lock_interruptible()
1040 	return mutex_trylock(&dev->mutex);  in device_trylock()
1045 	mutex_unlock(&dev->mutex);  in device_unlock()
1052 	lockdep_assert_held(&dev->mutex);  in DEFINE_GUARD()
1059 	if (dev->driver && dev->driver->sync_state)  in dev_has_sync_state()
1061 	if (dev->bus && dev->bus->sync_state)  in dev_has_sync_state()
1069 	dev->removable = removable;  in dev_set_removable()
1074 	return dev->removable == DEVICE_REMOVABLE;  in dev_is_removable()
1079 	return dev->removable != DEVICE_REMOVABLE_NOT_SUPPORTED;  in dev_removable_is_valid()
1103  * device_find_child_by_name - device iterator for locating a child device.
1119  * device_find_any_child - device iterator for locating a child device, if any.
1139 	return dev->bus && dev->bus->offline && dev->bus->online;  in device_supports_offline()
1145 	lock_set_class(&__d2->mutex.dep_map, name, key, 0, _THIS_IP_); \
1149  * device_lock_set_class - Specify a temporary lock class while a device
1155  * from driver ->probe(). Take care to only override the default
1162 	dev_WARN_ONCE(__d, !lockdep_match_class(&__d->mutex,               \
1172  * device_lock_reset_class - Return a device to the default lockdep novalidate state
1176  * from driver ->remove().
1181 	lock_set_novalidate_class(&__d->mutex.dep_map, "&dev->mutex",  \
1200 	return dev->of_node;  in dev_of_node()
1205 	if (dev->bus && dev->bus->num_vf)  in dev_num_vf()
1206 		return dev->bus->num_vf(dev);  in dev_num_vf()
1223 	return dev->platform_data;  in dev_get_platdata()
1278  * get_device - atomically increment the reference count for the device.
1311 	MODULE_ALIAS("char-major-" __stringify(major) "-" __stringify(minor))
1313 	MODULE_ALIAS("char-major-" __stringify(major) "-*")