diff mbox series

[v4,1/7] device property: Helper to match multiple connections

Message ID 20220307034040.1111107-1-bjorn.andersson@linaro.org (mailing list archive)
State New, archived
Headers show
Series [v4,1/7] device property: Helper to match multiple connections | expand

Commit Message

Bjorn Andersson March 7, 2022, 3:40 a.m. UTC
In some cases multiple connections with the same connection id
needs to be resolved from a fwnode graph.

One such example is when separate hardware is used for performing muxing
and/or orientation switching of the SuperSpeed and SBU lines in a USB
Type-C connector. In this case the connector needs to belong to a graph
with multiple matching remote endpoints, and the Type-C controller needs
to be able to resolve them both.

Add a new API that allows this kind of lookup.

Signed-off-by: Bjorn Andersson <bjorn.andersson@linaro.org>
---

Changes since v3:
- fwnode_connection_find_matches() should not adjust matches before calling
  fwnode_devcon_matches()
- Replaced return from within the loops with break
- Changed "count >= matches_len && matches" to "matches && count >=
  matches_len", to denote the significance of "matches"

Changes since v2:
- Allow the caller of the new api to pass a matches of NULL, to count possible
  matches. I previously argued that this will cause memory leaks, but Andy
  pointed out that this depends on the caller and the match function.
- Fixed spelling mistakes in commit message and kernel-doc.
- Use two "count" variables to make the math clearer.

Changes since v1:
- Iterator in fwnode_devcon_matches() is now unsigned.
- fwnode_handle_put() node for unavailable nodes.
- Extended commit message on the subject of supporting dynamically sized
  "matches" array.

 drivers/base/property.c  | 109 +++++++++++++++++++++++++++++++++++++++
 include/linux/property.h |   5 ++
 2 files changed, 114 insertions(+)

Comments

Andy Shevchenko March 7, 2022, 10:05 a.m. UTC | #1
On Sun, Mar 06, 2022 at 07:40:34PM -0800, Bjorn Andersson wrote:
> In some cases multiple connections with the same connection id
> needs to be resolved from a fwnode graph.
> 
> One such example is when separate hardware is used for performing muxing
> and/or orientation switching of the SuperSpeed and SBU lines in a USB
> Type-C connector. In this case the connector needs to belong to a graph
> with multiple matching remote endpoints, and the Type-C controller needs
> to be able to resolve them both.
> 
> Add a new API that allows this kind of lookup.

Thanks for the update!

First of all, I have noticed that subject misses the verb, something like Add
or Introduce.

...

> +/**
> + * fwnode_connection_find_matches - Find connections from a device node
> + * @fwnode: Device node with the connection
> + * @con_id: Identifier for the connection
> + * @data: Data for the match function
> + * @match: Function to check and convert the connection description
> + * @matches: Array of pointers to fill with matches

(Optional) array...

> + * @matches_len: Length of @matches
> + *
> + * Find up to @matches_len connections with unique identifier @con_id between
> + * @fwnode and other device nodes. @match will be used to convert the
> + * connection description to data the caller is expecting to be returned
> + * through the @matches array.

> + * If @matches is NULL @matches_len is ignored and the total number of resolved
> + * matches is returned.

I would require matches_len to be 0, see below.

> + * Return: Number of matches resolved, or negative errno.
> + */
> +int fwnode_connection_find_matches(struct fwnode_handle *fwnode,
> +				   const char *con_id, void *data,
> +				   devcon_match_fn_t match,
> +				   void **matches, unsigned int matches_len)
> +{
> +	unsigned int count_graph;
> +	unsigned int count_ref;
> +
> +	if (!fwnode || !match)
> +		return -EINVAL;
> +
> +	count_graph = fwnode_graph_devcon_matches(fwnode, con_id, data, match,
> +						  matches, matches_len);

> +	if (matches) {
> +		matches += count_graph;
> +		matches_len -= count_graph;
> +	}

So, the valid case is matches != NULL and matches_len == 0. For example, when
we have run something previously on the buffer and it becomes full.

In this case we have carefully handle this case.

	if (matches) {
		matches += count_graph;
		if (matches_len)
			matches_len -= count_graph;
	}

Seems it can be also

	if (matches)
		matches += count_graph;

	if (matches_len)
		matches_len -= count_graph;

That said, do we have a test cases for this?

> +	count_ref = fwnode_devcon_matches(fwnode, con_id, data, match,
> +					  matches, matches_len);
> +
> +	return count_graph + count_ref;
> +}
Bjorn Andersson March 7, 2022, 7:13 p.m. UTC | #2
On Mon 07 Mar 02:05 PST 2022, Andy Shevchenko wrote:

