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 C26FFC636D3 for ; Thu, 2 Feb 2023 00:30:26 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 15C2685E60; Thu, 2 Feb 2023 01:30:24 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; secure) header.d=gmx.de header.i=@gmx.de header.b="JjNyF6jp"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 5F9EF85E55; Thu, 2 Feb 2023 01:30:22 +0100 (CET) Received: from mout.gmx.net (mout.gmx.net [212.227.15.15]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 356C385E65; Thu, 2 Feb 2023 01:30:18 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=xypron.glpk@gmx.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.de; s=s31663417; t=1675297816; bh=f/GYeRjM78nD/nJctiEayaFQXwOSWf1IsMna6Vq6vsA=; h=X-UI-Sender-Class:Date:From:To:CC:Subject:In-Reply-To:References; b=JjNyF6jpBZGRrVRPS7HY8jWChJJ0ldunLAblSXUBYu8psWX/oWjGQCzplaLkKZgKs 4x7k9XdNhx6JuMLjekB9d/B0u31sTQbyfPJJpZmoNJCkUxn6FTpjGeo25QjwdJbcz4 SyBkFHDI6ED1GnK25l5TueVd+4uY8ll+u9PREydEV1OQ41OK0AMY657+ewZHH1WebN 8If7NGASzfZbrWjMuwg2UV0rIJbmUrAPJO3OnfGVAv8S3jq8NWJkc9fNBF+WF/+r0Y sgu3axrXjNLXcjdXD6oCuoowmRSaC4JhvDTiOPiEoiliwMgHVsFKf16e9FXq21sG9T hHSLQ7eHIE4sA== X-UI-Sender-Class: 724b4f7f-cbec-4199-ad4e-598c01a50d3a Received: from [127.0.0.1] ([88.152.145.137]) by mail.gmx.net (mrgmx005 [212.227.17.190]) with ESMTPSA (Nemesis) id 1Mzhj9-1oS8Eb11ij-00vfQw; Thu, 02 Feb 2023 01:30:16 +0100 Date: Thu, 02 Feb 2023 01:30:18 +0100 From: Heinrich Schuchardt To: u-boot-custodians@lists.denx.de, Simon Glass , u-boot@lists.denx.de CC: U-Boot Custodians , Tom Rini Subject: =?US-ASCII?Q?Re=3A_=5BPATCH_v3_4/8=5D_dm=3A_doc=3A_Update_doc?= =?US-ASCII?Q?umentation_for_new_driver_model_schema?= User-Agent: K-9 Mail for Android In-Reply-To: <20230201225428.2001161-5-sjg@chromium.org> References: <20230201225428.2001161-1-sjg@chromium.org> <20230201225428.2001161-5-sjg@chromium.org> Message-ID: <178038B6-E3AC-4786-9CB1-8CD9268368BB@gmx.de> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Provags-ID: V03:K1:Rfqjc9/R27OJlQe6jkgvnd4xTRfTj0jQ2/Qfb1dSYjSrCualiyM mvZm5HZEGrPvumuu/oqHdUPY76Gew334aIZy7XZ43SCyIOQdc9t+6CSNCsEwhNYCn0S2MA/ CxELOa9nU629TiAG63GGdYPY0KlV28WipFVZUTV/GFNROP39L4Pyy699aKR0LQJqeGfzg2a IvbdgZ1jjHJmZ8sSSfSSA== UI-OutboundReport: notjunk:1;M01:P0:xJ2gEOLt1Hk=;9CQOZ+dicR2/wxrdgGEWiW26p9l 0Rv5zCJsMfIKY50wCFGQAmcFqBpJ+45hoZtEItK4b3rvqRqaU4+JyqMieP8QaIGJk4YhtpPVJ ZOLY8W6nC4WS9DWIKhT6cVBVHCtY+6PsYkZedi5KJSPwUuprwp80SOTLlWDdsx7FgjcIOfGXg 4Cjgh6OzTyQxJB6Gp9FlxBMlyhII4q1+3jYdzQDxiltO+brLvmjiRf841zTIFpCXeEPoVjgI5 Q1bEeaYLk6u1xp6cRLLVpRBXGXCVmlc5eVu48YU1XvOFbzC2UvBEwFuAG/mZk43ZO5a9JvfK0 dXQ9aLQ6ZkzNtDcXeT0JlJd2UZL6XMal2zghKdy3Cgtq3TWqATMZYqdu9cqOWqpv2zlf8eaVq Od91j7HAG5cViCEgRc15kCk+LymQk9NYcp4CPqPTNDqHy4Y8aNoz0kYse1wAnhfY8bOQSeybP q9W+Wzit/XxusI9dLj3y1tnXBjdFj2Jd7cGdmpxQnqDduGmFOYWBvQti3IM9XsiR2HF/9c6zH Pm+dj+d0LEtqOQRgLNqu5BMTVxsw5dQQoL4jvC/Lsg8RE58A6KDjz0kySU4iShA0vdNm5+Kcs UDMM3qQH8emD3o5nSK+3DzMUYYOke8fcuxP/NNS2KMhxSjdPrfM93s9mX4t45bnl2oZvt9gx1 E29fQ3oCwGodkBOvEpHyldgrjPswVoNAscobFvVfQ4BzssbHqUKQU/WOh9z7M8p+/LzE/kQVb CBggEicOoBsl34vBJNJN2CGODElxaLoaMJA5yu7wHkbInaZsd/3sXl0aGOi2t2bcLhan1HTcS 6+TdQciFWWWzomNcSt00VNlVDfDKzDTMjxl5BrCdmHc/Oxg9enmg/LN3Rh+wQnA4/yVbIVS1w 91KXTqmnwwAZgusLdtzSKd7oczMcntzrYQU6NKle36RD3xDmyCAK9NrM9bn4eTF0HpFJqy3Eq MokxcTkg9SRv+mM4KUJQIUqMvtE= 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 Am 1=2E Februar 2023 23:54:24 MEZ schrieb Simon Glass = : >Now that Linux has accepted these tags, move U-Boot over to use them=2E >Tidy up the comments and formatting, making sure that VPL is mentioned >too=2E > >Signed-off-by: Simon Glass Should all these documents be converted to yaml (in future) so that we can= test devicetrees against schemas like the kernel does? Best regards Heinrich=20 >--- > >(no changes since v1) > > doc/README=2ETPL | 4 +-- > doc/develop/driver-model/design=2Erst | 15 +++++------ > =2E=2E=2E/driver-model/fs_firmware_loader=2Erst | 4 +-- > doc/develop/driver-model/of-plat=2Erst | 25 ++++++++++--------- > doc/develop/driver-model/pci-info=2Erst | 10 ++++---- > doc/develop/driver-model/serial-howto=2Erst | 24 +++++++++--------- > doc/develop/spl=2Erst | 5 ++-- > 7 files changed, 45 insertions(+), 42 deletions(-) > >diff --git a/doc/README=2ETPL b/doc/README=2ETPL >index 72027fd692e=2E=2E95b466e4af9 100644 >--- a/doc/README=2ETPL >+++ b/doc/README=2ETPL >@@ -35,8 +35,8 @@ is set=2E Source files can be compiled for TPL with opt= ions chosen in the > board config file=2E >=20 > TPL use a small device tree (u-boot-tpl=2Edtb), containing only the node= s with >-the pre-relocation properties: 'u-boot,dm-pre-reloc' and 'u-boot,dm-tpl' >-(see README=2ESPL for details)=2E >+the pre-relocation properties: 'bootph-all' and 'bootph-pre-sram' >+(see doc/develop/spl=2Erst for details)=2E >=20 > For example: >=20 >diff --git a/doc/develop/driver-model/design=2Erst b/doc/develop/driver-m= odel/design=2Erst >index 20611e85e34=2E=2E8c2c81d7ac9 100644 >--- a/doc/develop/driver-model/design=2Erst >+++ b/doc/develop/driver-model/design=2Erst >@@ -1114,12 +1114,12 @@ Pre-Relocation Support > ---------------------- >=20 > For pre-relocation we simply call the driver model init function=2E Only >-drivers marked with DM_FLAG_PRE_RELOC or the device tree 'u-boot,dm-pre-= reloc' >+drivers marked with DM_FLAG_PRE_RELOC or the device tree 'bootph-all' > property are initialised prior to relocation=2E This helps to reduce the= driver > model overhead=2E This flag applies to SPL and TPL as well, if device tr= ee is > enabled (CONFIG_OF_CONTROL) there=2E >=20 >-Note when device tree is enabled, the device tree 'u-boot,dm-pre-reloc' >+Note when device tree is enabled, the device tree 'bootph-all' > property can provide better control granularity on which device is bound > before relocation=2E While with DM_FLAG_PRE_RELOC flag of the driver all > devices with the same driver are bound, which requires allocation a larg= e >@@ -1128,14 +1128,15 @@ only way for statically declared devices via U_BO= OT_DRVINFO() to be bound > prior to relocation=2E >=20 > It is possible to limit this to specific relocation steps, by using >-the more specialized 'u-boot,dm-spl' and 'u-boot,dm-tpl' flags >-in the device tree node=2E For U-Boot proper you can use 'u-boot,dm-pre-= proper' >+the more specialized 'bootph-pre-ram' and 'bootph-pre-sram' flags >+in the device tree node=2E For U-Boot proper you can use 'bootph-some-ra= m' > which means that it will be processed (and a driver bound) in U-Boot pro= per > prior to relocation, but will not be available in SPL or TPL=2E >=20 >-To reduce the size of SPL and TPL, only the nodes with pre-relocation pr= operties >-('u-boot,dm-pre-reloc', 'u-boot,dm-spl' or 'u-boot,dm-tpl') are keept in= their >-device trees (see README=2ESPL for details); the remaining nodes are alw= ays bound=2E >+To reduce the size of SPL and TPL, only the nodes with pre-relocation >+properties ('bootph-all', 'bootph-pre-ram' or 'bootph-pre-sram') are kep= t in >+their device trees (see README=2ESPL for details); the remaining nodes a= re >+always bound=2E >=20 > Then post relocation we throw that away and re-init driver model again= =2E > For drivers which require some sort of continuity between pre- and >diff --git a/doc/develop/driver-model/fs_firmware_loader=2Erst b/doc/deve= lop/driver-model/fs_firmware_loader=2Erst >index a44708cb4c5=2E=2Eb0823700a90 100644 >--- a/doc/develop/driver-model/fs_firmware_loader=2Erst >+++ b/doc/develop/driver-model/fs_firmware_loader=2Erst >@@ -28,7 +28,7 @@ defined in fs-loader node as shown in below: > Example for block device:: >=20 > fs_loader0: fs-loader { >- u-boot,dm-pre-reloc; >+ bootph-all; > compatible =3D "u-boot,fs-loader"; > phandlepart =3D <&mmc 1>; > }; >@@ -41,7 +41,7 @@ device, it can be described in FDT as shown in below: > Example for ubi:: >=20 > fs_loader1: fs-loader { >- u-boot,dm-pre-reloc; >+ bootph-all; > compatible =3D "u-boot,fs-loader"; > mtdpart =3D "UBI", > ubivol =3D "ubi0"; >diff --git a/doc/develop/driver-model/of-plat=2Erst b/doc/develop/driver-= model/of-plat=2Erst >index b454f7be85e=2E=2E01724ba72ce 100644 >--- a/doc/develop/driver-model/of-plat=2Erst >+++ b/doc/develop/driver-model/of-plat=2Erst >@@ -67,7 +67,7 @@ device=2E As an example, consider this MMC node: > pinctrl-0 =3D <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdm= mc_bus4>; > vmmc-supply =3D <&vcc_sd>; > status =3D "okay"; >- u-boot,dm-pre-reloc; >+ bootph-all; > }; >=20 >=20 >@@ -632,7 +632,7 @@ the devicetree=2E For example, if the devicetree has:= : > grf: grf@20008000 { > compatible =3D "rockchip,rk3188-grf", "syscon"; > reg =3D <0x20008000 0x200>; >- u-boot,dm-spl; >+ bootph-pre-ram; > }; >=20 > then dtoc looks at the first compatible string ("rockchip,rk3188-grf"), >@@ -685,21 +685,22 @@ indicates that the two nodes have different phase s= ettings=2E Looking at the > source =2Edts:: >=20 > i2c_emul: emul { >- u-boot,dm-spl; >+ bootph-pre-ram; > reg =3D <0xff>; > compatible =3D "sandbox,i2c-emul-parent"; > emul0: emul0 { >- u-boot,dm-pre-reloc; >+ bootph-all; > compatible =3D "sandbox,i2c-rtc-emul"; > #emul-cells =3D <0>; > }; > }; >=20 >-you can see that the child node 'emul0' usees 'u-boot,dm-pre-reloc', ind= icating >-that the node is present in all SPL builds, but its parent uses 'u-boot,= dm-spl' >-indicating it is only present in SPL, not TPL=2E For a TPL build, this w= ill fail >-with the above message=2E The fix is to change 'emul0' to use the same >-'u-boot,dm-spl' condition, so that it is not present in TPL, like its pa= rent=2E >+you can see that the child node 'emul0' usees 'bootph-all', indicating >+that the node is present in all SPL builds, but its parent uses >+'bootph-pre-ram' indicating it is only present in SPL, not TPL=2E For a = TPL >+build, this will fail with the above message=2E The fix is to change 'em= ul0' to >+use the same 'bootph-pre-ram' condition, so that it is not present in TP= L, >+like its parent=2E >=20 > Link errors / undefined reference > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >@@ -715,16 +716,16 @@ you get a link error, e=2Eg=2E:: > The first one indicates that the device cannot find its driver=2E This m= eans that > there is a driver 'sandbox_spl_test' but it is not compiled into the bui= ld=2E > Check your Kconfig settings to make sure it is=2E If you don't want that= in the >-build, adjust your phase settings, e=2Eg=2E by using 'u-boot,dm-spl' in = the node >+build, adjust your phase settings, e=2Eg=2E by using 'bootph-pre-ram' in= the node > to exclude it from the TPL build:: >=20 > spl-test5 { >- u-boot,dm-tpl; >+ bootph-pre-sram; > compatible =3D "sandbox,spl-test"; > stringarray =3D "tpl"; > }; >=20 >-We can drop the 'u-boot,dm-tpl' line so this node won't appear in the TP= L >+We can drop the 'bootph-pre-sram' line so this node won't appear in the = TPL > devicetree and thus the driver won't be needed=2E >=20 > The second error above indicates that the MISC uclass is needed by the d= river >diff --git a/doc/develop/driver-model/pci-info=2Erst b/doc/develop/driver= -model/pci-info=2Erst >index 251601a51e3=2E=2Edea595b6cff 100644 >--- a/doc/develop/driver-model/pci-info=2Erst >+++ b/doc/develop/driver-model/pci-info=2Erst >@@ -52,7 +52,7 @@ their drivers accordingly=2E A working example like bel= ow:: > #address-cells =3D <3>; > #size-cells =3D <2>; > compatible =3D "pci-x86"; >- u-boot,dm-pre-reloc; >+ bootph-all; > ranges =3D <0x02000000 0x0 0x40000000 0x40000000 0 0x80000000 > 0x42000000 0x0 0xc0000000 0xc0000000 0 0x20000000 > 0x01000000 0x0 0x2000 0x2000 0 0xe000>; >@@ -61,14 +61,14 @@ their drivers accordingly=2E A working example like b= elow:: > #address-cells =3D <3>; > #size-cells =3D <2>; > compatible =3D "pci-bridge"; >- u-boot,dm-pre-reloc; >+ bootph-all; > reg =3D <0x0000b800 0x0 0x0 0x0 0x0>; >=20 > topcliff@0,0 { > #address-cells =3D <3>; > #size-cells =3D <2>; > compatible =3D "pci-bridge"; >- u-boot,dm-pre-reloc; >+ bootph-all; > reg =3D <0x00010000 0x0 0x0 0x0 0x0>; >=20 > pciuart0: uart@a,1 { >@@ -77,7 +77,7 @@ their drivers accordingly=2E A working example like bel= ow:: > "pciclass,070002", > "pciclass,0700", > "x86-uart"; >- u-boot,dm-pre-reloc; >+ bootph-all; > reg =3D <0x00025100 0x0 0x0 0x0 0x0 > 0x01025110 0x0 0x0 0x0 0x0>; > =2E=2E=2E=2E=2E=2E >@@ -98,7 +98,7 @@ bus hierarchy: on the root PCI bus, there is a PCIe roo= t port which connects > to a downstream device Topcliff chipset=2E Inside Topcliff chipset, it h= as a > PCIe-to-PCI bridge and all the chipset integrated devices like the PCI U= ART > device are on the PCI bus=2E Like other devices in the device tree, if w= e want >-to bind PCI devices before relocation, "u-boot,dm-pre-reloc" must be dec= lared >+to bind PCI devices before relocation, "bootph-all" must be declared > in each of these nodes=2E >=20 > If PCI devices are not listed in the device tree, U_BOOT_PCI_DEVICE can = be used >diff --git a/doc/develop/driver-model/serial-howto=2Erst b/doc/develop/dr= iver-model/serial-howto=2Erst >index 5b1d57d83a8=2E=2E17b53e3cabf 100644 >--- a/doc/develop/driver-model/serial-howto=2Erst >+++ b/doc/develop/driver-model/serial-howto=2Erst >@@ -62,7 +62,7 @@ what you need=2E U-Boot automatically includes these fi= les: see :ref:`dttweaks`=2E > Here are some things you might need to consider: >=20 > 1=2E The serial driver itself needs to be present before relocation, so = that the >- U-Boot banner appears=2E Make sure it has a u-boot,dm-pre-reloc tag i= n the device >+ U-Boot banner appears=2E Make sure it has a bootph-all tag in the dev= ice > tree, so that the serial driver is bound when U-Boot starts=2E >=20 > For example, on iMX8:: >@@ -75,11 +75,11 @@ Here are some things you might need to consider: > put this in your xxx-u-boot=2Edtsi file:: >=20 > &lpuart3 { >- u-boot,dm-pre-proper; >+ bootph-some-ram; > }; >=20 > 2=2E If your serial port requires a particular pinmux configuration, you= may need >- a pinctrl driver=2E This needs to have a u-boot,dm-pre-reloc tag also= =2E Take care >+ a pinctrl driver=2E This needs to have a bootph-all tag also=2E Take = care > that any subnodes have the same tag, if they are needed to make the c= orrect > pinctrl available=2E >=20 >@@ -107,15 +107,15 @@ Here are some things you might need to consider: > parents, so put this in your xxx-u-boot=2Edtsi file:: >=20 > &pinctrl { >- u-boot,dm-pre-reloc; >+ bootph-all; > }; >=20 > &uart2 { >- u-boot,dm-pre-reloc; >+ bootph-all; > }; >=20 > &uart2_xfer { >- u-boot,dm-pre-reloc; >+ bootph-all; > }; >=20 > 3=2E The same applies to power domains=2E For example, if a particular p= ower domain >@@ -125,11 +125,11 @@ Here are some things you might need to consider: > For example, on iMX8, put this in your xxx-u-boot=2Edtsi file:: >=20 > &pd_dma { >- u-boot,dm-pre-proper; >+ bootph-some-ram; > }; >=20 > &pd_dma_lpuart3 { >- u-boot,dm-pre-proper; >+ bootph-some-ram; > }; >=20 > 4=2E The same applies to clocks, in the same way=2E Make sure that when = your driver >@@ -168,10 +168,10 @@ some customisation=2E > Serial in SPL > ------------- >=20 >-A similar process is needed in SPL, but in this case the u-boot,dm-spl o= r >-u-boot,dm-tpl tags are used=2E Add these in the same way as above, to en= sure that >-the SPL device tree contains the required nodes (see spl/u-boot-spl=2Edt= b for >-what it actually contains)=2E >+A similar process is needed in SPL, but in this case the bootph-pre-ram = or >+bootph-pre-sram tags are used=2E Add these in the same way as above, to = ensure >+that the SPL device tree contains the required nodes (see spl/u-boot-spl= =2Edtb >+for what it actually contains)=2E >=20 > Removing old code > ----------------- >diff --git a/doc/develop/spl=2Erst b/doc/develop/spl=2Erst >index aec7b562faa=2E=2E3d1bff81fcd 100644 >--- a/doc/develop/spl=2Erst >+++ b/doc/develop/spl=2Erst >@@ -113,13 +113,14 @@ with: >=20 > - the mandatory nodes (/alias, /chosen, /config) > - the nodes with one pre-relocation property: >- 'u-boot,dm-pre-reloc' or 'u-boot,dm-spl' >+ 'bootph-all' or 'bootph-pre-ram' >=20 > fdtgrep is also used to remove: >=20 > - the properties defined in CONFIG_OF_SPL_REMOVE_PROPS > - all the pre-relocation properties >- ('u-boot,dm-pre-reloc', 'u-boot,dm-spl' and 'u-boot,dm-tpl') >+ ('bootph-all', 'bootph-pre-ram' (SPL), 'bootph-pre-sram' (TPL) and >+ 'bootph-verify' (TPL)) >=20 > All the nodes remaining in the SPL devicetree are bound > (see doc/driver-model/design=2Erst)=2E