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/kref.h>
13 #include <linux/list.h>
14 #include <linux/mutex.h>
15 #include <linux/slab.h>
16 #include <linux/debugfs.h>
21 * The component helper allows drivers to collect a pile of sub-devices,
22 * including their bound drivers, into an aggregate driver. Various subsystems
23 * already provide functions to get hold of such components, e.g.
24 * of_clk_get_by_name(). The component helper can be used when such a
25 * subsystem-specific way to find a device is not available: The component
26 * helper fills the niche of aggregate drivers for specific hardware, where
27 * further standardization into a subsystem would not be practical. The common
28 * example is when a logical device (e.g. a DRM display driver) is spread around
29 * the SoC on various components (scanout engines, blending blocks, transcoders
30 * for various outputs and so on).
32 * The component helper also doesn't solve runtime dependencies, e.g. for system
33 * suspend and resume operations. See also :ref:`device links<device_link>`.
35 * Components are registered using component_add() and unregistered with
36 * component_del(), usually from the driver's probe and disconnect functions.
38 * Aggregate drivers first assemble a component match list of what they need
39 * using component_match_add(). This is then registered as an aggregate driver
40 * using component_master_add_with_match(), and unregistered using
41 * component_master_del().
46 struct component_match_array
{
48 int (*compare
)(struct device
*, void *);
49 int (*compare_typed
)(struct device
*, int, void *);
50 void (*release
)(struct device
*, void *);
51 struct component
*component
;
55 struct component_match
{
58 struct component_match_array
*compare
;
62 struct list_head node
;
65 const struct component_master_ops
*ops
;
66 struct device
*parent
;
67 struct component_match
*match
;
71 struct list_head node
;
72 struct master
*master
;
75 const struct component_ops
*ops
;
80 static DEFINE_MUTEX(component_mutex
);
81 static LIST_HEAD(component_list
);
82 static LIST_HEAD(masters
);
84 #ifdef CONFIG_DEBUG_FS
86 static struct dentry
*component_debugfs_dir
;
88 static int component_devices_show(struct seq_file
*s
, void *data
)
90 struct master
*m
= s
->private;
91 struct component_match
*match
= m
->match
;
94 mutex_lock(&component_mutex
);
95 seq_printf(s
, "%-40s %20s\n", "master name", "status");
96 seq_puts(s
, "-------------------------------------------------------------\n");
97 seq_printf(s
, "%-40s %20s\n\n",
98 dev_name(m
->parent
), m
->bound
? "bound" : "not bound");
100 seq_printf(s
, "%-40s %20s\n", "device name", "status");
101 seq_puts(s
, "-------------------------------------------------------------\n");
102 for (i
= 0; i
< match
->num
; i
++) {
103 struct component
*component
= match
->compare
[i
].component
;
105 seq_printf(s
, "%-40s %20s\n",
106 component
? dev_name(component
->dev
) : "(unknown)",
107 component
? (component
->bound
? "bound" : "not bound") : "not registered");
109 mutex_unlock(&component_mutex
);
114 DEFINE_SHOW_ATTRIBUTE(component_devices
);
116 static int __init
component_debug_init(void)
118 component_debugfs_dir
= debugfs_create_dir("device_component", NULL
);
123 core_initcall(component_debug_init
);
125 static void component_master_debugfs_add(struct master
*m
)
127 debugfs_create_file(dev_name(m
->parent
), 0444, component_debugfs_dir
, m
,
128 &component_devices_fops
);
131 static void component_master_debugfs_del(struct master
*m
)
133 debugfs_remove(debugfs_lookup(dev_name(m
->parent
), component_debugfs_dir
));
138 static void component_master_debugfs_add(struct master
*m
)
141 static void component_master_debugfs_del(struct master
*m
)
146 static struct master
*__master_find(struct device
*parent
,
147 const struct component_master_ops
*ops
)
151 list_for_each_entry(m
, &masters
, node
)
152 if (m
->parent
== parent
&& (!ops
|| m
->ops
== ops
))
158 static struct component
*find_component(struct master
*master
,
159 struct component_match_array
*mc
)
163 list_for_each_entry(c
, &component_list
, node
) {
164 if (c
->master
&& c
->master
!= master
)
167 if (mc
->compare
&& mc
->compare(c
->dev
, mc
->data
))
170 if (mc
->compare_typed
&&
171 mc
->compare_typed(c
->dev
, c
->subcomponent
, mc
->data
))
178 static int find_components(struct master
*master
)
180 struct component_match
*match
= master
->match
;
185 * Scan the array of match functions and attach
186 * any components which are found to this master.
188 for (i
= 0; i
< match
->num
; i
++) {
189 struct component_match_array
*mc
= &match
->compare
[i
];
192 dev_dbg(master
->parent
, "Looking for component %zu\n", i
);
194 if (match
->compare
[i
].component
)
197 c
= find_component(master
, mc
);
203 dev_dbg(master
->parent
, "found component %s, duplicate %u\n", dev_name(c
->dev
), !!c
->master
);
205 /* Attach this component to the master */
206 match
->compare
[i
].duplicate
= !!c
->master
;
207 match
->compare
[i
].component
= c
;
213 /* Detach component from associated master */
214 static void remove_component(struct master
*master
, struct component
*c
)
218 /* Detach the component from this master. */
219 for (i
= 0; i
< master
->match
->num
; i
++)
220 if (master
->match
->compare
[i
].component
== c
)
221 master
->match
->compare
[i
].component
= NULL
;
225 * Try to bring up a master. If component is NULL, we're interested in
226 * this master, otherwise it's a component which must be present to try
227 * and bring up the master.
229 * Returns 1 for successful bringup, 0 if not ready, or -ve errno.
231 static int try_to_bring_up_master(struct master
*master
,
232 struct component
*component
)
236 dev_dbg(master
->parent
, "trying to bring up master\n");
238 if (find_components(master
)) {
239 dev_dbg(master
->parent
, "master has incomplete components\n");
243 if (component
&& component
->master
!= master
) {
244 dev_dbg(master
->parent
, "master is not for this component (%s)\n",
245 dev_name(component
->dev
));
249 if (!devres_open_group(master
->parent
, NULL
, GFP_KERNEL
))
252 /* Found all components */
253 ret
= master
->ops
->bind(master
->parent
);
255 devres_release_group(master
->parent
, NULL
);
256 if (ret
!= -EPROBE_DEFER
)
257 dev_info(master
->parent
, "master bind failed: %d\n", ret
);
261 master
->bound
= true;
265 static int try_to_bring_up_masters(struct component
*component
)
270 list_for_each_entry(m
, &masters
, node
) {
272 ret
= try_to_bring_up_master(m
, component
);
281 static void take_down_master(struct master
*master
)
284 master
->ops
->unbind(master
->parent
);
285 devres_release_group(master
->parent
, NULL
);
286 master
->bound
= false;
290 static void devm_component_match_release(struct device
*parent
, void *res
)
292 struct component_match
*match
= res
;
295 for (i
= 0; i
< match
->num
; i
++) {
296 struct component_match_array
*mc
= &match
->compare
[i
];
299 mc
->release(parent
, mc
->data
);
302 kfree(match
->compare
);
305 static int component_match_realloc(struct component_match
*match
, size_t num
)
307 struct component_match_array
*new;
309 if (match
->alloc
== num
)
312 new = kmalloc_array(num
, sizeof(*new), GFP_KERNEL
);
316 if (match
->compare
) {
317 memcpy(new, match
->compare
, sizeof(*new) *
318 min(match
->num
, num
));
319 kfree(match
->compare
);
321 match
->compare
= new;
327 static void __component_match_add(struct device
*master
,
328 struct component_match
**matchptr
,
329 void (*release
)(struct device
*, void *),
330 int (*compare
)(struct device
*, void *),
331 int (*compare_typed
)(struct device
*, int, void *),
334 struct component_match
*match
= *matchptr
;
340 match
= devres_alloc(devm_component_match_release
,
341 sizeof(*match
), GFP_KERNEL
);
343 *matchptr
= ERR_PTR(-ENOMEM
);
347 devres_add(master
, match
);
352 if (match
->num
== match
->alloc
) {
353 size_t new_size
= match
->alloc
+ 16;
356 ret
= component_match_realloc(match
, new_size
);
358 *matchptr
= ERR_PTR(ret
);
363 match
->compare
[match
->num
].compare
= compare
;
364 match
->compare
[match
->num
].compare_typed
= compare_typed
;
365 match
->compare
[match
->num
].release
= release
;
366 match
->compare
[match
->num
].data
= compare_data
;
367 match
->compare
[match
->num
].component
= NULL
;
372 * component_match_add_release - add a component match entry with release callback
373 * @master: device with the aggregate driver
374 * @matchptr: pointer to the list of component matches
375 * @release: release function for @compare_data
376 * @compare: compare function to match against all components
377 * @compare_data: opaque pointer passed to the @compare function
379 * Adds a new component match to the list stored in @matchptr, which the @master
380 * aggregate driver needs to function. The list of component matches pointed to
381 * by @matchptr must be initialized to NULL before adding the first match. This
382 * only matches against components added with component_add().
384 * The allocated match list in @matchptr is automatically released using devm
385 * actions, where upon @release will be called to free any references held by
386 * @compare_data, e.g. when @compare_data is a &device_node that must be
387 * released with of_node_put().
389 * See also component_match_add() and component_match_add_typed().
391 void component_match_add_release(struct device
*master
,
392 struct component_match
**matchptr
,
393 void (*release
)(struct device
*, void *),
394 int (*compare
)(struct device
*, void *), void *compare_data
)
396 __component_match_add(master
, matchptr
, release
, compare
, NULL
,
399 EXPORT_SYMBOL(component_match_add_release
);
402 * component_match_add_typed - add a component match entry for a typed component
403 * @master: device with the aggregate driver
404 * @matchptr: pointer to the list of component matches
405 * @compare_typed: compare function to match against all typed components
406 * @compare_data: opaque pointer passed to the @compare function
408 * Adds a new component match to the list stored in @matchptr, which the @master
409 * aggregate driver needs to function. The list of component matches pointed to
410 * by @matchptr must be initialized to NULL before adding the first match. This
411 * only matches against components added with component_add_typed().
413 * The allocated match list in @matchptr is automatically released using devm
416 * See also component_match_add_release() and component_match_add_typed().
418 void component_match_add_typed(struct device
*master
,
419 struct component_match
**matchptr
,
420 int (*compare_typed
)(struct device
*, int, void *), void *compare_data
)
422 __component_match_add(master
, matchptr
, NULL
, NULL
, compare_typed
,
425 EXPORT_SYMBOL(component_match_add_typed
);
427 static void free_master(struct master
*master
)
429 struct component_match
*match
= master
->match
;
432 component_master_debugfs_del(master
);
433 list_del(&master
->node
);
436 for (i
= 0; i
< match
->num
; i
++) {
437 struct component
*c
= match
->compare
[i
].component
;
447 * component_master_add_with_match - register an aggregate driver
448 * @parent: parent device of the aggregate driver
449 * @ops: callbacks for the aggregate driver
450 * @match: component match list for the aggregate driver
452 * Registers a new aggregate driver consisting of the components added to @match
453 * by calling one of the component_match_add() functions. Once all components in
454 * @match are available, it will be assembled by calling
455 * &component_master_ops.bind from @ops. Must be unregistered by calling
456 * component_master_del().
458 int component_master_add_with_match(struct device
*parent
,
459 const struct component_master_ops
*ops
,
460 struct component_match
*match
)
462 struct master
*master
;
465 /* Reallocate the match array for its true size */
466 ret
= component_match_realloc(match
, match
->num
);
470 master
= kzalloc(sizeof(*master
), GFP_KERNEL
);
474 master
->parent
= parent
;
476 master
->match
= match
;
478 component_master_debugfs_add(master
);
479 /* Add to the list of available masters. */
480 mutex_lock(&component_mutex
);
481 list_add(&master
->node
, &masters
);
483 ret
= try_to_bring_up_master(master
, NULL
);
488 mutex_unlock(&component_mutex
);
490 return ret
< 0 ? ret
: 0;
492 EXPORT_SYMBOL_GPL(component_master_add_with_match
);
495 * component_master_del - unregister an aggregate driver
496 * @parent: parent device of the aggregate driver
497 * @ops: callbacks for the aggregate driver
499 * Unregisters an aggregate driver registered with
500 * component_master_add_with_match(). If necessary the aggregate driver is first
501 * disassembled by calling &component_master_ops.unbind from @ops.
503 void component_master_del(struct device
*parent
,
504 const struct component_master_ops
*ops
)
506 struct master
*master
;
508 mutex_lock(&component_mutex
);
509 master
= __master_find(parent
, ops
);
511 take_down_master(master
);
514 mutex_unlock(&component_mutex
);
516 EXPORT_SYMBOL_GPL(component_master_del
);
518 static void component_unbind(struct component
*component
,
519 struct master
*master
, void *data
)
521 WARN_ON(!component
->bound
);
523 if (component
->ops
&& component
->ops
->unbind
)
524 component
->ops
->unbind(component
->dev
, master
->parent
, data
);
525 component
->bound
= false;
527 /* Release all resources claimed in the binding of this component */
528 devres_release_group(component
->dev
, component
);
532 * component_unbind_all - unbind all components of an aggregate driver
533 * @parent: parent device of the aggregate driver
534 * @data: opaque pointer, passed to all components
536 * Unbinds all components of the aggregate device by passing @data to their
537 * &component_ops.unbind functions. Should be called from
538 * &component_master_ops.unbind.
540 void component_unbind_all(struct device
*parent
, void *data
)
542 struct master
*master
;
546 WARN_ON(!mutex_is_locked(&component_mutex
));
548 master
= __master_find(parent
, NULL
);
552 /* Unbind components in reverse order */
553 for (i
= master
->match
->num
; i
--; )
554 if (!master
->match
->compare
[i
].duplicate
) {
555 c
= master
->match
->compare
[i
].component
;
556 component_unbind(c
, master
, data
);
559 EXPORT_SYMBOL_GPL(component_unbind_all
);
561 static int component_bind(struct component
*component
, struct master
*master
,
567 * Each component initialises inside its own devres group.
568 * This allows us to roll-back a failed component without
569 * affecting anything else.
571 if (!devres_open_group(master
->parent
, NULL
, GFP_KERNEL
))
575 * Also open a group for the device itself: this allows us
576 * to release the resources claimed against the sub-device
577 * at the appropriate moment.
579 if (!devres_open_group(component
->dev
, component
, GFP_KERNEL
)) {
580 devres_release_group(master
->parent
, NULL
);
584 dev_dbg(master
->parent
, "binding %s (ops %ps)\n",
585 dev_name(component
->dev
), component
->ops
);
587 ret
= component
->ops
->bind(component
->dev
, master
->parent
, data
);
589 component
->bound
= true;
592 * Close the component device's group so that resources
593 * allocated in the binding are encapsulated for removal
594 * at unbind. Remove the group on the DRM device as we
595 * can clean those resources up independently.
597 devres_close_group(component
->dev
, NULL
);
598 devres_remove_group(master
->parent
, NULL
);
600 dev_info(master
->parent
, "bound %s (ops %ps)\n",
601 dev_name(component
->dev
), component
->ops
);
603 devres_release_group(component
->dev
, NULL
);
604 devres_release_group(master
->parent
, NULL
);
606 if (ret
!= -EPROBE_DEFER
)
607 dev_err(master
->parent
, "failed to bind %s (ops %ps): %d\n",
608 dev_name(component
->dev
), component
->ops
, ret
);
615 * component_bind_all - bind all components of an aggregate driver
616 * @parent: parent device of the aggregate driver
617 * @data: opaque pointer, passed to all components
619 * Binds all components of the aggregate @dev by passing @data to their
620 * &component_ops.bind functions. Should be called from
621 * &component_master_ops.bind.
623 int component_bind_all(struct device
*parent
, void *data
)
625 struct master
*master
;
630 WARN_ON(!mutex_is_locked(&component_mutex
));
632 master
= __master_find(parent
, NULL
);
636 /* Bind components in match order */
637 for (i
= 0; i
< master
->match
->num
; i
++)
638 if (!master
->match
->compare
[i
].duplicate
) {
639 c
= master
->match
->compare
[i
].component
;
640 ret
= component_bind(c
, master
, data
);
647 if (!master
->match
->compare
[i
- 1].duplicate
) {
648 c
= master
->match
->compare
[i
- 1].component
;
649 component_unbind(c
, master
, data
);
655 EXPORT_SYMBOL_GPL(component_bind_all
);
657 static int __component_add(struct device
*dev
, const struct component_ops
*ops
,
660 struct component
*component
;
663 component
= kzalloc(sizeof(*component
), GFP_KERNEL
);
667 component
->ops
= ops
;
668 component
->dev
= dev
;
669 component
->subcomponent
= subcomponent
;
671 dev_dbg(dev
, "adding component (ops %ps)\n", ops
);
673 mutex_lock(&component_mutex
);
674 list_add_tail(&component
->node
, &component_list
);
676 ret
= try_to_bring_up_masters(component
);
678 if (component
->master
)
679 remove_component(component
->master
, component
);
680 list_del(&component
->node
);
684 mutex_unlock(&component_mutex
);
686 return ret
< 0 ? ret
: 0;
690 * component_add_typed - register a component
691 * @dev: component device
692 * @ops: component callbacks
693 * @subcomponent: nonzero identifier for subcomponents
695 * Register a new component for @dev. Functions in @ops will be call when the
696 * aggregate driver is ready to bind the overall driver by calling
697 * component_bind_all(). See also &struct component_ops.
699 * @subcomponent must be nonzero and is used to differentiate between multiple
700 * components registerd on the same device @dev. These components are match
701 * using component_match_add_typed().
703 * The component needs to be unregistered at driver unload/disconnect by
704 * calling component_del().
706 * See also component_add().
708 int component_add_typed(struct device
*dev
, const struct component_ops
*ops
,
711 if (WARN_ON(subcomponent
== 0))
714 return __component_add(dev
, ops
, subcomponent
);
716 EXPORT_SYMBOL_GPL(component_add_typed
);
719 * component_add - register a component
720 * @dev: component device
721 * @ops: component callbacks
723 * Register a new component for @dev. Functions in @ops will be called when the
724 * aggregate driver is ready to bind the overall driver by calling
725 * component_bind_all(). See also &struct component_ops.
727 * The component needs to be unregistered at driver unload/disconnect by
728 * calling component_del().
730 * See also component_add_typed() for a variant that allows multipled different
731 * components on the same device.
733 int component_add(struct device
*dev
, const struct component_ops
*ops
)
735 return __component_add(dev
, ops
, 0);
737 EXPORT_SYMBOL_GPL(component_add
);
740 * component_del - unregister a component
741 * @dev: component device
742 * @ops: component callbacks
744 * Unregister a component added with component_add(). If the component is bound
745 * into an aggregate driver, this will force the entire aggregate driver, including
746 * all its components, to be unbound.
748 void component_del(struct device
*dev
, const struct component_ops
*ops
)
750 struct component
*c
, *component
= NULL
;
752 mutex_lock(&component_mutex
);
753 list_for_each_entry(c
, &component_list
, node
)
754 if (c
->dev
== dev
&& c
->ops
== ops
) {
760 if (component
&& component
->master
) {
761 take_down_master(component
->master
);
762 remove_component(component
->master
, component
);
765 mutex_unlock(&component_mutex
);
770 EXPORT_SYMBOL_GPL(component_del
);