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

On Mon 8 October 2012 23:14:01 Guennadi Liakhovetski wrote:

On Mon, 8 Oct 2012, Laurent Pinchart wrote:

quoted

On Monday 08 October 2012 14:00:38 Stephen Warren wrote:

quoted

On 10/02/2012 08:33 AM, Guennadi Liakhovetski wrote:

quoted

On Tue, 2 Oct 2012, Rob Herring wrote:

quoted

On 09/27/2012 09:07 AM, Guennadi Liakhovetski wrote:

quoted

This patch adds a document, describing common V4L2 device tree bindings.

diff --git a/Documentation/devicetree/bindings/media/v4l2.txt

b/Documentation/devicetree/bindings/media/v4l2.txt>> 

One other comment below:

quoted

+
+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@0 {
+		link@0 { ... };
+		link@1 { ... };
+	};
+	port@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.

This name is a little vague. Perhaps "endpoint" would be better.

"endpoint" can also refer to something local like in USB case. Maybe
rather the description of the "remote" property should be improved?

The documentation doesn't show up in all the .dts files that use it; it
might be useful to try and make the .dts file as obviously readable as
possible.

Perhaps "remote-port" or "connected-port" would be sufficiently descriptive.

I like remote-port better than the already proposed remote-link.

Yes, remote-port sounds better, than remote-link, but might be more 
difficult to correlate with the fact, that the phandle value of this 
property points to a link DT node, and not to a port.

I first thought of remote-port as well, but it is just weird that it points to
a link node.

I seem to remember that 'link' was called 'pad' initially, but people didn't
like that due to possible confusion with other meanings of that word.

The problem with the word 'link' is that it doesn't describe a link but just
one endpoint of a link.

Is it an idea to rename 'link' to 'endpoint' and 'remote' to 'remote-endpoint'?

So a port has endpoints, and each endpoint has a remote-endpoint property.

Regards,

	Hans