From patchwork Thu Jul 18 07:33:51 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bin Meng X-Patchwork-Id: 1133585 X-Patchwork-Delegate: trini@ti.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (mailfrom) smtp.mailfrom=lists.denx.de (client-ip=81.169.180.215; helo=lists.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="GcXp/Fg3"; dkim-atps=neutral Received: from lists.denx.de (dione.denx.de [81.169.180.215]) by ozlabs.org (Postfix) with ESMTP id 45q5mG3br4z9s8m for ; Thu, 18 Jul 2019 17:46:06 +1000 (AEST) Received: by lists.denx.de (Postfix, from userid 105) id 21624C21F3E; Thu, 18 Jul 2019 07:38:11 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on lists.denx.de X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=FREEMAIL_FROM, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, T_DKIM_INVALID autolearn=unavailable autolearn_force=no version=3.4.0 Received: from lists.denx.de (localhost [IPv6:::1]) by lists.denx.de (Postfix) with ESMTP id 33BC6C21EDC; Thu, 18 Jul 2019 07:35:09 +0000 (UTC) Received: by lists.denx.de (Postfix, from userid 105) id 9D2B1C21F8C; Thu, 18 Jul 2019 07:34:56 +0000 (UTC) Received: from mail-pf1-f195.google.com (mail-pf1-f195.google.com [209.85.210.195]) by lists.denx.de (Postfix) with ESMTPS id 89FDFC21F3E for ; Thu, 18 Jul 2019 07:34:52 +0000 (UTC) Received: by mail-pf1-f195.google.com with SMTP id u14so12208703pfn.2 for ; Thu, 18 Jul 2019 00:34:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:subject:date:message-id:in-reply-to:references; bh=yD4rOFozSquHhG4XzKvu3K7dvqO9V/9e1fuSDoUOjOE=; b=GcXp/Fg3I383QiFTkw9D1Qo8tom0pFQYjKJGJLV0m/7lHvggPNTlLMXCfMAxjxhQ7S EPVrUq/U7QcqL0NqBi/8ULGwsrID8MhaAsuNYOqQ7whz6/ZAhilc4qcgJ1EpNnHipZoJ 6hbaPT+B0fz0t4Uh0dZTftgR/SrvtsOMKOzhQFGsTxZAhHouIjq/MhjOudZFvYE9vndB 7ga71KaAb21LAprvkk3h25keRCJ5BKm1Uu6PUYVKjdzzXId2l08bR8HdeHutD/Sb8wYK yrqlYjvcfTyQgiTE+t3F0l8stS+St2W+mt9NPOITwhF8Ml7wFTBxXPXPM3Bbm2GGnifC ming== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references; bh=yD4rOFozSquHhG4XzKvu3K7dvqO9V/9e1fuSDoUOjOE=; b=Ed/A+z2cTNnqcVc8uN+odzIlmv4IhP+0qavpgt0LwB0K7p1OdSMj4G15hPOh5PupZz GeL2csirFA/lPIMSRI2GQX7YpdwgM/JUBVPcVOs111MoQGM7765Eu8PIkFD7Hg1P4A5m FjocNGRqw0B92oMv9eIXICutBMfSA1b/5deT/Na6Skq/EQMl6QBKVD+k3iVIjt+kXdzU b06jEk7eU894ZuevaNd5Z4OmDW1f6GhUeCeNMJ+BlR14YKWr/szqAsa4hyifw4eaalGs zHF19FuOWAj5FX1Vg5d5txOuvElNg9VZqU4+MaJkPLqPROe/l4KoGlyrOmzJWZCuYpO6 ZHEQ== X-Gm-Message-State: APjAAAVhXYtS30R9ED8EN1PcUN/MJ7trn3V9ZzQqTpnt1GvZFBJOrxYW /JcpEJMDMvTre7h6eWueDfI= X-Google-Smtp-Source: APXvYqw5dfZsJuYH8TuLbPJYGoS2wejCX8bL9dc34QkKM2WPMZ5owh6cUt/40RvB93cr/uBl2KDLFA== X-Received: by 2002:a17:90a:fa07:: with SMTP id cm7mr14837127pjb.115.1563435287898; Thu, 18 Jul 2019 00:34:47 -0700 (PDT) Received: from localhost.localdomain (unknown-224-80.windriver.com. [147.11.224.80]) by smtp.gmail.com with ESMTPSA id q1sm39859821pfn.178.2019.07.18.00.34.46 (version=TLS1 cipher=AES128-SHA bits=128/128); Thu, 18 Jul 2019 00:34:47 -0700 (PDT) From: Bin Meng To: Tom Rini , Simon Glass , Wolfgang Denk , Heinrich Schuchardt , Mario Six , U-Boot Mailing List Date: Thu, 18 Jul 2019 00:33:51 -0700 Message-Id: <1563435275-22326-7-git-send-email-bmeng.cn@gmail.com> X-Mailer: git-send-email 1.7.1 In-Reply-To: <1563435275-22326-1-git-send-email-bmeng.cn@gmail.com> References: <1563435275-22326-1-git-send-email-bmeng.cn@gmail.com> Subject: [U-Boot] [PATCH 06/50] doc: driver-model: Convert fdt-fixup.txt to reST X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.18 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" Convert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change. Signed-off-by: Bin Meng --- doc/driver-model/{fdt-fixup.txt => fdt-fixup.rst} | 56 +++++++++++------------ doc/driver-model/index.rst | 1 + 2 files changed, 29 insertions(+), 28 deletions(-) rename doc/driver-model/{fdt-fixup.txt => fdt-fixup.rst} (89%) diff --git a/doc/driver-model/fdt-fixup.txt b/doc/driver-model/fdt-fixup.rst similarity index 89% rename from doc/driver-model/fdt-fixup.txt rename to doc/driver-model/fdt-fixup.rst index 70344bd..974c090 100644 --- a/doc/driver-model/fdt-fixup.txt +++ b/doc/driver-model/fdt-fixup.rst @@ -1,15 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. 2017-01-06, Mario Six + Pre-relocation device tree manipulation ======================================= -Contents: - -1. Purpose -2. Implementation -3. Example -4. Work to be done - -1. Purpose ----------- +Purpose +------- In certain markets, it is beneficial for manufacturers of embedded devices to offer certain ranges of products, where the functionality of the devices within @@ -61,14 +57,16 @@ we have the pre-relocation driver model at our disposal at this stage, which means that we can query the hardware for the existence and variety of the components easily. -2. Implementation ------------------ +Implementation +-------------- To take advantage of the pre-relocation device tree manipulation mechanism, boards have to implement the function board_fix_fdt, which has the following signature: -int board_fix_fdt (void *rw_fdt_blob) +.. code-block:: c + + int board_fix_fdt (void *rw_fdt_blob) The passed-in void pointer is a writeable pointer to the device tree, which can be used to manipulate the device tree using e.g. functions from @@ -79,10 +77,10 @@ unrecoverably halt the boot process, as with any function from init_sequence_f (in common/board_f.c). Furthermore, the Kconfig option OF_BOARD_FIXUP has to be set for the function -to be called: +to be called:: -Device Tree Control --> [*] Board-specific manipulation of Device Tree + Device Tree Control + -> [*] Board-specific manipulation of Device Tree +----------------------------------------------------------+ | WARNING: The actual manipulation of the device tree has | @@ -97,23 +95,27 @@ Device Tree Control Hence, the recommended layout of the board_fixup_fdt call-back function is the following: -int board_fix_fdt(void *rw_fdt_blob) -{ - /* Collect information about device's hardware and store them in e.g. - local variables */ +.. code-block:: c + + int board_fix_fdt(void *rw_fdt_blob) + { + /* + * Collect information about device's hardware and store + * them in e.g. local variables + */ - /* Do device tree manipulation using the values previously collected */ + /* Do device tree manipulation using the values previously collected */ - /* Return 0 on successful manipulation and non-zero otherwise */ -} + /* Return 0 on successful manipulation and non-zero otherwise */ + } If this convention is kept, both an "additive" approach, meaning that nodes for detected components are added to the device tree, as well as a "subtractive" approach, meaning that nodes for absent components are removed from the tree, as well as a combination of both approaches should work. -3. Example ----------- +Example +------- The controlcenterdc board (board/gdsys/a38x/controlcenterdc.c) features a board_fix_fdt function, in which six GPIO expanders (which might be present or @@ -123,10 +125,8 @@ subsequently deactivated in the device tree if they are not present. Note that the dm_i2c_simple_probe function does not use the device tree, hence it is safe to call it after the tree has already been manipulated. -4. Work to be done ------------------- +Work to be done +--------------- * The application of device tree overlay should be possible in board_fixup_fdt, but has not been tested at this stage. - -2017-01-06, Mario Six diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst index 663aa5d..71ad062 100644 --- a/doc/driver-model/index.rst +++ b/doc/driver-model/index.rst @@ -7,4 +7,5 @@ Driver Model :maxdepth: 2 design + fdt-fixup migration