From patchwork Wed Apr 15 14:45:15 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: 201997 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9D52CC2BA19 for ; Wed, 15 Apr 2020 14:47:12 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 6FAD62076D for ; Wed, 15 Apr 2020 14:47:12 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586962032; bh=a1eyqEdmzN0DfOJU1eSZCMjYbz9xksLR9xHit1mh8r8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=rTjybl6MS6DlMez4RSnnydJClxMvyAqbviXXzjzUTJyETp+xcihkCmKRwzSQknB8X ArSp/YhY9RbyAZWmAu4XIaea+YQp+RHnfxLVgR1BPITKx1XmdBqlUHxaBYIfCh9A0f ERmq4PPp0xxnK4a/wpMU+zG3Hadckcdrt1VFM2rQ= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2636789AbgDOOrK (ORCPT ); Wed, 15 Apr 2020 10:47:10 -0400 Received: from mail.kernel.org ([198.145.29.99]:39962 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2634635AbgDOOp3 (ORCPT ); Wed, 15 Apr 2020 10:45:29 -0400 Received: from mail.kernel.org (ip5f5ad4d8.dynamic.kabel-deutschland.de [95.90.212.216]) (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 D9F8A2137B; Wed, 15 Apr 2020 14:45:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961929; bh=a1eyqEdmzN0DfOJU1eSZCMjYbz9xksLR9xHit1mh8r8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=KlheR7OZFIOZpLzBn7hNLdU5/4QWs9zy1nGbgebiwZPxdc7gz9ORQLmmN2kqVAghY qnx7Plkm62MtehKP6H32vzSjXKortR29qSDIKrXpMnTyN0W2CMHGiyJlOGx7xePZFE oRh4oZyTVgDMkWMaN2mnYAFzbte9+bclBUI/Xkgg= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jOjI7-006kZB-2c; Wed, 15 Apr 2020 16:45:27 +0200 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 Subject: [PATCH v3 01/12] docs: dt: add an index.rst file for devicetree Date: Wed, 15 Apr 2020 16:45:15 +0200 Message-Id: X-Mailer: git-send-email 2.25.2 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 There are some device tree documentation under Documentation/devicetree. Add a top index file for it and add the already-existing ReST file on it. Signed-off-by: Mauro Carvalho Chehab --- Documentation/devicetree/index.rst | 10 ++++++++++ Documentation/index.rst | 3 +++ 2 files changed, 13 insertions(+) create mode 100644 Documentation/devicetree/index.rst diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst new file mode 100644 index 000000000000..a11efe26f205 --- /dev/null +++ b/Documentation/devicetree/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================= +Open Firmware and Device Tree +============================= + +.. toctree:: + :maxdepth: 1 + + writing-schema diff --git a/Documentation/index.rst b/Documentation/index.rst index 9599c0f3eea8..c7f89cb204d1 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. The Linux Kernel documentation master file, created by sphinx-quickstart on Fri Feb 12 13:51:46 2016. @@ -46,6 +48,7 @@ platform firmwares. :maxdepth: 2 firmware-guide/index + devicetree/index Application-developer documentation ----------------------------------- From patchwork Wed Apr 15 14:45:16 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: 202000 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id E42E2C2BA19 for ; Wed, 15 Apr 2020 14:46:07 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id BFD57208FE for ; Wed, 15 Apr 2020 14:46:07 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961967; bh=VYrdfxPvSnlAugkruISgIrBzyDsUwFovOIfuhVj7+P8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=NiZq0x0KjJO4kb9tThvg3lihoDkZxZlO1KwsyfNM0YHbcoV+uPpVVHDI8dOnBzf4C IjuvIJoK/PGF4DyCZThCyoqJK53w/tvK+Y/dUbgn97iJDwsRam8lJR4TqOAdQtH5xh PqowyVdH1h9IIJVib3/f+nU0A8ygoEkxsUo3HGG4= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2392322AbgDOOph (ORCPT ); Wed, 15 Apr 2020 10:45:37 -0400 Received: from mail.kernel.org ([198.145.29.99]:39900 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2634601AbgDOOp3 (ORCPT ); Wed, 15 Apr 2020 10:45:29 -0400 Received: from mail.kernel.org (ip5f5ad4d8.dynamic.kabel-deutschland.de [95.90.212.216]) (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 D119D2076D; Wed, 15 Apr 2020 14:45:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961929; bh=VYrdfxPvSnlAugkruISgIrBzyDsUwFovOIfuhVj7+P8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PiM4EXpPDrRBwxkowPnGLMDIDOWNN2E/dtaRmmR7brxfG/y3F6HHSZCvSwTptfsqY ncooAM4fpvzpjOerde2faQqfdSu3x+lkuMn5T8InoJfeA7UhX3oIm/w5wDs69kF4TJ AC2hj9IYRdphC7nvL1sSiYOVbjI+KyO71wc0fAOE= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jOjI7-006kZF-47; Wed, 15 Apr 2020 16:45:27 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Rob Herring , Lee Jones , devicetree@vger.kernel.org Subject: [PATCH v3 02/12] docs: dt: convert usage-model.txt to ReST Date: Wed, 15 Apr 2020 16:45:16 +0200 Message-Id: X-Mailer: git-send-email 2.25.2 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 - Add a SPDX header; - Adjust document title; - Use footnoote markups; - Some whitespace fixes and new line breaks; - Mark literal blocks as such; - Add it to devicetree/index.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/devicetree/index.rst | 1 + Documentation/devicetree/of_unittest.txt | 2 +- .../{usage-model.txt => usage-model.rst} | 35 +++++++++++-------- include/linux/mfd/core.h | 2 +- 4 files changed, 23 insertions(+), 17 deletions(-) rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%) diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index a11efe26f205..7a6aad7d384a 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -7,4 +7,5 @@ Open Firmware and Device Tree .. toctree:: :maxdepth: 1 + usage-model writing-schema diff --git a/Documentation/devicetree/of_unittest.txt b/Documentation/devicetree/of_unittest.txt index 3e4e7d48ae93..9fdd2de9b770 100644 --- a/Documentation/devicetree/of_unittest.txt +++ b/Documentation/devicetree/of_unittest.txt @@ -11,7 +11,7 @@ architecture. It is recommended to read the following documents before moving ahead. -[1] Documentation/devicetree/usage-model.txt +[1] Documentation/devicetree/usage-model.rst [2] http://www.devicetree.org/Device_Tree_Usage OF Selftest has been designed to test the interface (include/linux/of.h) diff --git a/Documentation/devicetree/usage-model.txt b/Documentation/devicetree/usage-model.rst similarity index 97% rename from Documentation/devicetree/usage-model.txt rename to Documentation/devicetree/usage-model.rst index 33a8aaac02a8..326d7af10c5b 100644 --- a/Documentation/devicetree/usage-model.txt +++ b/Documentation/devicetree/usage-model.rst @@ -1,14 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= Linux and the Device Tree -------------------------- +========================= + The Linux usage model for device tree data -Author: Grant Likely +:Author: Grant Likely This article describes how Linux uses the device tree. An overview of the device tree data format can be found on the device tree usage page -at devicetree.org[1]. +at devicetree.org\ [1]_. -[1] http://devicetree.org/Device_Tree_Usage +.. [1] http://devicetree.org/Device_Tree_Usage The "Open Firmware Device Tree", or simply Device Tree (DT), is a data structure and language for describing hardware. More specifically, it @@ -57,7 +61,7 @@ Tree (FDT) was created which could be passed to the kernel as a binary blob without requiring a real Open Firmware implementation. U-Boot, kexec, and other bootloaders were modified to support both passing a Device Tree Binary (dtb) and to modify a dtb at boot time. DT was -also added to the PowerPC boot wrapper (arch/powerpc/boot/*) so that +also added to the PowerPC boot wrapper (``arch/powerpc/boot/*``) so that a dtb could be wrapped up with the kernel image to support booting existing non-DT aware firmware. @@ -68,7 +72,7 @@ out of mainline (nios) have some level of DT support. 2. Data Model ------------- -If you haven't already read the Device Tree Usage[1] page, +If you haven't already read the Device Tree Usage\ [1]_ page, then go read it now. It's okay, I'll wait.... 2.1 High Level View @@ -88,6 +92,7 @@ duplication and make it easier to support a wide range of hardware with a single kernel image. Linux uses DT data for three major purposes: + 1) platform identification, 2) runtime configuration, and 3) device population. @@ -117,7 +122,7 @@ The 'compatible' property contains a sorted list of strings starting with the exact name of the machine, followed by an optional list of boards it is compatible with sorted from most compatible to least. For example, the root compatible properties for the TI BeagleBoard and its -successor, the BeagleBoard xM board might look like, respectively: +successor, the BeagleBoard xM board might look like, respectively:: compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3"; compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3"; @@ -183,7 +188,7 @@ configuration data like the kernel parameters string and the location of an initrd image. Most of this data is contained in the /chosen node, and when booting -Linux it will look something like this: +Linux it will look something like this:: chosen { bootargs = "console=ttyS0,115200 loglevel=8"; @@ -251,9 +256,9 @@ platform devices roughly correspond to device nodes at the root of the tree and children of simple memory mapped bus nodes. About now is a good time to lay out an example. Here is part of the -device tree for the NVIDIA Tegra board. +device tree for the NVIDIA Tegra board:: -/{ + /{ compatible = "nvidia,harmony", "nvidia,tegra20"; #address-cells = <1>; #size-cells = <1>; @@ -313,7 +318,7 @@ device tree for the NVIDIA Tegra board. i2s-controller = <&i2s1>; i2s-codec = <&wm8903>; }; -}; + }; At .init_machine() time, Tegra board support code will need to look at this DT and decide which nodes to create platform_devices for. @@ -379,13 +384,13 @@ device tree support code reflects that and makes the above example simpler. The second argument to of_platform_populate() is an of_device_id table, and any node that matches an entry in that table will also get its child nodes registered. In the Tegra case, the code -can look something like this: +can look something like this:: -static void __init harmony_init_machine(void) -{ + static void __init harmony_init_machine(void) + { /* ... */ of_platform_populate(NULL, of_default_bus_match_table, NULL, NULL); -} + } "simple-bus" is defined in the Devicetree Specification as a property meaning a simple memory mapped bus, so the of_platform_populate() code diff --git a/include/linux/mfd/core.h b/include/linux/mfd/core.h index d01d1299e49d..21718c8b2b48 100644 --- a/include/linux/mfd/core.h +++ b/include/linux/mfd/core.h @@ -74,7 +74,7 @@ struct mfd_cell { /* * Device Tree compatible string - * See: Documentation/devicetree/usage-model.txt Chapter 2.2 for details + * See: Documentation/devicetree/usage-model.rst Chapter 2.2 for details */ const char *of_compatible; From patchwork Wed Apr 15 14:45:18 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 202001 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D3DCAC2BA19 for ; Wed, 15 Apr 2020 14:45:44 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id A53112078B for ; Wed, 15 Apr 2020 14:45:44 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961944; bh=8Hkkx4BACJgLjEn4g35djfHCf6TM62vRDVNKbDplOY8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=ThuQaOUsVn7MRaOa1WU1N6c5nt9z+laR1noyG4rLfAkFOcVi4Zaf9PPoTuampxFGl MLtIYS72N9wksUmcn/W4N2nwwEzp7mqlAVAORQ8ocogf6qWGfy/egFRe/s7E860w8Z LXnXocrTRd55bKeODGhzJJV8h3W4rmc/rcn054vY= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S370912AbgDOOpk (ORCPT ); Wed, 15 Apr 2020 10:45:40 -0400 Received: from mail.kernel.org ([198.145.29.99]:40224 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2634643AbgDOOpe (ORCPT ); Wed, 15 Apr 2020 10:45:34 -0400 Received: from mail.kernel.org (ip5f5ad4d8.dynamic.kabel-deutschland.de [95.90.212.216]) (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 ECD35214AF; Wed, 15 Apr 2020 14:45:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961929; bh=8Hkkx4BACJgLjEn4g35djfHCf6TM62vRDVNKbDplOY8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=BAEW3CLMTJWFprZySyRLRYeuKB2WP+Iu6ubysSH693cdoNcys9MY5tXKlMKVKQUIt aypJvB3qvZILcqegOAbQVEFhWZvHWM+zZrTk+J2GS6iohUcl1WKtzebl3C5q4xZfYu vAm7N3N3rUKSwKonI4Lt5PNpwmoMSqdDWDGC0G04= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jOjI7-006kZQ-7N; Wed, 15 Apr 2020 16:45:27 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Rob Herring , Harry Wei , Alex Shi , devicetree@vger.kernel.org Subject: [PATCH v3 04/12] docs: dt: convert booting-without-of.txt to ReST format Date: Wed, 15 Apr 2020 16:45:18 +0200 Message-Id: X-Mailer: git-send-email 2.25.2 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 - Add a SPDX header; - Use copyright symbol; - Adjust document title; - Adjust document and section titles; - Some whitespace fixes and new line breaks; - Mark literal blocks as such; - Add table markups; - Add it to devicetree/index.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/arm/booting.rst | 2 +- ...-without-of.txt => booting-without-of.rst} | 299 ++++++++++-------- Documentation/devicetree/index.rst | 1 + Documentation/translations/zh_CN/arm/Booting | 2 +- 4 files changed, 169 insertions(+), 135 deletions(-) rename Documentation/devicetree/{booting-without-of.txt => booting-without-of.rst} (90%) diff --git a/Documentation/arm/booting.rst b/Documentation/arm/booting.rst index 4babb6c6ae1e..a2263451dc2c 100644 --- a/Documentation/arm/booting.rst +++ b/Documentation/arm/booting.rst @@ -128,7 +128,7 @@ it. The recommended placement is in the first 16KiB of RAM. The boot loader must load a device tree image (dtb) into system ram at a 64bit aligned address and initialize it with the boot data. The -dtb format is documented in Documentation/devicetree/booting-without-of.txt. +dtb format is documented in Documentation/devicetree/booting-without-of.rst. The kernel will look for the dtb magic value of 0xd00dfeed at the dtb physical address to determine if a dtb has been passed instead of a tagged list. diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.rst similarity index 90% rename from Documentation/devicetree/booting-without-of.txt rename to Documentation/devicetree/booting-without-of.rst index 4660ccee35a3..56e54e95efa7 100644 --- a/Documentation/devicetree/booting-without-of.txt +++ b/Documentation/devicetree/booting-without-of.rst @@ -1,15 +1,20 @@ - Booting the Linux/ppc kernel without Open Firmware - -------------------------------------------------- - -(c) 2005 Benjamin Herrenschmidt , - IBM Corp. -(c) 2005 Becky Bruce , - Freescale Semiconductor, FSL SOC and 32-bit additions -(c) 2006 MontaVista Software, Inc. - Flash chip node definition - -Table of Contents -================= +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +================================================== +Booting the Linux/ppc kernel without Open Firmware +================================================== + +Copyright |copy| 2005 Benjamin Herrenschmidt , +IBM Corp. + +Copyright |copy| 2005 Becky Bruce , +Freescale Semiconductor, FSL SOC and 32-bit additions + +Copyright |copy| 2006 MontaVista Software, Inc. +Flash chip node definition + +.. Table of Contents I - Introduction 1) Entry point for arch/arm @@ -61,15 +66,18 @@ Table of Contents Revision Information ==================== - May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet. + May 18, 2005: Rev 0.1 + - Initial draft, no chapter III yet. - May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or + May 19, 2005: Rev 0.2 + - Add chapter III and bits & pieces here or clarifies the fact that a lot of things are optional, the kernel only requires a very small device tree, though it is encouraged to provide an as complete one as possible. - May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM + May 24, 2005: Rev 0.3 + - Precise that DT block has to be in RAM - Misc fixes - Define version 3 and new format version 16 for the DT block (version 16 needs kernel @@ -82,7 +90,8 @@ Revision Information "name" property is now automatically deduced from the unit name - June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and + June 1, 2005: Rev 0.4 + - Correct confusion between OF_DT_END and OF_DT_END_NODE in structure definition. - Change version 16 format to always align property data to 4 bytes. Since tokens are @@ -115,7 +124,7 @@ Revision Information - Compare FSL SOC use of PCI to standard and make sure no new node definition required. - Add more information about node definitions for SOC devices - that currently have no standard, like the FSL CPM. + that currently have no standard, like the FSL CPM. I - Introduction @@ -260,7 +269,7 @@ it with special cases. b) create your main platform file as "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it - to the Makefile under the condition of your CONFIG_ + to the Makefile under the condition of your ``CONFIG_`` option. This file will define a structure of type "ppc_md" containing the various callbacks that the generic code will use to get to your platform specific code @@ -271,7 +280,7 @@ it with special cases. with classic Powerpc architectures. 3) Entry point for arch/x86 -------------------------------- +--------------------------- There is one single 32bit entry point to the kernel at code32_start, the decompressor (the real mode entry point goes to the same 32bit @@ -280,9 +289,9 @@ it with special cases. Documentation/x86/boot.rst The physical pointer to the device-tree block (defined in chapter II) is passed via setup_data which requires at least boot protocol 2.09. - The type filed is defined as + The type filed is defined as:: - #define SETUP_DTB 2 + #define SETUP_DTB 2 This device-tree is used as an extension to the "boot page". As such it does not parse / consider data which is already covered by the boot @@ -354,9 +363,9 @@ the block to RAM before passing it to the kernel. The kernel is passed the physical address pointing to an area of memory that is roughly described in include/linux/of_fdt.h by the structure - boot_param_header: + boot_param_header::: -struct boot_param_header { + struct boot_param_header { u32 magic; /* magic word OF_DT_HEADER */ u32 totalsize; /* total size of DT block */ u32 off_dt_struct; /* offset to structure */ @@ -374,19 +383,19 @@ struct boot_param_header { /* version 17 fields below */ u32 size_dt_struct; /* size of the DT structure block */ -}; + }; - Along with the constants: + Along with the constants:: -/* Definitions used by the flattened device tree */ -#define OF_DT_HEADER 0xd00dfeed /* 4: version, - 4: total size */ -#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name - */ -#define OF_DT_END_NODE 0x2 /* End node */ -#define OF_DT_PROP 0x3 /* Property: name off, - size, content */ -#define OF_DT_END 0x9 + /* Definitions used by the flattened device tree */ + #define OF_DT_HEADER 0xd00dfeed /* 4: version, + 4: total size */ + #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name + */ + #define OF_DT_END_NODE 0x2 /* End node */ + #define OF_DT_PROP 0x3 /* Property: name off, + size, content */ + #define OF_DT_END 0x9 All values in this header are in big endian format, the various fields in this header are defined more precisely below. All @@ -430,7 +439,7 @@ struct boot_param_header { way to avoid overriding critical things like, on Open Firmware capable machines, the RTAS instance, or on some pSeries, the TCE tables used for the iommu. Typically, the reserve map should - contain _at least_ this DT block itself (header,total_size). If + contain **at least** this DT block itself (header,total_size). If you are passing an initrd to the kernel, you should reserve it as well. You do not need to reserve the kernel image itself. The map should be 64-bit aligned. @@ -485,7 +494,7 @@ struct boot_param_header { So the typical layout of a DT block (though the various parts don't need to be in that order) looks like this (addresses go from top to - bottom): + bottom):: ------------------------------ @@ -511,9 +520,9 @@ struct boot_param_header { | --- (base + totalsize) - (*) The alignment gaps are not necessarily present; their presence - and size are dependent on the various alignment requirements of - the individual data blocks. + (*) The alignment gaps are not necessarily present; their presence + and size are dependent on the various alignment requirements of + the individual data blocks. 2) Device tree generalities @@ -600,7 +609,7 @@ discussed in a later chapter. At this point, it is only meant to give you a idea of what a device-tree looks like. I have purposefully kept the "name" and "linux,phandle" properties which aren't necessary in order to give you a better idea of what the tree looks like in -practice. +practice:: / o device-tree |- name = "device-tree" @@ -650,6 +659,7 @@ properties and their content. 3) Device tree "structure" block +-------------------------------- The structure of the device tree is a linearized tree structure. The "OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" @@ -666,12 +676,14 @@ Here's the basic structure of a single node: root node) * [align gap to next 4 bytes boundary] * for each property: + * token OF_DT_PROP (that is 0x00000003) * 32-bit value of property value size in bytes (or 0 if no value) * 32-bit value of offset in string block of property name * property value data if any * [align gap to next 4 bytes boundary] + * [child nodes if any] * token OF_DT_END_NODE (that is 0x00000002) @@ -688,6 +700,7 @@ manipulating a flattened tree must take care to preserve this constraint. 4) Device tree "strings" block +------------------------------ In order to save space, property names, which are generally redundant, are stored separately in the "strings" block. This block is simply the @@ -700,15 +713,17 @@ strings block. III - Required content of the device tree ========================================= -WARNING: All "linux,*" properties defined in this document apply only -to a flattened device-tree. If your platform uses a real -implementation of Open Firmware or an implementation compatible with -the Open Firmware client interface, those properties will be created -by the trampoline code in the kernel's prom_init() file. For example, -that's where you'll have to add code to detect your board model and -set the platform number. However, when using the flattened device-tree -entry point, there is no prom_init() pass, and thus you have to -provide those properties yourself. +.. Warning:: + + All ``linux,*`` properties defined in this document apply only + to a flattened device-tree. If your platform uses a real + implementation of Open Firmware or an implementation compatible with + the Open Firmware client interface, those properties will be created + by the trampoline code in the kernel's prom_init() file. For example, + that's where you'll have to add code to detect your board model and + set the platform number. However, when using the flattened device-tree + entry point, there is no prom_init() pass, and thus you have to + provide those properties yourself. 1) Note about cells and address representation @@ -769,7 +784,7 @@ addresses), all buses must contain a "ranges" property. If the "ranges" property is missing at a given level, it's assumed that translation isn't possible, i.e., the registers are not visible on the parent bus. The format of the "ranges" property for a bus is a list -of: +of:: bus address, parent bus address, size @@ -877,7 +892,7 @@ address which can extend beyond that limit. This node is the parent of all individual CPU nodes. It doesn't have any specific requirements, though it's generally good practice - to have at least: + to have at least:: #address-cells = <00000001> #size-cells = <00000000> @@ -887,7 +902,7 @@ address which can extend beyond that limit. that format when reading the "reg" properties of a CPU node, see below - c) The /cpus/* nodes + c) The ``/cpus/*`` nodes So under /cpus, you are supposed to create a node for every CPU on the machine. There is no specific restriction on the name of the @@ -903,21 +918,23 @@ address which can extend beyond that limit. - reg : This is the physical CPU number, it's a single 32-bit cell and is also used as-is as the unit number for constructing the unit name in the full path. For example, with 2 CPUs, you would - have the full path: + have the full path:: + /cpus/PowerPC,970FX@0 /cpus/PowerPC,970FX@1 + (unit addresses do not require leading zeroes) - - d-cache-block-size : one cell, L1 data cache block size in bytes (*) + - d-cache-block-size : one cell, L1 data cache block size in bytes [#]_ - i-cache-block-size : one cell, L1 instruction cache block size in bytes - d-cache-size : one cell, size of L1 data cache in bytes - i-cache-size : one cell, size of L1 instruction cache in bytes -(*) The cache "block" size is the size on which the cache management -instructions operate. Historically, this document used the cache -"line" size here which is incorrect. The kernel will prefer the cache -block size and will fallback to cache line size for backward -compatibility. + .. [#] The cache "block" size is the size on which the cache management + instructions operate. Historically, this document used the cache + "line" size here which is incorrect. The kernel will prefer the cache + block size and will fallback to cache line size for backward + compatibility. Recommended properties: @@ -963,10 +980,10 @@ compatibility. #address-cells and #size-cells of the root node. For example, with both of these properties being 2 like in the example given earlier, a 970 based machine with 6Gb of RAM could typically - have a "reg" property here that looks like: + have a "reg" property here that looks like:: - 00000000 00000000 00000000 80000000 - 00000001 00000000 00000001 00000000 + 00000000 00000000 00000000 80000000 + 00000001 00000000 00000001 00000000 That is a range starting at 0 of 0x80000000 bytes and a range starting at 0x100000000 and of 0x100000000 bytes. You can see @@ -1047,18 +1064,18 @@ compatibility. See 1) above for more details on defining #address-cells. - #size-cells : Size representation for "soc" devices - #interrupt-cells : Defines the width of cells used to represent - interrupts. Typically this value is <2>, which includes a - 32-bit number that represents the interrupt number, and a - 32-bit number that represents the interrupt sense and level. - This field is only needed if the SOC contains an interrupt - controller. + interrupts. Typically this value is <2>, which includes a + 32-bit number that represents the interrupt number, and a + 32-bit number that represents the interrupt sense and level. + This field is only needed if the SOC contains an interrupt + controller. The SOC node may contain child nodes for each SOC device that the platform uses. Nodes should not be created for devices which exist on the SOC but are not used by a particular platform. See chapter VI for more information on how to specify devices that are part of a SOC. - Example SOC node for the MPC8540: + Example SOC node for the MPC8540:: soc8540@e0000000 { #address-cells = <1>; @@ -1079,31 +1096,33 @@ IV - "dtc", the device tree compiler dtc source code can be found at -WARNING: This version is still in early development stage; the -resulting device-tree "blobs" have not yet been validated with the -kernel. The current generated block lacks a useful reserve map (it will -be fixed to generate an empty one, it's up to the bootloader to fill -it up) among others. The error handling needs work, bugs are lurking, -etc... +.. Warning:: + + This version is still in early development stage; the + resulting device-tree "blobs" have not yet been validated with the + kernel. The current generated block lacks a useful reserve map (it will + be fixed to generate an empty one, it's up to the bootloader to fill + it up) among others. The error handling needs work, bugs are lurking, + etc... dtc basically takes a device-tree in a given format and outputs a device-tree in another format. The currently supported formats are: - Input formats: - ------------- +Input formats +------------- - "dtb": "blob" format, that is a flattened device-tree block with - header all in a binary blob. + header all in a binary blob. - "dts": "source" format. This is a text file containing a "source" for a device-tree. The format is defined later in this - chapter. + chapter. - "fs" format. This is a representation equivalent to the - output of /proc/device-tree, that is nodes are directories and - properties are files + output of /proc/device-tree, that is nodes are directories and + properties are files - Output formats: - --------------- +Output formats +-------------- - "dtb": "blob" format - "dts": "source" format @@ -1113,7 +1132,7 @@ device-tree in another format. The currently supported formats are: assembly file exports some symbols that can be used. -The syntax of the dtc tool is +The syntax of the dtc tool is:: dtc [-I ] [-O ] [-o output-filename] [-V output_version] input_filename @@ -1127,43 +1146,45 @@ Additionally, dtc performs various sanity checks on the tree, like the uniqueness of linux, phandle properties, validity of strings, etc... The format of the .dts "source" file is "C" like, supports C and C++ -style comments. +style comments:: -/ { -} + / { + } The above is the "device-tree" definition. It's the only statement supported currently at the toplevel. -/ { - property1 = "string_value"; /* define a property containing a 0 - * terminated string - */ +:: - property2 = <0x1234abcd>; /* define a property containing a - * numerical 32-bit value (hexadecimal) - */ + / { + property1 = "string_value"; /* define a property containing a 0 + * terminated string + */ - property3 = <0x12345678 0x12345678 0xdeadbeef>; - /* define a property containing 3 - * numerical 32-bit values (cells) in - * hexadecimal - */ - property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef]; - /* define a property whose content is - * an arbitrary array of bytes - */ + property2 = <0x1234abcd>; /* define a property containing a + * numerical 32-bit value (hexadecimal) + */ - childnode@address { /* define a child node named "childnode" - * whose unit name is "childnode at - * address" - */ + property3 = <0x12345678 0x12345678 0xdeadbeef>; + /* define a property containing 3 + * numerical 32-bit values (cells) in + * hexadecimal + */ + property4 = [0x0a 0x0b 0x0c 0x0d 0xde 0xea 0xad 0xbe 0xef]; + /* define a property whose content is + * an arbitrary array of bytes + */ - childprop = "hello\n"; /* define a property "childprop" of - * childnode (in this case, a string) - */ - }; -}; + childnode@address { /* define a child node named "childnode" + * whose unit name is "childnode at + * address" + */ + + childprop = "hello\n"; /* define a property "childprop" of + * childnode (in this case, a string) + */ + }; + }; Nodes can contain other nodes etc... thus defining the hierarchical structure of the tree. @@ -1322,7 +1343,7 @@ phandle of the parent node. If the interrupt-parent property is not defined for a node, its interrupt parent is assumed to be an ancestor in the node's -_device tree_ hierarchy. +*device tree* hierarchy. 3) OpenPIC Interrupt Controllers -------------------------------- @@ -1334,10 +1355,12 @@ information. Sense and level information should be encoded as follows: - 0 = low to high edge sensitive type enabled - 1 = active low level sensitive type enabled - 2 = active high level sensitive type enabled - 3 = high to low edge sensitive type enabled + == ======================================== + 0 low to high edge sensitive type enabled + 1 active low level sensitive type enabled + 2 active high level sensitive type enabled + 3 high to low edge sensitive type enabled + == ======================================== 4) ISA Interrupt Controllers ---------------------------- @@ -1350,13 +1373,15 @@ information. ISA PIC interrupt controllers should adhere to the ISA PIC encodings listed below: - 0 = active low level sensitive type enabled - 1 = active high level sensitive type enabled - 2 = high to low edge sensitive type enabled - 3 = low to high edge sensitive type enabled + == ======================================== + 0 active low level sensitive type enabled + 1 active high level sensitive type enabled + 2 high to low edge sensitive type enabled + 3 low to high edge sensitive type enabled + == ======================================== VIII - Specifying Device Power Management Information (sleep property) -=================================================================== +====================================================================== Devices on SOCs often have mechanisms for placing devices into low-power states that are decoupled from the devices' own register blocks. Sometimes, @@ -1387,6 +1412,7 @@ reasonably grouped in this manner, then create a virtual sleep controller sleep-map should wait until its necessity is demonstrated). IX - Specifying dma bus information +=================================== Some devices may have DMA memory range shifted relatively to the beginning of RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC @@ -1404,25 +1430,30 @@ coherent DMA operations. The "dma-coherent" property is intended to be used for identifying devices supported coherent DMA operations in DT. * DMA Bus master + Optional property: + - dma-ranges: encoded as arbitrary number of triplets of - (child-bus-address, parent-bus-address, length). Each triplet specified - describes a contiguous DMA address range. - The dma-ranges property is used to describe the direct memory access (DMA) - structure of a memory-mapped bus whose device tree parent can be accessed - from DMA operations originating from the bus. It provides a means of - defining a mapping or translation between the physical address space of - the bus and the physical address space of the parent of the bus. - (for more information see the Devicetree Specification) + (child-bus-address, parent-bus-address, length). Each triplet specified + describes a contiguous DMA address range. + The dma-ranges property is used to describe the direct memory access (DMA) + structure of a memory-mapped bus whose device tree parent can be accessed + from DMA operations originating from the bus. It provides a means of + defining a mapping or translation between the physical address space of + the bus and the physical address space of the parent of the bus. + (for more information see the Devicetree Specification) * DMA Bus child + Optional property: + - dma-ranges: value. if present - It means that DMA addresses - translation has to be enabled for this device. + translation has to be enabled for this device. - dma-coherent: Present if dma operations are coherent -Example: -soc { +Example:: + + soc { compatible = "ti,keystone","simple-bus"; ranges = <0x0 0x0 0x0 0xc0000000>; dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>; @@ -1435,11 +1466,13 @@ soc { [...] dma-coherent; }; -}; + }; Appendix A - Sample SOC node for MPC8540 ======================================== +:: + soc@e0000000 { #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 7a6aad7d384a..6b4daf252375 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -9,3 +9,4 @@ Open Firmware and Device Tree usage-model writing-schema + booting-without-of diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting index 562e9a2957e6..c3d26ce5f6de 100644 --- a/Documentation/translations/zh_CN/arm/Booting +++ b/Documentation/translations/zh_CN/arm/Booting @@ -124,7 +124,7 @@ bootloader 必须传递一个系统内存的位置和最小值，以及根文件 bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统 RAM 中，并用启动数据初始化它。dtb 格式在文档 -Documentation/devicetree/booting-without-of.txt 中。内核将会在 +Documentation/devicetree/booting-without-of.rst 中。内核将会在 dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替 标签列表被传递进来。 From patchwork Wed Apr 15 14:45:19 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: 201996 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 723AAC2BB55 for ; Wed, 15 Apr 2020 14:47:26 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 50C8D208E4 for ; Wed, 15 Apr 2020 14:47:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586962046; bh=oVpWH0qpmsIfqBvaqvZk4DhmzrNPI+GFYenh6pTu4+I=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=wU8iQl3zfedSC1N5KvWDdK1YMkMhRtR7zzqq/NcpgMnr+x6OyB4w4koaP5mNjfHaI puBf8u/8PC40f0Kd0KQEZrfyfJprLQEPMx9RE8ThYYNaM7JWj2z3MUut5Qgc6gSjbg ZjXlYphnJyFxV3y5nWEaDB5mn1Z4SgmrgD3gfnjw= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2636848AbgDOOrL (ORCPT ); Wed, 15 Apr 2020 10:47:11 -0400 Received: from mail.kernel.org ([198.145.29.99]:39972 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2636787AbgDOOpa (ORCPT ); Wed, 15 Apr 2020 10:45:30 -0400 Received: from mail.kernel.org (ip5f5ad4d8.dynamic.kabel-deutschland.de [95.90.212.216]) (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 EED52214D8; Wed, 15 Apr 2020 14:45:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961929; bh=oVpWH0qpmsIfqBvaqvZk4DhmzrNPI+GFYenh6pTu4+I=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=UK/v4KpK8hxPFvXSdUhaebc9I2OHm5j+drtz7PhkVfQefhI+b6yMY1RUUP7Mwv9JA +xWMBf0BxWsUiuXvr6FGW+37qOFR1619I9UhjaqsUmn4vnrP3lIFxWHksns7Liibqz FiL6AMJEyKPuEP+pnKXNbQt0DLRlyACu363Y5Bcw= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jOjI7-006kZV-8O; Wed, 15 Apr 2020 16:45:27 +0200 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 Subject: [PATCH v3 05/12] docs: dt: convert changesets to ReST Date: Wed, 15 Apr 2020 16:45:19 +0200 Message-Id: <6ae9724c28cef35f44f3d99d3907f0228a233e27.1586961793.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.2 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 - Add a SPDX header; - Add a document title; - Some whitespace fixes and new line breaks; - Add it to devicetree/index.rst. Signed-off-by: Mauro Carvalho Chehab --- .../{changesets.txt => changesets.rst} | 24 ++++++++++++------- Documentation/devicetree/index.rst | 1 + 2 files changed, 16 insertions(+), 9 deletions(-) rename Documentation/devicetree/{changesets.txt => changesets.rst} (59%) diff --git a/Documentation/devicetree/changesets.txt b/Documentation/devicetree/changesets.rst similarity index 59% rename from Documentation/devicetree/changesets.txt rename to Documentation/devicetree/changesets.rst index cb488eeb6353..c7fd8cd6a270 100644 --- a/Documentation/devicetree/changesets.txt +++ b/Documentation/devicetree/changesets.rst @@ -1,3 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +DT Changesets +============= + A DT changeset is a method which allows one to apply changes in the live tree in such a way that either the full set of changes will be applied, or none of them will be. If an error occurs partway @@ -15,17 +21,17 @@ The sequence of a changeset is as follows. 1. of_changeset_init() - initializes a changeset 2. A number of DT tree change calls, of_changeset_attach_node(), -of_changeset_detach_node(), of_changeset_add_property(), -of_changeset_remove_property, of_changeset_update_property() to prepare -a set of changes. No changes to the active tree are made at this point. -All the change operations are recorded in the of_changeset 'entries' -list. + of_changeset_detach_node(), of_changeset_add_property(), + of_changeset_remove_property, of_changeset_update_property() to prepare + a set of changes. No changes to the active tree are made at this point. + All the change operations are recorded in the of_changeset 'entries' + list. 3. of_changeset_apply() - Apply the changes to the tree. Either the -entire changeset will get applied, or if there is an error the tree will -be restored to the previous state. The core ensures proper serialization -through locking. An unlocked version __of_changeset_apply is available, -if needed. + entire changeset will get applied, or if there is an error the tree will + be restored to the previous state. The core ensures proper serialization + through locking. An unlocked version __of_changeset_apply is available, + if needed. If a successfully applied changeset needs to be removed, it can be done with of_changeset_revert(). diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 6b4daf252375..64c78c3ffea6 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -10,3 +10,4 @@ Open Firmware and Device Tree usage-model writing-schema booting-without-of + changesets From patchwork Wed Apr 15 14:45:20 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: 201999 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE, SPF_PASS, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 826CDC38A2D for ; Wed, 15 Apr 2020 14:46:25 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 600142076D for ; Wed, 15 Apr 2020 14:46:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961985; bh=zjaZ+FY9k5t0F298mGBFOd6P5KCDBR9N1LMntsYEq9Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=LDf0p7bJkCnE1SV73jGfdI231M9L2BCnlbe40fvD3vTMK/845XhETqTBaXv77JOhJ 93HVdCUNBfm1OqfiHA1t/sPohHn3c0HrWBvgkvQDRx8dvzoB1phR000V/WKWd7olo1 wGq8HJnemXrUvEq4utewRxuEr+0kdkpl86U6YAvA= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S370894AbgDOOqY (ORCPT ); Wed, 15 Apr 2020 10:46:24 -0400 Received: from mail.kernel.org ([198.145.29.99]:40220 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2636790AbgDOOpd (ORCPT ); Wed, 15 Apr 2020 10:45:33 -0400 Received: from mail.kernel.org (ip5f5ad4d8.dynamic.kabel-deutschland.de [95.90.212.216]) (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 1608121556; Wed, 15 Apr 2020 14:45:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961929; bh=zjaZ+FY9k5t0F298mGBFOd6P5KCDBR9N1LMntsYEq9Y=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=RjiW4sfNN3VQYHu759vgsitq4kOPElObnihHUZu0byStwRHmUBWi0zfWdN2uUINFt 9jN7vHmsnAWqYnrf+9ZYqazIgsPvlwkcOG6rXl1h4TKxQ0675MUPTjw5cRx3Hz4W0R in8opOwOp7lzOD4pk1CrosXFd6nV1GLpT2PoWcJ4= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jOjI7-006kZa-9O; Wed, 15 Apr 2020 16:45:27 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Pantelis Antoniou , Frank Rowand , Rob Herring , "David S. Miller" , Greg Kroah-Hartman , devicetree@vger.kernel.org Subject: [PATCH v3 06/12] docs: dt: convert dynamic-resolution-notes.txt to ReST Date: Wed, 15 Apr 2020 16:45:20 +0200 Message-Id: X-Mailer: git-send-email 2.25.2 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 - Add a SPDX header; - Adjust document title; - Add it to devicetree/index.rst. Signed-off-by: Mauro Carvalho Chehab --- ...mic-resolution-notes.txt => dynamic-resolution-notes.rst} | 5 ++++- Documentation/devicetree/index.rst | 1 + Documentation/devicetree/overlay-notes.txt | 2 +- MAINTAINERS | 2 +- 4 files changed, 7 insertions(+), 3 deletions(-) rename Documentation/devicetree/{dynamic-resolution-notes.txt => dynamic-resolution-notes.rst} (90%) diff --git a/Documentation/devicetree/dynamic-resolution-notes.txt b/Documentation/devicetree/dynamic-resolution-notes.rst similarity index 90% rename from Documentation/devicetree/dynamic-resolution-notes.txt rename to Documentation/devicetree/dynamic-resolution-notes.rst index c24ec366c5dc..570b7e1f39eb 100644 --- a/Documentation/devicetree/dynamic-resolution-notes.txt +++ b/Documentation/devicetree/dynamic-resolution-notes.rst @@ -1,5 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== Device Tree Dynamic Resolver Notes ----------------------------------- +================================== This document describes the implementation of the in-kernel Device Tree resolver, residing in drivers/of/resolver.c diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 64c78c3ffea6..308cac9d7021 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -11,3 +11,4 @@ Open Firmware and Device Tree writing-schema booting-without-of changesets + dynamic-resolution-notes diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.txt index 725fb8d255c1..3f20a39e4bc2 100644 --- a/Documentation/devicetree/overlay-notes.txt +++ b/Documentation/devicetree/overlay-notes.txt @@ -3,7 +3,7 @@ Device Tree Overlay Notes This document describes the implementation of the in-kernel device tree overlay functionality residing in drivers/of/overlay.c and is a -companion document to Documentation/devicetree/dynamic-resolution-notes.txt[1] +companion document to Documentation/devicetree/dynamic-resolution-notes.rst[1] How overlays work ----------------- diff --git a/MAINTAINERS b/MAINTAINERS index 58725773cec4..12fb85313e1b 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -12553,7 +12553,7 @@ M: Pantelis Antoniou M: Frank Rowand L: devicetree@vger.kernel.org S: Maintained -F: Documentation/devicetree/dynamic-resolution-notes.txt +F: Documentation/devicetree/dynamic-resolution-notes.rst F: Documentation/devicetree/overlay-notes.txt F: drivers/of/overlay.c F: drivers/of/resolver.c From patchwork Wed Apr 15 14:45:22 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: 201998 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 89996C38A30 for ; Wed, 15 Apr 2020 14:46:27 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 61D922076D for ; Wed, 15 Apr 2020 14:46:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961987; bh=vmjZxcRiYIn7FqbxC+RA+SUWBoUTUvQ7ocSvEou+wZk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=HCjItC1d3kHzxeIF0Fx6QB7MWUf8GEGWiiBQhD0jWkm4oljrmnoQNjsFAHzUlLmnl dcxoszfR0RY8yz0tysUFKxV1paIvm2At8NSZ+GG08x85fAAC64Fwf9nX0YhqSPBLb1 MipPK8N7itKijMyzSYCutjhPt9Ni5HL4iz6A9cho= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2634684AbgDOOqY (ORCPT ); Wed, 15 Apr 2020 10:46:24 -0400 Received: from mail.kernel.org ([198.145.29.99]:40226 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2636789AbgDOOpd (ORCPT ); Wed, 15 Apr 2020 10:45:33 -0400 Received: from mail.kernel.org (ip5f5ad4d8.dynamic.kabel-deutschland.de [95.90.212.216]) (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 278D721744; Wed, 15 Apr 2020 14:45:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961929; bh=vmjZxcRiYIn7FqbxC+RA+SUWBoUTUvQ7ocSvEou+wZk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=xEszWOL29mZL3aJ9sJbLQzKtT9HddfoTVBJRKWZwU0GgZ2UeyjR6A7F1RepYYmWbC zMZKbx+cFLDvovRhE+CtYngN1LmVPfo8xEwt0HfGrDkQ9Cznf4b3SHlPQ+JIVUaxtA f0p82mF2C/3dXV+n1hqndWfJuA9nxlDSTA7z3ElA= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jOjI7-006kZk-CZ; Wed, 15 Apr 2020 16:45:27 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , Rob Herring , Pantelis Antoniou , Frank Rowand , "David S. Miller" , Greg Kroah-Hartman , devicetree@vger.kernel.org Subject: [PATCH v3 08/12] docs: dt: convert overlay-notes.txt to ReST format Date: Wed, 15 Apr 2020 16:45:22 +0200 Message-Id: <8d69f216ea22c38f5665c7782535837396804a24.1586961793.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.25.2 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 - Add a SPDX header; - Adjust document title; - Some whitespace fixes and new line breaks; - Mark literal blocks as such; - Add it to devicetree/index.rst. Signed-off-by: Mauro Carvalho Chehab --- Documentation/devicetree/index.rst | 1 + .../{overlay-notes.txt => overlay-notes.rst} | 141 +++++++++--------- MAINTAINERS | 2 +- 3 files changed, 74 insertions(+), 70 deletions(-) rename Documentation/devicetree/{overlay-notes.txt => overlay-notes.rst} (56%) diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index ca83258fbba5..0669a53fc617 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -13,3 +13,4 @@ Open Firmware and Device Tree changesets dynamic-resolution-notes of_unittest + overlay-notes diff --git a/Documentation/devicetree/overlay-notes.txt b/Documentation/devicetree/overlay-notes.rst similarity index 56% rename from Documentation/devicetree/overlay-notes.txt rename to Documentation/devicetree/overlay-notes.rst index 3f20a39e4bc2..7e8e568f64a8 100644 --- a/Documentation/devicetree/overlay-notes.txt +++ b/Documentation/devicetree/overlay-notes.rst @@ -1,5 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= Device Tree Overlay Notes -------------------------- +========================= This document describes the implementation of the in-kernel device tree overlay functionality residing in drivers/of/overlay.c and is a @@ -15,68 +18,68 @@ Since the kernel mainly deals with devices, any new device node that result in an active device should have it created while if the device node is either disabled or removed all together, the affected device should be deregistered. -Lets take an example where we have a foo board with the following base tree: - ----- foo.dts ----------------------------------------------------------------- - /* FOO platform */ - / { - compatible = "corp,foo"; - - /* shared resources */ - res: res { - }; - - /* On chip peripherals */ - ocp: ocp { - /* peripherals that are always instantiated */ - peripheral1 { ... }; - } - }; ----- foo.dts ----------------------------------------------------------------- - -The overlay bar.dts, when loaded (and resolved as described in [1]) should - ----- bar.dts ----------------------------------------------------------------- -/plugin/; /* allow undefined label references and record them */ -/ { - .... /* various properties for loader use; i.e. part id etc. */ - fragment@0 { - target = <&ocp>; - __overlay__ { - /* bar peripheral */ - bar { - compatible = "corp,bar"; - ... /* various properties and child nodes */ - } - }; - }; -}; ----- bar.dts ----------------------------------------------------------------- - -result in foo+bar.dts - ----- foo+bar.dts ------------------------------------------------------------- - /* FOO platform + bar peripheral */ - / { - compatible = "corp,foo"; - - /* shared resources */ - res: res { - }; - - /* On chip peripherals */ - ocp: ocp { - /* peripherals that are always instantiated */ - peripheral1 { ... }; - - /* bar peripheral */ - bar { - compatible = "corp,bar"; - ... /* various properties and child nodes */ - } - } - }; ----- foo+bar.dts ------------------------------------------------------------- +Lets take an example where we have a foo board with the following base tree:: + + ---- foo.dts -------------------------------------------------------------- + /* FOO platform */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + } + }; + ---- foo.dts -------------------------------------------------------------- + +The overlay bar.dts, when loaded (and resolved as described in [1]) should:: + + ---- bar.dts -------------------------------------------------------------- + /plugin/; /* allow undefined label references and record them */ + / { + .... /* various properties for loader use; i.e. part id etc. */ + fragment@0 { + target = <&ocp>; + __overlay__ { + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + }; + }; + }; + ---- bar.dts -------------------------------------------------------------- + +result in foo+bar.dts:: + + ---- foo+bar.dts ---------------------------------------------------------- + /* FOO platform + bar peripheral */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + } + }; + ---- foo+bar.dts ---------------------------------------------------------- As a result of the overlay, a new device node (bar) has been created so a bar platform device will be registered and if a matching device driver @@ -88,11 +91,11 @@ Overlay in-kernel API The API is quite easy to use. 1. Call of_overlay_fdt_apply() to create and apply an overlay changeset. The -return value is an error or a cookie identifying this overlay. + return value is an error or a cookie identifying this overlay. 2. Call of_overlay_remove() to remove and cleanup the overlay changeset -previously created via the call to of_overlay_fdt_apply(). Removal of an -overlay changeset that is stacked by another will not be permitted. + previously created via the call to of_overlay_fdt_apply(). Removal of an + overlay changeset that is stacked by another will not be permitted. Finally, if you need to remove all overlays in one-go, just call of_overlay_remove_all() which will remove every single one in the correct @@ -109,9 +112,9 @@ respective node it received. Overlay DTS Format ------------------ -The DTS of an overlay should have the following format: +The DTS of an overlay should have the following format:: -{ + { /* ignored properties by the overlay */ fragment@0 { /* first child node */ @@ -131,7 +134,7 @@ The DTS of an overlay should have the following format: ... }; /* more fragments follow */ -} + } Using the non-phandle based target method allows one to use a base DT which does not contain a __symbols__ node, i.e. it was not compiled with the -@ option. diff --git a/MAINTAINERS b/MAINTAINERS index 12fb85313e1b..4da583422186 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -12554,7 +12554,7 @@ M: Frank Rowand L: devicetree@vger.kernel.org S: Maintained F: Documentation/devicetree/dynamic-resolution-notes.rst -F: Documentation/devicetree/overlay-notes.txt +F: Documentation/devicetree/overlay-notes.rst F: drivers/of/overlay.c F: drivers/of/resolver.c K: of_overlay_notifier_ From patchwork Wed Apr 15 14:45:26 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: 202002 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-10.1 required=3.0 tests=DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D65F4C2BB55 for ; Wed, 15 Apr 2020 14:45:40 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id B48212078B for ; Wed, 15 Apr 2020 14:45:40 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961940; bh=Tgx8bhgHklE3FDZN9i6EsAGZk7UfLJB3Oy+zSTpJTjQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=pUHiumHQD2KRS+xOAtgPCjT45mahM3kblWHml5EqmI1yrLIImEro/0bVPFnn5PbA1 nWKy24Q0/7naUsIb4RtAJkbDdfnYznGZE7K+iCVTL89xejZrYBCCvl4AxvdSKeh4C6 X5rXFsEmISepw7jgvj1JlBmNhp/YEDnKwkHREPdM= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2636799AbgDOOpj (ORCPT ); Wed, 15 Apr 2020 10:45:39 -0400 Received: from mail.kernel.org ([198.145.29.99]:40254 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2636795AbgDOOpd (ORCPT ); Wed, 15 Apr 2020 10:45:33 -0400 Received: from mail.kernel.org (ip5f5ad4d8.dynamic.kabel-deutschland.de [95.90.212.216]) (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 46D72218AC; Wed, 15 Apr 2020 14:45:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586961929; bh=Tgx8bhgHklE3FDZN9i6EsAGZk7UfLJB3Oy+zSTpJTjQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=Qy38bo6tXyunOd7fssISCteEmQC1jwS+lxtVXlNgBuwUsCE1XBnGqltK8LvvfU38O N2qgx9t7zxpsbTrfhqCb2N3TorkMRnTTDQBaX02kYlJNP+Rn28JogIJyaA5xT8Wmdw hjai+vMqj0Mhhi6NEwCsGQmds4IRE5GmSuy6ng84= Received: from mchehab by mail.kernel.org with local (Exim 4.92.3) (envelope-from ) id 1jOjI7-006ka3-I8; Wed, 15 Apr 2020 16:45:27 +0200 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 Subject: [PATCH v3 12/12] docs: dt: convert writing-bindings.txt to ReST Date: Wed, 15 Apr 2020 16:45:26 +0200 Message-Id: X-Mailer: git-send-email 2.25.2 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 - 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 --- 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.