Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Sat, 6 May 2023 10:51:50 +0700
From:   Bagas Sanjaya <bagasdotme@gmail.com>
To:     Linus Walleij <linus.walleij@linaro.org>,
        Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>
Cc:     Grant Likely <grant.likely@linaro.org>, devicetree@vger.kernel.org,
        linux-kernel@vger.kernel.org,
        Linux Documentation <linux-doc@vger.kernel.org>
Subject: Re: [PATCH v2] docs: dt: Make references and mention kernel
 abstractions
Message-ID: <ZFXO1pRq4/fNw33/@debian.me>
References: <20230505-dt-docs-refresh-v2-1-56bf359c53b4@linaro.org>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
        protocol="application/pgp-signature"; boundary="4FC0DSTJcODP+zd/"
Content-Disposition: inline
In-Reply-To: <20230505-dt-docs-refresh-v2-1-56bf359c53b4@linaro.org>
Precedence: bulk


--4FC0DSTJcODP+zd/
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Fri, May 05, 2023 at 02:43:53PM +0200, Linus Walleij wrote:
> This document is named "Linux and Devicetree" so I think we
> should write a bit more about how the device tree fits into
> the Linux kernel frameworks these days after we have created
> the fwnode and swnode.
>=20

Also Cc: linux-doc list.

> +The Linux kernel supports several different hardware description
> +frameworks and DT is just one of them. The closest sibling is the
> +:ref:`Documentation/firmware-guide/acpi/index.rst ACPI`
> +DSDT (Differentiated System Description Table).
> <snipped>...
> +Further, when the DT core register devices these need to fold into the
> +Linux device driver model, which essentially means that some kind of
> +``struct device`` has to be created to match a corresponding
> +``struct device_driver``. This API can be explored in
> +detail in :ref:`Documentation/driver-api/driver-model/index.rst the driv=
er API documentation`
> +but what you need to know is that the Linux DT parser code will on its
> +own mostly spawn platform devices and AMBA devices on the platform
> +and AMBA bus respectively, and apart from that it will augment devices
> +spawn on other buses where applicable.
> +

Anchor text for :ref: links above don't mix well, so I have to override
them (also specifying intended doc target - correct me if these are wrong):

diff --git a/Documentation/devicetree/usage-model.rst b/Documentation/devic=
etree/usage-model.rst
index 37605cb549cf59..87f522d5feba81 100644
--- a/Documentation/devicetree/usage-model.rst
+++ b/Documentation/devicetree/usage-model.rst
@@ -80,8 +80,7 @@ then go read it now.  It's okay, I'll wait....
=20
 The Linux kernel supports several different hardware description
 frameworks and DT is just one of them. The closest sibling is the
-:ref:`Documentation/firmware-guide/acpi/index.rst ACPI`
-DSDT (Differentiated System Description Table).
+:doc:`DSDT (Differentiated System Description Table) from ACPI </firmware-=
guide/acpi/namespace>`.
=20
 To make it possible to write a device driver that will adapt to DT
 or other hardware description models, the kernel has grown some
@@ -101,7 +100,7 @@ Further, when the DT core register devices these need t=
o fold into the
 Linux device driver model, which essentially means that some kind of
 ``struct device`` has to be created to match a corresponding
 ``struct device_driver``. This API can be explored in
-detail in :ref:`Documentation/driver-api/driver-model/index.rst the driver=
 API documentation`
+detail in :doc:`the driver API documentation </driver-api/driver-model/ove=
rview>`
 but what you need to know is that the Linux DT parser code will on its
 own mostly spawn platform devices and AMBA devices on the platform
 and AMBA bus respectively, and apart from that it will augment devices

Thanks.

--=20
An old man doll... just what I always wanted! - Clara

--4FC0DSTJcODP+zd/
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iHUEABYKAB0WIQSSYQ6Cy7oyFNCHrUH2uYlJVVFOowUCZFXO0QAKCRD2uYlJVVFO
o1ADAP0U4Eqkto8ez70YgMni5+n70+3PXK2Djzh36Qxvq/oLfgD/ZqqHP4lXarNA
2qxmUqeGfJ78jWC2apff2dUzqklVLAw=
=2tz4
-----END PGP SIGNATURE-----

--4FC0DSTJcODP+zd/--