Skip to contentSkip to conversation

Improve V4L2 fwnode framework usability and documentation

PATCH In review Sakari Ailus 4 participants 10 messages Sep 8, 2020 – Sep 14, 2020

Subsystems (2)
lore
Share & tools
lore

Sakari Ailus

author maintainer
#0 lore raw

cover Improve V4L2 fwnode framework usability and documentation

Hi all,

This set makes it possible to set defaults for multiple bus types on a single call by using a little bit more memory. The documentation is also improved to allow getting the bus type from DT when bindings allow that.

Sakari Ailus (3):
v4l2-fwnode: Make number of data lanes a character
v4l2-fwnode: Make bus configuration a struct
v4l2-fwnode: Document changes usage patterns of
v4l2_fwnode_endpoint_parse

 include/media/v4l2-fwnode.h | 24 +++++++++++-------------
 1 file changed, 11 insertions(+), 13 deletions(-)
Signature · 1 line
2.27.0
author maintainer
#1 lore raw

PATCH 1/3 v4l2-fwnode: Make number of data lanes a character

The maximum is currently four (4). No short is needed.

---
 include/media/v4l2-fwnode.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/media/v4l2-fwnode.h +1 -1
index c47b70636e42..81e7eb123294 100644
@@ -40,7 +40,7 @@ struct v4l2_fwnode_bus_mipi_csi2 {
 	unsigned int flags;
 	unsigned char data_lanes[V4L2_FWNODE_CSI2_MAX_DATA_LANES];
 	unsigned char clock_lane;
-	unsigned short num_data_lanes;
+	unsigned char num_data_lanes;
 	bool lane_polarities[1 + V4L2_FWNODE_CSI2_MAX_DATA_LANES];
 };
 
Signature · 1 line
2.27.0
Reviewed-by on v1 1/3
#2 lore raw

Re: [PATCH 1/3] v4l2-fwnode: Make number of data lanes a character

Hi Sakari,

Thank you for the patch.

Quoted 12 lines · Sakari Ailus

The maximum is currently four (4). No short is needed.

---
 include/media/v4l2-fwnode.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/media/v4l2-fwnode.h +0 -0
index c47b70636e42..81e7eb123294 100644

