bus.h

  1// SPDX-License-Identifier: GPL-2.0
  2/*
  3 * bus.h - the bus-specific portions of the 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 * Copyright (c) 2012-2019 Greg Kroah-Hartman <gregkh@linuxfoundation.org>
  9 * Copyright (c) 2012-2019 Linux Foundation
 10 *
 11 * See Documentation/driver-api/driver-model/ for more information.
 12 */
 13
 14#ifndef _DEVICE_BUS_H_
 15#define _DEVICE_BUS_H_
 16
 17#include <linux/kobject.h>
 18#include <linux/klist.h>
 19#include <linux/pm.h>
 20
 21struct device_driver;
 22struct fwnode_handle;
 23
 24/**
 25 * struct bus_type - The bus type of the device
 26 *
 27 * @name:	The name of the bus.
 28 * @dev_name:	Used for subsystems to enumerate devices like ("foo%u", dev->id).
 29 * @bus_groups:	Default attributes of the bus.
 30 * @dev_groups:	Default attributes of the devices on the bus.
 31 * @drv_groups: Default attributes of the device drivers on the bus.
 32 * @match:	Called, perhaps multiple times, whenever a new device or driver
 33 *		is added for this bus. It should return a positive value if the
 34 *		given device can be handled by the given driver and zero
 35 *		otherwise. It may also return error code if determining that
 36 *		the driver supports the device is not possible. In case of
 37 *		-EPROBE_DEFER it will queue the device for deferred probing.
 38 * @uevent:	Called when a device is added, removed, or a few other things
 39 *		that generate uevents to add the environment variables.
 40 * @probe:	Called when a new device or driver add to this bus, and callback
 41 *		the specific driver's probe to initial the matched device.
 42 * @sync_state:	Called to sync device state to software state after all the
 43 *		state tracking consumers linked to this device (present at
 44 *		the time of late_initcall) have successfully bound to a
 45 *		driver. If the device has no consumers, this function will
 46 *		be called at late_initcall_sync level. If the device has
 47 *		consumers that are never bound to a driver, this function
 48 *		will never get called until they do.
 49 * @remove:	Called when a device removed from this bus.
 50 * @shutdown:	Called at shut-down time to quiesce the device.
 51 * @irq_get_affinity:	Get IRQ affinity mask for the device on this bus.
 52 *
 53 * @online:	Called to put the device back online (after offlining it).
 54 * @offline:	Called to put the device offline for hot-removal. May fail.
 55 *
 56 * @suspend:	Called when a device on this bus wants to go to sleep mode.
 57 * @resume:	Called to bring a device on this bus out of sleep mode.
 58 * @num_vf:	Called to find out how many virtual functions a device on this
 59 *		bus supports.
 60 * @dma_configure:	Called to setup DMA configuration on a device on
 61 *			this bus.
 62 * @dma_cleanup:	Called to cleanup DMA configuration on a device on
 63 *			this bus.
 64 * @pm:		Power management operations of this bus, callback the specific
 65 *		device driver's pm-ops.
 66 * @driver_override:	Set to true if this bus supports the driver_override
 67 *			mechanism, which allows userspace to force a specific
 68 *			driver to bind to a device via a sysfs attribute.
 69 * @need_parent_lock:	When probing or removing a device on this bus, the
 70 *			device core should lock the device's parent.
 71 *
 72 * A bus is a channel between the processor and one or more devices. For the
 73 * purposes of the device model, all devices are connected via a bus, even if
 74 * it is an internal, virtual, "platform" bus. Buses can plug into each other.
 75 * A USB controller is usually a PCI device, for example. The device model
 76 * represents the actual connections between buses and the devices they control.
 77 * A bus is represented by the bus_type structure. It contains the name, the
 78 * default attributes, the bus' methods, PM operations, and the driver core's
 79 * private data.
 80 */
 81struct bus_type {
 82	const char		*name;
 83	const char		*dev_name;
 84	const struct attribute_group **bus_groups;
 85	const struct attribute_group **dev_groups;
 86	const struct attribute_group **drv_groups;
 87
 88	int (*match)(struct device *dev, const struct device_driver *drv);
 89	int (*uevent)(const struct device *dev, struct kobj_uevent_env *env);
 90	int (*probe)(struct device *dev);
 91	void (*sync_state)(struct device *dev);
 92	void (*remove)(struct device *dev);
 93	void (*shutdown)(struct device *dev);
 94	const struct cpumask *(*irq_get_affinity)(struct device *dev,
 95			unsigned int irq_vec);
 96
 97	int (*online)(struct device *dev);
 98	int (*offline)(struct device *dev);
 99
100	int (*suspend)(struct device *dev, pm_message_t state);
101	int (*resume)(struct device *dev);
102
103	int (*num_vf)(struct device *dev);
104
105	int (*dma_configure)(struct device *dev);
106	void (*dma_cleanup)(struct device *dev);
107
108	const struct dev_pm_ops *pm;
109
110	bool driver_override;
111	bool need_parent_lock;
112};
113
114int __must_check bus_register(const struct bus_type *bus);
115
116void bus_unregister(const struct bus_type *bus);
117
118int __must_check bus_rescan_devices(const struct bus_type *bus);
119
120struct bus_attribute {
121	struct attribute	attr;
122	ssize_t (*show)(const struct bus_type *bus, char *buf);
123	ssize_t (*store)(const struct bus_type *bus, const char *buf, size_t count);
124};
125
126#define BUS_ATTR_RW(_name) \
127	struct bus_attribute bus_attr_##_name = __ATTR_RW(_name)
128#define BUS_ATTR_RO(_name) \
129	struct bus_attribute bus_attr_##_name = __ATTR_RO(_name)
130#define BUS_ATTR_WO(_name) \
131	struct bus_attribute bus_attr_##_name = __ATTR_WO(_name)
132
133int __must_check bus_create_file(const struct bus_type *bus, struct bus_attribute *attr);
134void bus_remove_file(const struct bus_type *bus, struct bus_attribute *attr);
135
136/* Matching function type for drivers/base APIs to find a specific device */
137typedef int (*device_match_t)(struct device *dev, const void *data);
138
139/* Generic device matching functions that all busses can use to match with */
140int device_match_name(struct device *dev, const void *name);
141int device_match_type(struct device *dev, const void *type);
142int device_match_of_node(struct device *dev, const void *np);
143int device_match_fwnode(struct device *dev, const void *fwnode);
144int device_match_devt(struct device *dev, const void *pdevt);
145int device_match_acpi_dev(struct device *dev, const void *adev);
146int device_match_acpi_handle(struct device *dev, const void *handle);
147int device_match_any(struct device *dev, const void *unused);
148
149/* Device iterating function type for various driver core for_each APIs */
150typedef int (*device_iter_t)(struct device *dev, void *data);
151
152/* iterator helpers for buses */
153int bus_for_each_dev(const struct bus_type *bus, struct device *start,
154		     void *data, device_iter_t fn);
155struct device *bus_find_device(const struct bus_type *bus, struct device *start,
156			       const void *data, device_match_t match);
157struct device *bus_find_device_reverse(const struct bus_type *bus,
158				       struct device *start, const void *data,
159				       device_match_t match);
160/**
161 * bus_find_device_by_name - device iterator for locating a particular device
162 * of a specific name.
163 * @bus: bus type
164 * @start: Device to begin with
165 * @name: name of the device to match
166 */
167static inline struct device *bus_find_device_by_name(const struct bus_type *bus,
168						     struct device *start,
169						     const char *name)
170{
171	return bus_find_device(bus, start, name, device_match_name);
172}
173
174/**
175 * bus_find_device_by_of_node : device iterator for locating a particular device
176 * matching the of_node.
177 * @bus: bus type
178 * @np: of_node of the device to match.
179 */
180static inline struct device *
181bus_find_device_by_of_node(const struct bus_type *bus, const struct device_node *np)
182{
183	return bus_find_device(bus, NULL, np, device_match_of_node);
184}
185
186/**
187 * bus_find_device_by_fwnode : device iterator for locating a particular device
188 * matching the fwnode.
189 * @bus: bus type
190 * @fwnode: fwnode of the device to match.
191 */
192static inline struct device *
193bus_find_device_by_fwnode(const struct bus_type *bus, const struct fwnode_handle *fwnode)
194{
195	return bus_find_device(bus, NULL, fwnode, device_match_fwnode);
196}
197
198/**
199 * bus_find_device_by_devt : device iterator for locating a particular device
200 * matching the device type.
201 * @bus: bus type
202 * @devt: device type of the device to match.
203 */
204static inline struct device *bus_find_device_by_devt(const struct bus_type *bus,
205						     dev_t devt)
206{
207	return bus_find_device(bus, NULL, &devt, device_match_devt);
208}
209
210/**
211 * bus_find_next_device - Find the next device after a given device in a
212 * given bus.
213 * @bus: bus type
214 * @cur: device to begin the search with.
215 */
216static inline struct device *
217bus_find_next_device(const struct bus_type *bus,struct device *cur)
218{
219	return bus_find_device(bus, cur, NULL, device_match_any);
220}
221
222#ifdef CONFIG_ACPI
223struct acpi_device;
224
225/**
226 * bus_find_device_by_acpi_dev : device iterator for locating a particular device
227 * matching the ACPI COMPANION device.
228 * @bus: bus type
229 * @adev: ACPI COMPANION device to match.
230 */
231static inline struct device *
232bus_find_device_by_acpi_dev(const struct bus_type *bus, const struct acpi_device *adev)
233{
234	return bus_find_device(bus, NULL, adev, device_match_acpi_dev);
235}
236#else
237static inline struct device *
238bus_find_device_by_acpi_dev(const struct bus_type *bus, const void *adev)
239{
240	return NULL;
241}
242#endif
243
244int bus_for_each_drv(const struct bus_type *bus, struct device_driver *start,
245		     void *data, int (*fn)(struct device_driver *, void *));
246void bus_sort_breadthfirst(const struct bus_type *bus,
247			   int (*compare)(const struct device *a,
248					  const struct device *b));
249/*
250 * Bus notifiers: Get notified of addition/removal of devices
251 * and binding/unbinding of drivers to devices.
252 * In the long run, it should be a replacement for the platform
253 * notify hooks.
254 */
255struct notifier_block;
256
257int bus_register_notifier(const struct bus_type *bus, struct notifier_block *nb);
258int bus_unregister_notifier(const struct bus_type *bus, struct notifier_block *nb);
259
260/**
261 * enum bus_notifier_event - Bus Notifier events that have happened
262 * @BUS_NOTIFY_ADD_DEVICE: device is added to this bus
263 * @BUS_NOTIFY_DEL_DEVICE: device is about to be removed from this bus
264 * @BUS_NOTIFY_REMOVED_DEVICE: device is successfully removed from this bus
265 * @BUS_NOTIFY_BIND_DRIVER: a driver is about to be bound to this device on this bus
266 * @BUS_NOTIFY_BOUND_DRIVER: a driver is successfully bound to this device on this bus
267 * @BUS_NOTIFY_UNBIND_DRIVER: a driver is about to be unbound from this device on this bus
268 * @BUS_NOTIFY_UNBOUND_DRIVER: a driver is successfully unbound from this device on this bus
269 * @BUS_NOTIFY_DRIVER_NOT_BOUND: a driver failed to be bound to this device on this bus
270 *
271 * These are the value passed to a bus notifier when a specific event happens.
272 *
273 * Note that bus notifiers are likely to be called with the device lock already
274 * held by the driver core, so be careful in any notifier callback as to what
275 * you do with the device structure.
276 *
277 * All bus notifiers are called with the target struct device * as an argument.
278 */
279enum bus_notifier_event {
280	BUS_NOTIFY_ADD_DEVICE,
281	BUS_NOTIFY_DEL_DEVICE,
282	BUS_NOTIFY_REMOVED_DEVICE,
283	BUS_NOTIFY_BIND_DRIVER,
284	BUS_NOTIFY_BOUND_DRIVER,
285	BUS_NOTIFY_UNBIND_DRIVER,
286	BUS_NOTIFY_UNBOUND_DRIVER,
287	BUS_NOTIFY_DRIVER_NOT_BOUND,
288};
289
290struct kset *bus_get_kset(const struct bus_type *bus);
291struct device *bus_get_dev_root(const struct bus_type *bus);
292
293#endif