1 // SPDX-License-Identifier: GPL-2.0
3 * Componentized device handling.
5 * This is work in progress. We gather up the component devices into a list,
6 * and bind them when instructed. At the moment, we're specific to the DRM
7 * subsystem, and only handles one master device, but this doesn't have to be
10 #include <linux/component.h>
11 #include <linux/device.h>
12 #include <linux/list.h>
13 #include <linux/mutex.h>
14 #include <linux/slab.h>
15 #include <linux/debugfs.h>
20 * The component helper allows drivers to collect a pile of sub-devices,
21 * including their bound drivers, into an aggregate driver. Various subsystems
22 * already provide functions to get hold of such components, e.g.
23 * of_clk_get_by_name(). The component helper can be used when such a
24 * subsystem-specific way to find a device is not available: The component
25 * helper fills the niche of aggregate drivers for specific hardware, where
26 * further standardization into a subsystem would not be practical. The common
27 * example is when a logical device (e.g. a DRM display driver) is spread around
28 * the SoC on various components (scanout engines, blending blocks, transcoders
29 * for various outputs and so on).
31 * The component helper also doesn't solve runtime dependencies, e.g. for system
32 * suspend and resume operations. See also :ref:`device links<device_link>`.
34 * Components are registered using component_add() and unregistered with
35 * component_del(), usually from the driver's probe and disconnect functions.
37 * Aggregate drivers first assemble a component match list of what they need
38 * using component_match_add(). This is then registered as an aggregate driver
39 * using component_master_add_with_match(), and unregistered using
40 * component_master_del().
45 struct component_match_array
{
47 int (*compare
)(struct device
*, void *);
48 int (*compare_typed
)(struct device
*, int, void *);
49 void (*release
)(struct device
*, void *);
50 struct component
*component
;
54 struct component_match
{
57 struct component_match_array
*compare
;
61 struct list_head node
;
64 const struct component_master_ops
*ops
;
65 struct device
*parent
;
66 struct component_match
*match
;
70 struct list_head node
;
71 struct master
*master
;
74 const struct component_ops
*ops
;
79 static DEFINE_MUTEX(component_mutex
);
80 static LIST_HEAD(component_list
);
81 static LIST_HEAD(masters
);
83 #ifdef CONFIG_DEBUG_FS
85 static struct dentry
*component_debugfs_dir
;
87 static int component_devices_show(struct seq_file
*s
, void *data
)
89 struct master
*m
= s
->private;
90 struct component_match
*match
= m
->match
;
93 mutex_lock(&component_mutex
);
94 seq_printf(s
, "%-40s %20s\n", "master name", "status");
95 seq_puts(s
, "-------------------------------------------------------------\n");
96 seq_printf(s
, "%-40s %20s\n\n",
97 dev_name(m
->parent
), m
->bound
? "bound" : "not bound");
99 seq_printf(s
, "%-40s %20s\n", "device name", "status");
100 seq_puts(s
, "-------------------------------------------------------------\n");
101 for (i
= 0; i
< match
->num
; i
++) {
102 struct component
*component
= match
->compare
[i
].component
;
104 seq_printf(s
, "%-40s %20s\n",
105 component
? dev_name(component
->dev
) : "(unknown)",
106 component
? (component
->bound
? "bound" : "not bound") : "not registered");
108 mutex_unlock(&component_mutex
);
113 DEFINE_SHOW_ATTRIBUTE(component_devices
);
115 static int __init
component_debug_init(void)
117 component_debugfs_dir
= debugfs_create_dir("device_component", NULL
);
122 core_initcall(component_debug_init
);
124 static void component_master_debugfs_add(struct master
*m
)
126 debugfs_create_file(dev_name(m
->parent
), 0444, component_debugfs_dir
, m
,
127 &component_devices_fops
);
130 static void component_master_debugfs_del(struct master
*m
)
132 debugfs_remove(debugfs_lookup(dev_name(m
->parent
), component_debugfs_dir
));
137 static void component_master_debugfs_add(struct master
*m
)
140 static void component_master_debugfs_del(struct master
*m
)
145 static struct master
*__master_find(struct device
*parent
,
146 const struct component_master_ops
*ops
)
150 list_for_each_entry(m
, &masters
, node
)
151 if (m
->parent
== parent
&& (!ops
|| m
->ops
== ops
))
157 static struct component
*find_component(struct master
*master
,
158 struct component_match_array
*mc
)
162 list_for_each_entry(c
, &component_list
, node
) {
163 if (c
->master
&& c
->master
!= master
)
166 if (mc
->compare
&& mc
->compare(c
->dev
, mc
->data
))
169 if (mc
->compare_typed
&&
170 mc
->compare_typed(c
->dev
, c
->subcomponent
, mc
->data
))
177 static int find_components(struct master
*master
)
179 struct component_match
*match
= master
->match
;
184 * Scan the array of match functions and attach
185 * any components which are found to this master.
187 for (i
= 0; i
< match
->num
; i
++) {
188 struct component_match_array
*mc
= &match
->compare
[i
];
191 dev_dbg(master
->parent
, "Looking for component %zu\n", i
);
193 if (match
->compare
[i
].component
)
196 c
= find_component(master
, mc
);
202 dev_dbg(master
->parent
, "found component %s, duplicate %u\n", dev_name(c
->dev
), !!c
->master
);
204 /* Attach this component to the master */
205 match
->compare
[i
].duplicate
= !!c
->master
;
206 match
->compare
[i
].component
= c
;
212 /* Detach component from associated master */
213 static void remove_component(struct master
*master
, struct component
*c
)
217 /* Detach the component from this master. */
218 for (i
= 0; i
< master
->match
->num
; i
++)
219 if (master
->match
->compare
[i
].component
== c
)
220 master
->match
->compare
[i
].component
= NULL
;
224 * Try to bring up a master. If component is NULL, we're interested in
225 * this master, otherwise it's a component which must be present to try
226 * and bring up the master.
228 * Returns 1 for successful bringup, 0 if not ready, or -ve errno.
230 static int try_to_bring_up_master(struct master
*master
,
231 struct component
*component
)
235 dev_dbg(master
->parent
, "trying to bring up master\n");
237 if (find_components(master
)) {
238 dev_dbg(master
->parent
, "master has incomplete components\n");
242 if (component
&& component
->master
!= master
) {
243 dev_dbg(master
->parent
, "master is not for this component (%s)\n",
244 dev_name(component
->dev
));
248 if (!devres_open_group(master
->parent
, NULL
, GFP_KERNEL
))
251 /* Found all components */
252 ret
= master
->ops
->bind(master
->parent
);
254 devres_release_group(master
->parent
, NULL
);
255 if (ret
!= -EPROBE_DEFER
)
256 dev_info(master
->parent
, "master bind failed: %d\n", ret
);
260 master
->bound
= true;
264 static int try_to_bring_up_masters(struct component
*component
)
269 list_for_each_entry(m
, &masters
, node
) {
271 ret
= try_to_bring_up_master(m
, component
);
280 static void take_down_master(struct master
*master
)
283 master
->ops
->unbind(master
->parent
);
284 devres_release_group(master
->parent
, NULL
);
285 master
->bound
= false;
289 static void devm_component_match_release(struct device
*parent
, void *res
)
291 struct component_match
*match
= res
;
294 for (i
= 0; i
< match
->num
; i
++) {
295 struct component_match_array
*mc
= &match
->compare
[i
];
298 mc
->release(parent
, mc
->data
);
301 kfree(match
->compare
);
304 static int component_match_realloc(struct component_match
*match
, size_t num
)
306 struct component_match_array
*new;
308 if (match
->alloc
== num
)
311 new = kmalloc_array(num
, sizeof(*new), GFP_KERNEL
);
315 if (match
->compare
) {
316 memcpy(new, match
->compare
, sizeof(*new) *
317 min(match
->num
, num
));
318 kfree(match
->compare
);
320 match
->compare
= new;
326 static void __component_match_add(struct device
*master
,
327 struct component_match
**matchptr
,
328 void (*release
)(struct device
*, void *),
329 int (*compare
)(struct device
*, void *),
330 int (*compare_typed
)(struct device
*, int, void *),
333 struct component_match
*match
= *matchptr
;
339 match
= devres_alloc(devm_component_match_release
,
340 sizeof(*match
), GFP_KERNEL
);
342 *matchptr
= ERR_PTR(-ENOMEM
);
346 devres_add(master
, match
);
351 if (match
->num
== match
->alloc
) {
352 size_t new_size
= match
->alloc
+ 16;
355 ret
= component_match_realloc(match
, new_size
);
357 *matchptr
= ERR_PTR(ret
);
362 match
->compare
[match
->num
].compare
= compare
;
363 match
->compare
[match
->num
].compare_typed
= compare_typed
;
364 match
->compare
[match
->num
].release
= release
;
365 match
->compare
[match
->num
].data
= compare_data
;
366 match
->compare
[match
->num
].component
= NULL
;
371 * component_match_add_release - add a component match entry with release callback
372 * @master: device with the aggregate driver
373 * @matchptr: pointer to the list of component matches
374 * @release: release function for @compare_data
375 * @compare: compare function to match against all components
376 * @compare_data: opaque pointer passed to the @compare function
378 * Adds a new component match to the list stored in @matchptr, which the @master
379 * aggregate driver needs to function. The list of component matches pointed to
380 * by @matchptr must be initialized to NULL before adding the first match. This
381 * only matches against components added with component_add().
383 * The allocated match list in @matchptr is automatically released using devm
384 * actions, where upon @release will be called to free any references held by
385 * @compare_data, e.g. when @compare_data is a &device_node that must be
386 * released with of_node_put().
388 * See also component_match_add() and component_match_add_typed().
390 void component_match_add_release(struct device
*master
,
391 struct component_match
**matchptr
,
392 void (*release
)(struct device
*, void *),
393 int (*compare
)(struct device
*, void *), void *compare_data
)
395 __component_match_add(master
, matchptr
, release
, compare
, NULL
,
398 EXPORT_SYMBOL(component_match_add_release
);
401 * component_match_add_typed - add a component match entry for a typed component
402 * @master: device with the aggregate driver
403 * @matchptr: pointer to the list of component matches
404 * @compare_typed: compare function to match against all typed components
405 * @compare_data: opaque pointer passed to the @compare function
407 * Adds a new component match to the list stored in @matchptr, which the @master
408 * aggregate driver needs to function. The list of component matches pointed to
409 * by @matchptr must be initialized to NULL before adding the first match. This
410 * only matches against components added with component_add_typed().
412 * The allocated match list in @matchptr is automatically released using devm
415 * See also component_match_add_release() and component_match_add_typed().
417 void component_match_add_typed(struct device
*master
,
418 struct component_match
**matchptr
,
419 int (*compare_typed
)(struct device
*, int, void *), void *compare_data
)
421 __component_match_add(master
, matchptr
, NULL
, NULL
, compare_typed
,
424 EXPORT_SYMBOL(component_match_add_typed
);
426 static void free_master(struct master
*master
)
428 struct component_match
*match
= master
->match
;
431 component_master_debugfs_del(master
);
432 list_del(&master
->node
);
435 for (i
= 0; i
< match
->num
; i
++) {
436 struct component
*c
= match
->compare
[i
].component
;
446 * component_master_add_with_match - register an aggregate driver
447 * @parent: parent device of the aggregate driver
448 * @ops: callbacks for the aggregate driver
449 * @match: component match list for the aggregate driver
451 * Registers a new aggregate driver consisting of the components added to @match
452 * by calling one of the component_match_add() functions. Once all components in
453 * @match are available, it will be assembled by calling
454 * &component_master_ops.bind from @ops. Must be unregistered by calling
455 * component_master_del().
457 int component_master_add_with_match(struct device
*parent
,
458 const struct component_master_ops
*ops
,
459 struct component_match
*match
)
461 struct master
*master
;
464 /* Reallocate the match array for its true size */
465 ret
= component_match_realloc(match
, match
->num
);
469 master
= kzalloc(sizeof(*master
), GFP_KERNEL
);
473 master
->parent
= parent
;
475 master
->match
= match
;
477 component_master_debugfs_add(master
);
478 /* Add to the list of available masters. */
479 mutex_lock(&component_mutex
);
480 list_add(&master
->node
, &masters
);
482 ret
= try_to_bring_up_master(master
, NULL
);
487 mutex_unlock(&component_mutex
);
489 return ret
< 0 ? ret
: 0;
491 EXPORT_SYMBOL_GPL(component_master_add_with_match
);
494 * component_master_del - unregister an aggregate driver
495 * @parent: parent device of the aggregate driver
496 * @ops: callbacks for the aggregate driver
498 * Unregisters an aggregate driver registered with
499 * component_master_add_with_match(). If necessary the aggregate driver is first
500 * disassembled by calling &component_master_ops.unbind from @ops.
502 void component_master_del(struct device
*parent
,
503 const struct component_master_ops
*ops
)
505 struct master
*master
;
507 mutex_lock(&component_mutex
);
508 master
= __master_find(parent
, ops
);
510 take_down_master(master
);
513 mutex_unlock(&component_mutex
);
515 EXPORT_SYMBOL_GPL(component_master_del
);
517 static void component_unbind(struct component
*component
,
518 struct master
*master
, void *data
)
520 WARN_ON(!component
->bound
);
522 if (component
->ops
&& component
->ops
->unbind
)
523 component
->ops
->unbind(component
->dev
, master
->parent
, data
);
524 component
->bound
= false;
526 /* Release all resources claimed in the binding of this component */
527 devres_release_group(component
->dev
, component
);
531 * component_unbind_all - unbind all components of an aggregate driver
532 * @parent: parent device of the aggregate driver
533 * @data: opaque pointer, passed to all components
535 * Unbinds all components of the aggregate device by passing @data to their
536 * &component_ops.unbind functions. Should be called from
537 * &component_master_ops.unbind.
539 void component_unbind_all(struct device
*parent
, void *data
)
541 struct master
*master
;
545 WARN_ON(!mutex_is_locked(&component_mutex
));
547 master
= __master_find(parent
, NULL
);
551 /* Unbind components in reverse order */
552 for (i
= master
->match
->num
; i
--; )
553 if (!master
->match
->compare
[i
].duplicate
) {
554 c
= master
->match
->compare
[i
].component
;
555 component_unbind(c
, master
, data
);
558 EXPORT_SYMBOL_GPL(component_unbind_all
);
560 static int component_bind(struct component
*component
, struct master
*master
,
566 * Each component initialises inside its own devres group.
567 * This allows us to roll-back a failed component without
568 * affecting anything else.
570 if (!devres_open_group(master
->parent
, NULL
, GFP_KERNEL
))
574 * Also open a group for the device itself: this allows us
575 * to release the resources claimed against the sub-device
576 * at the appropriate moment.
578 if (!devres_open_group(component
->dev
, component
, GFP_KERNEL
)) {
579 devres_release_group(master
->parent
, NULL
);
583 dev_dbg(master
->parent
, "binding %s (ops %ps)\n",
584 dev_name(component
->dev
), component
->ops
);
586 ret
= component
->ops
->bind(component
->dev
, master
->parent
, data
);
588 component
->bound
= true;
591 * Close the component device's group so that resources
592 * allocated in the binding are encapsulated for removal
593 * at unbind. Remove the group on the DRM device as we
594 * can clean those resources up independently.
596 devres_close_group(component
->dev
, NULL
);
597 devres_remove_group(master
->parent
, NULL
);
599 dev_info(master
->parent
, "bound %s (ops %ps)\n",
600 dev_name(component
->dev
), component
->ops
);
602 devres_release_group(component
->dev
, NULL
);
603 devres_release_group(master
->parent
, NULL
);
605 if (ret
!= -EPROBE_DEFER
)
606 dev_err(master
->parent
, "failed to bind %s (ops %ps): %d\n",
607 dev_name(component
->dev
), component
->ops
, ret
);
614 * component_bind_all - bind all components of an aggregate driver
615 * @parent: parent device of the aggregate driver
616 * @data: opaque pointer, passed to all components
618 * Binds all components of the aggregate @dev by passing @data to their
619 * &component_ops.bind functions. Should be called from
620 * &component_master_ops.bind.
622 int component_bind_all(struct device
*parent
, void *data
)
624 struct master
*master
;
629 WARN_ON(!mutex_is_locked(&component_mutex
));
631 master
= __master_find(parent
, NULL
);
635 /* Bind components in match order */
636 for (i
= 0; i
< master
->match
->num
; i
++)
637 if (!master
->match
->compare
[i
].duplicate
) {
638 c
= master
->match
->compare
[i
].component
;
639 ret
= component_bind(c
, master
, data
);
646 if (!master
->match
->compare
[i
- 1].duplicate
) {
647 c
= master
->match
->compare
[i
- 1].component
;
648 component_unbind(c
, master
, data
);
654 EXPORT_SYMBOL_GPL(component_bind_all
);
656 static int __component_add(struct device
*dev
, const struct component_ops
*ops
,
659 struct component
*component
;
662 component
= kzalloc(sizeof(*component
), GFP_KERNEL
);
666 component
->ops
= ops
;
667 component
->dev
= dev
;
668 component
->subcomponent
= subcomponent
;
670 dev_dbg(dev
, "adding component (ops %ps)\n", ops
);
672 mutex_lock(&component_mutex
);
673 list_add_tail(&component
->node
, &component_list
);
675 ret
= try_to_bring_up_masters(component
);
677 if (component
->master
)
678 remove_component(component
->master
, component
);
679 list_del(&component
->node
);
683 mutex_unlock(&component_mutex
);
685 return ret
< 0 ? ret
: 0;
689 * component_add_typed - register a component
690 * @dev: component device
691 * @ops: component callbacks
692 * @subcomponent: nonzero identifier for subcomponents
694 * Register a new component for @dev. Functions in @ops will be call when the
695 * aggregate driver is ready to bind the overall driver by calling
696 * component_bind_all(). See also &struct component_ops.
698 * @subcomponent must be nonzero and is used to differentiate between multiple
699 * components registerd on the same device @dev. These components are match
700 * using component_match_add_typed().
702 * The component needs to be unregistered at driver unload/disconnect by
703 * calling component_del().
705 * See also component_add().
707 int component_add_typed(struct device
*dev
, const struct component_ops
*ops
,
710 if (WARN_ON(subcomponent
== 0))
713 return __component_add(dev
, ops
, subcomponent
);
715 EXPORT_SYMBOL_GPL(component_add_typed
);
718 * component_add - register a component
719 * @dev: component device
720 * @ops: component callbacks
722 * Register a new component for @dev. Functions in @ops will be called when the
723 * aggregate driver is ready to bind the overall driver by calling
724 * component_bind_all(). See also &struct component_ops.
726 * The component needs to be unregistered at driver unload/disconnect by
727 * calling component_del().
729 * See also component_add_typed() for a variant that allows multipled different
730 * components on the same device.
732 int component_add(struct device
*dev
, const struct component_ops
*ops
)
734 return __component_add(dev
, ops
, 0);
736 EXPORT_SYMBOL_GPL(component_add
);
739 * component_del - unregister a component
740 * @dev: component device
741 * @ops: component callbacks
743 * Unregister a component added with component_add(). If the component is bound
744 * into an aggregate driver, this will force the entire aggregate driver, including
745 * all its components, to be unbound.
747 void component_del(struct device
*dev
, const struct component_ops
*ops
)
749 struct component
*c
, *component
= NULL
;
751 mutex_lock(&component_mutex
);
752 list_for_each_entry(c
, &component_list
, node
)
753 if (c
->dev
== dev
&& c
->ops
== ops
) {
759 if (component
&& component
->master
) {
760 take_down_master(component
->master
);
761 remove_component(component
->master
, component
);
764 mutex_unlock(&component_mutex
);
769 EXPORT_SYMBOL_GPL(component_del
);