bus.rst

  1=========
  2Bus Types
  3=========
  4
  5Definition
  6~~~~~~~~~~
  7See the kerneldoc for the struct bus_type.
  8
  9int bus_register(struct bus_type * bus);
 10
 11
 12Declaration
 13~~~~~~~~~~~
 14
 15Each bus type in the kernel (PCI, USB, etc) should declare one static
 16object of this type. They must initialize the name field, and may
 17optionally initialize the match callback::
 18
 19   struct bus_type pci_bus_type = {
 20          .name	= "pci",
 21          .match	= pci_bus_match,
 22   };
 23
 24The structure should be exported to drivers in a header file:
 25
 26extern struct bus_type pci_bus_type;
 27
 28
 29Registration
 30~~~~~~~~~~~~
 31
 32When a bus driver is initialized, it calls bus_register. This
 33initializes the rest of the fields in the bus object and inserts it
 34into a global list of bus types. Once the bus object is registered,
 35the fields in it are usable by the bus driver.
 36
 37
 38Callbacks
 39~~~~~~~~~
 40
 41match(): Attaching Drivers to Devices
 42~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 43
 44The format of device ID structures and the semantics for comparing
 45them are inherently bus-specific. Drivers typically declare an array
 46of device IDs of devices they support that reside in a bus-specific
 47driver structure.
 48
 49The purpose of the match callback is to give the bus an opportunity to
 50determine if a particular driver supports a particular device by
 51comparing the device IDs the driver supports with the device ID of a
 52particular device, without sacrificing bus-specific functionality or
 53type-safety.
 54
 55When a driver is registered with the bus, the bus's list of devices is
 56iterated over, and the match callback is called for each device that
 57does not have a driver associated with it.
 58
 59
 60
 61Device and Driver Lists
 62~~~~~~~~~~~~~~~~~~~~~~~
 63
 64The lists of devices and drivers are intended to replace the local
 65lists that many buses keep. They are lists of struct devices and
 66struct device_drivers, respectively. Bus drivers are free to use the
 67lists as they please, but conversion to the bus-specific type may be
 68necessary.
 69
 70The LDM core provides helper functions for iterating over each list::
 71
 72  int bus_for_each_dev(struct bus_type * bus, struct device * start,
 73		       void * data,
 74		       int (*fn)(struct device *, void *));
 75
 76  int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
 77		       void * data, int (*fn)(struct device_driver *, void *));
 78
 79These helpers iterate over the respective list, and call the callback
 80for each device or driver in the list. All list accesses are
 81synchronized by taking the bus's lock (read currently). The reference
 82count on each object in the list is incremented before the callback is
 83called; it is decremented after the next object has been obtained. The
 84lock is not held when calling the callback.
 85
 86
 87sysfs
 88~~~~~~~~
 89There is a top-level directory named 'bus'.
 90
 91Each bus gets a directory in the bus directory, along with two default
 92directories::
 93
 94	/sys/bus/pci/
 95	|-- devices
 96	`-- drivers
 97
 98Drivers registered with the bus get a directory in the bus's drivers
 99directory::
100
101	/sys/bus/pci/
102	|-- devices
103	`-- drivers
104	    |-- Intel ICH
105	    |-- Intel ICH Joystick
106	    |-- agpgart
107	    `-- e100
108
109Each device that is discovered on a bus of that type gets a symlink in
110the bus's devices directory to the device's directory in the physical
111hierarchy::
112
113	/sys/bus/pci/
114	|-- devices
115	|   |-- 00:00.0 -> ../../../root/pci0/00:00.0
116	|   |-- 00:01.0 -> ../../../root/pci0/00:01.0
117	|   `-- 00:02.0 -> ../../../root/pci0/00:02.0
118	`-- drivers
119
120
121Exporting Attributes
122~~~~~~~~~~~~~~~~~~~~
123
124::
125
126  struct bus_attribute {
127	struct attribute	attr;
128	ssize_t (*show)(const struct bus_type *, char * buf);
129	ssize_t (*store)(const struct bus_type *, const char * buf, size_t count);
130  };
131
132Bus drivers can export attributes using the BUS_ATTR_RW macro that works
133similarly to the DEVICE_ATTR_RW macro for devices. For example, a
134definition like this::
135
136	static BUS_ATTR_RW(debug);
137
138is equivalent to declaring::
139
140	static bus_attribute bus_attr_debug;
141
142This can then be used to add and remove the attribute from the bus's
143sysfs directory using::
144
145	int bus_create_file(struct bus_type *, struct bus_attribute *);
146	void bus_remove_file(struct bus_type *, struct bus_attribute *);