From 5bfa057c5800b561d69cdcb4b7ff032ecbb6d955 Mon Sep 17 00:00:00 2001 From: Brent Kowal Date: Mon, 16 Dec 2024 17:38:14 -0500 Subject: [PATCH 1/2] Add Petalinux/meta-adi Device Tree Information 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 --- .gitignore | 1 + docs/linux/kernel/petalinux-dts/index.rst | 72 ++++++ .../petalinux-dts/meta-adi-dts-order.drawio | 34 +++ .../meta-adi-dts-order.drawio.png | 3 + .../petalinux-config-machine-zcu102.png | 3 + .../petalinux-config-machinename.png | 3 + .../petalinux-config-remove-pl.png | 3 + .../petalinux-dts/petalinux-custom-dts.rst | 66 ++++++ .../petalinux-meta-adi-bypass.rst | 210 ++++++++++++++++++ .../petalinux-dts/petalinux-system-user.rst | 125 +++++++++++ docs/linux/kernel/petalinux.rst | 11 + 11 files changed, 531 insertions(+) create mode 100644 docs/linux/kernel/petalinux-dts/index.rst create mode 100644 docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio create mode 100644 docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.png create mode 100644 docs/linux/kernel/petalinux-dts/petalinux-config-machine-zcu102.png create mode 100644 docs/linux/kernel/petalinux-dts/petalinux-config-machinename.png create mode 100644 docs/linux/kernel/petalinux-dts/petalinux-config-remove-pl.png create mode 100644 docs/linux/kernel/petalinux-dts/petalinux-custom-dts.rst create mode 100644 docs/linux/kernel/petalinux-dts/petalinux-meta-adi-bypass.rst create mode 100644 docs/linux/kernel/petalinux-dts/petalinux-system-user.rst diff --git a/.gitignore b/.gitignore index 133dc522..a32b2a52 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ _build repos docs-mono Session.vim +venv diff --git a/docs/linux/kernel/petalinux-dts/index.rst b/docs/linux/kernel/petalinux-dts/index.rst new file mode 100644 index 00000000..ede0234d --- /dev/null +++ b/docs/linux/kernel/petalinux-dts/index.rst @@ -0,0 +1,72 @@ +.. _petalinux petalinux-dts: + +Petalinux Device Trees +======================= + +.. toctree:: + :hidden: + + petalinux-system-user + petalinux-custom-dts + petalinux-meta-adi-bypass + + +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.png + +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 ` + - 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 ` + - 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 ` + - 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. diff --git a/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio b/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio new file mode 100644 index 00000000..2c27f37a --- /dev/null +++ b/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.png b/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.png new file mode 100644 index 00000000..f4c2ae60 --- /dev/null +++ b/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8409483e2a35493f34c5a825289b6cb92543f3bc39c1554f7bbec03b070bbc5b +size 29964 diff --git a/docs/linux/kernel/petalinux-dts/petalinux-config-machine-zcu102.png b/docs/linux/kernel/petalinux-dts/petalinux-config-machine-zcu102.png new file mode 100644 index 00000000..02debd02 --- /dev/null +++ b/docs/linux/kernel/petalinux-dts/petalinux-config-machine-zcu102.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f9cb3742ad0ceed6f8ade0f86fe802d9a872c5e717f584de3fb9fa6561dc17e4 +size 19108 diff --git a/docs/linux/kernel/petalinux-dts/petalinux-config-machinename.png b/docs/linux/kernel/petalinux-dts/petalinux-config-machinename.png new file mode 100644 index 00000000..dd6e07ae --- /dev/null +++ b/docs/linux/kernel/petalinux-dts/petalinux-config-machinename.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4de0e17e7ad55fb4d59c410a3ce3a5705ca34ada6834054e667b5d59aa154cb4 +size 44972 diff --git a/docs/linux/kernel/petalinux-dts/petalinux-config-remove-pl.png b/docs/linux/kernel/petalinux-dts/petalinux-config-remove-pl.png new file mode 100644 index 00000000..5acbabc2 --- /dev/null +++ b/docs/linux/kernel/petalinux-dts/petalinux-config-remove-pl.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2e212236d7853e1d6f732cf33b3619a07fbb60b2a9d1a1711344bf852808bb30 +size 64949 diff --git a/docs/linux/kernel/petalinux-dts/petalinux-custom-dts.rst b/docs/linux/kernel/petalinux-dts/petalinux-custom-dts.rst new file mode 100644 index 00000000..0fbc7ab4 --- /dev/null +++ b/docs/linux/kernel/petalinux-dts/petalinux-custom-dts.rst @@ -0,0 +1,66 @@ +.. _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-`` 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" + diff --git a/docs/linux/kernel/petalinux-dts/petalinux-meta-adi-bypass.rst b/docs/linux/kernel/petalinux-dts/petalinux-meta-adi-bypass.rst new file mode 100644 index 00000000..552602c8 --- /dev/null +++ b/docs/linux/kernel/petalinux-dts/petalinux-meta-adi-bypass.rst @@ -0,0 +1,210 @@ +.. _petalinux meta-adi-bypass: + +Custom Device Trees with DTG (meta-adi Bypass) +============================================== +For certain applications, it may be necessary to leverage the Kernel, libraries +and other tools provided by *meta-adi*, but bypass the device tree process it +generates. For this type of application, the device tree will be based on the +Petalinux Device Tree Generator (DTG). The most practical use case for this +is working with custom hardware, however Petalinux does provide out of the box +support for Xilinx development kits. + +.. tip:: + This procedure acts as a “Quick start” guide for getting up and running with + a custom device tree and Petalinux's DTG. There are several features of the + DTG not covered in this, which may be helpful for your project. Refer to + Xilinx/AMD UG1144 - Petalinux Tools Reference Guide, DTG Settings sections + for more detailed information. + + `UG1144 (docs.amd.com) `_ + +1. Bypass meta-adi's Device trees +--------------------------------- +In order to strictly use the Petalinux device tree support, and bypass *meta-adi's* +man-in-the-middle approach to device trees, add the following highlighted line +to ``/project-spec/meta-user/conf/layer.conf``. This addition will +still allow meta-adi recipes to run (for kernel, IIO, etc), but exclude the +device tree support. + + .. code-block:: + :caption: conf/layer.conf + :emphasize-lines: 18 + + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have recipes-* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + # Define dynamic layers + BBFILES_DYNAMIC += " \ + xilinx-tools:${LAYERDIR}/meta-xilinx-tools/recipes-*/*/*.bbappend \ + " + + BBFILE_COLLECTIONS += "meta-user" + BBFILE_PATTERN_meta-user = "^${LAYERDIR}/" + BBFILE_PRIORITY_meta-user = "7" + LAYERSERIES_COMPAT_meta-user = "langdale" + + BBMASK += "meta-adi-xilinx/recipes-bsp/device-tree/" + +2. Select Petalinux Template +--------------------------------- +Petalinux's DTG generates a basic device tree based on the exported XSA file from +your HDL project. This will configure the minimal parameters for the SoC. In +addition to this basic generation, an optional EvKit may be selected. When +selecting an EvKit template, in addition to the SoC parameters, all of the fixed +devices on the kit (such as power control ICs, PHYs, etc) are also automatically +included into the device tree stack. This is recommended when using an EvKit for +prototyping, to reduce the additional work needed to bring the boards up. + +If using custom hardware, or hardware not provided by Xilinx, the additional +board devices will need to be included by you in your custom device tree. +The following table (extracted from the UG1144 Reference Guide) shows the +available EvKits in the Petalinux 2023.2 distribution. Always refer to +`UG1144 (docs.amd.com) `_ +for the most up to date information. + +.. list-table:: + :header-rows: 1 + + * - BSP + - Machine + * - ZCU102 + - zcu102-rev1.0 + * - ZCU104 + - zcu104-revc + * - ZCU106 + - zcu106-reva + * - ZCU111 + - zcu111-reva + * - ZCU1275 + - zcu1275-revb + * - ZCU1285 + - zcu1285-reva + * - ZCU216 + - zcu216-reva + * - ZCU208 + - zcu208-reva + * - ZCU670 + - zcu670-revb + * - ZCU208-SDFEC + - zcu208-reva + * - ZCU100 + - zcu100-revc + * - ZC702 + - zc702 + * - ZC706 + - zc706 + * - ZEDBOARD + - zedboard + * - AC701 + - ac701-full + * - KC705 + - kc705-full + * - KCU105 + - kcu105 + * - VCU118 + - vcu118-rev2.0 + * - SP701 + - sp701-rev1.0 + * - VCK190 + - versal-vck190-reva-x-ebm-01-reva + * - VPK120 + - versal-vpk120-reva + * - VMK180 + - versal-vmk180-reva-x-ebm-01-reva + * - VPK180 + - versal-vpk180-reva + +To set the template, run ``petalinux-config`` for your project. Navigate to +**DTG Settings**, then select **MACHINE_NAME** to choose the board. +Enter the appropriate machine from the list above. In this example, +the ZCU102 is used, so the machine is set to ``zcu102-rev1.0``. + +.. tip:: + For custom hardware, or to not utilize a provided board, the ``MACHINE_NAME`` + should be set to *template*. + +.. image:: petalinux-config-machinename.png +.. image:: petalinux-config-machine-zcu102.png + +3. Disabling PL Node Generation +--------------------------------- +By default, Petalinux's DTG generates device tree nodes for any IP blocks +included in the PL. This may be applicable for some scenarios, however when +attempting to use device specific Linux drivers (such as IIO drivers ), this +will cause device tree conflicts and require deleting nodes similar to what +*meta-adi* does. To disable the automatic generation of PL nodes and avoid the +conflicts, run ``petalinux-config``, navigate to **DTG Settings**, and enable +**Remove PL From Devicetree**. + +.. image:: petalinux-config-remove-pl.png + +4. Adding Custom Device Trees +--------------------------------- +At this point, Petalinux & DTG will generate a barebones device tree of either +the SoC only (if *template* was selected for ``MACHINE_NAME``), or the core +components for the EvKit selected for ``MACHINE_NAME``. To add custom nodes, +the ``project-spec/meta-user/recipes-bsp/device-tree`` configuration will be used. + +All of the device tree information can be placed in ``system-user.dtsi``, or it +may be included via separate file(s) for modularity and maintainability. +In this example, we'll assume we have a device tree file ``ad9081_fmc_support.dtsi``, +which includes all of the nodes needed to talk to the AD9081 FMC card. +By leveraging a modular device tree like this, it is possible to include it in +multiple different projects for common function through different boards. + +**1. Add files to the correct folder location** + +First, copy all device tree files you'd like to use to +``project-spec/meta-user/recipes-bsp/device-tree/files``. There should already +be a ``system-user.dtsi`` file in there. Keep that file. + +**2. Add your files to device-tree.bbappend** + +Next, any provided files above must be added to ``device-tree.bbappend``. +Open ``project-spec/meta-user/recipes-bsp/device-tree/device-tree.bbappend`` +and edit as shown below. You may have more files, or files with different names. + +In addition, the ``KERNEL_INCLUDE:append`` line must be specified to allow +inclusion of various device tree bindings files. By default, Petalinux DTG only +references a small subset of available bindings. The inclusion of this line +allows access to all binding files within the kernel sources. + +.. code-block:: + :caption: device-tree.bbappend + :emphasize-lines: 4, 6, 7 + + FILESEXTRAPATHS:prepend := "${THISDIR}/files:" + + SRC_URI:append = " file://system-user.dtsi \ + file://ad9081_fmc_support.dtsi" + + KERNEL_INCLUDE:append = " \ + ${STAGING_KERNEL_DIR}/include" + + KERNEL_DTB_PATH = "${WORKDIR}" + require ${@'device-tree-sdt.inc' if d.getVar('SYSTEM_DTFILE') != '' else ''} + +**3. Edit system-user.dtsi** + +``System-user.dtsi`` is automatically included at the tail end of the +Petalinux/DTG device tree hierarchy. Modifications may be performed directly in +here, or this may include additional files, or both. In this case, we'll just +include the new FMC support file. Edit +``project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi``: + +.. code-block:: dts + :caption: system-user.dtsi + :emphasize-lines: 3 + + /include/ "system-conf.dtsi" + + #include "ad9081_fmc_support.dtsi" + +Petalinux can now be built and deployed as normal, incorporating your new device +trees and updates. The resulting dts hierarchy can be found in +``/components/plnx_workspace/device-tree/device-tree`` for reference +purposes. \ No newline at end of file diff --git a/docs/linux/kernel/petalinux-dts/petalinux-system-user.rst b/docs/linux/kernel/petalinux-dts/petalinux-system-user.rst new file mode 100644 index 00000000..4c423cbc --- /dev/null +++ b/docs/linux/kernel/petalinux-dts/petalinux-system-user.rst @@ -0,0 +1,125 @@ +.. _petalinux system-user: + +Device Tree Modifications with system-user.dtsi +=============================================== +One of the simplest ways to customize or extend a device tree in a ADI Petalinux +project is to use the system-user.dtsi file, included as part of *meta-user*. + +During its device tree recipe, *meta-adi* will automatically re-append the +system-user.dtsi file to end of the device tree, allowing the ability to add +new nodes and customize existing nodes to meet the application. This is an +ideal solution when leveraging an existing reference design, and making minor +modifications for evaluation and test. + +Procedure +--------- +The following procedure describes how to leverage the system-user.dtsi file. +This assumes the project has been configured with *meta-adi* and utilizes one of +the existing device trees provided by the ADI kernel, as described in the +*meta-adi* readme file. + +This hypothetical example modifies the configuration of the +zynqmp-zcu102-rev10-ad9081-m8-l4 device tree with the following adjustments: + +* Change the AD9081 DAC frequency to 6.2GHz +* Update the Tx Channel 0 Shift to 400MHz +* Delete the LPM Mode Enable property on the Rx Xcvr node +* Add another channel to the HMC7044 to support an ADF4378 +* Add a ADF4378 to SPI1, using CS Line 1 + +.. warning:: + The device tree contents in this example a just hypothetical to illustrate + various actions that can be performed in system-user.dtsi. These in no way + likely represent a valid AD9081 configuration. + +To apply these changes, the ``/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi`` +file was modified as follows: + +.. code-block:: dts + :caption: system-user.dtsi + + /include/ "system-conf.dtsi" + + /* Update the DAC frequency */ + &trx0_ad9081 { + adi,tx-dacs { + adi,dac-frequency-hz = /bits/ 64 <6200000000>; + }; + }; + /* Update the Channel 0 shift */ + &ad9081_dac0 { + adi,nco-frequency-shift-hz = /bits/ 64 <400000000>; + }; + /* Remove the LPM Enable directive */ + &axi_ad9081_adxcvr_rx { + /delete-property/ adi,use-lpm-enable; + }; + /* Add another clock channel to the HMC7044 for the ADF4378. + Channel 1 is not used in the original device tree + */ + &hmc7044 { + hmc7044_c1: channel@1 { + reg = <1>; + adi,extended-name = "ADF4378_REFCLK"; + adi,divider = <12>; + adi,driver-mode = ; + }; + }; + /* Add a ADF4378 to SPI1, CS1 */ + &spi1 { + adf4378: adf4378@1 { + #address-cells = <1>; + #size-cells = <0>; + #clock-cells = <1>; + + compatible = "adi,adf4378"; + reg = <1>; /* CS 1*/ + spi-max-frequency = <10000000>; + clocks = <&hmc7044 1>; + clock-names = "ref_in"; + }; + }; + +Once system-user.dtsi has been modified, the project may be built as normal +using the standard ``petalinux-build`` command. To verify the changes, the most +concrete way is to inspect the resulting device tree binary created. + +The final dtb file will be in the ``images/linux`` folder of the project. To +decompile the dtb file, run the following. +*This assumes the shell is at the project root, and out_check.dts is the desired +output filename* + +``dtc -I dtb -O dts images/linux/system.dtb > out_check.dts`` + +out_check.dtb can be searched to confirm the incorporated changes. A subset of +incorporated changes verified below: + +.. code-block:: dts + :emphasize-lines: 4 + + adi,tx-dacs { + #size-cells = <0x00>; + #address-cells = <0x01>; + adi,dac_frequency-hz = <0x01 0x718c7e00>; + +.. code-block:: dts + :emphasize-lines: 4 + + dac@0 { + reg = <0x00>; + adi,crossbar-select = <0x28>; + adi,nco-frequency-shift-hz = <0x00 0x17d78400>; + phandle = <0xa5>; + }; + +.. code-block:: dts + :emphasize-lines: 1,3 + + channel@1 { + reg = <0x01>; + adi,extended-name = "ADF4378_REFCLK"; + adi,divider = <0x0c>; + adi,driver-mode = <0x02>; + phandle = <0xb8>; + }; + diff --git a/docs/linux/kernel/petalinux.rst b/docs/linux/kernel/petalinux.rst index c7dab932..6f45d867 100644 --- a/docs/linux/kernel/petalinux.rst +++ b/docs/linux/kernel/petalinux.rst @@ -3,6 +3,11 @@ Building with Petalinux ======================= +.. toctree:: + :hidden: + + petalinux-dts/index + The ADI Linux kernel can also be compiled using Petalinux to be used on Xilinx SoC FPGA based platforms (using :git-meta-adi:`ADI Yocto ` repository). The following table specifies the supported Petalinux versions and documentation: @@ -606,3 +611,9 @@ The user is: zynqmp-zcu102-fmcomms5 login: root Password: +Petalinux, meta-adi and Device Trees +------------------------------------ +There are several approaches for modifying and customizing the device trees of +a Petalinux project. Please see here: :doc:`petalinux-dts/index` +for more information. + From 8e222511597ebbe642d122d40413570354e87979 Mon Sep 17 00:00:00 2001 From: Jorge Marques Date: Thu, 19 Dec 2024 18:22:30 -0300 Subject: [PATCH 2/2] review: Add Petalinux/meta-adi Device Tree Information Reorder toctree directive, to append the pages to a coherent order in the singlehtml/pdf output. Drawio image as svg instead of png. Minor style fixes. Signed-off-by: Jorge Marques --- docs/linux/kernel/petalinux-dts/index.rst | 18 ++++---- .../meta-adi-dts-order.drawio.png | 3 -- .../meta-adi-dts-order.drawio.svg | 24 +++++++++++ .../petalinux-dts/petalinux-custom-dts.rst | 1 - .../petalinux-meta-adi-bypass.rst | 42 +++++++++---------- .../petalinux-dts/petalinux-system-user.rst | 3 +- docs/linux/kernel/petalinux.rst | 15 +++---- 7 files changed, 63 insertions(+), 43 deletions(-) delete mode 100644 docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.png create mode 100644 docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.svg diff --git a/docs/linux/kernel/petalinux-dts/index.rst b/docs/linux/kernel/petalinux-dts/index.rst index ede0234d..ef3e3492 100644 --- a/docs/linux/kernel/petalinux-dts/index.rst +++ b/docs/linux/kernel/petalinux-dts/index.rst @@ -1,15 +1,7 @@ .. _petalinux petalinux-dts: Petalinux Device Trees -======================= - -.. toctree:: - :hidden: - - petalinux-system-user - petalinux-custom-dts - petalinux-meta-adi-bypass - +====================== 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 @@ -38,7 +30,7 @@ device tree. During the ``do_configure()`` stage, the device tree recipe of the A high-level view of the final *meta-adi* device tree looks like the following: -.. image:: meta-adi-dts-order.drawio.png +.. image:: meta-adi-dts-order.drawio.svg Device Tree Modifications ------------------------- @@ -70,3 +62,9 @@ as well as recommended use cases: 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: + + * diff --git a/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.png b/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.png deleted file mode 100644 index f4c2ae60..00000000 --- a/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.png +++ /dev/null @@ -1,3 +0,0 @@ -version https://git-lfs.github.com/spec/v1 -oid sha256:8409483e2a35493f34c5a825289b6cb92543f3bc39c1554f7bbec03b070bbc5b -size 29964 diff --git a/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.svg b/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.svg new file mode 100644 index 00000000..8693614e --- /dev/null +++ b/docs/linux/kernel/petalinux-dts/meta-adi-dts-order.drawio.svg @@ -0,0 +1,24 @@ + + + + + + + + + Reference design dts file + pl.dtsi + pl-delete-nodes- + system-user.dtsi + + + From project-spec/meta-user/recipes-bsp/device-tree/files +Allows final modification of the overall system device tree + Sourced from meta-adi. This is unique per top +level dts file, and removes duplicate FPGA nodes + FPGA node device tree auto generated +from the XSA file by Xilinx DTG + Sourced from the ADI Linux kernel +i.e arch/<arch>/boot/dts + + diff --git a/docs/linux/kernel/petalinux-dts/petalinux-custom-dts.rst b/docs/linux/kernel/petalinux-dts/petalinux-custom-dts.rst index 0fbc7ab4..7a6b4621 100644 --- a/docs/linux/kernel/petalinux-dts/petalinux-custom-dts.rst +++ b/docs/linux/kernel/petalinux-dts/petalinux-custom-dts.rst @@ -8,7 +8,6 @@ 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 diff --git a/docs/linux/kernel/petalinux-dts/petalinux-meta-adi-bypass.rst b/docs/linux/kernel/petalinux-dts/petalinux-meta-adi-bypass.rst index 552602c8..858df561 100644 --- a/docs/linux/kernel/petalinux-dts/petalinux-meta-adi-bypass.rst +++ b/docs/linux/kernel/petalinux-dts/petalinux-meta-adi-bypass.rst @@ -26,31 +26,31 @@ to ``/project-spec/meta-user/conf/layer.conf``. This addition will still allow meta-adi recipes to run (for kernel, IIO, etc), but exclude the device tree support. - .. code-block:: - :caption: conf/layer.conf - :emphasize-lines: 18 +.. code-block:: + :caption: conf/layer.conf + :emphasize-lines: 18 - # We have a conf and classes directory, add to BBPATH - BBPATH .= ":${LAYERDIR}" + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" - # We have recipes-* directories, add to BBFILES - BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ - ${LAYERDIR}/recipes-*/*/*.bbappend" + # We have recipes-* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" - # Define dynamic layers - BBFILES_DYNAMIC += " \ - xilinx-tools:${LAYERDIR}/meta-xilinx-tools/recipes-*/*/*.bbappend \ - " + # Define dynamic layers + BBFILES_DYNAMIC += " \ + xilinx-tools:${LAYERDIR}/meta-xilinx-tools/recipes-*/*/*.bbappend \ + " - BBFILE_COLLECTIONS += "meta-user" - BBFILE_PATTERN_meta-user = "^${LAYERDIR}/" - BBFILE_PRIORITY_meta-user = "7" - LAYERSERIES_COMPAT_meta-user = "langdale" + BBFILE_COLLECTIONS += "meta-user" + BBFILE_PATTERN_meta-user = "^${LAYERDIR}/" + BBFILE_PRIORITY_meta-user = "7" + LAYERSERIES_COMPAT_meta-user = "langdale" - BBMASK += "meta-adi-xilinx/recipes-bsp/device-tree/" + BBMASK += "meta-adi-xilinx/recipes-bsp/device-tree/" 2. Select Petalinux Template ---------------------------------- +---------------------------- Petalinux's DTG generates a basic device tree based on the exported XSA file from your HDL project. This will configure the minimal parameters for the SoC. In addition to this basic generation, an optional EvKit may be selected. When @@ -131,7 +131,7 @@ the ZCU102 is used, so the machine is set to ``zcu102-rev1.0``. .. image:: petalinux-config-machine-zcu102.png 3. Disabling PL Node Generation ---------------------------------- +------------------------------- By default, Petalinux's DTG generates device tree nodes for any IP blocks included in the PL. This may be applicable for some scenarios, however when attempting to use device specific Linux drivers (such as IIO drivers ), this @@ -143,7 +143,7 @@ conflicts, run ``petalinux-config``, navigate to **DTG Settings**, and enable .. image:: petalinux-config-remove-pl.png 4. Adding Custom Device Trees ---------------------------------- +----------------------------- At this point, Petalinux & DTG will generate a barebones device tree of either the SoC only (if *template* was selected for ``MACHINE_NAME``), or the core components for the EvKit selected for ``MACHINE_NAME``. To add custom nodes, @@ -207,4 +207,4 @@ include the new FMC support file. Edit Petalinux can now be built and deployed as normal, incorporating your new device trees and updates. The resulting dts hierarchy can be found in ``/components/plnx_workspace/device-tree/device-tree`` for reference -purposes. \ No newline at end of file +purposes. diff --git a/docs/linux/kernel/petalinux-dts/petalinux-system-user.rst b/docs/linux/kernel/petalinux-dts/petalinux-system-user.rst index 4c423cbc..5da7e751 100644 --- a/docs/linux/kernel/petalinux-dts/petalinux-system-user.rst +++ b/docs/linux/kernel/petalinux-dts/petalinux-system-user.rst @@ -32,7 +32,8 @@ zynqmp-zcu102-rev10-ad9081-m8-l4 device tree with the following adjustments: various actions that can be performed in system-user.dtsi. These in no way likely represent a valid AD9081 configuration. -To apply these changes, the ``/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi`` +To apply these changes, the +``/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi`` file was modified as follows: .. code-block:: dts diff --git a/docs/linux/kernel/petalinux.rst b/docs/linux/kernel/petalinux.rst index 6f45d867..a0c8d91e 100644 --- a/docs/linux/kernel/petalinux.rst +++ b/docs/linux/kernel/petalinux.rst @@ -3,11 +3,6 @@ Building with Petalinux ======================= -.. toctree:: - :hidden: - - petalinux-dts/index - The ADI Linux kernel can also be compiled using Petalinux to be used on Xilinx SoC FPGA based platforms (using :git-meta-adi:`ADI Yocto ` repository). The following table specifies the supported Petalinux versions and documentation: @@ -614,6 +609,12 @@ The user is: Petalinux, meta-adi and Device Trees ------------------------------------ There are several approaches for modifying and customizing the device trees of -a Petalinux project. Please see here: :doc:`petalinux-dts/index` -for more information. +a Petalinux project. + +Please see: + +.. toctree:: + :titlesonly: + + petalinux-dts/index