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..ef3e3492 --- /dev/null +++ b/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 ` + - 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. + +.. toctree:: + :hidden: + :glob: + + * 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.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-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..7a6b4621 --- /dev/null +++ b/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-`` 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..858df561 --- /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. 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..5da7e751 --- /dev/null +++ b/docs/linux/kernel/petalinux-dts/petalinux-system-user.rst @@ -0,0 +1,126 @@ +.. _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..a0c8d91e 100644 --- a/docs/linux/kernel/petalinux.rst +++ b/docs/linux/kernel/petalinux.rst @@ -606,3 +606,15 @@ 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: + +.. toctree:: + :titlesonly: + + petalinux-dts/index +