Skip to contentSkip to conversation

V4L2 fwnode fixes, improvements and cleanups

PATCH Superseded Sakari Ailus 3 participants 20 messages Sep 30, 2020 – Oct 5, 2020

Subsystems (3)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

Sakari Ailus

author maintainer
#0 lore raw

cover V4L2 fwnode fixes, improvements and cleanups

Hi all,

This small set improves V4L2 fwnode framework in small but in an important ways. In particular:

- Default parameters are no longer zeroed for V4L2_MBUS_UNKNOWN --- this makes defaults for multiple bus types actually working, so it's a bugfix

- Don't tell to use v4l2_fwnode_endpoint_alloc_parse in all drivers; v4l2_fwnode_endpoint_parse is just as good if the device doesn't need link-frequencies.

- Rewrite v4l2_fwnode_endpoint(_alloc)_parse documentation

Laurent: I believe this addresses your request to parse multiple bus types with a single call to v4l2_fwnode_endpoint_(alloc_)parse --- please see the 4th patch. You don't really need to tell the default, but the caller will need to check the result is one of the known types. But as the caller very probably needs to do some work based on the bus type right afterwards this is hardly an actual burden for drivers.

Sakari Ailus (5):
adv748x: Zero entire struct v4l2_fwnode_endpoint
v4l2-fwnode: v4l2_fwnode_endpoint_parse caller must init vep argument
v4l2-fwnode: Don't zero parts of struct v4l2_fwnode_endpoint anymore
v4l2-fwnode: Rework v4l2_fwnode_endpoint_parse documentation
v4l2-fwnode: Say it's fine to use v4l2_fwnode_endpoint_parse

 drivers/media/i2c/adv748x/adv748x-core.c |  3 +-
 drivers/media/v4l2-core/v4l2-fwnode.c    | 12 ----
 include/media/v4l2-fwnode.h              | 70 ++++++++++++++++--------
 3 files changed, 47 insertions(+), 38 deletions(-)
Signature · 1 line
2.27.0
author maintainer
#1 lore raw

PATCH 1/5 adv748x: Zero entire struct v4l2_fwnode_endpoint

The v4l2_fwnode_parse_endpoint() function can make use of defaults in multiple bus types. To use this feature, all callers must zero the rest of the fields of this struct, too. All other drivers appear to do that already apart from this one.

---
 drivers/media/i2c/adv748x/adv748x-core.c | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
