Add Petalinux/meta-adi Device Tree Information (#9)

Added documentation aimed to provide more details when working with device trees in Petalinux with meta-adi.
The documentation provides a basic overview of meta-adi's device tree process, and procedures to perform the following:
 - Adjust a built-in device tree via system-user.dtsi
 - Add a custom device tree file to meta-user, but still leverage meta-adi process
 - Bypass meta-adi's device tree recipe, and use the Petalinux DTG for device tree, while still using the ADI kernel.

Signed-off-by: Brent Kowal <[email protected]>

.gitignore

@@ -3,3 +3,4 @@ _build
 repos
 docs-mono
 Session.vim
+venv

docs/linux/kernel/petalinux-dts/index.rst

@@ -0,0 +1,70 @@
+.. _petalinux petalinux-dts:
+
+Petalinux Device Trees
+======================
+
+Petalinux is Xilinx's flavor of Linux based on the Yocto project.  One of the
+unique pieces of Petalinux is how the device tree is automatically generated
+based on the imported XSA/HDF file, using Xilinx's Device Tree Generator (DTG).
+The generated device tree includes nodes for the PS as well as nodes for the
+Xilinx blocks located in the PL.  The DTG regenerates the device tree on each
+build, which makes it difficult to edit the .dts files directly for modification.
+Further, the PL nodes may conflict with Linux device drivers which may access
+the FPGA blocks.  This is especially a problem for ADI's provided reference
+designs which use IIO based drivers for accessing FPGA IP.
+
+For *meta-adi*, the work around for device trees is to effectively be a
+man-in-the-middle during the build process, overwriting the auto-generated
+device tree.  During the ``do_configure()`` stage, the device tree recipe of the
+*meta-adi* layer will perform the following actions:
+
+#. Replace the DTG generated system-top.dts with the specified device tree from
+   the ADI Kernel source tree.
+#. The DTG generated pl.dtsi file will then be included to capture the FPGA
+   block device nodes.
+#. The ADI specific pl-delete-nodes file, which removes any duplicates between
+   the DTG generated PL nodes and the ones specified by the selected device tree,
+   is added.
+#. Finally, the *meta-user* system-user.dtsi is included to allow modification of
+   the tree by the user.
+
+A high-level view of the final *meta-adi* device tree looks like the following:
+
+.. image:: meta-adi-dts-order.drawio.svg
+
+Device Tree Modifications
+-------------------------
+With Petalinux and *meta-adi*, there are several methods of modifying the device
+tree contents for your application. The following breaks down a few approaches
+as well as recommended use cases:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Method
+     - Description
+     - Use Case
+   * - :doc:`system-user.dtsi <petalinux-system-user>`
+     - Add and modify nodes of a ADI provided device tree through the system-user.dtsi
+       file
+     - Working with a standard evaluation kit and baseline reference design, with
+       minimal device tree adjustments.
+   * - :doc:`meta-adi and custom dts file <petalinux-custom-dts>`
+     - Use a custom .dts file as the top of the device tree hierarchy, but still
+       have access to the dtsi files available in the ADI Kernel source tree
+     - Working with a standard evaluation kit and baseline reference design, with
+       significant additional device nodes, or the breadth of changes are too
+       great to be done in system-user.dtsi to maintain an easy to follow update.
+       *This can also be used with custom hardware*
+   * - :doc:`Bypass meta-adi, Petalinux DTG <petalinux-meta-adi-bypass>`
+     - Start with a trimmed down device tree generated by the DTG, with custom
+       capabilities added.  The *meta-adi* device tree recipe is bypassed,
+       leveraging the DTG output as-is.
+     - This may be ideal when working with custom hardware without an existing
+       device tree in kernel source.
+
+.. toctree::
+   :hidden:
+   :glob:
+
+   *

docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio

@@ -0,0 +1,34 @@
+<mxfile host="Electron" agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/25.0.2 Chrome/128.0.6613.186 Electron/32.2.5 Safari/537.36" version="25.0.2">
+  <diagram name="Page-1" id="yhlp1mm2UpZfjMkueRri">
+    <mxGraphModel dx="1434" dy="854" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="42-o1ljI3i1nVvcHeXlm-1" value="Reference design dts file" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#1ba1e2;fontColor=#ffffff;strokeColor=#006EAF;strokeWidth=3;" vertex="1" parent="1">
+          <mxGeometry x="120" y="200" width="170" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="42-o1ljI3i1nVvcHeXlm-2" value="pl.dtsi" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d80073;fontColor=#ffffff;strokeColor=#A50040;strokeWidth=3;" vertex="1" parent="1">
+          <mxGeometry x="150" y="260" width="170" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="42-o1ljI3i1nVvcHeXlm-3" value="pl-delete-nodes-" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#008a00;fontColor=#ffffff;strokeColor=#005700;strokeWidth=3;" vertex="1" parent="1">
+          <mxGeometry x="150" y="320" width="170" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="42-o1ljI3i1nVvcHeXlm-4" value="system-user.dtsi" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#76608a;fontColor=#ffffff;strokeColor=#432D57;strokeWidth=3;" vertex="1" parent="1">
+          <mxGeometry x="150" y="380" width="170" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="42-o1ljI3i1nVvcHeXlm-5" value="Sourced from the ADI Linux kernel &lt;i&gt;i.e arch/&amp;lt;arch&amp;gt;/boot/dts&lt;/i&gt;" style="text;html=1;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="300" y="215" width="320" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="42-o1ljI3i1nVvcHeXlm-7" value="FPGA node device tree auto generated from the XSA file by Xilinx DTG" style="text;html=1;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="330" y="275" width="250" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="42-o1ljI3i1nVvcHeXlm-8" value="Sourced from meta-adi. This is unique per top level dts file, and removes duplicate FPGA nodes" style="text;html=1;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="330" y="335" width="310" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="42-o1ljI3i1nVvcHeXlm-9" value="From &lt;font face=&quot;Lucida Console&quot;&gt;project-spec/meta-user/recipes-bsp/device-tree/files&lt;/font&gt;&lt;div&gt;&lt;font face=&quot;Helvetica&quot;&gt;Allows final modification of the overall system device tree&lt;/font&gt;&lt;/div&gt;" style="text;html=1;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;fontSize=14;" vertex="1" parent="1">
+          <mxGeometry x="330" y="395" width="510" height="30" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

docs/linux/kernel/petalinux-dts/petalinux-custom-dts.rst

@@ -0,0 +1,65 @@
+.. _petalinux custom-dts:
+
+Custom Device Trees with meta-adi
+=================================
+This method of device tree modification allows for a custom dts files located
+outside of the kernel source tree, that gets incorporated in via the *meta-adi*
+device tree recipe.  This allows the flexibility and fine grained control of
+a custom device tree, while still being able to include and reference other dts
+files from the kernel source, such as a evaluation kit's base file.
+
+Procedure
+---------
+The following procedure describes how to incorporate a custom device tree file
+into the *meta-adi* device tree recipe.
+
+.. note::
+    These instructions leverage the *meta-user* layer of the project, but can easily
+    be incorporated into a custom layer if desired.
+
+#. Add your desired dts/dtsi files to the ``project-spec/meta-user/recipes-bsp/device-tree/files``
+   folder. This includes the device tree contents and pl-delete-nodes file.
+
+    .. important::
+        Even if you don't intend to delete any PL nodes, the *meta-adi* build
+        steps require a ``pl-delete-nodes-<dtsfile>`` file. It can be empty
+        if you want.  Existing ``pl-delete-nodes-`` files are located in
+        ``meta-adi/meta-adi-xilinx/recipes-bsp/device-tree/files``.
+
+#. Add the files to the ``SRC_URI:append`` line of the
+   ``project-spec/meta-user/recipes-bsp/device-tree/device-tree.bbappend`` file.
+#. In ``device-tree.bbappend`` Set the ``KERNEL_DTB_PATH`` to ``"${WORKDIR}"``
+   to point to the correct files folder.
+#. Modify ``project-spec/meta-user/conf/petalinuxbsp.conf`` for the newly created
+   ``KERNEL_DTB`` device tree name.
+#. Build the project as normal using ``petalinux-build``.
+
+The following example copied the ``zynqmp-zcu102-rev10-ad9081-m8-l4.dts`` from
+the kernel sources and ``pl-delete-nodes-zynqmp-zcu102-rev10-ad9081-m8-l4.dtsi``
+from *meta-adi* into the ``device-tree/files`` folder of *meta-user* as described
+above. The copied files were named ``my_ad9081.dts`` and
+``pl-delete-nodes-my_ad9081.dtsi`` respectively. The remainder of the changes
+are highlighted for reference.
+
+.. code-block::
+    :caption: device-tree.bbappend
+    :emphasize-lines: 4,5,7
+
+    FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
+
+    SRC_URI:append = " file://system-user.dtsi \
+                    file://pl-delete-nodes-my_ad9081.dtsi \
+                    file://my_ad9081.dts"
+
+    KERNEL_DTB_PATH = "${WORKDIR}"
+    require ${@'device-tree-sdt.inc' if d.getVar('SYSTEM_DTFILE') ≠ '' else ''}
+
+.. code-block::
+    :caption: petalinuxbsp.conf
+    :emphasize-lines: 4
+
+    #User Configuration
+
+    #OE_TERMINAL = "tmux"
+    KERNEL_DTB="my_ad9081"
+