Skip to contentSkip to conversation

device property: Add fwnode_graph_get_endpoint_by_id

PATCH Superseded Sakari Ailus 2 participants 7 messages Mar 16, 2019 – Mar 27, 2019

Subsystems (2)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Sakari Ailus

author reviewer
#0 lore raw

PATCH v2 1/1 device property: Add fwnode_graph_get_endpoint_by_id

fwnode_graph_get_endpoint_by_id() is intended for obtaining local endpoints by a given local port. fwnode_graph_get_endpoint_by_id() is slightly different from its OF counterpart is of_graph_get_endpoint_by_regs(): instead of using -1 as a value to signify that a port or an endpoint number does not matter, it uses flags to look for equal or greater endpoint. The port number is always fixed. It also returns only remote endpoints that belong to an available device, a behaviour that can be turned off with a flag.

---
since v1:

- Remove the PORT_NEXT flag.

- Replace the ENDPOINT_AVAILABLE flag with DEVICE_DISABLED flag and so effectively inverting its functionality.

- Rework the loop iterating over endpoint to find the best one. It's more simple and better commented now.

- Fixes in indentation and documentation (e.g. fwnode_node_put -> fwnode_handle_put).

 drivers/base/property.c  | 81 ++++++++++++++++++++++++++++++++++++++++++++++++
 include/linux/property.h | 19 ++++++++++++
 2 files changed, 100 insertions(+)
drivers/base/property.c +81 -0
index 8b91ab380d14..7b908cadbdd5 100644
@@ -984,6 +984,87 @@ fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id,
 EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_node);
 
 /**
+ * fwnode_graph_get_endpoint_by_id - get endpoint node by port and endpoint
+ *				     numbers
+ * @fwnode: pointer to parent fwnode_handle containing the graph
+ * @port: identifier of the port node
+ * @endpoint: identifier of the endpoint node under the port node
+ * @flags: fwnode graph flags
+ *
+ * Returns the fwnode handle to the local endpoint corresponding the port and
+ * endpoint IDs or NULL if not found.
+ *
+ * Flags may be set in order to obtain the endpoint instead of just returning
+ * the specified one or none at all, or to only return endpoints that belong to
+ * a device that is available.
+ *
+ * Use fwnode_handle_put() on the endpoint fwnode handle when done using it.
+ */
+struct fwnode_handle *
+fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode,
+				u32 port, u32 endpoint,
+				enum fwnode_graph_get_endpoint_flags flags)
+{
+	struct fwnode_handle *ep = NULL, *best_ep = NULL;
+	unsigned int best_ep_id = 0;
+	bool endpoint_next = flags & FWNODE_GRAPH_ENDPOINT_NEXT;
+	bool disabled = flags & FWNODE_GRAPH_DEVICE_DISABLED;
+
+	while ((ep = fwnode_graph_get_next_endpoint(fwnode, ep))) {
+		struct fwnode_endpoint fwnode_ep = { 0 };
+		int ret;
+
+		/*
+		 * Check the device is available unless we're explicitly told
+		 * not to.
+		 */
+		if (!disabled) {
+			struct fwnode_handle *dev;
+
+			dev = fwnode_graph_get_remote_port_parent(ep);
+
+			if (!fwnode_device_is_available(dev)) {
+				fwnode_handle_put(dev);
+				continue;
+			}
+
+			fwnode_handle_put(dev);
+		}
+
+		ret = fwnode_graph_parse_endpoint(ep, &fwnode_ep);
+		if (ret < 0)
+			continue;
+
+		/* Check we have the right port. */
+		if (fwnode_ep.port != port)
+			continue;
+
+		/* Is this an exact match? If so, return it immediately. */
+		if (fwnode_ep.id == endpoint)
+			return ep;
+
+		/* Is an exact match needed? If so, skip this one. */
+		if (!endpoint_next)
+			continue;
+
+		/*
+		 * Is this endpoint better than we already had?
+		 */
+		if (fwnode_ep.id < endpoint ||
+		    (best_ep && best_ep_id < fwnode_ep.id))
+			continue;
+
+		/* Replace the one we had with the newly found one. */
+		fwnode_handle_put(best_ep);
+		best_ep = fwnode_handle_get(ep);
+		best_ep_id = fwnode_ep.id;
+	}
+
+	return best_ep;
+}
+EXPORT_SYMBOL_GPL(fwnode_graph_get_endpoint_by_id);
+
+/**
  * fwnode_graph_parse_endpoint - parse common endpoint node properties
  * @fwnode: pointer to endpoint fwnode_handle
  * @endpoint: pointer to the fwnode endpoint data structure
include/linux/property.h +19 -0
index 3789ec755fb6..f3d924092890 100644
@@ -304,6 +304,25 @@ struct fwnode_handle *
 fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port,
 			     u32 endpoint);
 
+/**
+ * enum fwnode_graph_get_endpoint_flags - Flags for finding an endpoint
+ *
+ * @FWNODE_GRAPH_ENDPOINT_NEXT: if no specified endpoint is found, obtain the
+ *				smallest endpoint number greater than specified
+ * @FWNODE_GRAPH_DEVICE_DISABLED that the device to which the remote
+ *				 endpoint of the given endpoint belongs to,
+ *				 may be disabled
+ */
+enum fwnode_graph_get_endpoint_flags {
+	FWNODE_GRAPH_ENDPOINT_NEXT	= 0x00000001,
+	FWNODE_GRAPH_DEVICE_DISABLED	= 0x00000002,
+};
+
+struct fwnode_handle *
+fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode,
+				u32 port, u32 endpoint,
+				enum fwnode_graph_get_endpoint_flags flags);
+
 #define fwnode_graph_for_each_endpoint(fwnode, child)			\
 	for (child = NULL;						\
 	     (child = fwnode_graph_get_next_endpoint(fwnode, child)); )