drivers/media/i2c/adv748x/adv748x-core.c +1 -2
index 1fe7f97c6d52..ae8b7ebf3830 100644
@@ -589,14 +589,13 @@ static int adv748x_parse_csi2_lanes(struct adv748x_state *state,
 				    unsigned int port,
 				    struct device_node *ep)
 {
-	struct v4l2_fwnode_endpoint vep;
+	struct v4l2_fwnode_endpoint vep = { .bus_type = V4L2_MBUS_CSI2_DPHY };
 	unsigned int num_lanes;
 	int ret;
 
 	if (port != ADV748X_PORT_TXA && port != ADV748X_PORT_TXB)
 		return 0;
 
-	vep.bus_type = V4L2_MBUS_CSI2_DPHY;
 	ret = v4l2_fwnode_endpoint_parse(of_fwnode_handle(ep), &vep);
 	if (ret)
 		return ret;
Signature · 1 line
2.27.0
Reviewed-by on v1 1/5
#2 lore raw

Re: [PATCH 1/5] adv748x: Zero entire struct v4l2_fwnode_endpoint

Hi Sakari,

Thanks for your patch.

Quoted 6 lines · Sakari Ailus

The v4l2_fwnode_parse_endpoint() function can make use of defaults in multiple bus types. To use this feature, all callers must zero the rest of the fields of this struct, too. All other drivers appear to do that already apart from this one.

Quoted 28 lines
---
 drivers/media/i2c/adv748x/adv748x-core.c | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
drivers/media/i2c/adv748x/adv748x-core.c +1 -2
index 1fe7f97c6d52..ae8b7ebf3830 100644
@@ -589,14 +589,13 @@ static int adv748x_parse_csi2_lanes(struct adv748x_state *state,
 				    unsigned int port,
 				    struct device_node *ep)
 {
-	struct v4l2_fwnode_endpoint vep;
+	struct v4l2_fwnode_endpoint vep = { .bus_type = V4L2_MBUS_CSI2_DPHY };
 	unsigned int num_lanes;
 	int ret;
 
 	if (port != ADV748X_PORT_TXA && port != ADV748X_PORT_TXB)
 		return 0;
 
-	vep.bus_type = V4L2_MBUS_CSI2_DPHY;
 	ret = v4l2_fwnode_endpoint_parse(of_fwnode_handle(ep), &vep);
 	if (ret)
 		return ret;
Signature · 1 line
2.27.0
Signature · 2 lines
Regards,
Niklas Söderlund
Reviewed-by on v1 1/5
#3 lore raw

Re: [PATCH 1/5] adv748x: Zero entire struct v4l2_fwnode_endpoint

In reply to Sakari Ailus

Hi Sakari,

Thank you for the patch.

Quoted 6 lines · Sakari Ailus

The v4l2_fwnode_parse_endpoint() function can make use of defaults in multiple bus types. To use this feature, all callers must zero the rest of the fields of this struct, too. All other drivers appear to do that already apart from this one.

Quoted 24 lines
---
 drivers/media/i2c/adv748x/adv748x-core.c | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
drivers/media/i2c/adv748x/adv748x-core.c +1 -2
index 1fe7f97c6d52..ae8b7ebf3830 100644
@@ -589,14 +589,13 @@ static int adv748x_parse_csi2_lanes(struct adv748x_state *state,
 				    unsigned int port,
 				    struct device_node *ep)
 {
-	struct v4l2_fwnode_endpoint vep;
+	struct v4l2_fwnode_endpoint vep = { .bus_type = V4L2_MBUS_CSI2_DPHY };
 	unsigned int num_lanes;
 	int ret;
 
 	if (port != ADV748X_PORT_TXA && port != ADV748X_PORT_TXB)
 		return 0;
 
-	vep.bus_type = V4L2_MBUS_CSI2_DPHY;
 	ret = v4l2_fwnode_endpoint_parse(of_fwnode_handle(ep), &vep);
 	if (ret)
 		return ret;
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#4 lore raw

PATCH 2/5 v4l2-fwnode: v4l2_fwnode_endpoint_parse caller must init vep argument

In reply to Sakari Ailus

Document that the caller of v4l2_fwnode_endpoint_parse() must init the fields of struct v4l2_fwnode_endpoint (vep argument) fields.

It used to be that the fields were zeroed by v4l2_fwnode_endpoint_parse when bus type was set to V4L2_MBUS_UNKNOWN but with commit bb4bba9232fc that no longer makes sense.

Fixes bb4bba9232fc ("media: v4l2-fwnode: Make bus configuration a struct")
---
 include/media/v4l2-fwnode.h | 4 ++++
 1 file changed, 4 insertions(+)
include/media/v4l2-fwnode.h +4 -0
index c09074276543..0f9a768b1a8d 100644
@@ -231,6 +231,8 @@ struct v4l2_fwnode_connector {
  * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
  * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
  *
+ * The caller is required to initialise all fields of @vep.
+ *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
  * NOTE: This function does not parse properties the size of which is variable
@@ -273,6 +275,8 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep);
  * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
  * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
  *
+ * The caller is required to initialise all fields of @vep.
+ *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
  * v4l2_fwnode_endpoint_alloc_parse() has two important differences to
Signature · 1 line
2.27.0
Reviewed-by on v1 2/5
#5 lore raw

Re: [PATCH 2/5] v4l2-fwnode: v4l2_fwnode_endpoint_parse caller must init vep argument

Hi Sakari,

Thanks for your work.

Quoted 9 lines · Sakari Ailus

Document that the caller of v4l2_fwnode_endpoint_parse() must init the fields of struct v4l2_fwnode_endpoint (vep argument) fields.

It used to be that the fields were zeroed by v4l2_fwnode_endpoint_parse when bus type was set to V4L2_MBUS_UNKNOWN but with commit bb4bba9232fc that no longer makes sense.

Fixes bb4bba9232fc ("media: v4l2-fwnode: Make bus configuration a struct")
Quoted 30 lines
---
 include/media/v4l2-fwnode.h | 4 ++++
 1 file changed, 4 insertions(+)
include/media/v4l2-fwnode.h +4 -0
index c09074276543..0f9a768b1a8d 100644
@@ -231,6 +231,8 @@ struct v4l2_fwnode_connector {
  * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
  * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
  *
+ * The caller is required to initialise all fields of @vep.
+ *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
  * NOTE: This function does not parse properties the size of which is variable
@@ -273,6 +275,8 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep);
  * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
  * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
  *
+ * The caller is required to initialise all fields of @vep.
+ *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
  * v4l2_fwnode_endpoint_alloc_parse() has two important differences to
Signature · 1 line
2.27.0
Signature · 2 lines
Regards,
Niklas Söderlund
author maintainer
#6 lore raw

Re: [PATCH 2/5] v4l2-fwnode: v4l2_fwnode_endpoint_parse caller must init vep argument

Quoted 8 lines · Niklas Söderlund

Hi Sakari,

Thanks for your work.

Quoted 3 lines · Sakari Ailus

Document that the caller of v4l2_fwnode_endpoint_parse() must init the fields of struct v4l2_fwnode_endpoint (vep argument) fields.

Quoted 8 lines
Quoted 6 lines

It used to be that the fields were zeroed by v4l2_fwnode_endpoint_parse when bus type was set to V4L2_MBUS_UNKNOWN but with commit bb4bba9232fc that no longer makes sense.

Fixes bb4bba9232fc ("media: v4l2-fwnode: Make bus configuration a struct")

Thanks for the review!

Signature · 1 line
Sakari Ailus
Reviewed-by on v1 2/5
#7 lore raw

Re: [PATCH 2/5] v4l2-fwnode: v4l2_fwnode_endpoint_parse caller must init vep argument

In reply to Sakari Ailus

Hi Sakari,

Thank you for the patch.

Quoted 18 lines · Sakari Ailus

Document that the caller of v4l2_fwnode_endpoint_parse() must init the fields of struct v4l2_fwnode_endpoint (vep argument) fields.

It used to be that the fields were zeroed by v4l2_fwnode_endpoint_parse when bus type was set to V4L2_MBUS_UNKNOWN but with commit bb4bba9232fc that no longer makes sense.

Fixes bb4bba9232fc ("media: v4l2-fwnode: Make bus configuration a struct")
---
 include/media/v4l2-fwnode.h | 4 ++++
 1 file changed, 4 insertions(+)
include/media/v4l2-fwnode.h +0 -0
index c09074276543..0f9a768b1a8d 100644

include/media/v4l2-fwnode.h struct v4l2_fwnode_connector { · line 234

Quoted 4 lines
include/media/v4l2-fwnode.h +1 -0
@@ -231,6 +231,8 @@ struct v4l2_fwnode_connector {
  * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
  * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
  *
+ * The caller is required to initialise all fields of @vep.

Would it make sense to explicitly state that fields should be zeroed if no specific value is desired ? Maybe

* The caller is required to initialise all fields of @vep, either with
* explicitly values, or by zeroing them.

Apart from that,

Quoted 13 lines
include/media/v4l2-fwnode.h +3 -0
+ *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
  * NOTE: This function does not parse properties the size of which is variable
@@ -273,6 +275,8 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep);
  * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
  * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
  *
+ * The caller is required to initialise all fields of @vep.
+ *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
  * v4l2_fwnode_endpoint_alloc_parse() has two important differences to
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#8 lore raw

PATCH 3/5 v4l2-fwnode: Don't zero parts of struct v4l2_fwnode_endpoint anymore

In reply to Sakari Ailus

Don't zero parts of the vep argument to v4l2_fwnode_endpoint_parse() anymore as this can no longer be done while still supporting defaults on multiple bus types.

---
 drivers/media/v4l2-core/v4l2-fwnode.c | 12 ------------
 1 file changed, 12 deletions(-)
drivers/media/v4l2-core/v4l2-fwnode.c +0 -12
index dfc53d11053f..44dd04b05e29 100644
@@ -416,20 +416,8 @@ static int __v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode,
 	enum v4l2_mbus_type mbus_type;
 	int rval;
 
-	if (vep->bus_type == V4L2_MBUS_UNKNOWN) {
-		/* Zero fields from bus union to until the end */
-		memset(&vep->bus, 0,
-		       sizeof(*vep) - offsetof(typeof(*vep), bus));
-	}
-
 	pr_debug("===== begin parsing endpoint %pfw\n", fwnode);
 
-	/*
-	 * Zero the fwnode graph endpoint memory in case we don't end up parsing
-	 * the endpoint.
-	 */
-	memset(&vep->base, 0, sizeof(vep->base));
-
 	fwnode_property_read_u32(fwnode, "bus-type", &bus_type);
 	pr_debug("fwnode video bus type %s (%u), mbus type %s (%u)\n",
 		 v4l2_fwnode_bus_type_to_string(bus_type), bus_type,
Signature · 1 line
2.27.0
Reviewed-by on v1 3/5
#9 lore raw

Re: [PATCH 3/5] v4l2-fwnode: Don't zero parts of struct v4l2_fwnode_endpoint anymore

Hi Sakari,

Thanks for your work.

Quoted 5 lines · Sakari Ailus

Don't zero parts of the vep argument to v4l2_fwnode_endpoint_parse() anymore as this can no longer be done while still supporting defaults on multiple bus types.

Quoted 33 lines
---
 drivers/media/v4l2-core/v4l2-fwnode.c | 12 ------------
 1 file changed, 12 deletions(-)
drivers/media/v4l2-core/v4l2-fwnode.c +0 -12
index dfc53d11053f..44dd04b05e29 100644
@@ -416,20 +416,8 @@ static int __v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode,
 	enum v4l2_mbus_type mbus_type;
 	int rval;
 
-	if (vep->bus_type == V4L2_MBUS_UNKNOWN) {
-		/* Zero fields from bus union to until the end */
-		memset(&vep->bus, 0,
-		       sizeof(*vep) - offsetof(typeof(*vep), bus));
-	}
-
 	pr_debug("===== begin parsing endpoint %pfw\n", fwnode);
 
-	/*
-	 * Zero the fwnode graph endpoint memory in case we don't end up parsing
-	 * the endpoint.
-	 */
-	memset(&vep->base, 0, sizeof(vep->base));
-
 	fwnode_property_read_u32(fwnode, "bus-type", &bus_type);
 	pr_debug("fwnode video bus type %s (%u), mbus type %s (%u)\n",
 		 v4l2_fwnode_bus_type_to_string(bus_type), bus_type,
Signature · 1 line
2.27.0
Signature · 2 lines
Regards,
Niklas Söderlund
Reviewed-by on v1 3/5
#10 lore raw

Re: [PATCH 3/5] v4l2-fwnode: Don't zero parts of struct v4l2_fwnode_endpoint anymore

In reply to Sakari Ailus

Hi Sakari,

Thank you for the patch.

Quoted 5 lines · Sakari Ailus

Don't zero parts of the vep argument to v4l2_fwnode_endpoint_parse() anymore as this can no longer be done while still supporting defaults on multiple bus types.

Quoted 29 lines
---
 drivers/media/v4l2-core/v4l2-fwnode.c | 12 ------------
 1 file changed, 12 deletions(-)
drivers/media/v4l2-core/v4l2-fwnode.c +0 -12
index dfc53d11053f..44dd04b05e29 100644
@@ -416,20 +416,8 @@ static int __v4l2_fwnode_endpoint_parse(struct fwnode_handle *fwnode,
 	enum v4l2_mbus_type mbus_type;
 	int rval;
 
-	if (vep->bus_type == V4L2_MBUS_UNKNOWN) {
-		/* Zero fields from bus union to until the end */
-		memset(&vep->bus, 0,
-		       sizeof(*vep) - offsetof(typeof(*vep), bus));
-	}
-
 	pr_debug("===== begin parsing endpoint %pfw\n", fwnode);
 
-	/*
-	 * Zero the fwnode graph endpoint memory in case we don't end up parsing
-	 * the endpoint.
-	 */
-	memset(&vep->base, 0, sizeof(vep->base));
-
 	fwnode_property_read_u32(fwnode, "bus-type", &bus_type);
 	pr_debug("fwnode video bus type %s (%u), mbus type %s (%u)\n",
 		 v4l2_fwnode_bus_type_to_string(bus_type), bus_type,
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#11 lore raw

PATCH 4/5 v4l2-fwnode: Rework v4l2_fwnode_endpoint_parse documentation

In reply to Sakari Ailus

Rework the documentation of v4l2_fwnode_endpoint_parse for better readability, usefulness and correctness.

---
 include/media/v4l2-fwnode.h | 62 ++++++++++++++++++++++++-------------
 1 file changed, 40 insertions(+), 22 deletions(-)
include/media/v4l2-fwnode.h +40 -22
index 0f9a768b1a8d..0c28dc11e829 100644
@@ -219,17 +219,26 @@ struct v4l2_fwnode_connector {
  * @vep: pointer to the V4L2 fwnode data structure
  *
  * This function parses the V4L2 fwnode endpoint specific parameters from the
- * firmware. The caller is responsible for assigning @vep.bus_type to a valid
- * media bus type. The caller may also set the default configuration for the
- * endpoint --- a configuration that shall be in line with the DT binding
- * documentation. Should a device support multiple bus types, the caller may
- * call this function once the correct type is found --- with a default
- * configuration valid for that type.
- *
- * It is also allowed to set @vep.bus_type to V4L2_MBUS_UNKNOWN. USING THIS
- * FEATURE REQUIRES "bus-type" PROPERTY IN DT BINDINGS. For old drivers,
- * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
- * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
+ * firmware. There are two ways to use this function, either by letting it
+ * obtain the type of the bus (by setting the @vep.bus_type field to
+ * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum
+ * v4l2_mbus_type types.
+ *
+ * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type"
+ * property to determine the type when it is available. The caller is
+ * responsible for validating the contents of @vep.bus_type field after the call
+ * returns.
+ *
+ * As a deprecated functionality to support older DT bindings without "bus-type"
+ * property for devices that support multiple types, if the "bus-type" property
+ * does not exist, the function will attempt to guess the type based on the
+ * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW
+ * DRIVERS OR BINDINGS.
+ *
+ * It is also possible to set @vep.bus_type corresponding to an actual bus. In
+ * this case the function will only attempt to parse properties related to this
+ * bus, and it will return an error if the value of the "bus-type" property
+ * corresponds to a different bus.
  *
  * The caller is required to initialise all fields of @vep.
  *
@@ -263,17 +272,26 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep);
  * @vep: pointer to the V4L2 fwnode data structure
  *
  * This function parses the V4L2 fwnode endpoint specific parameters from the
- * firmware. The caller is responsible for assigning @vep.bus_type to a valid
- * media bus type. The caller may also set the default configuration for the
- * endpoint --- a configuration that shall be in line with the DT binding
- * documentation. Should a device support multiple bus types, the caller may
- * call this function once the correct type is found --- with a default
- * configuration valid for that type.
- *
- * It is also allowed to set @vep.bus_type to V4L2_MBUS_UNKNOWN. USING THIS
- * FEATURE REQUIRES "bus-type" PROPERTY IN DT BINDINGS. For old drivers,
- * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
- * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
+ * firmware. There are two ways to use this function, either by letting it
+ * obtain the type of the bus (by setting the @vep.bus_type field to
+ * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum
+ * v4l2_mbus_type types.
+ *
+ * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type"
+ * property to determine the type when it is available. The caller is
+ * responsible for validating the contents of @vep.bus_type field after the call
+ * returns.
+ *
+ * As a deprecated functionality to support older DT bindings without "bus-type"
+ * property for devices that support multiple types, if the "bus-type" property
+ * does not exist, the function will attempt to guess the type based on the
+ * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW
+ * DRIVERS OR BINDINGS.
+ *
+ * It is also possible to set @vep.bus_type corresponding to an actual bus. In
+ * this case the function will only attempt to parse properties related to this
+ * bus, and it will return an error if the value of the "bus-type" property
+ * corresponds to a different bus.
  *
  * The caller is required to initialise all fields of @vep.
  *
Signature · 1 line
2.27.0
Reviewed-by on v1 4/5
#12 lore raw

Re: [PATCH 4/5] v4l2-fwnode: Rework v4l2_fwnode_endpoint_parse documentation

Hi Sakari,

Thanks for your patch.

Quoted 4 lines · Sakari Ailus

Rework the documentation of v4l2_fwnode_endpoint_parse for better readability, usefulness and correctness.

Quoted 88 lines
---
 include/media/v4l2-fwnode.h | 62 ++++++++++++++++++++++++-------------
 1 file changed, 40 insertions(+), 22 deletions(-)
include/media/v4l2-fwnode.h +40 -22
index 0f9a768b1a8d..0c28dc11e829 100644
@@ -219,17 +219,26 @@ struct v4l2_fwnode_connector {
  * @vep: pointer to the V4L2 fwnode data structure
  *
  * This function parses the V4L2 fwnode endpoint specific parameters from the
- * firmware. The caller is responsible for assigning @vep.bus_type to a valid
- * media bus type. The caller may also set the default configuration for the
- * endpoint --- a configuration that shall be in line with the DT binding
- * documentation. Should a device support multiple bus types, the caller may
- * call this function once the correct type is found --- with a default
- * configuration valid for that type.
- *
- * It is also allowed to set @vep.bus_type to V4L2_MBUS_UNKNOWN. USING THIS
- * FEATURE REQUIRES "bus-type" PROPERTY IN DT BINDINGS. For old drivers,
- * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
- * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
+ * firmware. There are two ways to use this function, either by letting it
+ * obtain the type of the bus (by setting the @vep.bus_type field to
+ * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum
+ * v4l2_mbus_type types.
+ *
+ * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type"
+ * property to determine the type when it is available. The caller is
+ * responsible for validating the contents of @vep.bus_type field after the call
+ * returns.
+ *
+ * As a deprecated functionality to support older DT bindings without "bus-type"
+ * property for devices that support multiple types, if the "bus-type" property
+ * does not exist, the function will attempt to guess the type based on the
+ * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW
+ * DRIVERS OR BINDINGS.
+ *
+ * It is also possible to set @vep.bus_type corresponding to an actual bus. In
+ * this case the function will only attempt to parse properties related to this
+ * bus, and it will return an error if the value of the "bus-type" property
+ * corresponds to a different bus.
  *
  * The caller is required to initialise all fields of @vep.
  *
@@ -263,17 +272,26 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep);
  * @vep: pointer to the V4L2 fwnode data structure
  *
  * This function parses the V4L2 fwnode endpoint specific parameters from the
- * firmware. The caller is responsible for assigning @vep.bus_type to a valid
- * media bus type. The caller may also set the default configuration for the
- * endpoint --- a configuration that shall be in line with the DT binding
- * documentation. Should a device support multiple bus types, the caller may
- * call this function once the correct type is found --- with a default
- * configuration valid for that type.
- *
- * It is also allowed to set @vep.bus_type to V4L2_MBUS_UNKNOWN. USING THIS
- * FEATURE REQUIRES "bus-type" PROPERTY IN DT BINDINGS. For old drivers,
- * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
- * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
+ * firmware. There are two ways to use this function, either by letting it
+ * obtain the type of the bus (by setting the @vep.bus_type field to
+ * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum
+ * v4l2_mbus_type types.
+ *
+ * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type"
+ * property to determine the type when it is available. The caller is
+ * responsible for validating the contents of @vep.bus_type field after the call
+ * returns.
+ *
+ * As a deprecated functionality to support older DT bindings without "bus-type"
+ * property for devices that support multiple types, if the "bus-type" property
+ * does not exist, the function will attempt to guess the type based on the
+ * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW
+ * DRIVERS OR BINDINGS.
+ *
+ * It is also possible to set @vep.bus_type corresponding to an actual bus. In
+ * this case the function will only attempt to parse properties related to this
+ * bus, and it will return an error if the value of the "bus-type" property
+ * corresponds to a different bus.
  *
  * The caller is required to initialise all fields of @vep.
  *
Signature · 1 line
2.27.0
Signature · 2 lines
Regards,
Niklas Söderlund
Reviewed-by on v1 4/5
#13 lore raw

Re: [PATCH 4/5] v4l2-fwnode: Rework v4l2_fwnode_endpoint_parse documentation

In reply to Sakari Ailus

Hi Sakari,

Thank you for the patch.

Quoted 26 lines · Sakari Ailus

Rework the documentation of v4l2_fwnode_endpoint_parse for better readability, usefulness and correctness.

---
 include/media/v4l2-fwnode.h | 62 ++++++++++++++++++++++++-------------
 1 file changed, 40 insertions(+), 22 deletions(-)
include/media/v4l2-fwnode.h +0 -10
index 0f9a768b1a8d..0c28dc11e829 100644
@@ -219,17 +219,26 @@ struct v4l2_fwnode_connector {
  * @vep: pointer to the V4L2 fwnode data structure
  *
  * This function parses the V4L2 fwnode endpoint specific parameters from the
- * firmware. The caller is responsible for assigning @vep.bus_type to a valid
- * media bus type. The caller may also set the default configuration for the
- * endpoint --- a configuration that shall be in line with the DT binding
- * documentation. Should a device support multiple bus types, the caller may
- * call this function once the correct type is found --- with a default
- * configuration valid for that type.
- *
- * It is also allowed to set @vep.bus_type to V4L2_MBUS_UNKNOWN. USING THIS
- * FEATURE REQUIRES "bus-type" PROPERTY IN DT BINDINGS. For old drivers,
- * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is

include/media/v4l2-fwnode.h struct v4l2_fwnode_connector { · line 230

Quoted 10 lines
include/media/v4l2-fwnode.h +9 -1
- * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
+ * firmware. There are two ways to use this function, either by letting it
+ * obtain the type of the bus (by setting the @vep.bus_type field to
+ * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum
+ * v4l2_mbus_type types.
+ *
+ * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type"
+ * property to determine the type when it is available. The caller is
+ * responsible for validating the contents of @vep.bus_type field after the call
+ * returns.

As an additional improvement, I wonder if it would make sense to turn the bus types into a bit flag, to let the caller tell which bus types it supports. Or maybe that would be overkill ?

Quoted 52 lines
include/media/v4l2-fwnode.h +31 -11
+ *
+ * As a deprecated functionality to support older DT bindings without "bus-type"
+ * property for devices that support multiple types, if the "bus-type" property
+ * does not exist, the function will attempt to guess the type based on the
+ * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW
+ * DRIVERS OR BINDINGS.
+ *
+ * It is also possible to set @vep.bus_type corresponding to an actual bus. In
+ * this case the function will only attempt to parse properties related to this
+ * bus, and it will return an error if the value of the "bus-type" property
+ * corresponds to a different bus.
  *
  * The caller is required to initialise all fields of @vep.
  *
@@ -263,17 +272,26 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep);
  * @vep: pointer to the V4L2 fwnode data structure
  *
  * This function parses the V4L2 fwnode endpoint specific parameters from the
- * firmware. The caller is responsible for assigning @vep.bus_type to a valid
- * media bus type. The caller may also set the default configuration for the
- * endpoint --- a configuration that shall be in line with the DT binding
- * documentation. Should a device support multiple bus types, the caller may
- * call this function once the correct type is found --- with a default
- * configuration valid for that type.
- *
- * It is also allowed to set @vep.bus_type to V4L2_MBUS_UNKNOWN. USING THIS
- * FEATURE REQUIRES "bus-type" PROPERTY IN DT BINDINGS. For old drivers,
- * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is
- * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
+ * firmware. There are two ways to use this function, either by letting it
+ * obtain the type of the bus (by setting the @vep.bus_type field to
+ * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum
+ * v4l2_mbus_type types.
+ *
+ * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type"
+ * property to determine the type when it is available. The caller is
+ * responsible for validating the contents of @vep.bus_type field after the call
+ * returns.
+ *
+ * As a deprecated functionality to support older DT bindings without "bus-type"
+ * property for devices that support multiple types, if the "bus-type" property
+ * does not exist, the function will attempt to guess the type based on the
+ * endpoint properties available. NEVER RELY ON GUESSING THE BUS TYPE IN NEW
+ * DRIVERS OR BINDINGS.
+ *
+ * It is also possible to set @vep.bus_type corresponding to an actual bus. In
+ * this case the function will only attempt to parse properties related to this
+ * bus, and it will return an error if the value of the "bus-type" property
+ * corresponds to a different bus.
  *
  * The caller is required to initialise all fields of @vep.
  *
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#14 lore raw

Re: [PATCH 4/5] v4l2-fwnode: Rework v4l2_fwnode_endpoint_parse documentation

Hi Laurent,

Quoted 46 lines · Laurent Pinchart

Hi Sakari,

Thank you for the patch.

Quoted 26 lines · Sakari Ailus

Rework the documentation of v4l2_fwnode_endpoint_parse for better readability, usefulness and correctness.

---
 include/media/v4l2-fwnode.h | 62 ++++++++++++++++++++++++-------------
 1 file changed, 40 insertions(+), 22 deletions(-)
include/media/v4l2-fwnode.h +0 -10
index 0f9a768b1a8d..0c28dc11e829 100644
@@ -219,17 +219,26 @@ struct v4l2_fwnode_connector {
  * @vep: pointer to the V4L2 fwnode data structure
  *
  * This function parses the V4L2 fwnode endpoint specific parameters from the
- * firmware. The caller is responsible for assigning @vep.bus_type to a valid
- * media bus type. The caller may also set the default configuration for the
- * endpoint --- a configuration that shall be in line with the DT binding
- * documentation. Should a device support multiple bus types, the caller may
- * call this function once the correct type is found --- with a default
- * configuration valid for that type.
- *
- * It is also allowed to set @vep.bus_type to V4L2_MBUS_UNKNOWN. USING THIS
- * FEATURE REQUIRES "bus-type" PROPERTY IN DT BINDINGS. For old drivers,
- * guessing @vep.bus_type between CSI-2 D-PHY, parallel and BT.656 busses is

include/media/v4l2-fwnode.h struct v4l2_fwnode_connector { · line 230

Quoted 10 lines
include/media/v4l2-fwnode.h +9 -1
- * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!
+ * firmware. There are two ways to use this function, either by letting it
+ * obtain the type of the bus (by setting the @vep.bus_type field to
+ * V4L2_MBUS_UNKNOWN) or specifying the bus type explicitly to one of the &enum
+ * v4l2_mbus_type types.
+ *
+ * When @vep.bus_type is V4L2_MBUS_UNKNOWN, the function will use the "bus-type"
+ * property to determine the type when it is available. The caller is
+ * responsible for validating the contents of @vep.bus_type field after the call
+ * returns.

As an additional improvement, I wonder if it would make sense to turn the bus types into a bit flag, to let the caller tell which bus types it supports. Or maybe that would be overkill ?

Quoted 1 line

Thanks for the review!

I wonder how useful that would be as drivers typically do bus type specific checks right after this function returns. Although I wouldn't object a patch doing that if it's seen useful somewhere.

Signature · 1 line
Sakari Ailus
author maintainer
#15 lore raw

PATCH 5/5 v4l2-fwnode: Say it's fine to use v4l2_fwnode_endpoint_parse

In reply to Sakari Ailus

Earlier it was expected that there would be more variable size endpoint properties and that most if not all drivers would need them. For that reason it was expected also that v4l2_fwnode_endpoint_parse would no longer be needed.

What actually happened that not all drivers require "link-frequencies", the only variable size media endpoint property without a small upper limit. Therefore drivers that do not need that information are fine using v4l2_fwnode_endpoint_parse. So don't tell drivers to use v4l2_fwnode_endpoint_alloc_parse in all cases.

---
 include/media/v4l2-fwnode.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/media/v4l2-fwnode.h +2 -2
index 0c28dc11e829..cbd872e59f8e 100644
@@ -245,8 +245,8 @@ struct v4l2_fwnode_connector {
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
  * NOTE: This function does not parse properties the size of which is variable
- * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() in
- * new drivers instead.
+ * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() if
+ * you need properties of variable size.
  *
  * Return: %0 on success or a negative error code on failure:
  *	   %-ENOMEM on memory allocation failure
Signature · 1 line
2.27.0
Reviewed-by on v1 5/5
#16 lore raw

Re: [PATCH 5/5] v4l2-fwnode: Say it's fine to use v4l2_fwnode_endpoint_parse

Hi Sakari,

Thanks for your work.

Quoted 5 lines · Sakari Ailus

Earlier it was expected that there would be more variable size endpoint properties and that most if not all drivers would need them. For that reason it was expected also that v4l2_fwnode_endpoint_parse would no longer be needed.

Quoted 7 lines

What actually happened that not all drivers require "link-frequencies", the only variable size media endpoint property without a small upper limit. Therefore drivers that do not need that information are fine using v4l2_fwnode_endpoint_parse. So don't tell drivers to use v4l2_fwnode_endpoint_alloc_parse in all cases.

Quoted 23 lines
---
 include/media/v4l2-fwnode.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/media/v4l2-fwnode.h +2 -2
index 0c28dc11e829..cbd872e59f8e 100644
@@ -245,8 +245,8 @@ struct v4l2_fwnode_connector {
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
  * NOTE: This function does not parse properties the size of which is variable
- * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() in
- * new drivers instead.
+ * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() if
+ * you need properties of variable size.
  *
  * Return: %0 on success or a negative error code on failure:
  *	   %-ENOMEM on memory allocation failure
Signature · 1 line
2.27.0
Signature · 2 lines
Regards,
Niklas Söderlund
#17 lore raw

Re: [PATCH 5/5] v4l2-fwnode: Say it's fine to use v4l2_fwnode_endpoint_parse

In reply to Sakari Ailus

Hi Sakari,

Thank you for the patch.

Quoted 21 lines · Sakari Ailus

Earlier it was expected that there would be more variable size endpoint properties and that most if not all drivers would need them. For that reason it was expected also that v4l2_fwnode_endpoint_parse would no longer be needed.

What actually happened that not all drivers require "link-frequencies", the only variable size media endpoint property without a small upper limit. Therefore drivers that do not need that information are fine using v4l2_fwnode_endpoint_parse. So don't tell drivers to use v4l2_fwnode_endpoint_alloc_parse in all cases.

---
 include/media/v4l2-fwnode.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/media/v4l2-fwnode.h +0 -0
index 0c28dc11e829..cbd872e59f8e 100644

include/media/v4l2-fwnode.h struct v4l2_fwnode_connector { · line 249

Quoted 7 lines
include/media/v4l2-fwnode.h +2 -2
@@ -245,8 +245,8 @@ struct v4l2_fwnode_connector {
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
  * NOTE: This function does not parse properties the size of which is variable
- * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() in
- * new drivers instead.
+ * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() if
+ * you need properties of variable size.

Shouldn't we explicitly mention link-frequencies ? "properties the size of which is variable without a low fixed limit" is not very clear for a casual reader.

Quoted 3 lines
include/media/v4l2-fwnode.h +0 -0
  *
  * Return: %0 on success or a negative error code on failure:
  *	   %-ENOMEM on memory allocation failure
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#18 lore raw

Re: [PATCH 5/5] v4l2-fwnode: Say it's fine to use v4l2_fwnode_endpoint_parse

Quoted 21 lines · Laurent Pinchart

Hi Sakari,

Thank you for the patch.

Quoted 16 lines · Sakari Ailus

Earlier it was expected that there would be more variable size endpoint properties and that most if not all drivers would need them. For that reason it was expected also that v4l2_fwnode_endpoint_parse would no longer be needed.

What actually happened that not all drivers require "link-frequencies", the only variable size media endpoint property without a small upper limit. Therefore drivers that do not need that information are fine using v4l2_fwnode_endpoint_parse. So don't tell drivers to use v4l2_fwnode_endpoint_alloc_parse in all cases.

---
 include/media/v4l2-fwnode.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Quoted 16 lines

include/media/v4l2-fwnode.h struct v4l2_fwnode_connector { · line 249

Quoted 12 lines
include/media/v4l2-fwnode.h +2 -2
index 0c28dc11e829..cbd872e59f8e 100644
@@ -245,8 +245,8 @@ struct v4l2_fwnode_connector {
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
  * NOTE: This function does not parse properties the size of which is variable
- * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() in
- * new drivers instead.
+ * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() if
+ * you need properties of variable size.

Shouldn't we explicitly mention link-frequencies ? "properties the size of which is variable without a low fixed limit" is not very clear for a casual reader.

I can add that, sure.

Signature · 1 line
Sakari Ailus
author maintainer
#19 lore raw

Re: [PATCH 5/5] v4l2-fwnode: Say it's fine to use v4l2_fwnode_endpoint_parse

In reply to Laurent Pinchart
Quoted 21 lines · Laurent Pinchart

Hi Sakari,

Thank you for the patch.

Quoted 16 lines · Sakari Ailus

Earlier it was expected that there would be more variable size endpoint properties and that most if not all drivers would need them. For that reason it was expected also that v4l2_fwnode_endpoint_parse would no longer be needed.

What actually happened that not all drivers require "link-frequencies", the only variable size media endpoint property without a small upper limit. Therefore drivers that do not need that information are fine using v4l2_fwnode_endpoint_parse. So don't tell drivers to use v4l2_fwnode_endpoint_alloc_parse in all cases.

---
 include/media/v4l2-fwnode.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Quoted 16 lines

include/media/v4l2-fwnode.h struct v4l2_fwnode_connector { · line 249

Quoted 12 lines
include/media/v4l2-fwnode.h +2 -2
index 0c28dc11e829..cbd872e59f8e 100644
@@ -245,8 +245,8 @@ struct v4l2_fwnode_connector {
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
  * NOTE: This function does not parse properties the size of which is variable
- * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() in
- * new drivers instead.
+ * without a low fixed limit. Please use v4l2_fwnode_endpoint_alloc_parse() if
+ * you need properties of variable size.

Shouldn't we explicitly mention link-frequencies ? "properties the size of which is variable without a low fixed limit" is not very clear for a casual reader.

I'll use this in v2:

+ * NOTE: This function does not parse "link-frequencies" property as its size is
+ * not known in advance. Please use v4l2_fwnode_endpoint_alloc_parse() if you
+ * need properties of variable size.

Signature · 1 line
Sakari Ailus