Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
MIME-Version: 1.0
From:   Ken Sloat <ken.sloat@ohmlinxelectronics.com>
Date:   Wed, 23 Jan 2019 21:53:30 -0500
Message-ID: <CAPo_4QDW0r22ZTqtS_NDFWB3NFLBx9YEGgWKb-P9A3t_TBAFMQ@mail.gmail.com>
Subject: devicetree: media: Documentation of Bt.656 Bus DT bindings
Cc:     Ken Sloat <Ken.sloat@ohmlinxelectronics.com>,
        linux-media@vger.kernel.org, linux-arm-kernel@lists.infradead.org,
        linux-kernel@vger.kernel.org, yong.deng@magewell.com,
        mchehab@kernel.org, robh+dt@kernel.org, mark.rutland@arm.com,
        maxime.ripard@bootlin.com, wens@csie.org,
        kieran.bingham@ideasonboard.com, laurent.pinchart@ideasonboard.com,
        jean-michel.hautbois@vodalys.com,
        Nate Drude <nate.drude@ohmlinxelectronics.com>
Content-Type: text/plain; charset="UTF-8"
To:     unlisted-recipients:; (no To-header on input)
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

There are a number of v4l2 subdevices in the kernel that support a
Bt.656 bus also known as "embedded sync." Previously in older versions
of the kernel (and in the current 4.14 LTS kernel), the standard way
to enable this in device tree on a parallel bus was to simply omit all
hysync and vsync flags.

During some other kernel development I was doing, it was brought to my
attention that there is now a standard defined binding in
"video-interfaces.txt" called "bus-type" that should be used in order
to enable Bt.656 mode. While omitting the flags still appears to work
because of other assumptions made in v4l2-fwnode driver, this method
is now outdated and improper.

However, I have noticed that several dt binding docs have not been
updated to reflect this change and still reference the old method:

Documentation/devicetree/bindings/media/sun6i-csi.txt
/* If hsync-active/vsync-active are missing,
   embedded BT.656 sync is used */

Documentation/devicetree/bindings/media/i2c/tvp5150.txt
"If none of hsync-active, vsync-active and field-even-active is specified,
the endpoint is assumed to use embedded BT.656 synchronization."

Documentation/devicetree/bindings/media/i2c/adv7604.txt
"If none of hsync-active, vsync-active and pclk-sample is specified the
  endpoint will use embedded BT.656 synchronization."

and amazingly even
Documentation/devicetree/bindings/media/video-interfaces.txt in one of
the code snippets
/* If hsync-active/vsync-active are missing,
   embedded BT.656 sync is used */

In order to avoid future confusion in the matter and ensure that the
proper bindings are used, I am proposing submitting patches to update
these docs to at minimum remove these statements and maybe even adding
additional comments specifying the optional property and value for
Bt.656 where missing. I wanted to open a discussion here first before
doing this though. Thoughts?

Thanks,
Ken Sloat