Signature · 1 line
2.11.0
#1 lore raw
Quoted 34 lines · Sakari Ailus

fwnode_graph_get_endpoint_by_id() is intended for obtaining local endpoints by a given local port. fwnode_graph_get_endpoint_by_id() is slightly different from its OF counterpart is of_graph_get_endpoint_by_regs(): instead of using -1 as a value to signify that a port or an endpoint number does not matter, it uses flags to look for equal or greater endpoint. The port number is always fixed. It also returns only remote endpoints that belong to an available device, a behaviour that can be turned off with a flag.

---
since v1:

- Remove the PORT_NEXT flag.

- Replace the ENDPOINT_AVAILABLE flag with DEVICE_DISABLED flag and so effectively inverting its functionality.

- Rework the loop iterating over endpoint to find the best one. It's more simple and better commented now.

- Fixes in indentation and documentation (e.g. fwnode_node_put -> fwnode_handle_put).

 drivers/base/property.c  | 81 ++++++++++++++++++++++++++++++++++++++++++++++++
 include/linux/property.h | 19 ++++++++++++
 2 files changed, 100 insertions(+)
drivers/base/property.c +0 -0
index 8b91ab380d14..7b908cadbdd5 100644

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 988

Quoted 5 lines
drivers/base/property.c +2 -0
@@ -984,6 +984,87 @@ fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id,
 EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_node);
 
 /**
+ * fwnode_graph_get_endpoint_by_id - get endpoint node by port and endpoint
+ *                                  numbers

IMO you can drop "node" from the description line and then it will fit under 80 chars.

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 989

Quoted 1 line
drivers/base/property.c +1 -0
+ * @fwnode: pointer to parent fwnode_handle containing the graph

"pointer to" is redundant here IMO.

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 992

Quoted 3 lines
drivers/base/property.c +3 -0
+ * @port: identifier of the port node
+ * @endpoint: identifier of the endpoint node under the port node
+ * @flags: fwnode graph flags

s/graph/lookup/ ?

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 994

Quoted 2 lines
drivers/base/property.c +2 -0
+ *
+ * Returns the fwnode handle to the local endpoint corresponding the port and

s/to/of/ ?

Also there should be "corresponding to the port ..."

And I would say "Return ..."

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 995

Quoted 1 line
drivers/base/property.c +1 -0
+ * endpoint IDs or NULL if not found.

I would say here "If FWNODE_GRAPH_ENDPOINT_NEXT is passed in @flags and the specified endpoint has not been found, look for the closest endpoint ID greater than the specified one and return the endpoint that corresponds to it, if present".

Also "Do not return endpoints that belong to disabled devices, unless FWNODE_GRAPH_DEVICE_DISABLED is passed in @flags".

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1001

Quoted 6 lines
drivers/base/property.c +6 -0
+ *
+ * Flags may be set in order to obtain the endpoint instead of just returning
+ * the specified one or none at all, or to only return endpoints that belong to
+ * a device that is available.
+ *
+ * Use fwnode_handle_put() on the endpoint fwnode handle when done using it.

I would say "The returned endpoint needs to be released by calling fwnode_handle_put() on it when it is not necessary any more."

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1010

Quoted 9 lines
drivers/base/property.c +9 -0
+ */
+struct fwnode_handle *
+fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode,
+                               u32 port, u32 endpoint,
+                               enum fwnode_graph_get_endpoint_flags flags)
+{
+       struct fwnode_handle *ep = NULL, *best_ep = NULL;
+       unsigned int best_ep_id = 0;
+       bool endpoint_next = flags & FWNODE_GRAPH_ENDPOINT_NEXT;

I tend to apply !! to things like the right-hand side of the above to get a proper bool value.

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1011

Quoted 1 line
drivers/base/property.c +1 -0
+       bool disabled = flags & FWNODE_GRAPH_DEVICE_DISABLED;

I would call this "enabled_only" and reverse its meaning.

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1022

Quoted 11 lines
drivers/base/property.c +11 -0
+
+       while ((ep = fwnode_graph_get_next_endpoint(fwnode, ep))) {
+               struct fwnode_endpoint fwnode_ep = { 0 };
+               int ret;
+
+               /*
+                * Check the device is available unless we're explicitly told
+                * not to.
+                */
+               if (!disabled) {
+                       struct fwnode_handle *dev;

s/dev/dev_node/

bool available;

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1024

Quoted 2 lines
drivers/base/property.c +2 -0
+
+                       dev = fwnode_graph_get_remote_port_parent(ep);

available = fwnode_device_is_available(dev_node);
fwnode_handle_put(dev_node);
if (!available)

        continue;
Quoted 10 lines
drivers/base/property.c +10 -0
+
+                       if (!fwnode_device_is_available(dev)) {
+                               fwnode_handle_put(dev);
+                               continue;
+                       }
+
+                       fwnode_handle_put(dev);
+               }
+
+               ret = fwnode_graph_parse_endpoint(ep, &fwnode_ep);

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1044

Quoted 10 lines
drivers/base/property.c +10 -0
+               if (ret < 0)
+                       continue;
+
+               /* Check we have the right port. */
+               if (fwnode_ep.port != port)
+                       continue;
+
+               /* Is this an exact match? If so, return it immediately. */
+               if (fwnode_ep.id == endpoint)
+                       return ep;

This appears to mean that the endpoint has been reference-counted, but then the reference should be dropped before the "continue" above, shouldn't it?

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1048

Quoted 4 lines
drivers/base/property.c +4 -0
+
+               /* Is an exact match needed? If so, skip this one. */
+               if (!endpoint_next)
+                       continue;

And here?

Besides, the three comments above are redundant IMO (they don't explain anything, but just repeat what the code does).

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1052

Quoted 4 lines
drivers/base/property.c +4 -0
+
+               /*
+                * Is this endpoint better than we already had?
+                */

I would say in this comment "If the endpoint that has just been found is not the first matching one and the ID of the one found previously is closer to the requested endpoint ID, skip it."

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1054

Quoted 2 lines
drivers/base/property.c +2 -0
+               if (fwnode_ep.id < endpoint ||
+                   (best_ep && best_ep_id < fwnode_ep.id))

Drop the fwnode_ep reference?

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1057

Quoted 3 lines
drivers/base/property.c +3 -0
+                       continue;
+
+               /* Replace the one we had with the newly found one. */

Redundant comment.

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1058

Quoted 1 line
drivers/base/property.c +1 -0
+               fwnode_handle_put(best_ep);

Does this always work if best_ep is NULL?

Quoted 17 lines
drivers/base/property.c +9 -0
+               best_ep = fwnode_handle_get(ep);
+               best_ep_id = fwnode_ep.id;
+       }
+
+       return best_ep;
+}
+EXPORT_SYMBOL_GPL(fwnode_graph_get_endpoint_by_id);
+
+/**
  * fwnode_graph_parse_endpoint - parse common endpoint node properties
  * @fwnode: pointer to endpoint fwnode_handle
  * @endpoint: pointer to the fwnode endpoint data structure
include/linux/property.h +0 -0
index 3789ec755fb6..f3d924092890 100644

include/linux/property.h struct fwnode_handle * · line 311

Quoted 8 lines
include/linux/property.h +5 -0
@@ -304,6 +304,25 @@ struct fwnode_handle *
 fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port,
                             u32 endpoint);
 
+/**
+ * enum fwnode_graph_get_endpoint_flags - Flags for finding an endpoint
+ *
+ * @FWNODE_GRAPH_ENDPOINT_NEXT: if no specified endpoint is found, obtain the
+ *                             smallest endpoint number greater than specified

"In the no exact match case, look for the closest endpoint ID greater than the specified one."

include/linux/property.h struct fwnode_handle * · line 312

Quoted 1 line
include/linux/property.h +1 -0
+ * @FWNODE_GRAPH_DEVICE_DISABLED that the device to which the remote

Missing colon.

include/linux/property.h struct fwnode_handle * · line 314

Quoted 2 lines
include/linux/property.h +2 -0
+ *                              endpoint of the given endpoint belongs to,
+ *                              may be disabled

"Also return endpoints that belong to disabled devices."

include/linux/property.h struct fwnode_handle * · line 317

Quoted 3 lines
include/linux/property.h +3 -0
+ */
+enum fwnode_graph_get_endpoint_flags {
+       FWNODE_GRAPH_ENDPOINT_NEXT      = 0x00000001,

BIT(1) ?

include/linux/property.h struct fwnode_handle * · line 318

Quoted 1 line
include/linux/property.h +1 -0
+       FWNODE_GRAPH_DEVICE_DISABLED    = 0x00000002,

BIT(2) ?

Quoted 11 lines
include/linux/property.h +7 -1
+};
+
+struct fwnode_handle *
+fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode,
+                               u32 port, u32 endpoint,
+                               enum fwnode_graph_get_endpoint_flags flags);
+
 #define fwnode_graph_for_each_endpoint(fwnode, child)                  \
        for (child = NULL;                                              \
             (child = fwnode_graph_get_next_endpoint(fwnode, child)); )
