Component Helper for Aggregate Drivers — The Linux Kernel documentation
The Linux Kernel 7.4.0-rc3 Quick search Contents Working with the development community Development process Submitting patches Code of conduct Maintainer handbook All development-process docs Internal API manuals Core API Driver APIs General information for driver authors Useful support libraries Early Userspace Kernel Connector Bus-Independent Device Accesses Device Frequency Scaling Buffer Sharing and Synchronization (dma-buf) Component Helper for Aggregate Drivers The io_mapping functions Ordering I/O writes to memory-mapped addresses The Userspace I/O HOWTO VFIO Mediated devices VFIO - “Virtual Function I/O” Acceptance criteria for vfio-pci device specific driver variants VFIO Selftests Bus-level documentation Subsystem-specific APIs Subsystems Locking Development tools and processes Licensing rules Writing documentation Development tools Testing guide Hacking guide Tracing Fault injection Livepatching Rust User-oriented documentation Administration Build system Reporting issues Userspace tools Userspace API Firmware-related documentation Firmware Firmware and Devicetree Architecture-specific documentation CPU architectures Other documentation Unsorted documentation Translations Translations This Page Show Source Component Helper for Aggregate Drivers ¶ The component helper allows drivers to collect a pile of sub-devices, including their bound drivers, into an aggregate driver.
Various subsystems already provide functions to get hold of such components, e.g. of_clk_get_by_name() . The component helper can be used when such a subsystem-specific way to find a device is not available: The component helper fills the niche of aggregate drivers for specific hardware, where further standardization into a subsystem would not be practical. The common example is when a logical device (e.g. a DRM display driver) is spread around the SoC on various components (scanout engines, blending blocks, transcoders for various outputs and so on).
The component helper also doesn’t solve runtime dependencies, e.g. for system suspend and resume operations. See also device links . Components are registered using component_add() and unregistered with component_del() , usually from the driver’s probe and disconnect functions. Aggregate drivers first assemble a component match list of what they need using component_match_add() . This is then registered as an aggregate driver using component_master_add_with_match() , and unregistered using component_master_del() .
API ¶ struct component_ops ¶ callbacks for component drivers Definition : struct component_ops { int (*bind)(struct device *comp, struct device *master, void *master_data); void (*unbind)(struct device *comp, struct device *master, void *master_data); }; Members bind Called through component_bind_all() when the aggregate driver is ready to bind the overall driver. unbind Called through component_unbind_all() when the aggregate driver is ready to bind the overall driver, or when component_bind_all() fails part-ways through and needs to unbind some already bound components.
Description Components are registered with component_add() and unregistered with component_del() . struct component_master_ops ¶ callback for the aggregate driver Definition : struct component_master_ops { int (*bind)(struct device *master); void (*unbind)(struct device *master); }; Members bind Called when all components or the aggregate driver, as specified in the match list passed to component_master_add_with_match() , are ready.
Usually there are 3 steps to bind an aggregate driver: Allocate a structure for the aggregate driver. Bind all components to the aggregate driver by calling component_bind_all() with the aggregate driver structure as opaque pointer data. Register the aggregate driver with the subsystem to publish its interfaces. Note that the lifetime of the aggregate driver does not align with any of the underlying struct device instances.
Therefore devm cannot be used and all resources acquired or allocated in this callback must be explicitly released in the unbind callback. unbind Called when either the aggregate driver, using component_master_del() , or one of its components, using component_del() , is unregistered. Description Aggregate drivers are registered with component_master_add_with_match() and unregistered with component_master_del() . void component_match_add ( struct device * parent , struct component_match * * matchptr , int ( * compare ) ( struct device * , void * ) , void * compare_data ) ¶ add a component match entry Parameters struct device *parent device with the aggregate driver struct component_match **matchptr pointer to the list of component matches int (*compare)(struct device *, void *) compare function to match against all components void *compare_data opaque pointer passed to the compare function Description Adds a new component match to the list stored in matchptr , which the parent aggregate driver needs to function.
The list of component matches pointed to by matchptr must be initialized to NULL before adding the first match. This only matches against components added with component_add() . The allocated match list in matchptr is automatically released using devm actions. See also component_match_add_release() and component_match_add_typed() . int component_compare_of ( struct device * dev , void * data ) ¶ A common component compare function for of_node Parameters struct device *dev component device void *data compare_data from component_match_add_release() Description A common compare function when compare_data is device of_node. e.g. component_match_add_release(masterdev, match , component_release_of, component_compare_of, component_dev_of_node) void component_release_of ( struct device * dev , void * data ) ¶ A common component release function for of_node Parameters struct device *dev component device void *data compare_data from component_match_add_release() Description About the example, Please see component_compare_of() . int component_compare_dev ( struct device * dev , void * data ) ¶ A common component compare function for dev Parameters struct device *dev component device void *data compare_data from component_match_add_release() Description A common compare function when compare_data is struce device. e.g. component_match_add(masterdev, match , component_compare_dev, component_dev) int component_compare_dev_name ( struct device * dev , void * data ) ¶ A common component compare function for device name Parameters struct device *dev component device void *data compare_data from component_match_add_release() Description A common compare function when compare_data is device name string. e.g. component_match_add(masterdev, match , component_compare_dev_name, “component_dev_name”) void component_match_add_release ( struct device * parent , struct component_match * * matchptr , void ( * release ) ( struct device * , void * ) , int ( * compare ) ( struct device * , void * ) , void * compare_data ) ¶ add a component match entry with release callback Parameters struct device *parent parent device of the aggregate driver struct component_match **matchptr pointer to the list of component matches void (*release)(struct device *, void *) release function for compare_data int (*compare)(struct device *, void *) compare function to match against all components void *compare_data opaque pointer passed to the compare function Description Adds a new component match to the list stored in matchptr , which the aggregate driver needs to function.
The list of component matches pointed to by matchptr must be initialized to NULL before adding the first match. This only matches against components added with component_add() . The allocated match list in matchptr is automatically released using devm actions, where upon release will be called to free any references held by compare_data , e.g. when compare_data is a device_node that must be released with of_node_put() .
See also component_match_add
The rest of this page is on the live site.