device property: Add fwnode_graph_get_endpoint_by_id
Subsystems (2)
Sakari Ailus
reviewerPATCH 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
@@ -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
@@ -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
Rafael J. Wysocki
maintainerQuoted 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 isof_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.Signed-off-by Sakari Ailus <[email protected]>---
since v1:- Remove the
PORT_NEXTflag.- Replace the
ENDPOINT_AVAILABLEflag withDEVICE_DISABLEDflag 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
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
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)); ) --
Rafael J. Wysocki
maintainerQuoted 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 isof_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.Signed-off-by Sakari Ailus <[email protected]>---
since v1:- Remove the
PORT_NEXTflag.- Replace the
ENDPOINT_AVAILABLEflag withDEVICE_DISABLEDflag 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
-0drivers/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_NEXTis 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_DISABLEDis 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_epreference?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_epis 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
-0include/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.
Sakari Ailus
reviewerHi 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_DISABLEDis 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]
Rafael J. Wysocki
maintainerQuoted 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_DISABLEDis 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.
Sakari Ailus
reviewerHi 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 isof_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.Signed-off-by Sakari Ailus <[email protected]>---
since v1:- Remove the
PORT_NEXTflag.- Replace the
ENDPOINT_AVAILABLEflag withDEVICE_DISABLEDflag 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@@ -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_NEXTis 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_DISABLEDis 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_epreference?
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_epis 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@@ -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]
Rafael J. Wysocki
maintainerQuoted 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.
+ *
+ * Usefwnode_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_epreference?
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_epis 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@@ -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.