[PATCH 04/14] media: add V4L2 DT binding documentation

[Guennadi Liakhovetski]

Hi Sascha

On Fri, 5 Oct 2012, Sascha Hauer wrote:

> Hi Guennadi,
> 
> Some comments inline.
> 
> 
> On Thu, Sep 27, 2012 at 04:07:23PM +0200, Guennadi Liakhovetski wrote:
> > This patch adds a document, describing common V4L2 device tree bindings.
> > 
> > Co-authored-by: Sylwester Nawrocki <s.nawrocki at samsung.com>
> > Signed-off-by: Guennadi Liakhovetski <g.liakhovetski at gmx.de>
> > ---
> >  Documentation/devicetree/bindings/media/v4l2.txt |  162 ++++++++++++++++++++++
> >  1 files changed, 162 insertions(+), 0 deletions(-)
> >  create mode 100644 Documentation/devicetree/bindings/media/v4l2.txt
> > 
> > diff --git a/Documentation/devicetree/bindings/media/v4l2.txt b/Documentation/devicetree/bindings/media/v4l2.txt
> > new file mode 100644
> > index 0000000..b8b3f41
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/media/v4l2.txt
> > @@ -0,0 +1,162 @@
> > +Video4Linux Version 2 (V4L2)
> > +
> > +General concept
> > +---------------
> > +
> > +Video pipelines consist of external devices, e.g. camera sensors, controlled
> > +over an I2C, SPI or UART bus, and SoC internal IP blocks, including video DMA
> > +engines and video data processors.
> > +
> > +SoC internal blocks are described by DT nodes, placed similarly to other SoC
> > +blocks. External devices are represented as child nodes of their respective bus
> > +controller nodes, e.g. I2C.
> > +
> > +Data interfaces on all video devices are described by "port" child DT nodes.
> > +Configuration of a port depends on other devices participating in the data
> > +transfer and is described by "link" DT nodes, specified as children of the
> > +"port" nodes:
> > +
> > +/foo {
> > +	port at 0 {
> > +		link at 0 { ... };
> > +		link at 1 { ... };
> > +	};
> > +	port at 1 { ... };
> > +};
> > +
> > +If a port can be configured to work with more than one other device on the same
> > +bus, a "link" child DT node must be provided for each of them. If more than one
> > +port is present on a device or more than one link is connected to a port, a
> > +common scheme, using "#address-cells," "#size-cells" and "reg" properties is
> > +used.
> > +
> > +Optional link properties:
> > +- remote: phandle to the other endpoint link DT node.
> > +- slave-mode: a boolean property, run the link in slave mode. Default is master
> > +  mode.
> > +- data-shift: on parallel data busses, if data-width is used to specify the
> > +  number of data lines, data-shift can be used to specify which data lines are
> > +  used, e.g. "data-width=<10>; data-shift=<2>;" means, that lines 9:2 are used.
> > +- hsync-active: 1 or 0 for active-high or -low HSYNC signal polarity
> > +  respectively.
> > +- vsync-active: ditto for VSYNC. Note, that if HSYNC and VSYNC polarities are
> > +  not specified, embedded synchronisation may be required, where supported.
> > +- data-active: similar to HSYNC and VSYNC specifies data line polarity.
> > +- field-even-active: field signal level during the even field data transmission.
> > +- pclk-sample: rising (1) or falling (0) edge to sample the pixel clock pin.
> > +- data-lanes: array of serial, e.g. MIPI CSI-2, data hardware lane numbers in
> > +  the ascending order, beginning with logical lane 0.
> > +- clock-lanes: hardware lane number, used for the clock lane.
> > +- clock-noncontinuous: a boolean property to allow MIPI CSI-2 non-continuous
> > +  clock mode.
> > +
> > +Example:
> > +
> > +	ceu0: ceu at 0xfe910000 {
> > +		compatible = "renesas,sh-mobile-ceu";
> > +		reg = <0xfe910000 0xa0>;
> > +		interrupts = <0x880>;
> > +
> > +		mclk: master_clock {
> > +			compatible = "renesas,ceu-clock";
> > +			#clock-cells = <1>;
> > +			clock-frequency = <50000000>;	/* max clock frequency */
> > +			clock-output-names = "mclk";
> > +		};
> > +
> > +		port {
> > +			#address-cells = <1>;
> > +			#size-cells = <0>;
> > +
> > +			ceu0_1: link at 1 {
> > +				reg = <1>;		/* local link # */
> > +				remote = <&ov772x_1_1>;	/* remote phandle */
> > +				bus-width = <8>;	/* used data lines */
> > +				data-shift = <0>;	/* lines 7:0 are used */
> > +
> > +				/* If [hv]sync-active are missing, embedded bt.605 sync is used */
> > +				hsync-active = <1>;	/* active high */
> > +				vsync-active = <1>;	/* active high */
> > +				data-active = <1>;	/* active high */
> > +				pclk-sample = <1>;	/* rising */
> > +			};
> > +
> > +			ceu0_0: link at 0 {
> > +				reg = <0>;
> > +				remote = <&csi2_2>;
> > +				immutable;
> > +			};
> > +		};
> > +	};
> > +
> > +	i2c0: i2c at 0xfff20000 {
> > +		...
> > +		ov772x_1: camera at 0x21 {
> > +			compatible = "omnivision,ov772x";
> > +			reg = <0x21>;
> > +			vddio-supply = <&regulator1>;
> > +			vddcore-supply = <&regulator2>;
> > +
> > +			clock-frequency = <20000000>;
> > +			clocks = <&mclk 0>;
> > +			clock-names = "xclk";
> > +
> > +			port {
> > +				/* With 1 link per port no need in addresses */
> > +				ov772x_1_1: link {
> > +					bus-width = <8>;
> > +					remote = <&ceu0_1>;
> > +					hsync-active = <1>;
> > +					vsync-active = <0>;	/* who came up with an inverter here?... */
> > +					data-active = <1>;
> > +					pclk-sample = <1>;
> > +				};
> 
> I currently do not understand why these properties are both in the sensor
> and in the link. What happens if they conflict? Are inverters assumed
> like suggested above? I think the bus can only have a single bus-width,
> why allow multiple bus widths here?

Yes, these nodes represent port configuration of each party on a certain 
link. And they can differ in certain properties, like - as you correctly 
notice - in the case, when there's an inverter on a line. As for other 
properties, some of them must be identical, like bus-width, still, they 
have to be provided on both ends, because generally drivers have to be 
able to perform all the required configuration based only on the 
information from their own nodes, without looking at "remote" partner node 
properties.

> > +		reg = <0xffc90000 0x1000>;
> > +		interrupts = <0x17a0>;
> > +		#address-cells = <1>;
> > +		#size-cells = <0>;
> > +
> > +		port at 1 {
> > +			compatible = "renesas,csi2c";	/* one of CSI2I and CSI2C */
> > +			reg = <1>;			/* CSI-2 PHY #1 of 2: PHY_S, PHY_M has port address 0, is unused */
> > +
> > +			csi2_1: link {
> > +				clock-lanes = <0>;
> > +				data-lanes = <2>, <1>;
> > +				remote = <&imx074_1>;
> > +			};
> > +		};
> > +		port at 2 {
> > +			reg = <2>;			/* port 2: link to the CEU */
> > +
> > +			csi2_2: link {
> > +				immutable;
> > +				remote = <&ceu0_0>;
> > +			};
> > +		};
> 
> Maybe the example would be clearer if you split it up in two, one simple
> case with the csi2_1 <-> imx074_1 and a more advanced with the link in
> between.

With no link between two ports no connection is possible, so, only 
examples with links make sense.

> It took me some time until I figured out that these are two
> separate camera/sensor pairs. Somehow I was looking for a multiplexer
> between them.

Maybe I can add more comments to the file, perhaps, add an ASCII-art 
chart.

> I am not sure we really want to have these circular phandles here.

It has been suggested and accepted during a discussion at the KS / LPC a 
month ago. The original version only had phandle referencing in one 
direction.

> I
> think phandles in the direction of data flow should be enough. I mean
> the devices probe in arbitrary order anyway and the SoC camera core must
> keep track of the possible sensor/csi combinations anyway, so it should
> be enough to make the connections in a single direction.

Thanks
Guennadi
---
Guennadi Liakhovetski, Ph.D.
Freelance Open-Source Software Developer
http://www.open-technology.de/