From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 00F2AC636D3 for ; Wed, 1 Feb 2023 22:56:11 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id C1F4385DC6; Wed, 1 Feb 2023 23:55:44 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; unprotected) header.d=chromium.org header.i=@chromium.org header.b="nEWfHs6i"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 5669685D8C; Wed, 1 Feb 2023 23:55:26 +0100 (CET) Received: from mail-il1-x12c.google.com (mail-il1-x12c.google.com [IPv6:2607:f8b0:4864:20::12c]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 9D7DA85D8C for ; Wed, 1 Feb 2023 23:54:36 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=sjg@chromium.org Received: by mail-il1-x12c.google.com with SMTP id k12so93172ilv.10 for ; Wed, 01 Feb 2023 14:54:36 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=fejzi5Dh0QvcbrXU2PDi5FFVTpWF813AiekwInzGBGs=; b=nEWfHs6iu+NvUHmKlG/dKauQHRGnLc4YqdzSl0SKtYwE2tZMkwyX/4NHhhPl1K9lVe fXnkaNteBpqQYhKz5pPiNPFG191Sp8AhDf3dO32GOGR0BQ+M64EEXYBe05IDUSApgO2J Dti1cxONd1+UBuq2hKCtFZpuW6qFbGvZZqbMg= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=fejzi5Dh0QvcbrXU2PDi5FFVTpWF813AiekwInzGBGs=; b=dJeZweLtZua/kSiYClzaSEuDQpYk2Z0POsiELoSWDpwXE9spZBl9sTAMI9/2YoX9ME EdLk4ZEGOyyhZAqskillxe6xvg8TOnPG1y2BnxR/qhrOrLyesp+DmRIvBVdoYMJluGBn AuWZK01FCqujtePr1QJv9QDPA19x0x5Waq9MPzAcTMIorikJwyWW3TdOOLCUjhQLacBS nZFEQ6jmeR9FtrtnrPhENrFbY/r1witBaTHMtAPgTKJLkaw7IuQ3wexeUJtxa/sphIKW ti1xb5gYW15lzadmM0Qkux0Mcg1wtKj3uE3VzB/EE0FHMgaOyh6P91lcBcnrl2gQWu5G xfUA== X-Gm-Message-State: AO0yUKWtztXmNUF0d+pUlVOppxSkATMn8QhmxihxIQf/GLxJoigEl/sj Y73W+1vqSj3zQVTN1nl/FXWysga10WSSHMU1 X-Google-Smtp-Source: AK7set/9jPfhbv/Tq//nfTaHVanfI0Q+X2EyrW75TYAErqfffObwfGCUebUVMK45hLAbmsCn/tQwSg== X-Received: by 2002:a05:6e02:1a68:b0:30f:5fb7:117e with SMTP id w8-20020a056e021a6800b0030f5fb7117emr3473376ilv.2.1675292074944; Wed, 01 Feb 2023 14:54:34 -0800 (PST) Received: from kea.bld.corp.google.com ([2620:15c:183:200:1fda:cca0:9a42:148c]) by smtp.gmail.com with ESMTPSA id b21-20020a029a15000000b00374fa5b600csm6964474jal.0.2023.02.01.14.54.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 01 Feb 2023 14:54:34 -0800 (PST) From: Simon Glass To: u-boot@lists.denx.de Cc: U-Boot Custodians , Tom Rini , Simon Glass Subject: [PATCH v3 1/8] schemas: Add schema for U-Boot driver model 'phase tags' Date: Wed, 1 Feb 2023 15:54:21 -0700 Message-Id: <20230201225428.2001161-2-sjg@chromium.org> X-Mailer: git-send-email 2.39.1.456.gfc5497dd1b-goog In-Reply-To: <20230201225428.2001161-1-sjg@chromium.org> References: <20230201225428.2001161-1-sjg@chromium.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.6 at phobos.denx.de X-Virus-Status: Clean U-Boot has some particular challenges with device tree and devices: - U-Boot has multiple build phases, such as a Secondary Program Loader (SPL) phase which typically runs in a pre-SDRAM environment where code and data space are limited. In particular, there may not be enough space for the full device tree blob. U-Boot uses various automated techniques to reduce the size from perhaps 40KB to 3KB. It is not always possible to handle these tags entirely at build time, since U-Boot proper must have the full device tree, even though we do not want it to process all nodes until after relocation. - Some U-Boot phases needs to run before the clocks are properly set up, where the CPU may be running very slowly. Therefore it is important to bind only those devices which are actually needed in that phase - U-Boot uses lazy initialisation for its devices, with 'bind' and 'probe' being separate steps. Even if a device is bound, it is not actually probed until it is used. This is necessary to keep the boot time reasonable, e.g. to under a second The phases of U-Boot in order are: TPL, VPL, SPL, U-Boot (first pre-relocation, then post-relocation). ALl but the last two are optional. For the above reasons, U-Boot only includes the full device tree in the final 'U-Boot proper' build. Even then, before relocation U-Boot only processes nodes which are marked as being needed. For this to work, U-Boot's driver model[1] provides a way to mark device tree nodes as applicable for a particular phase. This works by adding a tag to the node, e.g.: cru: clock-controller@ff760000 { bootph-all; compatible = "rockchip,rk3399-cru"; reg = <0x0 0xff760000 0x0 0x1000>; rockchip,grf = <&grf>; #clock-cells = <1>; #reset-cells = <1>; ... }; Here the "bootph-all" tag indicates that the node must be present in all phases, since the clock driver is required. There has been discussion over the years about whether this could be done in a property instead, e.g. options { bootph-all = <&cru> <&gpio_a> ...; ... }; Some problems with this: - we need to be able to merge several such tags from different .dtsi files since many boards have their own specific requirements - it is hard to find and cross-reference the affected nodes - it is more error-prone - it requires significant tool rework in U-Boot, including fdtgrep and the build system - is harder (slower, more code) to process since it involves scanning another node/property to find out what to do with a particular node - we don't want to add phandle arguments to the above since we are referring, e.g., to the clock device as a whole, not a paricular clock - the of-platdata feature[2], which converts device tree to C for even more constrained environments, would need to become aware of the /options node There is also the question about whether this needs to be U-Boot-specific, or whether the tags could be generic. From what I can tell, U-Boot is the only bootloader which seriously attempts to use a runtime device tree in all cases. For this version, an attempt is made to name the phases in a generic manner. It should also be noted that the approach provided here has stood the test of time, used in U-Boot for 8 years so far. So add the schema for this. This will allow a major class of schema exceptions to be dropped from the U-Boot source tree. This has been applied upstream[3] [1] https://u-boot.readthedocs.io/en/latest/develop/driver-model/index.html [2] https://u-boot.readthedocs.io/en/latest/develop/driver-model/of-plat.html [3] https://github.com/devicetree-org/dt-schema/commit/63bd847 Signed-off-by: Simon Glass --- (no changes since v2) Changes in v2: - Add binding document doc/device-tree-bindings/bootph.yaml | 88 ++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 doc/device-tree-bindings/bootph.yaml diff --git a/doc/device-tree-bindings/bootph.yaml b/doc/device-tree-bindings/bootph.yaml new file mode 100644 index 00000000000..a3ccf06efa7 --- /dev/null +++ b/doc/device-tree-bindings/bootph.yaml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: BSD-2-Clause +# Copyright 2022 Google LLC +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bootph.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Boot-phase-specific device nodes + +maintainers: + - Simon Glass + +description: | + Some programs run in memory-constrained environments yet want to make use + of device tree. + + The full device tree is often quite large relative to the available memory + of a boot phase, so cannot fit into every phase of the boot process. Even + when memory is not a problem, some phases may wish to limit which device + nodes are present, so as to reduce execution time. + + This binding supports adding tags to device tree nodes to allow them to be + marked according to the phases where they should be included. + + Without any tags, nodes are included only in the final phase, where all + memory is available. Any untagged nodes are dropped from previous phases + and are ignored before the final phase is reached. + + The build process produces a separate executable for each phase. It can + use fdtgrep to drop any nodes which are not needed for a particular build. + For example, the pre-sram build will drop any nodes which are not marked + with bootph-pre-sram or bootph-all tags. + + Note that phase builds may drop the tags, since they have served their + purpose by that point. So when looking at phase-specific device tree files + you may not see these tags. + + Multiple tags can be used in the same node. + + Tags in a child node are implied to be present in all parent nodes as well. + This is important, since some missing properties (such as "ranges", or + "compatible") can cause the child node to be ignored or incorrectly + parsed. + + That said, at present, fdtgrep applies tags only to the node they are + added to, not to any parents. This means U-Boot device tree files often + add the same tag to parent nodes, rather than relying on tooling to do + this. This is a limitation of fdtgrep and it will be addressed so that + 'Linux DTs' do not need to do this. + + The available tags are described as properties below, in order of phase + execution. + +select: true + +properties: + bootph-pre-sram: + type: boolean + description: + Enable this node when SRAM is not available. This phase must set up + some SRAM or cache-as-RAM so it can obtain data/BSS space to use + during execution. + + bootph-verify: + type: boolean + description: + Enable this node in the verification step, which decides which of the + available images should be run next. + + bootph-pre-ram: + type: boolean + description: + Enable this node in the phase that sets up SDRAM. + + bootph-some-ram: + type: boolean + description: + Enable this node in the phase that is run after SDRAM is working but + before all of it is available. Some RAM is available but it is limited + (e.g. it may be split into two pieces by the location of the running + program) because the program code is not yet relocated out of the way. + + bootph-all: + type: boolean + description: + Include this node in all phases (for U-Boot see enum u_boot_phase). + +additionalProperties: true -- 2.39.1.456.gfc5497dd1b-goog