include/media/v4l2-fwnode.h struct v4l2_fwnode_bus_mipi_csi2 { · line 44

Quoted 6 lines
include/media/v4l2-fwnode.h +1 -1
@@ -40,7 +40,7 @@ struct v4l2_fwnode_bus_mipi_csi2 {
 	unsigned int flags;
 	unsigned char data_lanes[V4L2_FWNODE_CSI2_MAX_DATA_LANES];
 	unsigned char clock_lane;
-	unsigned short num_data_lanes;
+	unsigned char num_data_lanes;
 	bool lane_polarities[1 + V4L2_FWNODE_CSI2_MAX_DATA_LANES];

That's a 4 bytes gain, it's useful.

Quoted 1 line
include/media/v4l2-fwnode.h +0 -0
 };
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#3 lore raw

PATCH 2/3 v4l2-fwnode: Make bus configuration a struct

In reply to Sakari Ailus

The bus specific parameters were an union. This made providing bus specific defaults impossible as the memory used to store the defaults for multiple different busses was the same.

Make it struct instead. It's not large so the size isn't really an issue.

---
 include/media/v4l2-fwnode.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/media/v4l2-fwnode.h +2 -2
index 81e7eb123294..d04f39b60096 100644
@@ -78,7 +78,7 @@ struct v4l2_fwnode_bus_mipi_csi1 {
  * struct v4l2_fwnode_endpoint - the endpoint data structure
  * @base: fwnode endpoint of the v4l2_fwnode
  * @bus_type: bus type
- * @bus: union with bus configuration data structure
+ * @bus: bus configuration data structure
  * @bus.parallel: embedded &struct v4l2_fwnode_bus_parallel.
  *		  Used if the bus is parallel.
  * @bus.mipi_csi1: embedded &struct v4l2_fwnode_bus_mipi_csi1.
@@ -99,7 +99,7 @@ struct v4l2_fwnode_endpoint {
 	 * v4l2_fwnode_endpoint_parse()
 	 */
 	enum v4l2_mbus_type bus_type;
-	union {
+	struct {
 		struct v4l2_fwnode_bus_parallel parallel;
 		struct v4l2_fwnode_bus_mipi_csi1 mipi_csi1;
 		struct v4l2_fwnode_bus_mipi_csi2 mipi_csi2;
Signature · 1 line
2.27.0
Reviewed-by on v1 2/3
#4 lore raw

Re: [PATCH 2/3] v4l2-fwnode: Make bus configuration a struct

Hi Sakari,

Thank you for the patch.

Quoted 7 lines · Sakari Ailus

The bus specific parameters were an union. This made providing bus specific defaults impossible as the memory used to store the defaults for multiple different busses was the same.

Make it struct instead. It's not large so the size isn't really an issue.

Quoted 26 lines
---
 include/media/v4l2-fwnode.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/media/v4l2-fwnode.h +2 -2
index 81e7eb123294..d04f39b60096 100644
@@ -78,7 +78,7 @@ struct v4l2_fwnode_bus_mipi_csi1 {
  * struct v4l2_fwnode_endpoint - the endpoint data structure
  * @base: fwnode endpoint of the v4l2_fwnode
  * @bus_type: bus type
- * @bus: union with bus configuration data structure
+ * @bus: bus configuration data structure
  * @bus.parallel: embedded &struct v4l2_fwnode_bus_parallel.
  *		  Used if the bus is parallel.
  * @bus.mipi_csi1: embedded &struct v4l2_fwnode_bus_mipi_csi1.
@@ -99,7 +99,7 @@ struct v4l2_fwnode_endpoint {
 	 * v4l2_fwnode_endpoint_parse()
 	 */
 	enum v4l2_mbus_type bus_type;
-	union {
+	struct {
 		struct v4l2_fwnode_bus_parallel parallel;
 		struct v4l2_fwnode_bus_mipi_csi1 mipi_csi1;
 		struct v4l2_fwnode_bus_mipi_csi2 mipi_csi2;
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#5 lore raw

PATCH 3/3 v4l2-fwnode: Document changes usage patterns of v4l2_fwnode_endpoint_parse

In reply to Sakari Ailus

Document that it is possible to provide defaults for multiple bus types to v4l2_fwnode_endpoint_parse and v4l2_fwnode_endpoint_alloc_parse. Also underline the fact that detecting the bus type without bus-type property is only for the old drivers.

---
 include/media/v4l2-fwnode.h | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)
include/media/v4l2-fwnode.h +8 -10
index d04f39b60096..ccaa5693df14 100644
@@ -226,11 +226,10 @@ struct v4l2_fwnode_connector {
  * call this function once the correct type is found --- with a default
  * configuration valid for that type.
  *
- * As a compatibility means guessing the bus type is also supported by setting
- * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default
- * configuration in this case as the defaults are specific to a given bus type.
- * This functionality is deprecated and should not be used in new drivers and it
- * is only supported for CSI-2 D-PHY, parallel and Bt.656 buses.
+ * 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!
  *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
@@ -269,11 +268,10 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep);
  * call this function once the correct type is found --- with a default
  * configuration valid for that type.
  *
- * As a compatibility means guessing the bus type is also supported by setting
- * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default
- * configuration in this case as the defaults are specific to a given bus type.
- * This functionality is deprecated and should not be used in new drivers and it
- * is only supported for CSI-2 D-PHY, parallel and Bt.656 buses.
+ * 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!
  *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
Signature · 1 line
2.27.0
#6 lore raw

Re: [PATCH 3/3] v4l2-fwnode: Document changes usage patterns of v4l2_fwnode_endpoint_parse

The subject should have been: "[PATCH 3/3] v4l2-fwnode: Document new usage patterns of v4l2_fwnode_endpoint_parse".

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

Re: [PATCH 3/3] v4l2-fwnode: Document changes usage patterns of v4l2_fwnode_endpoint_parse

In reply to Sakari Ailus

Hi Sakari,

Thank you for the patch.

Quoted 16 lines · Sakari Ailus

Document that it is possible to provide defaults for multiple bus types to v4l2_fwnode_endpoint_parse and v4l2_fwnode_endpoint_alloc_parse. Also underline the fact that detecting the bus type without bus-type property is only for the old drivers.

---
 include/media/v4l2-fwnode.h | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)
include/media/v4l2-fwnode.h +0 -0
index d04f39b60096..ccaa5693df14 100644
@@ -226,11 +226,10 @@ struct v4l2_fwnode_connector {
  * call this function once the correct type is found --- with a default

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

Quoted 10 lines
include/media/v4l2-fwnode.h +3 -5
  * configuration valid for that type.
  *
- * As a compatibility means guessing the bus type is also supported by setting
- * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default
- * configuration in this case as the defaults are specific to a given bus type.
- * This functionality is deprecated and should not be used in new drivers and it
- * is only supported for CSI-2 D-PHY, parallel and Bt.656 buses.
+ * 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

While at it, s/Bt/BT/.

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

Quoted 1 line
include/media/v4l2-fwnode.h +1 -0
+ * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!

That's fairly clear :-)

I wonder if, as a further improvement, we should turn the enum v4l2_mbus_type into a bitfield, to let drivers tell which bus types they support. The helpers could then return an error if the bus type reported by the firmware doesn't match.

Quoted 19 lines
include/media/v4l2-fwnode.h +4 -5
  *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
@@ -269,11 +268,10 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep);
  * call this function once the correct type is found --- with a default
  * configuration valid for that type.
  *
- * As a compatibility means guessing the bus type is also supported by setting
- * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default
- * configuration in this case as the defaults are specific to a given bus type.
- * This functionality is deprecated and should not be used in new drivers and it
- * is only supported for CSI-2 D-PHY, parallel and Bt.656 buses.
+ * 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!
  *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
Signature · 3 lines
Regards,

Laurent Pinchart
author maintainer
#8 lore raw

Re: [PATCH 3/3] v4l2-fwnode: Document changes usage patterns of v4l2_fwnode_endpoint_parse

Hi Laurent,

Quoted 3 lines · Laurent Pinchart

Hi Sakari,

Thank you for the patch.

Thank you for the review!

Quoted 22 lines · Sakari Ailus
Quoted 20 lines

Document that it is possible to provide defaults for multiple bus types to v4l2_fwnode_endpoint_parse and v4l2_fwnode_endpoint_alloc_parse. Also underline the fact that detecting the bus type without bus-type property is only for the old drivers.

---
 include/media/v4l2-fwnode.h | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)
include/media/v4l2-fwnode.h +0 -2
index d04f39b60096..ccaa5693df14 100644
@@ -226,11 +226,10 @@ struct v4l2_fwnode_connector {
  * call this function once the correct type is found --- with a default
  * configuration valid for that type.
  *
- * As a compatibility means guessing the bus type is also supported by setting
- * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default
Quoted 8 lines

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

Quoted 6 lines
include/media/v4l2-fwnode.h +3 -3
- * configuration in this case as the defaults are specific to a given bus type.
- * This functionality is deprecated and should not be used in new drivers and it
- * is only supported for CSI-2 D-PHY, parallel and Bt.656 buses.
+ * 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

While at it, s/Bt/BT/.

Yes.

Quoted 11 lines

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

Quoted 2 lines
include/media/v4l2-fwnode.h +1 -0
+ * supported. NEVER RELY ON GUESSING @vep.bus_type IN NEW DRIVERS!

That's fairly clear :-)

I wonder if, as a further improvement, we should turn the enum v4l2_mbus_type into a bitfield, to let drivers tell which bus types they support. The helpers could then return an error if the bus type reported by the firmware doesn't match.

I agree. That'd be less work for the caller. That does require changing a bunch of drivers though. Unless we add another field for that purpose, just like the I²C framework did. I guess it's not necessary. Ideally it'd be done so that trying to use it the old way would generate a compiler warning.

Signature · 3 lines
Regards,

Sakari Ailus
#9 lore raw

Re: [PATCH 3/3] v4l2-fwnode: Document changes usage patterns of v4l2_fwnode_endpoint_parse

In reply to Sakari Ailus

Hi Sakari,

Quoted 17 lines · Sakari Ailus

Document that it is possible to provide defaults for multiple bus types to v4l2_fwnode_endpoint_parse and v4l2_fwnode_endpoint_alloc_parse. Also underline the fact that detecting the bus type without bus-type property is only for the old drivers.

---
 include/media/v4l2-fwnode.h | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)
include/media/v4l2-fwnode.h +0 -0
index d04f39b60096..ccaa5693df14 100644
@@ -226,11 +226,10 @@ struct v4l2_fwnode_connector {
  * call this function once the correct type is found --- with a default
  * configuration valid for that type.

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

Quoted 10 lines
include/media/v4l2-fwnode.h +4 -5
  *
- * As a compatibility means guessing the bus type is also supported by setting
- * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default
- * configuration in this case as the defaults are specific to a given bus type.
- * This functionality is deprecated and should not be used in new drivers and it
- * is only supported for CSI-2 D-PHY, parallel and Bt.656 buses.
+ * 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!

As per the discussion in:
[PATCH v4 1/3] media: i2c: ov772x: Parse endpoint properties this leaves a bit of gray area on how to address cases where older dts do not report any "bus-type" property, as in the case of PARALLEL vs BT.656 Prabhakar has, it gets impossible to detect mis-configurations.

I have suggested him two different behaviours, depending if 'bus-type' is present in the fwnode or not, but I'm not sure that's the best way forward. What do you think ?

Quoted 22 lines
include/media/v4l2-fwnode.h +4 -6
  *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
@@ -269,11 +268,10 @@ void v4l2_fwnode_endpoint_free(struct v4l2_fwnode_endpoint *vep);
  * call this function once the correct type is found --- with a default
  * configuration valid for that type.
  *
- * As a compatibility means guessing the bus type is also supported by setting
- * @vep.bus_type to V4L2_MBUS_UNKNOWN. The caller may not provide a default
- * configuration in this case as the defaults are specific to a given bus type.
- * This functionality is deprecated and should not be used in new drivers and it
- * is only supported for CSI-2 D-PHY, parallel and Bt.656 buses.
+ * 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!
  *
  * The function does not change the V4L2 fwnode endpoint state if it fails.
  *
--

2.27.0