From patchwork Thu Jul 18 07:33:55 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bin Meng X-Patchwork-Id: 1133571 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="Uu3um2Z1"; dkim-atps=neutral Received: from lists.denx.de (dione.denx.de [81.169.180.215]) by ozlabs.org (Postfix) with ESMTP id 45q5d75ZPfz9s00 for ; Thu, 18 Jul 2019 17:39:55 +1000 (AEST) Received: by lists.denx.de (Postfix, from userid 105) id 5EA23C21FBD; Thu, 18 Jul 2019 07:38:44 +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 465DDC21F78; Thu, 18 Jul 2019 07:35:13 +0000 (UTC) Received: by lists.denx.de (Postfix, from userid 105) id A9E7EC21F13; Thu, 18 Jul 2019 07:34:57 +0000 (UTC) Received: from mail-pl1-f196.google.com (mail-pl1-f196.google.com [209.85.214.196]) by lists.denx.de (Postfix) with ESMTPS id 72B11C21F58 for ; Thu, 18 Jul 2019 07:34:53 +0000 (UTC) Received: by mail-pl1-f196.google.com with SMTP id c14so13381379plo.0 for ; Thu, 18 Jul 2019 00:34:53 -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=NPAfRjsxOHVDHFZ1biCSgwnhpMt/C+RNeY56Tbr6WB0=; b=Uu3um2Z1GuN7d8lmDGORT2uX1bINHKDcVeOY62Y0N0bNHmrUa0lvPTO7ayRthU7z9Y U2dGlbDwsfUzOwU/fS8dro3p2FLH44ZiQOF+bh+FdvEWo/kWqjNEYQu/wjkB72/PeVdM G2IXb/kWH7VKwfK50Eh9HwJ3jaSH97aZzPnnS82H44+OIavlcdYHkE+ViRhMYPqcvXYY 82NtmSeDlIHTp/8laWzYnBq27NkJ50VehoJK7pf7GtzQ3hr9kfApTvYgGHFE+qq3ypVV fKDvhJMrHLjuwff2enWPx2uCBXctwCruMtDRd+WyIvVbd7n4IcbfR25z+OiPk5T3h+An pONA== 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=NPAfRjsxOHVDHFZ1biCSgwnhpMt/C+RNeY56Tbr6WB0=; b=GoMiAw+Ls4/l3Cr/4A1EV1q8XD+95B28681TFCGpXI+0WhXGYzLrup76eyS/SexXwE vYish3HpCfWzdgaoMOPkbWxB6gqkGf1ASA79ykk3nRTL/U/hfVZBYHI1IXDFm55LLTBJ jBhYRsQdzKWIbFj01fsGYeFVOHK8OoGaE315I7yms8tS/abe5fgIQGG9gzEL+K4yIuoa jId2T7kuQoLfVQlBXSyLU27IdJbskolMsIfzixjMl+ONBrpyoZ7hP0XTBNg21LlNuWw7 7H7lXYY1M4QB/Fb1jQ8gGWcEJZtSsNZz+sCGpyEvxmg3VJV6MHWqyEcEQBKHYLh4B/g1 PhEg== X-Gm-Message-State: APjAAAUBnG5SfiwTPGPWYwShGG+U7Lab90lqztII9Ljd2BnI83BJ6ogt WpcGeQrBWrpbCD5qFxjROmc= X-Google-Smtp-Source: APXvYqyS2RS9hEjlziT1ZumafBtVgqsVvD1GAnHimZYBb1w0NwUB8aVy4ViuFCQmfbexU0+m2DuaqQ== X-Received: by 2002:a17:902:4401:: with SMTP id k1mr25025673pld.193.1563435292086; Thu, 18 Jul 2019 00:34:52 -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.51 (version=TLS1 cipher=AES128-SHA bits=128/128); Thu, 18 Jul 2019 00:34:51 -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:55 -0700 Message-Id: <1563435275-22326-11-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 10/50] doc: driver-model: Convert of-plat.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/index.rst | 1 + doc/driver-model/{of-plat.txt => of-plat.rst} | 193 ++++++++++++++------------ 2 files changed, 106 insertions(+), 88 deletions(-) rename doc/driver-model/{of-plat.txt => of-plat.rst} (65%) diff --git a/doc/driver-model/index.rst b/doc/driver-model/index.rst index ff9b183..d1c19a4 100644 --- a/doc/driver-model/index.rst +++ b/doc/driver-model/index.rst @@ -12,3 +12,4 @@ Driver Model i2c-howto livetree migration + of-plat diff --git a/doc/driver-model/of-plat.txt b/doc/driver-model/of-plat.rst similarity index 65% rename from doc/driver-model/of-plat.txt rename to doc/driver-model/of-plat.rst index 0109ec5..0d3cd8c 100644 --- a/doc/driver-model/of-plat.txt +++ b/doc/driver-model/of-plat.rst @@ -1,5 +1,7 @@ -Driver Model Compiled-in Device Tree / Platform Data -==================================================== +.. SPDX-License-Identifier: GPL-2.0+ + +Compiled-in Device Tree / Platform Data +======================================= Introduction @@ -40,36 +42,36 @@ There are many problems with this features. It should only be used when strictly necessary. Notable problems include: - Device tree does not describe data types. But the C code must define a - type for each property. These are guessed using heuristics which - are wrong in several fairly common cases. For example an 8-byte value - is considered to be a 2-item integer array, and is byte-swapped. A - boolean value that is not present means 'false', but cannot be - included in the structures since there is generally no mention of it - in the device tree file. + type for each property. These are guessed using heuristics which + are wrong in several fairly common cases. For example an 8-byte value + is considered to be a 2-item integer array, and is byte-swapped. A + boolean value that is not present means 'false', but cannot be + included in the structures since there is generally no mention of it + in the device tree file. - Naming of nodes and properties is automatic. This means that they follow - the naming in the device tree, which may result in C identifiers that - look a bit strange. + the naming in the device tree, which may result in C identifiers that + look a bit strange. - It is not possible to find a value given a property name. Code must use - the associated C member variable directly in the code. This makes - the code less robust in the face of device-tree changes. It also - makes it very unlikely that your driver code will be useful for more - than one SoC. Even if the code is common, each SoC will end up with - a different C struct name, and a likely a different format for the - platform data. + the associated C member variable directly in the code. This makes + the code less robust in the face of device-tree changes. It also + makes it very unlikely that your driver code will be useful for more + than one SoC. Even if the code is common, each SoC will end up with + a different C struct name, and a likely a different format for the + platform data. - The platform data is provided to drivers as a C structure. The driver - must use the same structure to access the data. Since a driver - normally also supports device tree it must use #ifdef to separate - out this code, since the structures are only available in SPL. + must use the same structure to access the data. Since a driver + normally also supports device tree it must use #ifdef to separate + out this code, since the structures are only available in SPL. - Correct relations between nodes are not implemented. This means that - parent/child relations (like bus device iteration) do not work yet. - Some phandles (those that are recognised as such) are converted into - a pointer to platform data. This pointer can potentially be used to - access the referenced device (by searching for the pointer value). - This feature is not yet implemented, however. + parent/child relations (like bus device iteration) do not work yet. + Some phandles (those that are recognised as such) are converted into + a pointer to platform data. This pointer can potentially be used to + access the referenced device (by searching for the pointer value). + This feature is not yet implemented, however. How it works @@ -78,30 +80,34 @@ How it works The feature is enabled by CONFIG OF_PLATDATA. This is only available in SPL/TPL and should be tested with: - #if CONFIG_IS_ENABLED(OF_PLATDATA) +.. code-block:: c + + #if CONFIG_IS_ENABLED(OF_PLATDATA) A new tool called 'dtoc' converts a device tree file either into a set of struct declarations, one for each compatible node, and a set of U_BOOT_DEVICE() declarations along with the actual platform data for each device. As an example, consider this MMC node: - sdmmc: dwmmc@ff0c0000 { - compatible = "rockchip,rk3288-dw-mshc"; - clock-freq-min-max = <400000 150000000>; - clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>, - <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>; - clock-names = "biu", "ciu", "ciu_drv", "ciu_sample"; - fifo-depth = <0x100>; - interrupts = ; - reg = <0xff0c0000 0x4000>; - bus-width = <4>; - cap-mmc-highspeed; - cap-sd-highspeed; - card-detect-delay = <200>; - disable-wp; - num-slots = <1>; - pinctrl-names = "default"; - pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>; +.. code-block:: none + + sdmmc: dwmmc@ff0c0000 { + compatible = "rockchip,rk3288-dw-mshc"; + clock-freq-min-max = <400000 150000000>; + clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>, + <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>; + clock-names = "biu", "ciu", "ciu_drv", "ciu_sample"; + fifo-depth = <0x100>; + interrupts = ; + reg = <0xff0c0000 0x4000>; + bus-width = <4>; + cap-mmc-highspeed; + cap-sd-highspeed; + card-detect-delay = <200>; + disable-wp; + num-slots = <1>; + pinctrl-names = "default"; + pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>; vmmc-supply = <&vcc_sd>; status = "okay"; u-boot,dm-pre-reloc; @@ -112,52 +118,59 @@ Some of these properties are dropped by U-Boot under control of the CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce the following C struct declaration: -struct dtd_rockchip_rk3288_dw_mshc { - fdt32_t bus_width; - bool cap_mmc_highspeed; - bool cap_sd_highspeed; - fdt32_t card_detect_delay; - fdt32_t clock_freq_min_max[2]; - struct phandle_1_arg clocks[4]; - bool disable_wp; - fdt32_t fifo_depth; - fdt32_t interrupts[3]; - fdt32_t num_slots; - fdt32_t reg[2]; - fdt32_t vmmc_supply; -}; +.. code-block:: c + + struct dtd_rockchip_rk3288_dw_mshc { + fdt32_t bus_width; + bool cap_mmc_highspeed; + bool cap_sd_highspeed; + fdt32_t card_detect_delay; + fdt32_t clock_freq_min_max[2]; + struct phandle_1_arg clocks[4]; + bool disable_wp; + fdt32_t fifo_depth; + fdt32_t interrupts[3]; + fdt32_t num_slots; + fdt32_t reg[2]; + fdt32_t vmmc_supply; + }; and the following device declaration: -static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = { - .fifo_depth = 0x100, - .cap_sd_highspeed = true, - .interrupts = {0x0, 0x20, 0x4}, - .clock_freq_min_max = {0x61a80, 0x8f0d180}, - .vmmc_supply = 0xb, - .num_slots = 0x1, - .clocks = {{&dtv_clock_controller_at_ff760000, 456}, - {&dtv_clock_controller_at_ff760000, 68}, - {&dtv_clock_controller_at_ff760000, 114}, - {&dtv_clock_controller_at_ff760000, 118}}, - .cap_mmc_highspeed = true, - .disable_wp = true, - .bus_width = 0x4, - .u_boot_dm_pre_reloc = true, - .reg = {0xff0c0000, 0x4000}, - .card_detect_delay = 0xc8, -}; -U_BOOT_DEVICE(dwmmc_at_ff0c0000) = { - .name = "rockchip_rk3288_dw_mshc", - .platdata = &dtv_dwmmc_at_ff0c0000, - .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000), -}; +.. code-block:: c + + static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = { + .fifo_depth = 0x100, + .cap_sd_highspeed = true, + .interrupts = {0x0, 0x20, 0x4}, + .clock_freq_min_max = {0x61a80, 0x8f0d180}, + .vmmc_supply = 0xb, + .num_slots = 0x1, + .clocks = {{&dtv_clock_controller_at_ff760000, 456}, + {&dtv_clock_controller_at_ff760000, 68}, + {&dtv_clock_controller_at_ff760000, 114}, + {&dtv_clock_controller_at_ff760000, 118}}, + .cap_mmc_highspeed = true, + .disable_wp = true, + .bus_width = 0x4, + .u_boot_dm_pre_reloc = true, + .reg = {0xff0c0000, 0x4000}, + .card_detect_delay = 0xc8, + }; + + U_BOOT_DEVICE(dwmmc_at_ff0c0000) = { + .name = "rockchip_rk3288_dw_mshc", + .platdata = &dtv_dwmmc_at_ff0c0000, + .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000), + }; The device is then instantiated at run-time and the platform data can be accessed using: - struct udevice *dev; - struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev); +.. code-block:: c + + struct udevice *dev; + struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev); This avoids the code overhead of converting the device tree data to platform data in the driver. The ofdata_to_platdata() method should @@ -173,7 +186,9 @@ each 'compatible' string. Where a node has multiple compatible strings, a #define is used to make them equivalent, e.g.: -#define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc +.. code-block:: c + + #define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc Converting of-platdata to a useful form @@ -204,6 +219,8 @@ ofdata_to_platdata() method and wrapped with #if. For example: +.. code-block:: c + #include struct mmc_platdata { @@ -313,12 +330,12 @@ This is an implementation of an idea by Tom Rini . Future work ----------- - Consider programmatically reading binding files instead of device tree - contents + contents - Complete the phandle feature - Move to using a full Python libfdt module --- -Simon Glass -Google, Inc -6/6/16 -Updated Independence Day 2016 + +.. Simon Glass +.. Google, Inc +.. 6/6/16 +.. Updated Independence Day 2016