From patchwork Sat Dec 15 21:13:36 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sylwester Nawrocki X-Patchwork-Id: 1883351 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork2.kernel.org Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by patchwork2.kernel.org (Postfix) with ESMTP id 46EC3DF2EF for ; Sat, 15 Dec 2012 21:13:58 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752219Ab2LOVN4 (ORCPT ); Sat, 15 Dec 2012 16:13:56 -0500 Received: from mail-ea0-f174.google.com ([209.85.215.174]:60467 "EHLO mail-ea0-f174.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751745Ab2LOVNz (ORCPT ); Sat, 15 Dec 2012 16:13:55 -0500 Received: by mail-ea0-f174.google.com with SMTP id e13so1821523eaa.19 for ; Sat, 15 Dec 2012 13:13:54 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:date:message-id:x-mailer:in-reply-to:references; bh=JZzNtl//xvG3Hm6cZ+isfmNsAub2eZrKtBAMcto/Ufw=; b=EBdn+OC7OwXpdwMDLBNdUpyA2vg0SUjHqBlZ0PvBPo2SSp3CEXyqix0y8tL3ioBi0v oDkHJ9Aa6hM068hOihJJD+yvXYjy4mRpY+s7ykrpcFbUS5xx4bJc6y8XueXhHfhAJV1o yhngQk7NPQSZxoG4AqZRNQgKk7uBVLFiHs5TzdqJmD6xQCZBfwP47YlMbPjkf/Pbn6Yw O7UYAZU+Vcea9YeJCJPr0XmwunIMSGJ0bkirGfNX3BBtxTC/RrR81rHWMcWKGrXZJRDO poMuMIT9pQEDlvt3wtHi8HkoiuIa9TO/eMdticLPVhg9Ze27Ai9pklaDSf8PEjuodVyC NU4A== Received: by 10.14.214.132 with SMTP id c4mr26273827eep.18.1355606033928; Sat, 15 Dec 2012 13:13:53 -0800 (PST) Received: from localhost.localdomain (178235118103.warszawa.vectranet.pl. [178.235.118.103]) by mx.google.com with ESMTPS id e2sm18214451eeo.8.2012.12.15.13.13.51 (version=TLSv1/SSLv3 cipher=OTHER); Sat, 15 Dec 2012 13:13:52 -0800 (PST) From: Sylwester Nawrocki To: g.liakhovetski@gmx.de, linux-media@vger.kernel.org Cc: swarren@wwwdotorg.org, grant.likely@secretlab.ca, rob.herring@calxeda.com, nicolas.thery@st.com, s.hauer@pengutronix.de, laurent.pinchart@ideasonboard.com, hverkuil@xs4all.nl, devicetree-discuss@lists.ozlabs.org, linux-doc@vger.kernel.org, Sylwester Nawrocki Subject: [PATCH] [media] Add common binding documentation for video interfaces Date: Sat, 15 Dec 2012 22:13:36 +0100 Message-Id: <1355606016-6509-1-git-send-email-sylvester.nawrocki@gmail.com> X-Mailer: git-send-email 1.7.4.1 In-Reply-To: <1355168499-5847-9-git-send-email-s.nawrocki@samsung.com> References: <1355168499-5847-9-git-send-email-s.nawrocki@samsung.com> Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org From: Guennadi Liakhovetski This patch adds a document describing common OF bindings for video capture, output and video processing devices. It is currently mainly focused on video capture devices, with data interfaces defined in standards like ITU-R BT.656 or MIPI CSI-2. It also documents a method of describing data links between devices. Signed-off-by: Guennadi Liakhovetski Signed-off-by: Sylwester Nawrocki Reviewed-by: Stephen Warren Acked-by: Rob Herring --- Hi, This is an updated version of patch [1]. My changes include resolving issues pointed out during review, i.e.: - renaming 'link' node to 'endpoint, - renaming 'remote' phandle to 'remote-endpoint', - file v4l2.txt renamed to video-interfaces.txt, - removed references to V4L2, - added short description of the example DT snippet and additionally: - added "Required properties' paragraph, - updated description of 'data-lanes' property, - renamed all erroneous occurrences of 'data-width' to 'bus-width', - added 'bus-width' property description, - modified description of hsync-active, vsync-active properties, - added a little paragraph further explaining that each endpoint node has properties determining configuration of its corresponding device. [1] https://patchwork.kernel.org/patch/1514381/ I'm still unsure about the first sentence, as these bindings can be used for describing SoC internal connections between modules as well. I was considering adding something like: "This document describes common bindings for video capture, processing and output devices using data buses defined in standards like ITU-R BT.656, MIPI CSI-2,..." before the "General concept" paragraph. And maybe Documentation/devicetree/bindings/video/ would a better place for this video-interfaces.txt file ? Thanks, Sylwester --- .../devicetree/bindings/media/video-interfaces.txt | 198 ++++++++++++++++++++ 1 files changed, 198 insertions(+), 0 deletions(-) create mode 100644 Documentation/devicetree/bindings/media/video-interfaces.txt -- 1.7.4.1 -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt new file mode 100644 index 0000000..10ebbc4 --- /dev/null +++ b/Documentation/devicetree/bindings/media/video-interfaces.txt @@ -0,0 +1,198 @@ +Common bindings for video data receiver and transmitter interfaces + +General concept +--------------- + +Video data pipelines usually 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 their child 'port' nodes. +Configuration of a port depends on other devices participating in the data +transfer and is described by 'endpoint' subnodes. + +dev { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + endpoint@0 { ... }; + endpoint@1 { ... }; + }; + port@1 { ... }; +}; + +If a port can be configured to work with more than one other device on the same +bus, an 'endpoint' child node must be provided for each of them. If more than +one port is present in a device node or there is more than one endpoint at a +port, a common scheme, using '#address-cells', '#size-cells' and 'reg' properties +is used. + +Two 'endpoint' nodes are linked with each other through their 'remote-endpoint' +phandles. An endpoint subnode of a device contains all properties needed for +configuration of this device for data exchange with the other device. In most +cases properties at the peer 'endpoint' nodes will be identical, however +they might need to be different when there are any signal modifications on the +bus between two devices, e.g. there are logic signal inverters on the lines. + +Required properties +------------------- + +If there is more that one 'port' or more than one 'endpoint' node following +properties are required in relevant parent node: + +- #address-cells : number of cells required to define port number, should be 1. +- #size-cells : should be zero. + +Optional endpoint properties +---------------------------- + +- remote-endpoint : phandle to an 'endpoint' subnode of the other device node. +- slave-mode : a boolean property, run the link in slave mode. Default is master + mode. +- bus-width : the number of data lines, valid for parallel buses. +- data-shift: on parallel data busses, if bus-width is used to specify the + number of data lines, data-shift can be used to specify which data lines are + used, e.g. "bus-width=<10>; data-shift=<2>;" means, that lines 9:2 are used. +- hsync-active : active state of HSYNC signal, 0/1 for LOW/HIGH respectively. +- vsync-active : active state of VSYNC signal, 0/1 for LOW/HIGH respectively. + Note, that if HSYNC and VSYNC polarities are not specified, embedded + synchronization 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 signal. +- data-lanes : an array of physical data lane indexes. Position of an entry + determines logical lane number, while the value of an entry indicates physical + lane, e.g. for 2-lane MIPI CSI-2 bus we could have "data-lanes = <1>, <2>;", + assuming the clock lane is on hardware lane 0. This property is valid for + serial buses only (e.g. MIPI CSI-2). +- clock-lanes : a number of physical lane used as a clock lane. +- clock-noncontinuous : a boolean property to allow MIPI CSI-2 non-continuous + clock mode. + +Example +------- + +The below example snippet describes two data pipelines. ov772x and imx074 are +camera sensors with parallel and serial (MIPI CSI-2) video bus respectively. +Both sensors are on I2C control bus corresponding to i2c0 controller node. +ov772x sensor is linked directly to the ceu0 video host interface. imx074 is +linked to ceu0 through MIPI CSI-2 receiver (csi2). ceu0 has a (single) DMA +engine writing captured data to memory. ceu0 node has single 'port' node which +indicates at any time only one of following data pipeline can be active: +ov772x -> ceu0 or imx074 -> csi2 -> ceu0. + + ceu0: ceu@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: endpoint@1 { + reg = <1>; /* Local endpoint # */ + remote = <&ov772x_1_1>; /* Remote phandle */ + bus-width = <8>; /* Used data lines */ + data-shift = <0>; /* Lines 7:0 are used */ + + /* If hsync-active/vsync-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: endpoint@0 { + reg = <0>; + remote = <&csi2_2>; + immutable; + }; + }; + }; + + i2c0: i2c@0xfff20000 { + ... + ov772x_1: camera@0x21 { + compatible = "omnivision,ov772x"; + reg = <0x21>; + vddio-supply = <®ulator1>; + vddcore-supply = <®ulator2>; + + clock-frequency = <20000000>; + clocks = <&mclk 0>; + clock-names = "xclk"; + + port { + /* With 1 endpoint per port no need in addresses. */ + ov772x_1_1: endpoint { + bus-width = <8>; + remote-endpoint = <&ceu0_1>; + hsync-active = <1>; + vsync-active = <0>; /* Who came up with an + inverter here ?... */ + data-active = <1>; + pclk-sample = <1>; + }; + }; + }; + + imx074: camera@0x1a { + compatible = "sony,imx074"; + reg = <0x1a>; + vddio-supply = <®ulator1>; + vddcore-supply = <®ulator2>; + + clock-frequency = <30000000>; /* Shared clock with ov772x_1 */ + clocks = <&mclk 0>; + clock-names = "sysclk"; /* Assuming this is the + name in the datasheet */ + port { + imx074_1: endpoint { + clock-lanes = <0>; + data-lanes = <1>, <2>; + remote-endpoint = <&csi2_1>; + }; + }; + }; + }; + + csi2: csi2@0xffc90000 { + compatible = "renesas,sh-mobile-csi2"; + reg = <0xffc90000 0x1000>; + interrupts = <0x17a0>; + #address-cells = <1>; + #size-cells = <0>; + + port@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: endpoint { + clock-lanes = <0>; + data-lanes = <2>, <1>; + remote-endpoint = <&imx074_1>; + }; + }; + port@2 { + reg = <2>; /* port 2: link to the CEU */ + + csi2_2: endpoint { + immutable; + remote-endpoint = <&ceu0_0>; + }; + }; + };