> On Sun, Mar 06, 2022 at 07:40:34PM -0800, Bjorn Andersson wrote:
> > In some cases multiple connections with the same connection id
> > needs to be resolved from a fwnode graph.
> > 
> > One such example is when separate hardware is used for performing muxing
> > and/or orientation switching of the SuperSpeed and SBU lines in a USB
> > Type-C connector. In this case the connector needs to belong to a graph
> > with multiple matching remote endpoints, and the Type-C controller needs
> > to be able to resolve them both.
> > 
> > Add a new API that allows this kind of lookup.
> 
> Thanks for the update!
> 
> First of all, I have noticed that subject misses the verb, something like Add
> or Introduce.
> 

Will update accordingly.

> ...
> 
> > +/**
> > + * fwnode_connection_find_matches - Find connections from a device node
> > + * @fwnode: Device node with the connection
> > + * @con_id: Identifier for the connection
> > + * @data: Data for the match function
> > + * @match: Function to check and convert the connection description
> > + * @matches: Array of pointers to fill with matches
> 
> (Optional) array...
> 

Ditto.

> > + * @matches_len: Length of @matches
> > + *
> > + * Find up to @matches_len connections with unique identifier @con_id between
> > + * @fwnode and other device nodes. @match will be used to convert the
> > + * connection description to data the caller is expecting to be returned
> > + * through the @matches array.
> 
> > + * If @matches is NULL @matches_len is ignored and the total number of resolved
> > + * matches is returned.
> 
> I would require matches_len to be 0, see below.
> 
> > + * Return: Number of matches resolved, or negative errno.
> > + */
> > +int fwnode_connection_find_matches(struct fwnode_handle *fwnode,
> > +				   const char *con_id, void *data,
> > +				   devcon_match_fn_t match,
> > +				   void **matches, unsigned int matches_len)
> > +{
> > +	unsigned int count_graph;
> > +	unsigned int count_ref;
> > +
> > +	if (!fwnode || !match)
> > +		return -EINVAL;
> > +
> > +	count_graph = fwnode_graph_devcon_matches(fwnode, con_id, data, match,
> > +						  matches, matches_len);
> 
> > +	if (matches) {
> > +		matches += count_graph;
> > +		matches_len -= count_graph;
> > +	}
> 
> So, the valid case is matches != NULL and matches_len == 0. For example, when
> we have run something previously on the buffer and it becomes full.
> 
> In this case we have carefully handle this case.
> 
> 	if (matches) {
> 		matches += count_graph;
> 		if (matches_len)
> 			matches_len -= count_graph;

When matches is non-NULL, both the sub-functions are limited by
matches_len and as such count_graph <= matches_len.

As such matches_len >= 0.

In the event that the originally passed matches_len was 0, then
count_graph will be 0 and matches_len will remain 0.

I therefor don't see that this additional check changes things.

> 	}
> 
> Seems it can be also
> 
> 	if (matches)
> 		matches += count_graph;
> 
> 	if (matches_len)
> 		matches_len -= count_graph;

We covered the case of matches && (matches_len || !matches_len) above.

For the case of !matches && matches_len, this added conditional would
cause matches_len to be extra ignored by keeping it at 0, but per
kernel-doc and implementation we ignore all other values already.


Note that this is in contrast from vsnprintf() where the code will
continue to produce results, only store the first "matches_len"
entires and return the final count.

Unfortunately we can't follow such semantics here, instead it is clearly
documented in the kernel-doc that @matches_len is ignored when @matches
is NULL.


So unless I'm missing something I don't see what you gain over keeping
the check on only matches.

> 
> That said, do we have a test cases for this?
> 

I looked briefly at adding some kunit tests for this, but was discourage
by the prospect of building up the graphs to run the tests against.

Regards,
Bjorn

> > +	count_ref = fwnode_devcon_matches(fwnode, con_id, data, match,
> > +					  matches, matches_len);
> > +
> > +	return count_graph + count_ref;
> > +}
> 
> -- 
> With Best Regards,
> Andy Shevchenko
> 
>
diff mbox series

Patch

diff --git a/drivers/base/property.c b/drivers/base/property.c
index c0e94cce9c29..7fccb0587855 100644
--- a/drivers/base/property.c
+++ b/drivers/base/property.c
@@ -1218,6 +1218,40 @@  fwnode_graph_devcon_match(struct fwnode_handle *fwnode, const char *con_id,
 	return NULL;
 }
 
