# Example - Generating DTSI and DTBO Overlay Files for Smartcam

In this example, we will show the steps to create a working SmartCam DTBO overlay file. We will first generate a pl.dtsi file using [DTG](https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18842279/Build+Device+Tree+Blob), and then explain the modifications required to make the .dtsi file fully functional. This example is based on [2022.1 smartcam release](https://xilinx.github.io/kria-apps-docs/kv260/2022.1/build/html/docs/smartcamera/smartcamera_landing.html).

## Pre-requisites

First read through [Generating DTSI and DTBO Overlay Files](./dtsi_dtbo_generation.md) and install required tools.

The XSA file required can be obtained using these [instructions](https://xilinx.github.io/kria-apps-docs/kv260/2022.1/build/html/docs/build_vivado_design.html). They are summarized below:

```shell
cd $workdir
git clone --recursive --branch xlnx_rel_v2022.1 https://github.com/Xilinx/kria-vitis-platforms.git
cd $workdir/kria-vitis-platforms/kv260/platforms/vivado/kv260_ispMipiRx_vcu_DP
make xsa
```

The generated XSA will be located at: ```$workdir/kria-vitis-platforms/kv260/platforms/vivado/kv260_ispMipiRx_vcu_DP/project/kv260_ispMipiRx_vcu_DP.xsa```.

## Generating DTSI based on platform xsa file using DTG

Call XSCT:

``` shell
cd $workdir
xsct
```

In XSCT, perform the following commands which will extract the HW configuration information and generate a DTSI file: 

```bash
hsi open_hw_design kria-vitis-platforms/kv260/platforms/vivado/kv260_ispMipiRx_vcu_DP/project/kv260_ispMipiRx_vcu_DP.xsa
hsi set_repo_path <path to device-tree-xlnx repository>
hsi create_sw_design device-tree -os device_tree -proc psu_cortexa53_0
hsi set_property CONFIG.dt_overlay true [hsi::get_os]
hsi set_property CONFIG.dt_zocl true [hsi get_os]
hsi generate_target -dir smartcam_dtg_output
hsi close_hw_design kv260_ispMipiRx_vcu_DP_wrapper
```

A file ```smartcam_dtg_output/pl.dtsi``` will be created. It should look identical to [pl.dtsi here](./example_src/smartcam_dtsi_example/pl.dtsi), we will modify it in the next step to add the necessary information that cannot be automatically generated.

## Modify generated pl.dtsi

Note that the released [kv260-smartcam.dtsi](https://github.com/Xilinx/kria-apps-firmware/blob/xlnx_rel_v2022.1/boards/kv260/smartcam/kv260-smartcam.dtsi) is using sugar syntax while the generated [pl.dtsi](./example_src/smartcam_dtsi_example/pl.dtsi) is using fragmented syntax - they both will work. We will continue the fragmented syntax for this tutorial.

### Add AP1302 Node

The AP1302 sensor is on the carrier card, and not something the .XSA platform is aware of as the FPGA/PL design only can infer the generic MIPI and I2C interfaces. Add the required information below to overlay2, for AP1302 clock and regulators:

```dtsi
ap1302_clk: sensor_clk {
   compatible = "fixed-clock";
   clock-frequency = <0x48000000>;
};
ap1302_vdd: fixedregulator@0 {
   compatible = "regulator-fixed";
   regulator-name = "ap1302_vdd";
   regulator-min-microvolt = <2800000>;
   regulator-max-microvolt = <2800000>;
   enable-active-high;
};

ap1302_vaa: fixedregulator@1 {
   compatible = "regulator-fixed";
   regulator-name = "ap1302_vaa";
   regulator-min-microvolt = <1800000>;
   regulator-max-microvolt = <1800000>;
};

ap1302_vddio: fixedregulator@2 {
   compatible = "regulator-fixed";
   regulator-name = "ap1302_vddio";
   regulator-min-microvolt = <1200000>;
   regulator-max-microvolt = <1200000>;
};
```

### I2C MUX

The I2C mux connecting to control AP1302 also exist outside of zynq MPSoC and .xsa file does not have awareness, therefore they also need to be added manually. The device tree binding is documented [here](https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/i2c/nxp%2Cpca9541.txt) and [here](https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/media/i2c/onnn%2Cap1302.yaml). Note that the port connection to mipi_csi_incapture_pipeline_mipi_csi2_rx_subsyst_0 on mipi_csi_portscapture_pipeline_mipi_csi2_rx_subsyst_0 (both names were auto generated by DTG) corresponds to the mipi_phy_if in the platform Vivado design.

```dtsi
i2c_mux: i2c-mux@74 {
   compatible = "nxp,pca9546";
   reg = <0x74>;
   i2c@0 {
      reg = <0>;
      ap1302: isp@3c {
         compatible = "onnn,ap1302";
         reg = <0x3c>;
         reset-gpios = <&gpio 79 1>;
         clocks = <&ap1302_clk>;
         sensors {
            onnn,model = "onnn,ar1335";
            sensor@0 {
               reg = <0>;
               vdd-supply = <&ap1302_vdd>;
               vaa-supply = <&ap1302_vaa>;
               vddio-supply = <&ap1302_vddio>;
            };
         };
         ports {
            port@0 {
               reg = <2>;
               isp_out: endpoint {
               remote-endpoint = <&mipi_csi_incapture_pipeline_mipi_csi2_rx_subsyst_0>;
               data-lanes = <1 2 3 4>;
               };
            };
         };
      };
   };
};
```

### mipi csi node

The mipi_csi2_rx_subsystem@80000000 node requires a few modification. the device tree binding information for AMD MIPI CSI-2 Receiver Subsystem is[here](https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/media/xilinx/xlnx%2Ccsi2rxss.yaml)
Add property:

```dtsi
xlnx,csi-pxl-format = <0x18>;
xlnx,en-active-lanes;
```

Remove xlnx,cfa-pattern, xlnx,video-format, and xlnx,video-width setting  - those are no longer used by driver and 2022.1 through 2023.1 DTG is not yet updated.

Connect the remote end point to camera serial output:

```dtsi
mipi_csi_incapture_pipeline_mipi_csi2_rx_subsyst_0: endpoint {
   data-lanes = <1 2 3 4>;
   remote-endpoint = <&isp_out>;
};
```

### ZOCL node

Lastly, in 2022.1 through 2023.1, ZOCL node need to specify the interrupts reserved for the platform (as seen in platform setting tab in Vivado) if interrupts are directly connected to GIC (instead of through a axi_intc). 

```dtsi
zyxclmm_drm {
   compatible = "xlnx,zocl";
   status = "okay";
   interrupt-parent = <&gic>;
   interrupts = <0 89  4>, <0 90  4>, <0 91  4>, <0 92  4>,
               <0 93  4>, <0 94  4>, <0 95  4>, <0 96  4>;
};
```

### Final dtsi file

The final dtsi file should look like [pl_modify.dtsi](./example_src/smartcam_dtsi_example/pl_modify.dtsi).

## Compile the .dtsi to .dtbo using DTC

Now generate the .dtbo file using command below:

```bash
dtc -@ -O dtb -o pl_modify.dtbo pl_modify.dtsi
```

As a sanity test rename the generated pl.dtbo to a unique name for tracking purposes, move it to the kv260 target and confirm that replacing the kv260_smartcam.dtbo with the generated one that the SmartCam app still works.

## License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at
[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

<p class="sphinxhide" align="center">Copyright&copy; 2023 Advanced Micro Devices, Inc</p>