From patchwork Sat Aug 26 09:06:33 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sughosh Ganu X-Patchwork-Id: 717230 Delivered-To: patch@linaro.org Received: by 2002:a5d:688a:0:b0:317:ecd7:513f with SMTP id h10csp294766wru; Sat, 26 Aug 2023 02:07:52 -0700 (PDT) X-Google-Smtp-Source: AGHT+IFd9fAa+15mg8fOyyzuFTsKu5XnXKNvSnLeS790CoSQEtmMKqS0hnT11ueJLqYovmGoICbq X-Received: by 2002:a05:6000:1245:b0:319:8979:8fcc with SMTP id j5-20020a056000124500b0031989798fccmr15464535wrx.70.1693040872171; Sat, 26 Aug 2023 02:07:52 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1693040872; cv=none; d=google.com; s=arc-20160816; b=KA+Q9LaTHfzerS/sqnkvxxERCTLGlwQeGP4pRAetfqtU/VWUGH2irdNoXo1vaLuyfz 9tDDN9kEIozZLu7ASlg+ukqh7rmmxIcyoHRIJLg8pHGi7UPcsUQx/5gembF8WlL/kbxC QgHHN++1Fzfp8oEIBNBZZl3XH8BVvTmoaALgQkk3TUGFtme02TjLzdYmgqUI99MxlR51 zui9P2tOpFyx7gcIuAjpLsn+7OzWdYY3mvxlRjuoVZXLh2L4d9aRg163IecTgUg2t6Dd yZdtT25oopZ7ZPdFZqlE+EAttSTkkTbDU3kvWga5wYqigndCAo7UHBQgT/sEIhQjMYCE lsGw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from; bh=wfYdew0jrZYyGUHUPqDy815QX/rv6r7KRizp2bYhc28=; fh=wxXZJCQRz/XgBTfKhuJFfNV+eZ/MzU8zncY23uTJ9bU=; b=Ek93E+z3lcJXZIGEDHvXBZF5RL0Sag+Ka89WGAEAYXfDqMCWqJyG4zk9JzTPB09qbc BwOtzLym62JgIKHzeJDKRpv2BVHKf6JG5Dk9Xnxs+/lA+S1OtWz5YDfsnonhxR9GjBkU zd3VqCOxGM6bT1GpCeuJkxN5YS2Dl9IBRECwIcX1s7ip7cuBasE+7EiWaTt12wAaBuKf uldJ/DZGur+keyy2H9RfpvWFjGCokYeSITnztAlq2OoVphSK5Bfju5dyFhNsSsj+NdZ5 P0IDq2muUYtYHOYdKC23eXuiEMco6yMlfUnkY15U8rRGCxckrwACm3A/Ua8Zc1WNtHJQ TXSg== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of u-boot-bounces@lists.denx.de designates 2a01:238:438b:c500:173d:9f52:ddab:ee01 as permitted sender) smtp.mailfrom=u-boot-bounces@lists.denx.de; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from phobos.denx.de (phobos.denx.de. [2a01:238:438b:c500:173d:9f52:ddab:ee01]) by mx.google.com with ESMTPS id z6-20020a5d6546000000b003198b11feedsi13237wrv.646.2023.08.26.02.07.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 26 Aug 2023 02:07:52 -0700 (PDT) Received-SPF: pass (google.com: domain of u-boot-bounces@lists.denx.de designates 2a01:238:438b:c500:173d:9f52:ddab:ee01 as permitted sender) client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; Authentication-Results: mx.google.com; spf=pass (google.com: domain of u-boot-bounces@lists.denx.de designates 2a01:238:438b:c500:173d:9f52:ddab:ee01 as permitted sender) smtp.mailfrom=u-boot-bounces@lists.denx.de; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 0F30586B19; Sat, 26 Aug 2023 11:07:17 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Received: by phobos.denx.de (Postfix, from userid 109) id 463DE86B19; Sat, 26 Aug 2023 11:07:16 +0200 (CEST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-1.2 required=5.0 tests=BAYES_00,SPF_HELO_NONE, SPF_SOFTFAIL autolearn=no autolearn_force=no version=3.4.2 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by phobos.denx.de (Postfix) with ESMTP id A8D4086B47 for ; Sat, 26 Aug 2023 11:07:12 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: phobos.denx.de; spf=fail smtp.mailfrom=sughosh.ganu@linaro.org Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 68327D75; Sat, 26 Aug 2023 02:07:52 -0700 (PDT) Received: from a076522.blr.arm.com (a076522.blr.arm.com [10.162.46.7]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 2772D3F740; Sat, 26 Aug 2023 02:07:09 -0700 (PDT) From: Sughosh Ganu To: u-boot@lists.denx.de Cc: Tom Rini , Heinrich Schuchardt , Ilias Apalodimas , Simon Glass , Sughosh Ganu Subject: [RFC PATCH 5/5] doc: Add a document for non-compliant DT node/property removal Date: Sat, 26 Aug 2023 14:36:33 +0530 Message-Id: <20230826090633.239342-6-sughosh.ganu@linaro.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230826090633.239342-1-sughosh.ganu@linaro.org> References: <20230826090633.239342-1-sughosh.ganu@linaro.org> MIME-Version: 1.0 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.8 at phobos.denx.de X-Virus-Status: Clean Add a document explaining the need for removal of non-compliant devicetree nodes and properties. Also describe in brief, the macros that can be used for this removal. Signed-off-by: Sughosh Ganu --- .../devicetree/dt_non_compliant_purge.rst | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 doc/develop/devicetree/dt_non_compliant_purge.rst diff --git a/doc/develop/devicetree/dt_non_compliant_purge.rst b/doc/develop/devicetree/dt_non_compliant_purge.rst new file mode 100644 index 0000000000..c3a8feab5b --- /dev/null +++ b/doc/develop/devicetree/dt_non_compliant_purge.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Removal of non-compliant nodes and properties +============================================= + +The devicetree used in U-Boot might contain nodes and properties which +are specific only to U-Boot, and are not necessarily being used to +describe hardware but to pass information to U-Boot. An example of +such a property would be the public key being passed to U-Boot for +verification. + +This devicetree can then be passed to the OS. Since certain nodes and +properties are not really describing hardware, and more importantly, +these are only relevant to U-Boot, bindings for these cannot be +upstreamed into the devicetree repository. There have been instances +of attempts being made to upstream such bindings, and these deemed not +fit for upstreaming. Not having a binding for these nodes and +properties means that the devicetree fails the schema compliance tests +[1]. This also means that the platform cannot get certifications like +SystemReady [2] which, among other things require a devicetree which +passes the schema compliance tests. + +For such nodes and properties, it has been suggested by the devicetree +maintainers that the right thing to do is to remove them from the +devicetree before it gets passed on to the OS [3]. + +Removing nodes/properties +------------------------- + +In U-Boot, this is been done through adding information on such nodes +and properties in a list. The entire node can be deleted, or a +specific property under a node can be deleted. The list of such nodes +and properties is generated at compile time, and the function to purge +these can be invoked through a EVT_FT_FIXUP event notify call. + +For deleting a node, this can be done by declaring a macro:: + + DT_NON_COMPLIANT_PURGE(fwu_mdata) = { + .node_path = "/fwu-mdata", + }; + +Similarly, for deleting a property under a node, that can be done by +specifying the property name:: + + DT_NON_COMPLIANT_PURGE(capsule_key) = { + .node_path = "/signature", + .prop = "capsule-key", + }; + +In the first example, the entire node with path /fwu-mdata will be +removed. In the second example, the property capsule-key +under /signature node will be removed. + +Similarly, a list of nodes and properties can be specified using the +following macro:: + + DT_NON_COMPLIANT_PURGE_LIST(foo) = { + { .node_path = "/some_node", .prop = "some_bar" }, + { .node_path = "/some_node" }, + }; + +[1] - https://github.com/devicetree-org/dt-schema +[2] - https://www.arm.com/architecture/system-architectures/systemready-certification-program +[3] - https://lore.kernel.org/u-boot/CAL_JsqJN4FeHomL7z3yj0WJ9bpx1oSE7zf26L_GV2oS6cg-5qg@mail.gmail.com/