+static unsigned int fwnode_graph_devcon_matches(struct fwnode_handle *fwnode,
+						const char *con_id, void *data,
+						devcon_match_fn_t match,
+						void **matches,
+						unsigned int matches_len)
+{
+	struct fwnode_handle *node;
+	struct fwnode_handle *ep;
+	unsigned int count = 0;
+	void *ret;
+
+	fwnode_graph_for_each_endpoint(fwnode, ep) {
+		if (matches && count >= matches_len) {
+			fwnode_handle_put(ep);
+			break;
+		}
+
+		node = fwnode_graph_get_remote_port_parent(ep);
+		if (!fwnode_device_is_available(node)) {
+			fwnode_handle_put(node);
+			continue;
+		}
+
+		ret = match(node, con_id, data);
+		fwnode_handle_put(node);
+		if (ret) {
+			if (matches)
+				matches[count] = ret;
+			count++;
+		}
+	}
+	return count;
+}
+
 static void *
 fwnode_devcon_match(struct fwnode_handle *fwnode, const char *con_id,
 		    void *data, devcon_match_fn_t match)
@@ -1240,6 +1274,37 @@  fwnode_devcon_match(struct fwnode_handle *fwnode, const char *con_id,
 	return NULL;
 }
 
+static unsigned int fwnode_devcon_matches(struct fwnode_handle *fwnode,
+					  const char *con_id, void *data,
+					  devcon_match_fn_t match,
+					  void **matches,
+					  unsigned int matches_len)
+{
+	struct fwnode_handle *node;
+	unsigned int count = 0;
+	unsigned int i;
+	void *ret;
+
+	for (i = 0; ; i++) {
+		if (matches && count >= matches_len)
+			break;
+
+		node = fwnode_find_reference(fwnode, con_id, i);
+		if (IS_ERR(node))
+			break;
+
+		ret = match(node, NULL, data);
+		fwnode_handle_put(node);
+		if (ret) {
+			if (matches)
+				matches[count] = ret;
+			count++;
+		}
+	}
+
+	return count;
+}
+
 /**
  * fwnode_connection_find_match - Find connection from a device node
  * @fwnode: Device node with the connection
@@ -1267,3 +1332,47 @@  void *fwnode_connection_find_match(struct fwnode_handle *fwnode,
 	return fwnode_devcon_match(fwnode, con_id, data, match);
 }
 EXPORT_SYMBOL_GPL(fwnode_connection_find_match);
+
+/**
+ * fwnode_connection_find_matches - Find connections from a device node
+ * @fwnode: Device node with the connection
+ * @con_id: Identifier for the connection
+ * @data: Data for the match function
+ * @match: Function to check and convert the connection description
+ * @matches: Array of pointers to fill with matches
+ * @matches_len: Length of @matches
+ *
+ * Find up to @matches_len connections with unique identifier @con_id between
+ * @fwnode and other device nodes. @match will be used to convert the
+ * connection description to data the caller is expecting to be returned
+ * through the @matches array.
+ * If @matches is NULL @matches_len is ignored and the total number of resolved
+ * matches is returned.
+ *
+ * Return: Number of matches resolved, or negative errno.
+ */
+int fwnode_connection_find_matches(struct fwnode_handle *fwnode,
+				   const char *con_id, void *data,
+				   devcon_match_fn_t match,
+				   void **matches, unsigned int matches_len)
+{
+	unsigned int count_graph;
+	unsigned int count_ref;
+
+	if (!fwnode || !match)
+		return -EINVAL;
+
+	count_graph = fwnode_graph_devcon_matches(fwnode, con_id, data, match,
+						  matches, matches_len);
+
+	if (matches) {
+		matches += count_graph;
+		matches_len -= count_graph;
+	}
+
+	count_ref = fwnode_devcon_matches(fwnode, con_id, data, match,
+					  matches, matches_len);
+
+	return count_graph + count_ref;
+}
+EXPORT_SYMBOL_GPL(fwnode_connection_find_matches);
diff --git a/include/linux/property.h b/include/linux/property.h
index 4cd4b326941f..de7ff336d2c8 100644
--- a/include/linux/property.h
+++ b/include/linux/property.h
@@ -447,6 +447,11 @@  static inline void *device_connection_find_match(struct device *dev,
 	return fwnode_connection_find_match(dev_fwnode(dev), con_id, data, match);
 }
 
+int fwnode_connection_find_matches(struct fwnode_handle *fwnode,
+				   const char *con_id, void *data,
+				   devcon_match_fn_t match,
+				   void **matches, unsigned int matches_len);
+
 /* -------------------------------------------------------------------------- */
 /* Software fwnode support - when HW description is incomplete or missing */