From patchwork Mon Nov 20 08:40:44 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Krzysztof Kozlowski X-Patchwork-Id: 13460914 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 348D8C197A0 for ; Mon, 20 Nov 2023 08:41:40 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20210309; h=Sender: Content-Transfer-Encoding:Content-Type:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:Message-Id:Date:Subject:Cc :To:From:Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:In-Reply-To:References: List-Owner; bh=TyJcnWhUqMAIpEvubvN9c3Y/RW8hTGF0axL+lcmgkMo=; b=SdGQOSNAu/oHGs 3/iiJnFxg28URXPQSXz9BHaJh6N2C8S3En2U+lJhlofO37+aN0yowoXvgFu6Tq5qkbEh7nmObnx2q v1zjslHeyBYK+qlaWjghSihjZU3+SUFu+92PJCEJkRn+Q/TdLqvlvjmZb43UWXIFlO2l2IjG0vJJZ Ami1ITL2Al9Xho6aJqS3D7yhq0GhkRSkxgmm6GwJv2zC7UbCQDTE+I7BidcMZC75sX6qcm2ZZ5yzO 8xwgudbXTthKv0MBf1RZaEn2UljCpFaXcrS1YO49pze52q0fL0gj7sSQVa1DsxbRJw57A3rU/ztu2 2nZ6ZOrTpnTKik/R//xA==; Received: from localhost ([::1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.96 #2 (Red Hat Linux)) id 1r4zq7-00BWkh-0I; Mon, 20 Nov 2023 08:41:07 +0000 Received: from mail-lf1-x136.google.com ([2a00:1450:4864:20::136]) by bombadil.infradead.org with esmtps (Exim 4.96 #2 (Red Hat Linux)) id 1r4zpw-00BWgx-1Q for linux-arm-kernel@lists.infradead.org; Mon, 20 Nov 2023 08:41:03 +0000 Received: by mail-lf1-x136.google.com with SMTP id 2adb3069b0e04-507bd644a96so5683875e87.3 for ; Mon, 20 Nov 2023 00:40:53 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; t=1700469652; x=1701074452; darn=lists.infradead.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=Uja6WpBlyTBG5jgby6fiOGTUsSLknCmEeqWb3eouYXA=; b=g7hFVpwGhSvWE6ToDtmxCP4sGuKRLqXLLkgsnTREkHTUENvYhhKhm5l00ethg8FeH9 VuJVRtCQbgGERaWWtp9K5A2HxaBs2l11BqcyhJqaO/dbg4ckTucI8yk/lDrEW8rCY0OO zaydqa+LOTuIazXwpVU7Ppx2e/QBkB3f1vwuDQH1K1MMAam6QQKYqpKAxsa29C3nFNoD DPxE6kqS1iUnkc5d33U6GQxjTt835/sTphxo4olYNzQdELVsC8dDoYQvcLPMK5TB1eZO P9cv7oFwwr0yGLEr166U2usJ16dIdRUQGx0QcxmxcjT4+zGhAEl1vFyg0K+vqVrNoroV RTBg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1700469652; x=1701074452; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=Uja6WpBlyTBG5jgby6fiOGTUsSLknCmEeqWb3eouYXA=; b=vpz88Te5youUVTGY/EXKY6+rD6ufh8Brba6HZi4yCOig3nT913hNf09d85Ow+TJG+m gtoN5x3qO77RffEZLnq5IVOW76GVzUPzgm2i1NMWlEeSio2uaj7vAGaOT99FfsYpq3I6 cwZsvhAv1nLCAKHvWhMXYQDaDqeMcli11fOdt/35n93RJD27NAdDuPzjVqsB07xOCu9t ZDZqCz/rI5cGhI29cMJv87m84uVcyyr9itlnV2Iq/toDZA3ETDjCoeAuNmc/eP9M0Jkr 61WgNdItXI8ZM7bmpPNIRhpF+/3uuzK9VMQttBZBWwZjMgf84/rVYxU1sGGPoAYJj2IQ Wjsw== X-Gm-Message-State: AOJu0Yz87htWB6UeZ9regrRj9X1dfQplsOxDMNNQOBUvfVuCW3sTRw9N hoCGhrMheuNPOkW6rm97HxqwVA== X-Google-Smtp-Source: AGHT+IF2z2UJKmxACAGYnsgCuyDmhU5DSNYyJ8jl3UYFsf5HLqN43Rt4pV8YyXHZTojYeH5cxbBtXA== X-Received: by 2002:a2e:bc0f:0:b0:2c6:eccb:344d with SMTP id b15-20020a2ebc0f000000b002c6eccb344dmr6049660ljf.40.1700469652204; Mon, 20 Nov 2023 00:40:52 -0800 (PST) Received: from krzk-bin.. ([178.197.222.11]) by smtp.gmail.com with ESMTPSA id m7-20020a05600c4f4700b0040772138bb7sm17248340wmq.2.2023.11.20.00.40.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 20 Nov 2023 00:40:51 -0800 (PST) From: Krzysztof Kozlowski To: Rob Herring , Krzysztof Kozlowski , Conor Dooley , Matthias Brugger , AngeloGioacchino Del Regno , devicetree@vger.kernel.org, linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, linux-mediatek@lists.infradead.org Cc: Krzysztof Kozlowski , Andrew Davis , Arnd Bergmann , Bjorn Andersson , Geert Uytterhoeven , Heiko Stuebner , Konrad Dybcio , Michal Simek , Neil Armstrong , Nishanth Menon , Olof Johansson , linux-rockchip@lists.infradead.org, linux-samsung-soc@vger.kernel.org, linux-amlogic@lists.infradead.org, linux-arm-msm@vger.kernel.org Subject: [PATCH v2] docs: dt-bindings: add DTS Coding Style document Date: Mon, 20 Nov 2023 09:40:44 +0100 Message-Id: <20231120084044.23838-1-krzysztof.kozlowski@linaro.org> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20231120_004056_613307_D6CF3968 X-CRM114-Status: GOOD ( 23.00 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org Document preferred coding style for Devicetree sources (DTS and DTSI), to bring consistency among all (sub)architectures and ease in reviews. Cc: Andrew Davis Cc: AngeloGioacchino Del Regno Cc: Arnd Bergmann Cc: Bjorn Andersson Cc: Geert Uytterhoeven Cc: Heiko Stuebner Cc: Konrad Dybcio Cc: Matthias Brugger Cc: Michal Simek Cc: Neil Armstrong Cc: Nishanth Menon Cc: Olof Johansson Signed-off-by: Krzysztof Kozlowski Acked-by: Neil Armstrong Acked-by: Heiko Stuebner --- Merging idea: Rob/DT bindings Changes in v2 ============= 1. Hopefully incorporate entire feedback from comments: a. Fix \ { => / { (Rob) b. Name: dts-coding-style (Rob) c. Exceptions for ordering nodes by name for Renesas and pinctrl (Geert, Konrad) d. Ordering properties by common/vendor (Rob) e. Array entries in <> (Rob) 2. New chapter: Organizing DTSI and DTS 3. Several grammar fixes (missing articles) Cc: linux-rockchip@lists.infradead.org Cc: linux-mediatek@lists.infradead.org Cc: linux-samsung-soc@vger.kernel.org Cc: linux-amlogic@lists.infradead.org Cc: linux-arm-kernel@lists.infradead.org Cc: linux-arm-msm@vger.kernel.org --- .../devicetree/bindings/dts-coding-style.rst | 163 ++++++++++++++++++ Documentation/devicetree/bindings/index.rst | 1 + 2 files changed, 164 insertions(+) create mode 100644 Documentation/devicetree/bindings/dts-coding-style.rst diff --git a/Documentation/devicetree/bindings/dts-coding-style.rst b/Documentation/devicetree/bindings/dts-coding-style.rst new file mode 100644 index 000000000000..cc7e3b4d1b92 --- /dev/null +++ b/Documentation/devicetree/bindings/dts-coding-style.rst @@ -0,0 +1,163 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. _dtscodingstyle: + +===================================== +Devicetree Sources (DTS) Coding Style +===================================== + +When writing Devicetree Sources (DTS) please observe below guidelines. They +should be considered complementary to any rules expressed already in Devicetree +Specification and dtc compiler (including W=1 and W=2 builds). + +Individual architectures and sub-architectures can add additional rules, making +the style stricter. + +Naming and Valid Characters +--------------------------- + +1. Node and property names are allowed to use only: + + * lowercase characters: [a-z] + * digits: [0-9] + * dash: - + +2. Labels are allowed to use only: + + * lowercase characters: [a-z] + * digits: [0-9] + * underscore: _ + +3. Unit addresses should use lowercase hex, without leading zeros (padding). + +4. Hex values in properties, e.g. "reg", should use lowercase hex. The address + part can be padded with leading zeros. + +Example:: + + gpi_dma2: dma-controller@800000 { + compatible = "qcom,sm8550-gpi-dma", "qcom,sm6350-gpi-dma"; + reg = <0x0 0x00800000 0x0 0x60000>; + } + +Order of Nodes +-------------- + +1. Nodes within any bus, thus using unit addresses for children, shall be + ordered incrementally by unit address. + Alternatively for some sub-architectures, nodes of the same type can be + grouped together (e.g. all I2C controllers one after another even if this + breaks unit address ordering). + +2. Nodes without unit addresses should be ordered alpha-numerically by the node + name. For a few types of nodes, they can be ordered by the main property + (e.g. pin configuration states ordered by value of "pins" property). + +3. When extending nodes in the board DTS via &label, the entries should be + ordered alpha-numerically. + +Example:: + + // SoC DTSI + + / { + cpus { + // ... + }; + + psci { + // ... + }; + + soc@ { + dma: dma-controller@10000 { + // ... + }; + + clk: clock-controller@80000 { + // ... + }; + }; + }; + + // Board DTS + + &clk { + // ... + }; + + &dma { + // ... + }; + + +Order of Properties in Device Node +---------------------------------- + +Following order of properties in device nodes is preferred: + +1. compatible +2. reg +3. ranges +4. Standard/common properties (defined by common bindings, e.g. without + vendor-prefixes) +5. Vendor-specific properties +6. status (if applicable) +7. Child nodes, where each node is preceded with a blank line + +The "status" property is by default "okay", thus it can be omitted. + +Example:: + + // SoC DTSI + + usb_1_hsphy: phy@88e3000 { + compatible = "qcom,sm8550-snps-eusb2-phy"; + reg = <0x0 0x088e3000 0x0 0x154>; + #phy-cells = <0>; + resets = <&gcc GCC_QUSB2PHY_PRIM_BCR>; + status = "disabled"; + }; + + // Board DTS + + &usb_1_hsphy { + clocks = <&tcsr TCSR_USB2_CLKREF_EN>; + clock-names = "ref"; + status = "okay"; + }; + + +Indentation +----------- + +1. Use indentation according to :ref:`codingstyle`. +2. For arrays spanning across lines, it is preferred to align the continued + entries with opening < from the first line. +3. Each entry in arrays with multiple cells (e.g. "reg" with two IO addresses) + should be enclosed in <>. + +Example:: + + thermal-sensor@c271000 { + compatible = "qcom,sm8550-tsens", "qcom,tsens-v2"; + reg = <0x0 0x0c271000 0x0 0x1000>, + <0x0 0x0c222000 0x0 0x1000>; + }; + +Organizing DTSI and DTS +----------------------- + +The DTSI and DTS files should be organized in a way representing the common +(and re-usable) parts of the hardware. Typically this means organizing DTSI +and DTS files into several files: + +1. DTSI with contents of the entire SoC (without nodes for hardware not present + on the SoC). +2. If applicable: DTSI with common or re-usable parts of the hardware (e.g. + entire System-on-Module). +3. DTS representing the board. + +Hardware components which are present on the board should be placed in the +board DTS, not in the SoC or SoM DTSI. A partial exception is a common +external reference SoC-input clock, which could be coded as a fixed-clock in +the SoC DTSI with its frequency provided by each board DTS. diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst index d9002a3a0abb..cc1fbdc05657 100644 --- a/Documentation/devicetree/bindings/index.rst +++ b/Documentation/devicetree/bindings/index.rst @@ -4,6 +4,7 @@ :maxdepth: 1 ABI + dts-coding-style writing-bindings writing-schema submitting-patches