From 4d69c80e0d0fd8cf12d985841eb0fce5c29819ad Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 8 Feb 2019 00:27:56 +0100 Subject: component: Add documentation While typing these I think doing an s/component_master/aggregate/ would be useful: - it's shorter :-) - I think component/aggregate is much more meaningful naming than component/puppetmaster or something like that. At least to my English ear "aggregate" emphasizes much more the "assemble a pile of things into something bigger" aspect, and there's not really much of a control hierarchy between aggregate and constituing components. But that's way more than a quick doc typing exercise ... Thanks to Ram for commenting on an initial draft of these docs. v2: Review from Rafael: - git add Documenation/driver-api/component.rst - lots of polish to the wording + spelling fixes. v3: Review from Russell: - s/framework/helper - clarify the documentation for component_match_add functions. v4: Remove a few superflous "This". Reviewed-by: Rafael J. Wysocki Cc: "C, Ramalingam" Cc: Greg Kroah-Hartman Cc: Russell King Cc: Rafael J. Wysocki Cc: Jaroslav Kysela Cc: Takashi Iwai Cc: Rodrigo Vivi Cc: Jani Nikula Reviewed-by: Greg Kroah-Hartman Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20190207232759.14553-1-daniel.vetter@ffwll.ch --- include/linux/component.h | 70 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) (limited to 'include/linux/component.h') diff --git a/include/linux/component.h b/include/linux/component.h index e71fbbbc74e2..83da25bdf59c 100644 --- a/include/linux/component.h +++ b/include/linux/component.h @@ -4,11 +4,31 @@ #include + struct device; +/** + * struct component_ops - callbacks for component drivers + * + * Components are registered with component_add() and unregistered with + * component_del(). + */ struct component_ops { + /** + * @bind: + * + * Called through component_bind_all() when the aggregate driver is + * ready to bind the overall driver. + */ int (*bind)(struct device *comp, struct device *master, void *master_data); + /** + * @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. + */ void (*unbind)(struct device *comp, struct device *master, void *master_data); }; @@ -21,8 +41,42 @@ void component_unbind_all(struct device *master, void *master_data); struct master; +/** + * struct component_master_ops - callback for the aggregate driver + * + * Aggregate drivers are registered with component_master_add_with_match() and + * unregistered with component_master_del(). + */ struct component_master_ops { + /** + * @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: + * + * 1. Allocate a structure for the aggregate driver. + * + * 2. Bind all components to the aggregate driver by calling + * component_bind_all() with the aggregate driver structure as opaque + * pointer data. + * + * 3. 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. + */ int (*bind)(struct device *master); + /** + * @unbind: + * + * Called when either the aggregate driver, using + * component_master_del(), or one of its components, using + * component_del(), is unregistered. + */ void (*unbind)(struct device *master); }; @@ -38,6 +92,22 @@ void component_match_add_release(struct device *master, void (*release)(struct device *, void *), int (*compare)(struct device *, void *), void *compare_data); +/** + * component_match_add - add a compent match + * @master: device with the aggregate driver + * @matchptr: pointer to the list of component matches + * @compare: compare function to match against all components + * @compare_data: opaque pointer passed to the @compare function + * + * Adds a new component match to the list stored in @matchptr, which the @master + * aggregate driver needs to function. The list of component matches pointed to + * by @matchptr must be initialized to NULL before adding the first match. + * + * The allocated match list in @matchptr is automatically released using devm + * actions. + * + * See also component_match_add_release(). + */ static inline void component_match_add(struct device *master, struct component_match **matchptr, int (*compare)(struct device *, void *), void *compare_data) -- cgit v1.2.3-59-g8ed1b From 3521ee994bca90c57b539e106ff7e12a839aa8ea Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Fri, 8 Feb 2019 00:27:57 +0100 Subject: components: multiple components for a device Component framework is extended to support multiple components for a struct device. These will be matched with different masters based on its sub component value. We are introducing this, as I915 needs two different components with different subcomponent value, which will be matched to two different component masters(Audio and HDCP) based on the subcomponent values. v2: Add documenation. v3: Rebase on top of updated documenation. v4: Review from Rafael: - Remove redundant "This" from kerneldoc (also in the previous patch) - Streamline the logic in find_component() a bit. Signed-off-by: Daniel Vetter (v1 code) Signed-off-by: Ramalingam C (v1 commit message) Cc: Ramalingam C Cc: Greg Kroah-Hartman Cc: Russell King Cc: Rafael J. Wysocki Cc: Jaroslav Kysela Cc: Takashi Iwai Cc: Rodrigo Vivi Cc: Jani Nikula Reviewed-by: Greg Kroah-Hartman Reviewed-by: Rafael J. Wysocki Signed-off-by: Daniel Vetter Link: https://patchwork.freedesktop.org/patch/msgid/20190207232759.14553-2-daniel.vetter@ffwll.ch --- drivers/base/component.c | 158 +++++++++++++++++++++++++++++++++++----------- include/linux/component.h | 10 ++- 2 files changed, 129 insertions(+), 39 deletions(-) (limited to 'include/linux/component.h') diff --git a/drivers/base/component.c b/drivers/base/component.c index 1624c2a892a5..7dbc41cccd58 100644 --- a/drivers/base/component.c +++ b/drivers/base/component.c @@ -47,6 +47,7 @@ struct component; struct component_match_array { void *data; int (*compare)(struct device *, void *); + int (*compare_typed)(struct device *, int, void *); void (*release)(struct device *, void *); struct component *component; bool duplicate; @@ -74,6 +75,7 @@ struct component { bool bound; const struct component_ops *ops; + int subcomponent; struct device *dev; }; @@ -158,7 +160,7 @@ static struct master *__master_find(struct device *dev, } static struct component *find_component(struct master *master, - int (*compare)(struct device *, void *), void *compare_data) + struct component_match_array *mc) { struct component *c; @@ -166,7 +168,11 @@ static struct component *find_component(struct master *master, if (c->master && c->master != master) continue; - if (compare(c->dev, compare_data)) + if (mc->compare && mc->compare(c->dev, mc->data)) + return c; + + if (mc->compare_typed && + mc->compare_typed(c->dev, c->subcomponent, mc->data)) return c; } @@ -192,7 +198,7 @@ static int find_components(struct master *master) if (match->compare[i].component) continue; - c = find_component(master, mc->compare, mc->data); + c = find_component(master, mc); if (!c) { ret = -ENXIO; break; @@ -327,29 +333,12 @@ static int component_match_realloc(struct device *dev, return 0; } -/** - * component_match_add_release - add a component match with release callback - * @master: device with the aggregate driver - * @matchptr: pointer to the list of component matches - * @release: release function for @compare_data - * @compare: compare function to match against all components - * @compare_data: opaque pointer passed to the @compare function - * - * Adds a new component match to the list stored in @matchptr, which the @master - * aggregate driver needs to function. The list of component matches pointed to - * by @matchptr must be initialized to NULL before adding the first match. - * - * 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(). - */ -void component_match_add_release(struct device *master, +static void __component_match_add(struct device *master, struct component_match **matchptr, void (*release)(struct device *, void *), - int (*compare)(struct device *, void *), void *compare_data) + int (*compare)(struct device *, void *), + int (*compare_typed)(struct device *, int, void *), + void *compare_data) { struct component_match *match = *matchptr; @@ -381,13 +370,69 @@ void component_match_add_release(struct device *master, } match->compare[match->num].compare = compare; + match->compare[match->num].compare_typed = compare_typed; match->compare[match->num].release = release; match->compare[match->num].data = compare_data; match->compare[match->num].component = NULL; match->num++; } + +/** + * component_match_add_release - add a component match with release callback + * @master: device with the aggregate driver + * @matchptr: pointer to the list of component matches + * @release: release function for @compare_data + * @compare: compare function to match against all components + * @compare_data: opaque pointer passed to the @compare function + * + * Adds a new component match to the list stored in @matchptr, which the @master + * 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() and component_match_add_typed(). + */ +void component_match_add_release(struct device *master, + struct component_match **matchptr, + void (*release)(struct device *, void *), + int (*compare)(struct device *, void *), void *compare_data) +{ + __component_match_add(master, matchptr, release, compare, NULL, + compare_data); +} EXPORT_SYMBOL(component_match_add_release); +/** + * component_match_add_typed - add a compent match for a typed component + * @master: device with the aggregate driver + * @matchptr: pointer to the list of component matches + * @compare_typed: compare function to match against all typed components + * @compare_data: opaque pointer passed to the @compare function + * + * Adds a new component match to the list stored in @matchptr, which the @master + * 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_typed(). + * + * The allocated match list in @matchptr is automatically released using devm + * actions. + * + * See also component_match_add_release() and component_match_add_typed(). + */ +void component_match_add_typed(struct device *master, + struct component_match **matchptr, + int (*compare_typed)(struct device *, int, void *), void *compare_data) +{ + __component_match_add(master, matchptr, NULL, NULL, compare_typed, + compare_data); +} +EXPORT_SYMBOL(component_match_add_typed); + static void free_master(struct master *master) { struct component_match *match = master->match; @@ -616,19 +661,8 @@ int component_bind_all(struct device *master_dev, void *data) } EXPORT_SYMBOL_GPL(component_bind_all); -/** - * component_add - register a component - * @dev: component device - * @ops: component callbacks - * - * Register a new component for @dev. Functions in @ops will be called when the - * aggregate driver is ready to bind the overall driver by calling - * component_bind_all(). See also &struct component_ops. - * - * The component needs to be unregistered at driver unload/disconnect by calling - * component_del(). - */ -int component_add(struct device *dev, const struct component_ops *ops) +static int __component_add(struct device *dev, const struct component_ops *ops, + int subcomponent) { struct component *component; int ret; @@ -639,6 +673,7 @@ int component_add(struct device *dev, const struct component_ops *ops) component->ops = ops; component->dev = dev; + component->subcomponent = subcomponent; dev_dbg(dev, "adding component (ops %ps)\n", ops); @@ -657,6 +692,55 @@ int component_add(struct device *dev, const struct component_ops *ops) return ret < 0 ? ret : 0; } + +/** + * component_add_typed - register a component + * @dev: component device + * @ops: component callbacks + * @subcomponent: nonzero identifier for subcomponents + * + * Register a new component for @dev. Functions in @ops will be call when the + * aggregate driver is ready to bind the overall driver by calling + * component_bind_all(). See also &struct component_ops. + * + * @subcomponent must be nonzero and is used to differentiate between multiple + * components registerd on the same device @dev. These components are match + * using component_match_add_typed(). + * + * The component needs to be unregistered at driver unload/disconnect by + * calling component_del(). + * + * See also component_add(). + */ +int component_add_typed(struct device *dev, const struct component_ops *ops, + int subcomponent) +{ + if (WARN_ON(subcomponent == 0)) + return -EINVAL; + + return __component_add(dev, ops, subcomponent); +} +EXPORT_SYMBOL_GPL(component_add_typed); + +/** + * component_add - register a component + * @dev: component device + * @ops: component callbacks + * + * Register a new component for @dev. Functions in @ops will be called when the + * aggregate driver is ready to bind the overall driver by calling + * component_bind_all(). See also &struct component_ops. + * + * The component needs to be unregistered at driver unload/disconnect by + * calling component_del(). + * + * See also component_add_typed() for a variant that allows multipled different + * components on the same device. + */ +int component_add(struct device *dev, const struct component_ops *ops) +{ + return __component_add(dev, ops, 0); +} EXPORT_SYMBOL_GPL(component_add); /** diff --git a/include/linux/component.h b/include/linux/component.h index 83da25bdf59c..30bcc7e590eb 100644 --- a/include/linux/component.h +++ b/include/linux/component.h @@ -34,6 +34,8 @@ struct component_ops { }; int component_add(struct device *, const struct component_ops *); +int component_add_typed(struct device *dev, const struct component_ops *ops, + int subcomponent); void component_del(struct device *, const struct component_ops *); int component_bind_all(struct device *master, void *master_data); @@ -91,6 +93,9 @@ void component_match_add_release(struct device *master, struct component_match **matchptr, void (*release)(struct device *, void *), int (*compare)(struct device *, void *), void *compare_data); +void component_match_add_typed(struct device *master, + struct component_match **matchptr, + int (*compare_typed)(struct device *, int, void *), void *compare_data); /** * component_match_add - add a compent match @@ -101,12 +106,13 @@ void component_match_add_release(struct device *master, * * Adds a new component match to the list stored in @matchptr, which the @master * aggregate driver needs to function. The list of component matches pointed to - * by @matchptr must be initialized to NULL before adding the first match. + * 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(). + * See also component_match_add_release() and component_match_add_typed(). */ static inline void component_match_add(struct device *master, struct component_match **matchptr, -- cgit v1.2.3-59-g8ed1b From e4246b05507fc6102008bac0aee848f207bd96de Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Mon, 18 Feb 2019 17:36:48 +0100 Subject: drivers/component: kerneldoc polish Polish the kerneldoc a bit with suggestions from Randy. v2: Randy found another typo: s/compent/component/ Signed-off-by: Daniel Vetter Cc: "Rafael J. Wysocki" Cc: Daniel Vetter Cc: Ramalingam C Acked-by: Randy Dunlap Signed-off-by: Greg Kroah-Hartman --- drivers/base/component.c | 14 +++++++------- include/linux/component.h | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) (limited to 'include/linux/component.h') diff --git a/drivers/base/component.c b/drivers/base/component.c index 7dbc41cccd58..532a3a5d8f63 100644 --- a/drivers/base/component.c +++ b/drivers/base/component.c @@ -27,7 +27,7 @@ * 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 component (scanout engines, blending blocks, transcoders + * 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 @@ -378,7 +378,7 @@ static void __component_match_add(struct device *master, } /** - * component_match_add_release - add a component match with release callback + * component_match_add_release - add a component match entry with release callback * @master: device with the aggregate driver * @matchptr: pointer to the list of component matches * @release: release function for @compare_data @@ -408,7 +408,7 @@ void component_match_add_release(struct device *master, EXPORT_SYMBOL(component_match_add_release); /** - * component_match_add_typed - add a compent match for a typed component + * component_match_add_typed - add a component match entry for a typed component * @master: device with the aggregate driver * @matchptr: pointer to the list of component matches * @compare_typed: compare function to match against all typed components @@ -537,11 +537,11 @@ static void component_unbind(struct component *component, } /** - * component_unbind_all - unbind all component to an aggregate driver + * component_unbind_all - unbind all components of an aggregate driver * @master_dev: device with the aggregate driver * @data: opaque pointer, passed to all components * - * Unbinds all components to the aggregate @dev by passing @data to their + * Unbinds all components of the aggregate @dev by passing @data to their * &component_ops.unbind functions. Should be called from * &component_master_ops.unbind. */ @@ -619,11 +619,11 @@ static int component_bind(struct component *component, struct master *master, } /** - * component_bind_all - bind all component to an aggregate driver + * component_bind_all - bind all components of an aggregate driver * @master_dev: device with the aggregate driver * @data: opaque pointer, passed to all components * - * Binds all components to the aggregate @dev by passing @data to their + * Binds all components of the aggregate @dev by passing @data to their * &component_ops.bind functions. Should be called from * &component_master_ops.bind. */ diff --git a/include/linux/component.h b/include/linux/component.h index 30bcc7e590eb..16de18f473d7 100644 --- a/include/linux/component.h +++ b/include/linux/component.h @@ -98,7 +98,7 @@ void component_match_add_typed(struct device *master, int (*compare_typed)(struct device *, int, void *), void *compare_data); /** - * component_match_add - add a compent match + * component_match_add - add a component match entry * @master: device with the aggregate driver * @matchptr: pointer to the list of component matches * @compare: compare function to match against all components -- cgit v1.2.3-59-g8ed1b