From patchwork Mon Mar 2 07:38:05 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 1247472 Return-Path: X-Original-To: incoming-dt@patchwork.ozlabs.org Delivered-To: patchwork-incoming-dt@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (no SPF record) smtp.mailfrom=vger.kernel.org (client-ip=209.132.180.67; helo=vger.kernel.org; envelope-from=devicetree-owner@vger.kernel.org; receiver=) Authentication-Results: ozlabs.org; dmarc=pass (p=none dis=none) header.from=kernel.org Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=kernel.org header.i=@kernel.org header.a=rsa-sha256 header.s=default header.b=Pd+dd1Kf; dkim-atps=neutral Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by ozlabs.org (Postfix) with ESMTP id 48WBpV70p6z9sSV for ; Mon, 2 Mar 2020 18:38:42 +1100 (AEDT) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726880AbgCBHim (ORCPT ); Mon, 2 Mar 2020 02:38:42 -0500 Received: from mail.kernel.org ([198.145.29.99]:44752 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727007AbgCBHiQ (ORCPT ); Mon, 2 Mar 2020 02:38:16 -0500 Received: from mail.kernel.org (ip5f5ad4e9.dynamic.kabel-deutschland.de [95.90.212.233]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 2EFA4246C4; Mon, 2 Mar 2020 07:38:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1583134696; bh=PTj+Ja/Yeo69nLXy3U/JB2sT7irHsQjm4cp+7aSi9js=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Pd+dd1Kf9m5nNqUWxcz/aT01s97KtKRFlnYjcQtn3saiAXmgoPj2ye95gFRRNNZww 7id63w+Tv5hwOzJpQRdqmekDVJy+gS0BOp6mAuXRGrOl0rcNOdgWiAkA3QhqPPTYOW L+kc9CiCUB5RYRd3hvTjUz2nTMwT0wZg6yzY1Sto= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1j8feW-0003W2-1Q; Mon, 02 Mar 2020 08:38:12 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Rob Herring , devicetree@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 10/12] docs: dt: convert ABI.txt to ReST format Date: Mon, 2 Mar 2020 08:38:05 +0100 Message-Id: <099b1f43450e7ed5670b585204c6e37dea90a5ad.1583134242.git.mchehab+samsung@kernel.org> X-Mailer: git-send-email 2.21.1 In-Reply-To: References: MIME-Version: 1.0 Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org From: Mauro Carvalho Chehab This file only requires a properly-formatted title to be recognized as a ReST file. As there will be more files under bindings/ that will be included at the documentation body, add a new index.rst file there. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Mauro Carvalho Chehab --- Documentation/arm/microchip.rst | 2 +- Documentation/devicetree/bindings/{ABI.txt => ABI.rst} | 5 ++++- Documentation/devicetree/bindings/arm/amlogic.yaml | 2 +- Documentation/devicetree/bindings/arm/syna.txt | 2 +- Documentation/devicetree/bindings/index.rst | 10 ++++++++++ Documentation/devicetree/index.rst | 2 ++ 6 files changed, 19 insertions(+), 4 deletions(-) rename Documentation/devicetree/bindings/{ABI.txt => ABI.rst} (94%) create mode 100644 Documentation/devicetree/bindings/index.rst diff --git a/Documentation/arm/microchip.rst b/Documentation/arm/microchip.rst index 05e5f2dfb814..9c013299fd3b 100644 --- a/Documentation/arm/microchip.rst +++ b/Documentation/arm/microchip.rst @@ -192,7 +192,7 @@ Device Tree files and Device Tree bindings that apply to AT91 SoCs and boards ar considered as "Unstable". To be completely clear, any at91 binding can change at any time. So, be sure to use a Device Tree Binary and a Kernel Image generated from the same source tree. -Please refer to the Documentation/devicetree/bindings/ABI.txt file for a +Please refer to the Documentation/devicetree/bindings/ABI.rst file for a definition of a "Stable" binding/ABI. This statement will be removed by AT91 MAINTAINERS when appropriate. diff --git a/Documentation/devicetree/bindings/ABI.txt b/Documentation/devicetree/bindings/ABI.rst similarity index 94% rename from Documentation/devicetree/bindings/ABI.txt rename to Documentation/devicetree/bindings/ABI.rst index d25f8d379680..a885713cf184 100644 --- a/Documentation/devicetree/bindings/ABI.txt +++ b/Documentation/devicetree/bindings/ABI.rst @@ -1,5 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 - Devicetree (DT) ABI +=================== +Devicetree (DT) ABI +=================== I. Regarding stable bindings/ABI, we quote from the 2013 ARM mini-summit summary document: diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index f74aba48cec1..a21ce4ad63f6 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -17,7 +17,7 @@ description: |+ any time. Be sure to use a device tree binary and a kernel image generated from the same source tree. - Please refer to Documentation/devicetree/bindings/ABI.txt for a definition of a + Please refer to Documentation/devicetree/bindings/ABI.rst for a definition of a stable binding/ABI. properties: diff --git a/Documentation/devicetree/bindings/arm/syna.txt b/Documentation/devicetree/bindings/arm/syna.txt index 2face46a5f64..d8b48f2edf1b 100644 --- a/Documentation/devicetree/bindings/arm/syna.txt +++ b/Documentation/devicetree/bindings/arm/syna.txt @@ -13,7 +13,7 @@ considered "unstable". Any Marvell Berlin device tree binding may change at any time. Be sure to use a device tree binary and a kernel image generated from the same source tree. -Please refer to Documentation/devicetree/bindings/ABI.txt for a definition of a +Please refer to Documentation/devicetree/bindings/ABI.rst for a definition of a stable binding/ABI. --------------------------------------------------------------- diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst new file mode 100644 index 000000000000..98ebdab24b51 --- /dev/null +++ b/Documentation/devicetree/bindings/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========== +Device Tree +=========== + +.. toctree:: + :maxdepth: 1 + + ABI diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 0669a53fc617..2f2c93c75713 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -14,3 +14,5 @@ Open Firmware and Device Tree dynamic-resolution-notes of_unittest overlay-notes + + bindings/index From patchwork Mon Mar 2 07:38:06 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 1247473 Return-Path: X-Original-To: incoming-dt@patchwork.ozlabs.org Delivered-To: patchwork-incoming-dt@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (no SPF record) smtp.mailfrom=vger.kernel.org (client-ip=209.132.180.67; helo=vger.kernel.org; envelope-from=devicetree-owner@vger.kernel.org; receiver=) Authentication-Results: ozlabs.org; dmarc=pass (p=none dis=none) header.from=kernel.org Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=kernel.org header.i=@kernel.org header.a=rsa-sha256 header.s=default header.b=lCBXGKPA; dkim-atps=neutral Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by ozlabs.org (Postfix) with ESMTP id 48WBpj39Bmz9sSh for ; Mon, 2 Mar 2020 18:38:53 +1100 (AEDT) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727213AbgCBHim (ORCPT ); Mon, 2 Mar 2020 02:38:42 -0500 Received: from mail.kernel.org ([198.145.29.99]:44750 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727000AbgCBHiQ (ORCPT ); Mon, 2 Mar 2020 02:38:16 -0500 Received: from mail.kernel.org (ip5f5ad4e9.dynamic.kabel-deutschland.de [95.90.212.233]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 2EE50246C0; Mon, 2 Mar 2020 07:38:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1583134696; bh=2TtBEHYP8On9sIWR4gcqIRwIEpYNaIxyBBVVuOhc88k=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=lCBXGKPANlUHp5H68c6rvvpph0DqMP40oX+anruF05QYT6jHl3VyrMZIYeIVbOn/c KFfLXiDogsL+AWMjs0S0zHEJgakwm3Pdkl5atTUdH8TpPJeHDjMWqjHdf7y1dOZ2pa eXV7MDLuYm8xAREfvVBbItr3v2lWJ47V519Q0J8s= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1j8feW-0003W6-2C; Mon, 02 Mar 2020 08:38:12 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Rob Herring , Federico Vaga , Andy Whitcroft , Joe Perches , devicetree@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 11/12] docs: dt: convert submitting-patches.txt to ReST format Date: Mon, 2 Mar 2020 08:38:06 +0100 Message-Id: <4daa548a98f7fde56ed20cc30bcb31b7e8b1a9aa.1583134242.git.mchehab+samsung@kernel.org> X-Mailer: git-send-email 2.21.1 In-Reply-To: References: MIME-Version: 1.0 Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org From: Mauro Carvalho Chehab - Add a SPDX header; - Adjust document and section titles; - Mark literal blocks as such; - Add it to bindings/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Mauro Carvalho Chehab --- Documentation/devicetree/bindings/index.rst | 1 + ...submitting-patches.txt => submitting-patches.rst} | 12 +++++++++--- .../devicetree/bindings/writing-bindings.txt | 2 +- Documentation/process/submitting-patches.rst | 2 +- .../it_IT/process/submitting-patches.rst | 2 +- scripts/checkpatch.pl | 2 +- 6 files changed, 14 insertions(+), 7 deletions(-) rename Documentation/devicetree/bindings/{submitting-patches.txt => submitting-patches.rst} (92%) diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst index 98ebdab24b51..6b87875a049c 100644 --- a/Documentation/devicetree/bindings/index.rst +++ b/Documentation/devicetree/bindings/index.rst @@ -8,3 +8,4 @@ Device Tree :maxdepth: 1 ABI + submitting-patches diff --git a/Documentation/devicetree/bindings/submitting-patches.txt b/Documentation/devicetree/bindings/submitting-patches.rst similarity index 92% rename from Documentation/devicetree/bindings/submitting-patches.txt rename to Documentation/devicetree/bindings/submitting-patches.rst index 98bee6240b65..0aab2b3f16d0 100644 --- a/Documentation/devicetree/bindings/submitting-patches.txt +++ b/Documentation/devicetree/bindings/submitting-patches.rst @@ -1,13 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0 - Submitting devicetree (DT) binding patches +========================================== +Submitting devicetree (DT) binding patches +========================================== I. For patch submitters +======================= 0) Normal patch submission rules from Documentation/process/submitting-patches.rst applies. 1) The Documentation/ and include/dt-bindings/ portion of the patch should - be a separate patch. The preferred subject prefix for binding patches is: + be a separate patch. The preferred subject prefix for binding patches is:: "dt-bindings: : ..." @@ -17,7 +21,7 @@ I. For patch submitters 2) DT binding files are written in DT schema format using json-schema vocabulary and YAML file format. The DT binding files must pass validation - by running: + by running:: make dt_binding_check @@ -60,6 +64,7 @@ I. For patch submitters II. For kernel maintainers +========================== 1) If you aren't comfortable reviewing a given binding, reply to it and ask the devicetree maintainers for guidance. This will help them prioritize @@ -76,6 +81,7 @@ II. For kernel maintainers kept with the driver using the binding. III. Notes +========== 0) Please see ...bindings/ABI.txt for details regarding devicetree ABI. diff --git a/Documentation/devicetree/bindings/writing-bindings.txt b/Documentation/devicetree/bindings/writing-bindings.txt index 27dfd2d8016e..ca024b9c7433 100644 --- a/Documentation/devicetree/bindings/writing-bindings.txt +++ b/Documentation/devicetree/bindings/writing-bindings.txt @@ -4,7 +4,7 @@ This is a list of common review feedback items focused on binding design. With every rule, there are exceptions and bindings have many gray areas. For guidelines related to patches, see -Documentation/devicetree/bindings/submitting-patches.txt +Documentation/devicetree/bindings/submitting-patches.rst Overall design diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index ba5e944c7a63..1699b7f8e63a 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -16,7 +16,7 @@ for a list of items to check before submitting code. If you are submitting a driver, also read :ref:`Documentation/process/submitting-drivers.rst `; for device tree binding patches, read -Documentation/devicetree/bindings/submitting-patches.txt. +Documentation/devicetree/bindings/submitting-patches.rst. Many of these steps describe the default behavior of the ``git`` version control system; if you use ``git`` to prepare your patches, you'll find much diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index cba1f8cb61ed..7c23c08e4401 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -21,7 +21,7 @@ Leggete anche :ref:`Documentation/translations/it_IT/process/submit-checklist.rs per una lista di punti da verificare prima di inviare del codice. Se state inviando un driver, allora leggete anche :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst `; per delle patch relative alle associazioni per Device Tree leggete -Documentation/devicetree/bindings/submitting-patches.txt. +Documentation/devicetree/bindings/submitting-patches.rst. Molti di questi passi descrivono il comportamento di base del sistema di controllo di versione ``git``; se utilizzate ``git`` per preparare le vostre diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index 4480d5eec2fa..14c7277e60a0 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -2607,7 +2607,7 @@ sub process { if (($last_binding_patch != -1) && ($last_binding_patch ^ $is_binding_patch)) { WARN("DT_SPLIT_BINDING_PATCH", - "DT binding docs and includes should be a separate patch. See: Documentation/devicetree/bindings/submitting-patches.txt\n"); + "DT binding docs and includes should be a separate patch. See: Documentation/devicetree/bindings/submitting-patches.rst\n"); } } From patchwork Mon Mar 2 07:38:07 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 1247470 Return-Path: X-Original-To: incoming-dt@patchwork.ozlabs.org Delivered-To: patchwork-incoming-dt@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (no SPF record) smtp.mailfrom=vger.kernel.org (client-ip=209.132.180.67; helo=vger.kernel.org; envelope-from=devicetree-owner@vger.kernel.org; receiver=) Authentication-Results: ozlabs.org; dmarc=pass (p=none dis=none) header.from=kernel.org Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=kernel.org header.i=@kernel.org header.a=rsa-sha256 header.s=default header.b=XfLrHLjX; dkim-atps=neutral Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by ozlabs.org (Postfix) with ESMTP id 48WBpQ09q2z9sSd for ; Mon, 2 Mar 2020 18:38:38 +1100 (AEDT) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727103AbgCBHiS (ORCPT ); Mon, 2 Mar 2020 02:38:18 -0500 Received: from mail.kernel.org ([198.145.29.99]:44812 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727032AbgCBHiR (ORCPT ); Mon, 2 Mar 2020 02:38:17 -0500 Received: from mail.kernel.org (ip5f5ad4e9.dynamic.kabel-deutschland.de [95.90.212.233]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 2E87D246BF; Mon, 2 Mar 2020 07:38:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1583134696; bh=bQRwx5N1oMLXQUYzamAbbIdg3iVXNtnWVf4W1C9hQYM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XfLrHLjXrkIM7eQBCCeL+qHVgyG/Gy2SZ8JbcLR9/CSIIblyRHnFBz1NKwe+m8xhB +djCBge5zD/6eTZJYYpOmgcNvCOvpHDd9NosavfqLoSoO22DkXr/LtaF8eGiIPtQ6i 0WaKDxNLAiQvAz1genTg6GluUq0oq7bZJSCxSdLo= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1j8feW-0003WA-2y; Mon, 02 Mar 2020 08:38:12 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Rob Herring , devicetree@vger.kernel.org, Mauro Carvalho Chehab Subject: [PATCH 12/12] docs: dt: convert writing-bindings.txt to ReST Date: Mon, 2 Mar 2020 08:38:07 +0100 Message-Id: <00ea462a2db1a9b4fd188e0100c52fdf0d68aaf0.1583134242.git.mchehab+samsung@kernel.org> X-Mailer: git-send-email 2.21.1 In-Reply-To: References: MIME-Version: 1.0 Sender: devicetree-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: devicetree@vger.kernel.org From: Mauro Carvalho Chehab - Add a SPDX header; - Adjust document and section titles; - Mark literal blocks as such; - Add it to bindings/index.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Mauro Carvalho Chehab --- Documentation/devicetree/bindings/index.rst | 1 + .../{writing-bindings.txt => writing-bindings.rst} | 7 +++++++ 2 files changed, 8 insertions(+) rename Documentation/devicetree/bindings/{writing-bindings.txt => writing-bindings.rst} (92%) diff --git a/Documentation/devicetree/bindings/index.rst b/Documentation/devicetree/bindings/index.rst index 6b87875a049c..3837b17c234f 100644 --- a/Documentation/devicetree/bindings/index.rst +++ b/Documentation/devicetree/bindings/index.rst @@ -9,3 +9,4 @@ Device Tree ABI submitting-patches + writing-bindings diff --git a/Documentation/devicetree/bindings/writing-bindings.txt b/Documentation/devicetree/bindings/writing-bindings.rst similarity index 92% rename from Documentation/devicetree/bindings/writing-bindings.txt rename to Documentation/devicetree/bindings/writing-bindings.rst index ca024b9c7433..45ff426d0019 100644 --- a/Documentation/devicetree/bindings/writing-bindings.txt +++ b/Documentation/devicetree/bindings/writing-bindings.rst @@ -1,4 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================================ DOs and DON'Ts for designing and writing Devicetree bindings +============================================================ This is a list of common review feedback items focused on binding design. With every rule, there are exceptions and bindings have many gray areas. @@ -8,6 +12,7 @@ Documentation/devicetree/bindings/submitting-patches.rst Overall design +============== - DO attempt to make bindings complete even if a driver doesn't support some features. For example, if a device has an interrupt, then include the @@ -32,6 +37,7 @@ Overall design Properties +========== - DO make 'compatible' properties specific. DON'T use wildcards in compatible strings. DO use fallback compatibles when devices are the same as or a subset @@ -53,6 +59,7 @@ Properties Board/SoC .dts Files +==================== - DO put all MMIO devices under a bus node and not at the top-level.