| From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 |
| From: Saravana Kannan <saravanak@google.com> |
| Date: Fri, 11 Oct 2019 12:15:20 -0700 |
| Subject: FROMGIT: driver: core: Improve documentation for |
| fwnode_operations.add_links() |
| |
| The add_links() ops shouldn't return on the first failed device link |
| add. It needs to continue trying to add device links to other suppliers |
| that are available. The documentation didn't explain WHY this behavior |
| is necessary. So, update the documentation with an example that explains |
| why this is necessary. |
| |
| Signed-off-by: Saravana Kannan <saravanak@google.com> |
| Link: https://lore.kernel.org/r/20191011191521.179614-3-saravanak@google.com |
| Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> |
| (cherry-pick from commit 92df01e3601fe29eb3727a82705eafa6209053f5 |
| https://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core.git driver-core-next) |
| Bug: 142657042 |
| Change-Id: I58621ad08084fee1ab9725026e54abe7eb79b741 |
| --- |
| include/linux/fwnode.h | 21 +++++++++++++++++++-- |
| 1 file changed, 19 insertions(+), 2 deletions(-) |
| |
| diff --git a/include/linux/fwnode.h b/include/linux/fwnode.h |
| index 6ae05b9ce359..97223e2410bd 100644 |
| --- a/include/linux/fwnode.h |
| +++ b/include/linux/fwnode.h |
| @@ -71,8 +71,25 @@ struct fwnode_reference_args { |
| * links to all the suppliers of the device that are available at |
| * the time this function is called. The function must NOT stop |
| * at the first failed device link if other unlinked supplier |
| - * devices are present in the system. If some suppliers are not |
| - * yet available, this function will be called again when other |
| + * devices are present in the system. This is necessary for the |
| + * driver/bus sync_state() callbacks to work correctly. |
| + * |
| + * For example, say Device-C depends on suppliers Device-S1 and |
| + * Device-S2 and the dependency is listed in that order in the |
| + * firmware. Say, S1 gets populated from the firmware after |
| + * late_initcall_sync(). Say S2 is populated and probed way |
| + * before that in device_initcall(). When C is populated, if this |
| + * add_links() function doesn't continue past a "failed linking to |
| + * S1" and continue linking C to S2, then S2 will get a |
| + * sync_state() callback before C is probed. This is because from |
| + * the perspective of S2, C was never a consumer when its |
| + * sync_state() evaluation is done. To avoid this, the add_links() |
| + * function has to go through all available suppliers of the |
| + * device (that corresponds to this fwnode) and link to them |
| + * before returning. |
| + * |
| + * If some suppliers are not yet available (indicated by an error |
| + * return value), this function will be called again when other |
| * devices are added to allow creating device links to any newly |
| * available suppliers. |
| * |
