0001 =========
0002 Bus Types
0003 =========
0004
0005 Definition
0006 ~~~~~~~~~~
0007 See the kerneldoc for the struct bus_type.
0008
0009 int bus_register(struct bus_type * bus);
0010
0011
0012 Declaration
0013 ~~~~~~~~~~~
0014
0015 Each bus type in the kernel (PCI, USB, etc) should declare one static
0016 object of this type. They must initialize the name field, and may
0017 optionally initialize the match callback::
0018
0019 struct bus_type pci_bus_type = {
0020 .name = "pci",
0021 .match = pci_bus_match,
0022 };
0023
0024 The structure should be exported to drivers in a header file:
0025
0026 extern struct bus_type pci_bus_type;
0027
0028
0029 Registration
0030 ~~~~~~~~~~~~
0031
0032 When a bus driver is initialized, it calls bus_register. This
0033 initializes the rest of the fields in the bus object and inserts it
0034 into a global list of bus types. Once the bus object is registered,
0035 the fields in it are usable by the bus driver.
0036
0037
0038 Callbacks
0039 ~~~~~~~~~
0040
0041 match(): Attaching Drivers to Devices
0042 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0043
0044 The format of device ID structures and the semantics for comparing
0045 them are inherently bus-specific. Drivers typically declare an array
0046 of device IDs of devices they support that reside in a bus-specific
0047 driver structure.
0048
0049 The purpose of the match callback is to give the bus an opportunity to
0050 determine if a particular driver supports a particular device by
0051 comparing the device IDs the driver supports with the device ID of a
0052 particular device, without sacrificing bus-specific functionality or
0053 type-safety.
0054
0055 When a driver is registered with the bus, the bus's list of devices is
0056 iterated over, and the match callback is called for each device that
0057 does not have a driver associated with it.
0058
0059
0060
0061 Device and Driver Lists
0062 ~~~~~~~~~~~~~~~~~~~~~~~
0063
0064 The lists of devices and drivers are intended to replace the local
0065 lists that many buses keep. They are lists of struct devices and
0066 struct device_drivers, respectively. Bus drivers are free to use the
0067 lists as they please, but conversion to the bus-specific type may be
0068 necessary.
0069
0070 The LDM core provides helper functions for iterating over each list::
0071
0072 int bus_for_each_dev(struct bus_type * bus, struct device * start,
0073 void * data,
0074 int (*fn)(struct device *, void *));
0075
0076 int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
0077 void * data, int (*fn)(struct device_driver *, void *));
0078
0079 These helpers iterate over the respective list, and call the callback
0080 for each device or driver in the list. All list accesses are
0081 synchronized by taking the bus's lock (read currently). The reference
0082 count on each object in the list is incremented before the callback is
0083 called; it is decremented after the next object has been obtained. The
0084 lock is not held when calling the callback.
0085
0086
0087 sysfs
0088 ~~~~~~~~
0089 There is a top-level directory named 'bus'.
0090
0091 Each bus gets a directory in the bus directory, along with two default
0092 directories::
0093
0094 /sys/bus/pci/
0095 |-- devices
0096 `-- drivers
0097
0098 Drivers registered with the bus get a directory in the bus's drivers
0099 directory::
0100
0101 /sys/bus/pci/
0102 |-- devices
0103 `-- drivers
0104 |-- Intel ICH
0105 |-- Intel ICH Joystick
0106 |-- agpgart
0107 `-- e100
0108
0109 Each device that is discovered on a bus of that type gets a symlink in
0110 the bus's devices directory to the device's directory in the physical
0111 hierarchy::
0112
0113 /sys/bus/pci/
0114 |-- devices
0115 | |-- 00:00.0 -> ../../../root/pci0/00:00.0
0116 | |-- 00:01.0 -> ../../../root/pci0/00:01.0
0117 | `-- 00:02.0 -> ../../../root/pci0/00:02.0
0118 `-- drivers
0119
0120
0121 Exporting Attributes
0122 ~~~~~~~~~~~~~~~~~~~~
0123
0124 ::
0125
0126 struct bus_attribute {
0127 struct attribute attr;
0128 ssize_t (*show)(struct bus_type *, char * buf);
0129 ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
0130 };
0131
0132 Bus drivers can export attributes using the BUS_ATTR_RW macro that works
0133 similarly to the DEVICE_ATTR_RW macro for devices. For example, a
0134 definition like this::
0135
0136 static BUS_ATTR_RW(debug);
0137
0138 is equivalent to declaring::
0139
0140 static bus_attribute bus_attr_debug;
0141
0142 This can then be used to add and remove the attribute from the bus's
0143 sysfs directory using::
0144
0145 int bus_create_file(struct bus_type *, struct bus_attribute *);
0146 void bus_remove_file(struct bus_type *, struct bus_attribute *);
