LXR linux/include/linux/component.h

   1/* SPDX-License-Identifier: GPL-2.0 */
   2#ifndef COMPONENT_H
   3#define COMPONENT_H
   4
   5#include <linux/stddef.h>
   6
   7
   8struct device;
   9
  10/**
  11 * struct component_ops - callbacks for component drivers
  12 *
  13 * Components are registered with component_add() and unregistered with
  14 * component_del().
  15 */
  16struct component_ops {
  17        /**
  18         * @bind:
  19         *
  20         * Called through component_bind_all() when the aggregate driver is
  21         * ready to bind the overall driver.
  22         */
  23        int (*bind)(struct device *comp, struct device *master,
  24                    void *master_data);
  25        /**
  26         * @unbind:
  27         *
  28         * Called through component_unbind_all() when the aggregate driver is
  29         * ready to bind the overall driver, or when component_bind_all() fails
  30         * part-ways through and needs to unbind some already bound components.
  31         */
  32        void (*unbind)(struct device *comp, struct device *master,
  33                       void *master_data);
  34};
  35
  36int component_add(struct device *, const struct component_ops *);
  37int component_add_typed(struct device *dev, const struct component_ops *ops,
  38        int subcomponent);
  39void component_del(struct device *, const struct component_ops *);
  40
  41int component_bind_all(struct device *master, void *master_data);
  42void component_unbind_all(struct device *master, void *master_data);
  43
  44struct master;
  45
  46/**
  47 * struct component_master_ops - callback for the aggregate driver
  48 *
  49 * Aggregate drivers are registered with component_master_add_with_match() and
  50 * unregistered with component_master_del().
  51 */
  52struct component_master_ops {
  53        /**
  54         * @bind:
  55         *
  56         * Called when all components or the aggregate driver, as specified in
  57         * the match list passed to component_master_add_with_match(), are
  58         * ready. Usually there are 3 steps to bind an aggregate driver:
  59         *
  60         * 1. Allocate a structure for the aggregate driver.
  61         *
  62         * 2. Bind all components to the aggregate driver by calling
  63         *    component_bind_all() with the aggregate driver structure as opaque
  64         *    pointer data.
  65         *
  66         * 3. Register the aggregate driver with the subsystem to publish its
  67         *    interfaces.
  68         *
  69         * Note that the lifetime of the aggregate driver does not align with
  70         * any of the underlying &struct device instances. Therefore devm cannot
  71         * be used and all resources acquired or allocated in this callback must
  72         * be explicitly released in the @unbind callback.
  73         */
  74        int (*bind)(struct device *master);
  75        /**
  76         * @unbind:
  77         *
  78         * Called when either the aggregate driver, using
  79         * component_master_del(), or one of its components, using
  80         * component_del(), is unregistered.
  81         */
  82        void (*unbind)(struct device *master);
  83};
  84
  85void component_master_del(struct device *,
  86        const struct component_master_ops *);
  87
  88struct component_match;
  89
  90int component_master_add_with_match(struct device *,
  91        const struct component_master_ops *, struct component_match *);
  92void component_match_add_release(struct device *master,
  93        struct component_match **matchptr,
  94        void (*release)(struct device *, void *),
  95        int (*compare)(struct device *, void *), void *compare_data);
  96void component_match_add_typed(struct device *master,
  97        struct component_match **matchptr,
  98        int (*compare_typed)(struct device *, int, void *), void *compare_data);
  99
 100/**
 101 * component_match_add - add a component match entry
 102 * @master: device with the aggregate driver
 103 * @matchptr: pointer to the list of component matches
 104 * @compare: compare function to match against all components
 105 * @compare_data: opaque pointer passed to the @compare function
 106 *
 107 * Adds a new component match to the list stored in @matchptr, which the @master
 108 * aggregate driver needs to function. The list of component matches pointed to
 109 * by @matchptr must be initialized to NULL before adding the first match. This
 110 * only matches against components added with component_add().
 111 *
 112 * The allocated match list in @matchptr is automatically released using devm
 113 * actions.
 114 *
 115 * See also component_match_add_release() and component_match_add_typed().
 116 */
 117static inline void component_match_add(struct device *master,
 118        struct component_match **matchptr,
 119        int (*compare)(struct device *, void *), void *compare_data)
 120{
 121        component_match_add_release(master, matchptr, NULL, compare,
 122                                    compare_data);
 123}
 124
 125#endif
 126