Re: [PATCH v2] docs: dt: Make references and mention kernel abstractions

[Bagas Sanjaya <bagasdotme@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2912 bytes --]

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.
> 

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 driver 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/devicetree/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....
 
 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>`.
 
 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 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 driver API documentation`
+detail in :doc:`the driver API documentation </driver-api/driver-model/overview>`
 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.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]