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