From patchwork Wed Feb 6 16:45:49 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 10799609 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id AACCA6C2 for ; Wed, 6 Feb 2019 16:46:16 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 956232B9C1 for ; Wed, 6 Feb 2019 16:46:16 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 886562CBD6; Wed, 6 Feb 2019 16:46:16 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-5.2 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_MED autolearn=unavailable version=3.3.1 Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id C44952B9C1 for ; Wed, 6 Feb 2019 16:46:15 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 9D61D6E98F; Wed, 6 Feb 2019 16:46:11 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-ed1-x544.google.com (mail-ed1-x544.google.com [IPv6:2a00:1450:4864:20::544]) by gabe.freedesktop.org (Postfix) with ESMTPS id 791DB6EAB3 for ; Wed, 6 Feb 2019 16:46:09 +0000 (UTC) Received: by mail-ed1-x544.google.com with SMTP id t3so1611884edq.0 for ; Wed, 06 Feb 2019 08:46:09 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=KDH+kPSjGciywNth8V2WQqmymvSZPttcXvRSqBoXC0I=; b=chShmYlgWwk/+e9czS03jhySRZuLcvluFO/iqV8qvxiXUn1GyzP1UTk3JPMMQY982J f3oqMJ5o0Jptc8wHYbV4EL//m1XTvdSmMNDZNU9/ePO+8/f63bfrfWESwyqxx2In5XDK s1jH77qxDH02BdQQyw6rA60IfHd5upJTQNdyPuVaznDwNWFvYaBDnEG0uU8je1mwi5Gp giPEBdPXtqfqlALiMDIFIOF5bplf2rhRs97+QZ8InCJsA1BZSBjBsQSoIKUxpn9DLFKG MvLd/9eDrK8CZU6HmsP0t3lI0PbAzTvaTcTkdieOcqsBeDhzluT7Hbpg8aEa7/cus/iS cFhQ== X-Gm-Message-State: AHQUAuagDjsl6kbpsDOBNItdmO8wAQEET6pQPM6EaDcYQJhWNWXt7zhw Yvh4p9xhg20vqNpjwcvMsRyo1smc4y0= X-Google-Smtp-Source: AHgI3IZUuVzgoRkUiXSS4rAUpv4RqAFEx+uA/N+8UDuGwsF/7QbmaBrLMuZLL2ZoMxI8Xfk2RKAvRQ== X-Received: by 2002:a17:906:1f98:: with SMTP id t24mr7990916ejr.247.1549471567607; Wed, 06 Feb 2019 08:46:07 -0800 (PST) Received: from phenom.ffwll.local ([2a02:168:569e:0:3106:d637:d723:e855]) by smtp.gmail.com with ESMTPSA id b43sm1375372edf.54.2019.02.06.08.46.05 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 06 Feb 2019 08:46:06 -0800 (PST) From: Daniel Vetter To: DRI Development Subject: [PATCH 1/3] component: Add documentation Date: Wed, 6 Feb 2019 17:45:49 +0100 Message-Id: <20190206164551.29400-1-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.20.1 In-Reply-To: <1548917996-28081-2-git-send-email-ramalingam.c@intel.com> References: <1548917996-28081-2-git-send-email-ramalingam.c@intel.com> MIME-Version: 1.0 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Rafael J . Wysocki" , Daniel Vetter , Daniel Vetter , Intel Graphics Development , Rodrigo Vivi , Takashi Iwai , Jaroslav Kysela , Greg Kroah-Hartman , Russell King Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Virus-Scanned: ClamAV using ClamSMTP Someone owes me a beer ... 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. 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 Signed-off-by: Daniel Vetter --- Documentation/driver-api/component.rst | 17 ++++ Documentation/driver-api/device_link.rst | 3 + Documentation/driver-api/index.rst | 1 + drivers/base/component.c | 107 ++++++++++++++++++++++- include/linux/component.h | 71 +++++++++++++++ 5 files changed, 196 insertions(+), 3 deletions(-) create mode 100644 Documentation/driver-api/component.rst diff --git a/Documentation/driver-api/component.rst b/Documentation/driver-api/component.rst new file mode 100644 index 000000000000..2da4a8f20607 --- /dev/null +++ b/Documentation/driver-api/component.rst @@ -0,0 +1,17 @@ +====================================== +Component Helper for Aggregate Drivers +====================================== + +.. kernel-doc:: drivers/base/component.c + :doc: overview + + +API +=== + +.. kernel-doc:: include/linux/component.h + :internal: + +.. kernel-doc:: drivers/base/component.c + :export: + diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst index d6763272e747..2d5919b2b337 100644 --- a/Documentation/driver-api/device_link.rst +++ b/Documentation/driver-api/device_link.rst @@ -1,6 +1,9 @@ .. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain ` .. |struct generic_pm_domain| replace:: :c:type:`struct generic_pm_domain ` + +.. _device_link: + ============ Device links ============ diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index ab38ced66a44..c0b600ed9961 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -22,6 +22,7 @@ available subsections can be seen below. device_connection dma-buf device_link + component message-based sound frame-buffer diff --git a/drivers/base/component.c b/drivers/base/component.c index ddcea8739c12..f34d4b784709 100644 --- a/drivers/base/component.c +++ b/drivers/base/component.c @@ -16,6 +16,32 @@ #include #include +/** + * DOC: overview + * + * 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 component (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 :ref:`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(). + */ + struct component; struct component_match_array { @@ -301,10 +327,25 @@ static int component_match_realloc(struct device *dev, return 0; } -/* - * Add a component to be matched, with a release function. +/** + * 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 + * + * This 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(). * - * The match array is first created or extended if necessary. + * See also component_match_add(). */ void component_match_add_release(struct device *master, struct component_match **matchptr, @@ -367,6 +408,18 @@ static void free_master(struct master *master) kfree(master); } +/** + * component_master_add_with_match - register an aggregate driver + * @dev: device with the aggregate driver + * @ops: callbacks for the aggregate driver + * @match: component match list for the aggregate driver + * + * Registers a new aggregate driver consisting of the components added to @match + * by calling one of the component_match_add() functions. Once all components in + * @match are available, it will be assembled by calling + * &component_master_ops.bind from @ops. Must be unregistered by calling + * component_master_del(). + */ int component_master_add_with_match(struct device *dev, const struct component_master_ops *ops, struct component_match *match) @@ -403,6 +456,15 @@ int component_master_add_with_match(struct device *dev, } EXPORT_SYMBOL_GPL(component_master_add_with_match); +/** + * component_master_del - unregister an aggregate driver + * @dev: device with the aggregate driver + * @ops: callbacks for the aggregate driver + * + * Unregisters an aggregate driver registered with + * component_master_add_with_match(). If necessary the aggregate driver is first + * disassembled by calling &component_master_ops.unbind from @ops. + */ void component_master_del(struct device *dev, const struct component_master_ops *ops) { @@ -430,6 +492,15 @@ static void component_unbind(struct component *component, devres_release_group(component->dev, component); } +/** + * component_unbind_all - unbind all component to 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 + * &component_ops.unbind functions. Should be called from + * &component_master_ops.unbind. + */ void component_unbind_all(struct device *master_dev, void *data) { struct master *master; @@ -503,6 +574,15 @@ static int component_bind(struct component *component, struct master *master, return ret; } +/** + * component_bind_all - bind all component to 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 + * &component_ops.bind functions. Should be called from + * &component_master_ops.bind. + */ int component_bind_all(struct device *master_dev, void *data) { struct master *master; @@ -537,6 +617,18 @@ 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) { struct component *component; @@ -568,6 +660,15 @@ int component_add(struct device *dev, const struct component_ops *ops) } EXPORT_SYMBOL_GPL(component_add); +/** + * component_del - unregister a component + * @dev: component device + * @ops: component callbacks + * + * Unregister a component added with component_add(). If the component is bound + * into an aggregate driver, this will force the entire aggregate driver, including + * all its components, to be unbound. + */ void component_del(struct device *dev, const struct component_ops *ops) { struct component *c, *component = NULL; diff --git a/include/linux/component.h b/include/linux/component.h index e71fbbbc74e2..4911598b4c42 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,23 @@ 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 + * + * This 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)