linux-kernel - [PATCH v4 10/18] devcon property: Document devcon_match_fn

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20240901040658.157425-11-swboyd@chromium.org>
Date: Sat, 31 Aug 2024 21:06:48 -0700
From: Stephen Boyd <swboyd@...omium.org>
To: chrome-platform@...ts.linux.dev
Cc: linux-kernel@...r.kernel.org,
	patches@...ts.linux.dev,
	devicetree@...r.kernel.org,
	Douglas Anderson <dianders@...omium.org>,
	Pin-yen Lin <treapking@...omium.org>,
	Andrzej Hajda <andrzej.hajda@...el.com>,
	Benson Leung <bleung@...omium.org>,
	Conor Dooley <conor+dt@...nel.org>,
	Daniel Vetter <daniel@...ll.ch>,
	David Airlie <airlied@...il.com>,
	Dmitry Baryshkov <dmitry.baryshkov@...aro.org>,
	dri-devel@...ts.freedesktop.org,
	Guenter Roeck <groeck@...omium.org>,
	Jernej Skrabec <jernej.skrabec@...il.com>,
	Jonas Karlman <jonas@...boo.se>,
	Krzysztof Kozlowski <krzysztof.kozlowski+dt@...aro.org>,
	Laurent Pinchart <Laurent.pinchart@...asonboard.com>,
	Lee Jones <lee@...nel.org>,
	Maarten Lankhorst <maarten.lankhorst@...ux.intel.com>,
	Maxime Ripard <mripard@...nel.org>,
	Neil Armstrong <neil.armstrong@...aro.org>,
	Prashant Malani <pmalani@...omium.org>,
	Robert Foss <rfoss@...nel.org>,
	Rob Herring <robh+dt@...nel.org>,
	Thomas Zimmermann <tzimmermann@...e.de>,
	Tzung-Bi Shih <tzungbi@...nel.org>,
	Alexandre Belloni <alexandre.belloni@...tlin.com>,
	Andy Shevchenko <andriy.shevchenko@...ux.intel.com>,
	Daniel Scally <djrscally@...il.com>,
	Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
	Heikki Krogerus <heikki.krogerus@...ux.intel.com>,
	Ivan Orlov <ivan.orlov0322@...il.com>,
	linux-acpi@...r.kernel.org,
	linux-usb@...r.kernel.org,
	Mika Westerberg <mika.westerberg@...ux.intel.com>,
	"Rafael J . Wysocki" <rafael.j.wysocki@...el.com>,
	Sakari Ailus <sakari.ailus@...ux.intel.com>,
	Vinod Koul <vkoul@...nel.org>
Subject: [PATCH v4 10/18] devcon property: Document devcon_match_fn_t

The usage of this match function is hard to understand at a glance.
Document the arguments and the return value so it is clear how to
implement the function.

Suggested-by: Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
Signed-off-by: Stephen Boyd <swboyd@...omium.org>
---
 include/linux/property.h | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/include/linux/property.h b/include/linux/property.h
index 61fc20e5f81f..797b1eeda7d2 100644
--- a/include/linux/property.h
+++ b/include/linux/property.h
@@ -507,8 +507,25 @@ unsigned int fwnode_graph_get_endpoint_count(const struct fwnode_handle *fwnode,
 int fwnode_graph_parse_endpoint(const struct fwnode_handle *fwnode,
 				struct fwnode_endpoint *endpoint);
 
-typedef void *(*devcon_match_fn_t)(const struct fwnode_handle *fwnode, const char *id,
-				   void *data);
+/**
+ * devcon_match_fn_t - device connection match function
+ * @fwnode: Remote connection's device node
+ * @con_id: Identifier for the connection
+ * @data: Match function caller specific data
+ *
+ * Implement a callback with this function signature to search a fwnode's
+ * connections for a match with a function like device_connection_find_match().
+ * This function will be called possibly multiple times, once for each
+ * connection. The match function should inspect the @fwnode to look for a
+ * match. The @con_id and @data provided are the same as the @con_id and @data
+ * arguments passed to the functions that take a devcon_match_fn_t argument.
+ *
+ * Note: This function can be called multiple times.
+ *
+ * Return: Pointer to match or NULL if no match found.
+ */
+typedef void *(*devcon_match_fn_t)(const struct fwnode_handle *fwnode,
+				   const char *con_id, void *data);
 
 void *fwnode_connection_find_match(const struct fwnode_handle *fwnode,
 				   const char *con_id, void *data,
-- 
https://chromeos.dev