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@xxxxxxxxxxxxxxx> Signed-off-by: Stephen Boyd <swboyd@xxxxxxxxxxxx> --- 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
