doc: dts: add design goals defining the scope of DT

Add a page describing the high-level design goals for how Zephyr
should use DT, with examples and counter-examples from current
practice.

Add a TBD section for code generation. It's not clear (to me at least)
where the discussion on that has landed.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>

doc/guides/dts/design.rst

@@ -0,0 +1,92 @@
+.. _dt-design:
+
+Design goals
+############
+
+Zephyr's use of devicetree has evolved significantly over time, and further
+changes are expected. The following are the general design goals, along with
+specific examples about how they impact Zephyr's source code, and areas where
+more work remains to be done.
+
+Single source for all hardware information
+******************************************
+
+Zephyr shall obtain its hardware descriptions exclusively from devicetree.
+
+Examples
+========
+
+- New device drivers shall use :ref:`existence macros <dt-existence-macros>` to
+  determine whether a device is available and enabled.
+
+- In-tree sample applications shall use :ref:`aliases <dt-alias-chosen>` to
+  determine which of multiple possible generic devices of a given type will be
+  used in the current build. For example, the :ref:`blinky-sample` uses this to
+  determine the LED to blink.
+
+Example remaining work
+======================
+
+- Zephyr's :ref:`sanitycheck_script` currently uses :file:`board.yaml` files to
+  determine the hardware supported by a board. This should be obtained from
+  devicetree instead.
+
+- Various device drivers currently use Kconfig to determine which instances of a
+  particular compatible are enabled. This can and should be done with devicetree
+  overlays instead.
+
+- Board-level documentation still contains tables of hardware support which are
+  generated and maintained by hand. This can and should be obtained from the
+  board level devicetree instead.
+
+- Runtime determination of ``struct device`` relationships should be done using
+  information obtained from devicetree, e.g. for device power management.
+
+- Pin muxing and pin control, at least at boot time, should be accomplished via
+  devicetree.
+
+Source compatibility with other operating systems
+*************************************************
+
+Zephyr's devicetree tooling is based on a generic layer which is interoperable
+with other devicetree users, such as the Linux kernel.
+
+Zephyr's binding language *semantics* can support Zephyr-specific attributes,
+but shall not express Zephyr-specific relationships.
+
+Examples
+========
+
+- Zephyr's devicetree source parser, :ref:`dtlib.py <dt-scripts>`, is
+  source-compatible with other tools like `dtc`_ in both directions:
+  :file:`dtlib.py` can parse ``dtc`` output, and ``dtc`` can parse
+  :file:`dtlib.py` output.
+
+- Zephyr's "extended dtlib" library, :file:`edtlib.py`, shall not include
+  Zephyr-specific features. Its purpose is to provide a higher-level view of the
+  devicetree for common elements like interrupts and buses.
+
+  Only the high-level :file:`gen_defines.py` script, which is built on top of
+  :file:`edtlib.py`, contains Zephyr-specific knowledge and features.
+
+.. _dtc: https://git.kernel.org/pub/scm/utils/dtc/dtc.git/about/
+
+Example remaining work
+======================
+
+- Zephyr has a custom :ref:`dt-bindings` language *syntax*. While Linux's
+  dtschema does not yet meet Zephyr's needs, we should try to follow what it is
+  capable of representing in Zephyr's own bindings.
+
+- Due to namespace collisions and inflexibility in the bindings language,
+  Zephyr-specific :ref:`dt-macros` do not support the full set of possible node
+  paths and bindings supported by Linux.
+
+- Devicetree source sharing between Zephyr and Linux is not done.
+
+To be determined
+****************
+
+The scope and amount of code generation for device instantiation has been the
+subject of extended discussion and prototyping without reaching a firm
+conclusion.

doc/guides/dts/index.rst

@@ -15,6 +15,7 @@ configuration.
    :maxdepth: 2
 
    intro.rst
+   design.rst
    bindings.rst
    macros.rst
    howtos.rst

doc/guides/dts/intro.rst

@@ -268,6 +268,8 @@ build/zephyr/zephyr.dts
    The final merged devicetree. This file is specifically output as a
    debugging aid, and is unused otherwise.
 
+.. _dt-scripts:
+
 The following libraries and scripts, located in :zephyr_file:`scripts/dts/`,
 are used to generate C headers from the devicetree and its bindings. Note that
 the source code has extensive comments and documentation.

doc/guides/dts/macros.rst

@@ -570,6 +570,8 @@ will get generated for ``spi-slave@0``:
    #define DT_<node>_CS_GPIOS_CONTROLLER    "GPIOA"
    #define DT_<node>_CS_GPIOS_PIN           1
 
+.. _dt-existence-macros:
+
 Compatible-string and node existence macros
 *******************************************