--
#2 lore raw
Quoted 227 lines · Rafael J. Wysocki
Quoted 34 lines · Sakari Ailus

fwnode_graph_get_endpoint_by_id() is intended for obtaining local endpoints by a given local port. fwnode_graph_get_endpoint_by_id() is slightly different from its OF counterpart is of_graph_get_endpoint_by_regs(): instead of using -1 as a value to signify that a port or an endpoint number does not matter, it uses flags to look for equal or greater endpoint. The port number is always fixed. It also returns only remote endpoints that belong to an available device, a behaviour that can be turned off with a flag.

---
since v1:

- Remove the PORT_NEXT flag.

- Replace the ENDPOINT_AVAILABLE flag with DEVICE_DISABLED flag and so effectively inverting its functionality.

- Rework the loop iterating over endpoint to find the best one. It's more simple and better commented now.

- Fixes in indentation and documentation (e.g. fwnode_node_put -> fwnode_handle_put).

 drivers/base/property.c  | 81 ++++++++++++++++++++++++++++++++++++++++++++++++
 include/linux/property.h | 19 ++++++++++++
 2 files changed, 100 insertions(+)
drivers/base/property.c +0 -0
index 8b91ab380d14..7b908cadbdd5 100644

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 988

Quoted 5 lines
drivers/base/property.c +2 -0
@@ -984,6 +984,87 @@ fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id,
 EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_node);
 
 /**
+ * fwnode_graph_get_endpoint_by_id - get endpoint node by port and endpoint
+ *                                  numbers

IMO you can drop "node" from the description line and then it will fit under 80 chars.

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 989

Quoted 1 line
drivers/base/property.c +1 -0
+ * @fwnode: pointer to parent fwnode_handle containing the graph

"pointer to" is redundant here IMO.

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 992

Quoted 3 lines
drivers/base/property.c +3 -0
+ * @port: identifier of the port node
+ * @endpoint: identifier of the endpoint node under the port node
+ * @flags: fwnode graph flags

s/graph/lookup/ ?

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 994

Quoted 2 lines
drivers/base/property.c +2 -0
+ *
+ * Returns the fwnode handle to the local endpoint corresponding the port and

s/to/of/ ?

Also there should be "corresponding to the port ..."

And I would say "Return ..."

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 995

Quoted 1 line
drivers/base/property.c +1 -0
+ * endpoint IDs or NULL if not found.

I would say here "If FWNODE_GRAPH_ENDPOINT_NEXT is passed in @flags and the specified endpoint has not been found, look for the closest endpoint ID greater than the specified one and return the endpoint that corresponds to it, if present".

Also "Do not return endpoints that belong to disabled devices, unless FWNODE_GRAPH_DEVICE_DISABLED is passed in @flags".

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1001

Quoted 6 lines
drivers/base/property.c +6 -0
+ *
+ * Flags may be set in order to obtain the endpoint instead of just returning
+ * the specified one or none at all, or to only return endpoints that belong to
+ * a device that is available.
+ *
+ * Use fwnode_handle_put() on the endpoint fwnode handle when done using it.

I would say "The returned endpoint needs to be released by calling fwnode_handle_put() on it when it is not necessary any more."

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1010

Quoted 9 lines
drivers/base/property.c +9 -0
+ */
+struct fwnode_handle *
+fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode,
+                               u32 port, u32 endpoint,
+                               enum fwnode_graph_get_endpoint_flags flags)
+{
+       struct fwnode_handle *ep = NULL, *best_ep = NULL;
+       unsigned int best_ep_id = 0;
+       bool endpoint_next = flags & FWNODE_GRAPH_ENDPOINT_NEXT;

I tend to apply !! to things like the right-hand side of the above to get a proper bool value.

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1011

Quoted 1 line
drivers/base/property.c +1 -0
+       bool disabled = flags & FWNODE_GRAPH_DEVICE_DISABLED;

I would call this "enabled_only" and reverse its meaning.

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1022

Quoted 11 lines
drivers/base/property.c +11 -0
+
+       while ((ep = fwnode_graph_get_next_endpoint(fwnode, ep))) {
+               struct fwnode_endpoint fwnode_ep = { 0 };
+               int ret;
+
+               /*
+                * Check the device is available unless we're explicitly told
+                * not to.
+                */
+               if (!disabled) {
+                       struct fwnode_handle *dev;

s/dev/dev_node/

bool available;

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1024

Quoted 2 lines
drivers/base/property.c +2 -0
+
+                       dev = fwnode_graph_get_remote_port_parent(ep);

available = fwnode_device_is_available(dev_node);
fwnode_handle_put(dev_node);
if (!available)

        continue;
Quoted 10 lines
drivers/base/property.c +10 -0
+
+                       if (!fwnode_device_is_available(dev)) {
+                               fwnode_handle_put(dev);
+                               continue;
+                       }
+
+                       fwnode_handle_put(dev);
+               }
+
+               ret = fwnode_graph_parse_endpoint(ep, &fwnode_ep);

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1044

Quoted 10 lines
drivers/base/property.c +10 -0
+               if (ret < 0)
+                       continue;
+
+               /* Check we have the right port. */
+               if (fwnode_ep.port != port)
+                       continue;
+
+               /* Is this an exact match? If so, return it immediately. */
+               if (fwnode_ep.id == endpoint)
+                       return ep;

This appears to mean that the endpoint has been reference-counted, but then the reference should be dropped before the "continue" above, shouldn't it?

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1048

Quoted 4 lines
drivers/base/property.c +4 -0
+
+               /* Is an exact match needed? If so, skip this one. */
+               if (!endpoint_next)
+                       continue;

And here?

Besides, the three comments above are redundant IMO (they don't explain anything, but just repeat what the code does).

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1052

Quoted 4 lines
drivers/base/property.c +4 -0
+
+               /*
+                * Is this endpoint better than we already had?
+                */

I would say in this comment "If the endpoint that has just been found is not the first matching one and the ID of the one found previously is closer to the requested endpoint ID, skip it."

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1054

Quoted 2 lines
drivers/base/property.c +2 -0
+               if (fwnode_ep.id < endpoint ||
+                   (best_ep && best_ep_id < fwnode_ep.id))

Drop the fwnode_ep reference?

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1057

Quoted 3 lines
drivers/base/property.c +3 -0
+                       continue;
+
+               /* Replace the one we had with the newly found one. */

Redundant comment.

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1058

Quoted 1 line
drivers/base/property.c +1 -0
+               fwnode_handle_put(best_ep);

Does this always work if best_ep is NULL?

Quoted 17 lines
drivers/base/property.c +9 -0
+               best_ep = fwnode_handle_get(ep);
+               best_ep_id = fwnode_ep.id;
+       }
+
+       return best_ep;
+}
+EXPORT_SYMBOL_GPL(fwnode_graph_get_endpoint_by_id);
+
+/**
  * fwnode_graph_parse_endpoint - parse common endpoint node properties
  * @fwnode: pointer to endpoint fwnode_handle
  * @endpoint: pointer to the fwnode endpoint data structure
include/linux/property.h +0 -0
index 3789ec755fb6..f3d924092890 100644

include/linux/property.h struct fwnode_handle * · line 311

Quoted 8 lines
include/linux/property.h +5 -0
@@ -304,6 +304,25 @@ struct fwnode_handle *
 fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port,
                             u32 endpoint);
 
+/**
+ * enum fwnode_graph_get_endpoint_flags - Flags for finding an endpoint
+ *
+ * @FWNODE_GRAPH_ENDPOINT_NEXT: if no specified endpoint is found, obtain the
+ *                             smallest endpoint number greater than specified

"In the no exact match case, look for the closest endpoint ID greater than the specified one."

include/linux/property.h struct fwnode_handle * · line 312

Quoted 1 line
include/linux/property.h +1 -0
+ * @FWNODE_GRAPH_DEVICE_DISABLED that the device to which the remote

Missing colon.

include/linux/property.h struct fwnode_handle * · line 314

Quoted 2 lines
include/linux/property.h +2 -0
+ *                              endpoint of the given endpoint belongs to,
+ *                              may be disabled

"Also return endpoints that belong to disabled devices."

include/linux/property.h struct fwnode_handle * · line 317

Quoted 3 lines
include/linux/property.h +3 -0
+ */
+enum fwnode_graph_get_endpoint_flags {
+       FWNODE_GRAPH_ENDPOINT_NEXT      = 0x00000001,
Quoted 7 lines

BIT(1) ?

include/linux/property.h struct fwnode_handle * · line 318

Quoted 1 line
include/linux/property.h +1 -0
+       FWNODE_GRAPH_DEVICE_DISABLED    = 0x00000002,

BIT(2) ?

Quoted 1 line
include/linux/property.h +1 -0
+};

Actually, enum types are not particularly suitable for flags in my view, because something like

FWNODE_GRAPH_ENDPOINT_NEXT | FWNODE_GRAPH_DEVICE_DISABLED

is not really defined within the enum type, for example.

It's better to #define the flags IMO and use unsigned int as the type.

author reviewer
#3 lore raw

Hi Rafael,

On Wed, Mar 27, 2019 at 10:42:23AM +0100, Rafael J. Wysocki wrote:
...

Quoted 12 lines
Quoted 11 lines

include/linux/property.h struct fwnode_handle * · line 317

Quoted 3 lines

+ */

include/linux/property.h +2 -0
+enum fwnode_graph_get_endpoint_flags {
+       FWNODE_GRAPH_ENDPOINT_NEXT      = 0x00000001,

BIT(1) ?

Quoted 1 line

+ FWNODE_GRAPH_DEVICE_DISABLED = 0x00000002,

BIT(2) ?

Quoted 1 line

+};

Quoted 8 lines

Actually, enum types are not particularly suitable for flags in my view, because something like

FWNODE_GRAPH_ENDPOINT_NEXT | FWNODE_GRAPH_DEVICE_DISABLED

is not really defined within the enum type, for example.

It's better to #define the flags IMO and use unsigned int as the type.

Enums can have better kerneldoc documentation; that's been the reasoning to make flags fields enums in e.g. V4L2 kAPI. In C it's still valid use of enums even if the value isn't any value listen in an enum as such.

Anyway, I'll switch to #define and make the comment just a regular comment if you prefer that.

Signature · 2 lines
Sakari Ailus
[email protected]
#4 lore raw
Quoted 24 lines · Sakari Ailus

Hi Rafael,

On Wed, Mar 27, 2019 at 10:42:23AM +0100, Rafael J. Wysocki wrote:
...

Quoted 19 lines
Quoted 11 lines

include/linux/property.h struct fwnode_handle * · line 317

Quoted 3 lines

+ */

include/linux/property.h +2 -0
+enum fwnode_graph_get_endpoint_flags {
+       FWNODE_GRAPH_ENDPOINT_NEXT      = 0x00000001,

BIT(1) ?

Quoted 1 line

+ FWNODE_GRAPH_DEVICE_DISABLED = 0x00000002,

BIT(2) ?

Quoted 1 line

+};

Actually, enum types are not particularly suitable for flags in my view, because something like

FWNODE_GRAPH_ENDPOINT_NEXT | FWNODE_GRAPH_DEVICE_DISABLED

is not really defined within the enum type, for example.

Quoted 8 lines
Quoted 1 line

It's better to #define the flags IMO and use unsigned int as the type.

Enums can have better kerneldoc documentation; that's been the reasoning to make flags fields enums in e.g. V4L2 kAPI. In C it's still valid use of enums even if the value isn't any value listen in an enum as such.

Anyway, I'll switch to #define and make the comment just a regular comment if you prefer that.

I do.

I did something like that with device links flags, for example.

author reviewer
#5 lore raw
In reply to Rafael J. Wysocki

Hi Rafael,

Thank you for the review.

Quoted 38 lines · Rafael J. Wysocki
Quoted 36 lines · Sakari Ailus

fwnode_graph_get_endpoint_by_id() is intended for obtaining local endpoints by a given local port. fwnode_graph_get_endpoint_by_id() is slightly different from its OF counterpart is of_graph_get_endpoint_by_regs(): instead of using -1 as a value to signify that a port or an endpoint number does not matter, it uses flags to look for equal or greater endpoint. The port number is always fixed. It also returns only remote endpoints that belong to an available device, a behaviour that can be turned off with a flag.

---
since v1:

- Remove the PORT_NEXT flag.

- Replace the ENDPOINT_AVAILABLE flag with DEVICE_DISABLED flag and so effectively inverting its functionality.

- Rework the loop iterating over endpoint to find the best one. It's more simple and better commented now.

- Fixes in indentation and documentation (e.g. fwnode_node_put -> fwnode_handle_put).

 drivers/base/property.c  | 81 ++++++++++++++++++++++++++++++++++++++++++++++++
 include/linux/property.h | 19 ++++++++++++
 2 files changed, 100 insertions(+)
drivers/base/property.c +0 -0
index 8b91ab380d14..7b908cadbdd5 100644
@@ -984,6 +984,87 @@ fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id,
 EXPORT_SYMBOL_GPL(fwnode_graph_get_remote_node);
 
Quoted 6 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 988

Quoted 3 lines
drivers/base/property.c +2 -0
 /**
+ * fwnode_graph_get_endpoint_by_id - get endpoint node by port and endpoint
+ *                                  numbers

IMO you can drop "node" from the description line and then it will fit under 80 chars.

Done.

Quoted 4 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 989

Quoted 2 lines
drivers/base/property.c +1 -0
+ * @fwnode: pointer to parent fwnode_handle containing the graph

"pointer to" is redundant here IMO.

Fixed.

Quoted 6 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 992

Quoted 4 lines
drivers/base/property.c +3 -0
+ * @port: identifier of the port node
+ * @endpoint: identifier of the endpoint node under the port node
+ * @flags: fwnode graph flags

s/graph/lookup/ ?

Yes.

Quoted 5 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 994

Quoted 3 lines
drivers/base/property.c +2 -0
+ *
+ * Returns the fwnode handle to the local endpoint corresponding the port and

s/to/of/ ?

Yes.

Quoted 2 lines

Also there should be "corresponding to the port ..."

I'd say "to" doesn't belong there. I guess neither of us is a native speaker so I'd hope to get a comment from one. :-)

Quoted 2 lines

And I would say "Return ..."

Fixed.

Quoted 10 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 995

Quoted 2 lines
drivers/base/property.c +1 -0
+ * endpoint IDs or NULL if not found.

I would say here "If FWNODE_GRAPH_ENDPOINT_NEXT is passed in @flags and the specified endpoint has not been found, look for the closest endpoint ID greater than the specified one and return the endpoint that corresponds to it, if present".

Also "Do not return endpoints that belong to disabled devices, unless FWNODE_GRAPH_DEVICE_DISABLED is passed in @flags".

I replaced the original with this as such.

Quoted 10 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1001

Quoted 7 lines
drivers/base/property.c +6 -0
+ *
+ * Flags may be set in order to obtain the endpoint instead of just returning
+ * the specified one or none at all, or to only return endpoints that belong to
+ * a device that is available.
+ *
+ * Use fwnode_handle_put() on the endpoint fwnode handle when done using it.

I would say "The returned endpoint needs to be released by calling fwnode_handle_put() on it when it is not necessary any more."

How about s/necessary/needed/ ?

Quoted 13 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1010

Quoted 10 lines
drivers/base/property.c +9 -0
+ */
+struct fwnode_handle *
+fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode,
+                               u32 port, u32 endpoint,
+                               enum fwnode_graph_get_endpoint_flags flags)
+{
+       struct fwnode_handle *ep = NULL, *best_ep = NULL;
+       unsigned int best_ep_id = 0;
+       bool endpoint_next = flags & FWNODE_GRAPH_ENDPOINT_NEXT;

I tend to apply !! to things like the right-hand side of the above to get a proper bool value.

It's not necessary: casting any non-zero value to bool is true. I couldn't find an authoritative reference tut it's not hard to find examples around the kernel, including arch/x86.

Quoted 4 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1011

Quoted 2 lines
drivers/base/property.c +1 -0
+       bool disabled = flags & FWNODE_GRAPH_DEVICE_DISABLED;

I would call this "enabled_only" and reverse its meaning.

Makes sense, that makes the code below easier to follow.

Quoted 17 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1022

Quoted 12 lines
drivers/base/property.c +11 -0
+
+       while ((ep = fwnode_graph_get_next_endpoint(fwnode, ep))) {
+               struct fwnode_endpoint fwnode_ep = { 0 };
+               int ret;
+
+               /*
+                * Check the device is available unless we're explicitly told
+                * not to.
+                */
+               if (!disabled) {
+                       struct fwnode_handle *dev;

s/dev/dev_node/

bool available;

Quoted 7 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1024

Quoted 2 lines
drivers/base/property.c +2 -0
+
+                       dev = fwnode_graph_get_remote_port_parent(ep);

available = fwnode_device_is_available(dev_node);
fwnode_handle_put(dev_node);
if (!available)

        continue;

Yes, makes sense.

Quoted 17 lines
Quoted 17 lines
drivers/base/property.c +16 -0
+
+                       if (!fwnode_device_is_available(dev)) {
+                               fwnode_handle_put(dev);
+                               continue;
+                       }
+
+                       fwnode_handle_put(dev);
+               }
+
+               ret = fwnode_graph_parse_endpoint(ep, &fwnode_ep);
+               if (ret < 0)
+                       continue;
+
+               /* Check we have the right port. */
+               if (fwnode_ep.port != port)
+                       continue;
Quoted 8 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1044

Quoted 4 lines
drivers/base/property.c +4 -0
+
+               /* Is this an exact match? If so, return it immediately. */
+               if (fwnode_ep.id == endpoint)
+                       return ep;

This appears to mean that the endpoint has been reference-counted, but then the reference should be dropped before the "continue" above, shouldn't it?

This is handled by fwnode_graph_get_next_endpoint() which puts the previous endpoint on every iteration.

Quoted 10 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1048

Quoted 5 lines
drivers/base/property.c +4 -0
+
+               /* Is an exact match needed? If so, skip this one. */
+               if (!endpoint_next)
+                       continue;

And here?

Besides, the three comments above are redundant IMO (they don't explain anything, but just repeat what the code does).

Well, true; I thought they might be useful to understand what the function does. I have no problem removing them.

Quoted 9 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1052

Quoted 5 lines
drivers/base/property.c +4 -0
+
+               /*
+                * Is this endpoint better than we already had?
+                */

I would say in this comment "If the endpoint that has just been found is not the first matching one and the ID of the one found previously is closer to the requested endpoint ID, skip it."

Yes.

Quoted 5 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1054

Quoted 3 lines
drivers/base/property.c +2 -0
+               if (fwnode_ep.id < endpoint ||
+                   (best_ep && best_ep_id < fwnode_ep.id))

Drop the fwnode_ep reference?

fwnode_graph_parse_endpoint() takes no reference.

Quoted 6 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1057

Quoted 4 lines
drivers/base/property.c +3 -0
+                       continue;
+
+               /* Replace the one we had with the newly found one. */

Redundant comment.

Removed.

Quoted 4 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1058

Quoted 2 lines
drivers/base/property.c +1 -0
+               fwnode_handle_put(best_ep);

Does this always work if best_ep is NULL?

Yes, the fwnode API functions (mostly?) are safe to call with NULL fwnode; at least this one is.

Quoted 21 lines
Quoted 21 lines
drivers/base/property.c +9 -0
+               best_ep = fwnode_handle_get(ep);
+               best_ep_id = fwnode_ep.id;
+       }
+
+       return best_ep;
+}
+EXPORT_SYMBOL_GPL(fwnode_graph_get_endpoint_by_id);
+
+/**
  * fwnode_graph_parse_endpoint - parse common endpoint node properties
  * @fwnode: pointer to endpoint fwnode_handle
  * @endpoint: pointer to the fwnode endpoint data structure
include/linux/property.h +0 -0
index 3789ec755fb6..f3d924092890 100644
@@ -304,6 +304,25 @@ struct fwnode_handle *
 fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port,
                             u32 endpoint);
 
Quoted 8 lines

include/linux/property.h struct fwnode_handle * · line 311

Quoted 5 lines
include/linux/property.h +5 -0
+/**
+ * enum fwnode_graph_get_endpoint_flags - Flags for finding an endpoint
+ *
+ * @FWNODE_GRAPH_ENDPOINT_NEXT: if no specified endpoint is found, obtain the
+ *                             smallest endpoint number greater than specified

"In the no exact match case, look for the closest endpoint ID greater than the specified one."

How about: "In the case of no exact match, ..."?

Quoted 4 lines

include/linux/property.h struct fwnode_handle * · line 312

Quoted 2 lines
include/linux/property.h +1 -0
+ * @FWNODE_GRAPH_DEVICE_DISABLED that the device to which the remote

Missing colon.

Fixed.

Quoted 11 lines

include/linux/property.h struct fwnode_handle * · line 314

Quoted 3 lines
include/linux/property.h +2 -0
+ *                              endpoint of the given endpoint belongs to,
+ *                              may be disabled

"Also return endpoints that belong to disabled devices."

include/linux/property.h struct fwnode_handle * · line 317

Quoted 3 lines
include/linux/property.h +3 -0
+ */
+enum fwnode_graph_get_endpoint_flags {
+       FWNODE_GRAPH_ENDPOINT_NEXT      = 0x00000001,

BIT(1) ?

BIT(0), BIT(1) below.

Quoted 16 lines

include/linux/property.h struct fwnode_handle * · line 318

Quoted 2 lines
include/linux/property.h +1 -0
+       FWNODE_GRAPH_DEVICE_DISABLED    = 0x00000002,

BIT(2) ?

Quoted 11 lines
include/linux/property.h +7 -1
+};
+
+struct fwnode_handle *
+fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode,
+                               u32 port, u32 endpoint,
+                               enum fwnode_graph_get_endpoint_flags flags);
+
 #define fwnode_graph_for_each_endpoint(fwnode, child)                  \
        for (child = NULL;                                              \
             (child = fwnode_graph_get_next_endpoint(fwnode, child)); )
