1 .. SPDX-License-Identifier: GPL-2.0-only
9 In some subsystems, the functionality of the core device (PCI/ACPI/other) is
10 too complex for a single device to be managed by a monolithic driver
11 (e.g. Sound Open Firmware), multiple devices might implement a common
12 intersection of functionality (e.g. NICs + RDMA), or a driver may want to
13 export an interface for another subsystem to drive (e.g. SIOV Physical Function
14 export Virtual Function management). A split of the functionality into child-
15 devices representing sub-domains of functionality makes it possible to
16 compartmentalize, layer, and distribute domain-specific concerns via a Linux
19 An example for this kind of requirement is the audio subsystem where a single
20 IP is handling multiple entities such as HDMI, Soundwire, local devices such as
21 mics/speakers etc. The split for the core's functionality can be arbitrary or
22 be defined by the DSP firmware topology and include hooks for test/debug. This
23 allows for the audio core device to be minimal and focused on hardware-specific
24 control and communication.
26 Each auxiliary_device represents a part of its parent functionality. The
27 generic behavior can be extended and specialized as needed by encapsulating an
28 auxiliary_device within other domain-specific structures and the use of .ops
29 callbacks. Devices on the auxiliary bus do not share any structures and the use
30 of a communication channel with the parent is domain-specific.
32 Note that ops are intended as a way to augment instance behavior within a class
33 of auxiliary devices, it is not the mechanism for exporting common
34 infrastructure from the parent. Consider EXPORT_SYMBOL_NS() to convey
35 infrastructure from the parent module to the auxiliary module(s).
38 When Should the Auxiliary Bus Be Used
39 =====================================
41 The auxiliary bus is to be used when a driver and one or more kernel modules,
42 who share a common header file with the driver, need a mechanism to connect and
43 provide access to a shared object allocated by the auxiliary_device's
44 registering driver. The registering driver for the auxiliary_device(s) and the
45 kernel module(s) registering auxiliary_drivers can be from the same subsystem,
46 or from multiple subsystems.
48 The emphasis here is on a common generic interface that keeps subsystem
49 customization out of the bus infrastructure.
51 One example is a PCI network device that is RDMA-capable and exports a child
52 device to be driven by an auxiliary_driver in the RDMA subsystem. The PCI
53 driver allocates and registers an auxiliary_device for each physical
54 function on the NIC. The RDMA driver registers an auxiliary_driver that claims
55 each of these auxiliary_devices. This conveys data/ops published by the parent
56 PCI device/driver to the RDMA auxiliary_driver.
58 Another use case is for the PCI device to be split out into multiple sub
59 functions. For each sub function an auxiliary_device is created. A PCI sub
60 function driver binds to such devices that creates its own one or more class
61 devices. A PCI sub function auxiliary device is likely to be contained in a
62 struct with additional attributes such as user defined sub function number and
63 optional attributes such as resources and a link to the parent device. These
64 attributes could be used by systemd/udev; and hence should be initialized
65 before a driver binds to an auxiliary_device.
67 A key requirement for utilizing the auxiliary bus is that there is no
68 dependency on a physical bus, device, register accesses or regmap support.
69 These individual devices split from the core cannot live on the platform bus as
70 they are not physical devices that are controlled by DT/ACPI. The same
71 argument applies for not using MFD in this scenario as MFD relies on individual
72 function devices being physical devices.
74 Auxiliary Device Creation
75 =========================
77 An auxiliary_device represents a part of its parent device's functionality. It
78 is given a name that, combined with the registering drivers KBUILD_MODNAME,
79 creates a match_name that is used for driver binding, and an id that combined
80 with the match_name provide a unique name to register with the bus subsystem.
84 struct auxiliary_device {
90 Registering an auxiliary_device is a three-step process.
92 First, a 'struct auxiliary_device' needs to be defined or allocated for each
93 sub-device desired. The name, id, dev.release, and dev.parent fields of this
94 structure must be filled in as follows.
96 The 'name' field is to be given a name that is recognized by the auxiliary
97 driver. If two auxiliary_devices with the same match_name, eg
98 "mod.MY_DEVICE_NAME", are registered onto the bus, they must have unique id
99 values (e.g. "x" and "y") so that the registered devices names are "mod.foo.x"
100 and "mod.foo.y". If match_name + id are not unique, then the device_add fails
101 and generates an error message.
103 The auxiliary_device.dev.type.release or auxiliary_device.dev.release must be
104 populated with a non-NULL pointer to successfully register the
105 auxiliary_device. This release call is where resources associated with the
106 auxiliary device must be free'ed. Because once the device is placed on the bus
107 the parent driver can not tell what other code may have a reference to this
110 The auxiliary_device.dev.parent should be set. Typically to the registering
113 Second, call auxiliary_device_init(), which checks several aspects of the
114 auxiliary_device struct and performs a device_initialize(). After this step
115 completes, any error state must have a call to auxiliary_device_uninit() in its
118 The third and final step in registering an auxiliary_device is to perform a
119 call to auxiliary_device_add(), which sets the name of the device and adds the
124 struct auxiliary_device *my_aux_dev = my_aux_dev_alloc(xxx);
127 my_aux_dev->name = MY_DEVICE_NAME;
128 my_aux_dev->id = my_unique_id_alloc(xxx);
129 my_aux_dev->dev.release = my_aux_dev_release;
130 my_aux_dev->dev.parent = my_dev;
133 if (auxiliary_device_init(my_aux_dev))
137 if (auxiliary_device_add(my_aux_dev)) {
138 auxiliary_device_uninit(my_aux_dev);
142 Unregistering an auxiliary_device is a two-step process to mirror the register
143 process. First call auxiliary_device_delete(), then call
144 auxiliary_device_uninit().
149 auxiliary_device_delete(my_dev->my_aux_dev);
150 auxiliary_device_uninit(my_dev->my_aux_dev);
153 Auxiliary Device Memory Model and Lifespan
154 ------------------------------------------
156 The registering driver is the entity that allocates memory for the
157 auxiliary_device and register it on the auxiliary bus. It is important to note
158 that, as opposed to the platform bus, the registering driver is wholly
159 responsible for the management for the memory used for the driver object.
161 A parent object, defined in the shared header file, contains the
162 auxiliary_device. It also contains a pointer to the shared object(s), which
163 also is defined in the shared header. Both the parent object and the shared
164 object(s) are allocated by the registering driver. This layout allows the
165 auxiliary_driver's registering module to perform a container_of() call to go
166 from the pointer to the auxiliary_device, that is passed during the call to the
167 auxiliary_driver's probe function, up to the parent object, and then have
168 access to the shared object(s).
170 The memory for the auxiliary_device is freed only in its release() callback
171 flow as defined by its registering driver.
173 The memory for the shared object(s) must have a lifespan equal to, or greater
174 than, the lifespan of the memory for the auxiliary_device. The auxiliary_driver
175 should only consider that this shared object is valid as long as the
176 auxiliary_device is still registered on the auxiliary bus. It is up to the
177 registering driver to manage (e.g. free or keep available) the memory for the
178 shared object beyond the life of the auxiliary_device.
180 The registering driver must unregister all auxiliary devices before its own
181 driver.remove() is completed.
186 Auxiliary drivers follow the standard driver model convention, where
187 discovery/enumeration is handled by the core, and drivers
188 provide probe() and remove() methods. They support power management
189 and shutdown notifications using the standard conventions.
193 struct auxiliary_driver {
194 int (*probe)(struct auxiliary_device *,
195 const struct auxiliary_device_id *id);
196 void (*remove)(struct auxiliary_device *);
197 void (*shutdown)(struct auxiliary_device *);
198 int (*suspend)(struct auxiliary_device *, pm_message_t);
199 int (*resume)(struct auxiliary_device *);
200 struct device_driver driver;
201 const struct auxiliary_device_id *id_table;
204 Auxiliary drivers register themselves with the bus by calling
205 auxiliary_driver_register(). The id_table contains the match_names of auxiliary
206 devices that a driver can bind with.
211 Auxiliary devices are created and registered by a subsystem-level core device
212 that needs to break up its functionality into smaller fragments. One way to
213 extend the scope of an auxiliary_device is to encapsulate it within a domain-
214 pecific structure defined by the parent device. This structure contains the
215 auxiliary_device and any associated shared data/callbacks needed to establish
216 the connection with the parent.
223 struct auxiliary_device auxdev;
224 void (*connect)(struct auxiliary_device *auxdev);
225 void (*disconnect)(struct auxiliary_device *auxdev);
229 The parent device then registers the auxiliary_device by calling
230 auxiliary_device_init(), and then auxiliary_device_add(), with the pointer to
231 the auxdev member of the above structure. The parent provides a name for the
232 auxiliary_device that, combined with the parent's KBUILD_MODNAME, creates a
233 match_name that is be used for matching and binding with a driver.
235 Whenever an auxiliary_driver is registered, based on the match_name, the
236 auxiliary_driver's probe() is invoked for the matching devices. The
237 auxiliary_driver can also be encapsulated inside custom drivers that make the
238 core device's functionality extensible by adding additional domain-specific ops
244 void (*send)(struct auxiliary_device *auxdev);
245 void (*receive)(struct auxiliary_device *auxdev);
250 struct auxiliary_driver auxiliary_drv;
251 const struct my_ops ops;
254 An example of this type of usage is:
258 const struct auxiliary_device_id my_auxiliary_id_table[] = {
259 { .name = "foo_mod.foo_dev" },
263 const struct my_ops my_custom_ops = {
268 const struct my_driver my_drv = {
270 .name = "myauxiliarydrv",
271 .id_table = my_auxiliary_id_table,
274 .shutdown = my_shutdown,
276 .ops = my_custom_ops,