--
Signature · 4 lines
Kind regards,

Sakari Ailus
[email protected]
#6 lore raw
Quoted 4 lines · Sakari Ailus

Hi Rafael,

Thank you for the review.

No problem. That's my job after all ...

[cut]

Quoted 8 lines
Quoted 8 lines
Quoted 7 lines

+ *
+ * Flags may be set in order to obtain the endpoint instead of just returning
+ * the specified one or none at all, or to only return endpoints that belong to
+ * a device that is available.
+ *
+ * Use fwnode_handle_put() on the endpoint fwnode handle when done using it.

Quoted 4 lines
Quoted 2 lines

I would say "The returned endpoint needs to be released by calling fwnode_handle_put() on it when it is not necessary any more."

How about s/necessary/needed/ ?

That works too.

Quoted 14 lines
Quoted 13 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1010

Quoted 10 lines

+ */

drivers/base/property.c +8 -0
+struct fwnode_handle *
+fwnode_graph_get_endpoint_by_id(const struct fwnode_handle *fwnode,
+                               u32 port, u32 endpoint,
+                               enum fwnode_graph_get_endpoint_flags flags)
+{
+       struct fwnode_handle *ep = NULL, *best_ep = NULL;
+       unsigned int best_ep_id = 0;
+       bool endpoint_next = flags & FWNODE_GRAPH_ENDPOINT_NEXT;

I tend to apply !! to things like the right-hand side of the above to get a proper bool value.

Quoted 1 line

It's not necessary: casting any non-zero value to bool is true.

Every nonzero value is regarded as "true" in C because of the lack of a bool type in the language, but since we pretend to have one ...

Quoted 63 lines

I couldn't find an authoritative reference tut it's not hard to find examples around the kernel, including arch/x86.

Quoted 4 lines
Quoted 2 lines

+ bool disabled = flags & FWNODE_GRAPH_DEVICE_DISABLED;

I would call this "enabled_only" and reverse its meaning.

Makes sense, that makes the code below easier to follow.

Quoted 17 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1022

Quoted 12 lines
drivers/base/property.c +11 -0
+
+       while ((ep = fwnode_graph_get_next_endpoint(fwnode, ep))) {
+               struct fwnode_endpoint fwnode_ep = { 0 };
+               int ret;
+
+               /*
+                * Check the device is available unless we're explicitly told
+                * not to.
+                */
+               if (!disabled) {
+                       struct fwnode_handle *dev;

s/dev/dev_node/

bool available;

Quoted 7 lines

Review

Quoted 2 lines
(quoted diff) +2 -0
+
+                       dev = fwnode_graph_get_remote_port_parent(ep);

available = fwnode_device_is_available(dev_node);
fwnode_handle_put(dev_node);
if (!available)

        continue;

Yes, makes sense.

Quoted 17 lines
Quoted 17 lines
drivers/base/property.c +16 -0
+
+                       if (!fwnode_device_is_available(dev)) {
+                               fwnode_handle_put(dev);
+                               continue;
+                       }
+
+                       fwnode_handle_put(dev);
+               }
+
+               ret = fwnode_graph_parse_endpoint(ep, &fwnode_ep);
+               if (ret < 0)
+                       continue;
+
+               /* Check we have the right port. */
+               if (fwnode_ep.port != port)
+                       continue;
Quoted 8 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1044

Quoted 4 lines
drivers/base/property.c +4 -0
+
+               /* Is this an exact match? If so, return it immediately. */
+               if (fwnode_ep.id == endpoint)
+                       return ep;

This appears to mean that the endpoint has been reference-counted, but then the reference should be dropped before the "continue" above, shouldn't it?

Quoted 2 lines

This is handled by fwnode_graph_get_next_endpoint() which puts the previous endpoint on every iteration.

OK

Quoted 6 lines
Quoted 6 lines
Quoted 5 lines
drivers/base/property.c +4 -0
+
+               /* Is an exact match needed? If so, skip this one. */
+               if (!endpoint_next)
+                       continue;
Quoted 7 lines
Quoted 4 lines

And here?

Besides, the three comments above are redundant IMO (they don't explain anything, but just repeat what the code does).

Well, true; I thought they might be useful to understand what the function does. I have no problem removing them.

Yes, please drop them.

Quoted 13 lines
Quoted 9 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1052

Quoted 5 lines
drivers/base/property.c +4 -0
+
+               /*
+                * Is this endpoint better than we already had?
+                */

I would say in this comment "If the endpoint that has just been found is not the first matching one and the ID of the one found previously is closer to the requested endpoint ID, skip it."

Yes.

Quoted 1 line
Quoted 6 lines
Quoted 4 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1054

Quoted 2 lines
drivers/base/property.c +2 -0
+               if (fwnode_ep.id < endpoint ||
+                   (best_ep && best_ep_id < fwnode_ep.id))

Drop the fwnode_ep reference?

fwnode_graph_parse_endpoint() takes no reference.

OK

Quoted 10 lines
Quoted 6 lines

drivers/base/property.c fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port_id, · line 1057

Quoted 4 lines
drivers/base/property.c +3 -0
+                       continue;
+
+               /* Replace the one we had with the newly found one. */

Redundant comment.

Removed.

Quoted 1 line
Quoted 6 lines
Quoted 3 lines
Quoted 1 line

+ fwnode_handle_put(best_ep);

Does this always work if best_ep is NULL?

Yes, the fwnode API functions (mostly?) are safe to call with NULL fwnode; at least this one is.

OK

Quoted 30 lines
Quoted 21 lines
Quoted 21 lines
drivers/base/property.c +9 -0
+               best_ep = fwnode_handle_get(ep);
+               best_ep_id = fwnode_ep.id;
+       }
+
+       return best_ep;
+}
+EXPORT_SYMBOL_GPL(fwnode_graph_get_endpoint_by_id);
+
+/**
  * fwnode_graph_parse_endpoint - parse common endpoint node properties
  * @fwnode: pointer to endpoint fwnode_handle
  * @endpoint: pointer to the fwnode endpoint data structure
include/linux/property.h +0 -0
index 3789ec755fb6..f3d924092890 100644
@@ -304,6 +304,25 @@ struct fwnode_handle *
 fwnode_graph_get_remote_node(const struct fwnode_handle *fwnode, u32 port,
                             u32 endpoint);
 
Quoted 8 lines

include/linux/property.h struct fwnode_handle * · line 311

Quoted 5 lines
include/linux/property.h +5 -0
+/**
+ * enum fwnode_graph_get_endpoint_flags - Flags for finding an endpoint
+ *
+ * @FWNODE_GRAPH_ENDPOINT_NEXT: if no specified endpoint is found, obtain the
+ *                             smallest endpoint number greater than specified

"In the no exact match case, look for the closest endpoint ID greater than the specified one."

Quoted 1 line

How about: "In the case of no exact match, ..."?

Sure.

Quoted 13 lines
Quoted 4 lines

include/linux/property.h struct fwnode_handle * · line 312

Quoted 2 lines
include/linux/property.h +1 -0
+ * @FWNODE_GRAPH_DEVICE_DISABLED that the device to which the remote

Missing colon.

Fixed.

Quoted 6 lines

include/linux/property.h struct fwnode_handle * · line 314

Quoted 3 lines
include/linux/property.h +2 -0
+ *                              endpoint of the given endpoint belongs to,
+ *                              may be disabled

"Also return endpoints that belong to disabled devices."

Quoted 7 lines
Quoted 5 lines

include/linux/property.h struct fwnode_handle * · line 317

Quoted 3 lines
include/linux/property.h +3 -0
+ */
+enum fwnode_graph_get_endpoint_flags {
+       FWNODE_GRAPH_ENDPOINT_NEXT      = 0x00000001,

BIT(1) ?

BIT(0), BIT(1) below.

Right, sorry.