Xilinx ZYNQMP Boards


1. About this document
======================
This document provides common and non-hardware specific information.
Please refer to README.hardware for hardware specific information.

Dependencies
------------
This layer depends on the oe-core version supplied with Wind River Linux
and the wrlinux layer.


Maintenance
-----------
This layer is maintained by Wind River Systems, Inc.
Contact <support@windriver.com> or your support representative for more
information on submitting changes.


Building the zynqmp layer
-----------------------------
This layer and wrlinux layer should be added to bblayers.conf.


License
-------
Copyright (C) 2018 Wind River Systems, Inc.

Source code included in the tree for individual recipes is under the LICENSE
stated in the associated recipe (.bb file) unless otherwise stated.

The metadata is under the following license unless otherwise stated.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

2. BSP Kernel and Distros
=========================

The following table summarizes the valid Wind River Linux distros for this BSP.
'Y' in each content cell stands for supported; 'N' stands for not supported:

  +--------------+-------------+-------------+------------------+
  | valid/distro |   wrlinux   | wrlinux-cgl | wrlinux-std-sato |
  +--------------+-------------+-------------+------------------+
  |    valid     |      Y      |      N      |         y        |
  +--------------+-------------+-------------+------------------+

For the supported kernel type for this BSP, check the TARGET_SUPPORTED_KTYPES
by running 'bitbake -e | grep "^TARGET_SUPPORTED_KTYPES"'.

Note: The preempt-rt ktype can be used with this BSP/Machine.


3. Board Specific Patches
=========================

To get a list of patches applied to the kernel specific to this BSP,
along with patch descriptions, use git to see what changed on the default
kernel (git whatchanged <kernel_type>..<bsp_name>). For example:

	# cd path_to_project/tmp-glibc/work-shared/xilinx-zynqmp/kernel-source
	# git whatchanged standard/base..HEAD


4. Boot Instructions
====================

You must load the DTB (device tree blob) into the target's memory
prior to booting the kernel Image. The DTB file can be found in the export
directory after building a project, or you can generate it manually with the
following commands:

        # bitbake -c devshell virtual/kernel
        # vim arch/arm64/boot/dts/xilinx/the_file_you_edit*.dts
	# make xilinx/zynqmp-zcu102-rev1.0.dtb

The resulting DTB file can be found here:
path_to_project/build/tmp-glibc/work/<bsp name>-wrs-linux/linux-yocto/<kernel version>/linux-<bsp name>-<kernel type>-build/arch/arm64/boot/dts/xilinx/

Assuming all files can be downloaded from a network, deploy your board and host
properly to ensure your network is available from the board.

4.1 MTD Root File System (NOR and NAND Flash)
---------------------------------------------

The NOR device on the xilinx-zynqmp board is a 128M Byte NOR flash.
The default layout of the NOR device is:

    0x000000000000-0x000000100000 : "qspi-fsbl-uboot"
    0x000000100000-0x000000600000 : "qspi-linux"
    0x000000600000-0x000000620000 : "qspi-device-tree"
    0x000000620000-0x000002620000 : "qspi-bitstream"
    0x000002620000-0x000008000000 : "qspi-rootfs"

4.1.1 Generate the boot image:
------------------------------

Configure your project with the following options in your local.conf file
to generate the jffs2 boot image and enable the necessary kernel options:

        LINUX_KERNEL_TYPE="standard"
        IMAGE_FSTYPES="jffs2"

Start menuconfig and enable flash filesystem support:
        # bitbake -c menuconfig linux-yocto
You will find flash under the Filesystems section of menuconfig.


The kernel image and jffs2 image can be found in the export directory.

Program the image into flash with the following command:

	# flash_eraseall /dev/mtdx
	# flashcp -v wrlinux-image-glibc-small-xilinx-zynqmp.jffs2 /dev/mtdx
	# mkdir /mnt/jffs2
	# mount -t jffs2 /dev/mtdblockx	/mnt/jffs2
	# umount /mnt/jffs2

NOTE: Before writing to the flash memory, you need to know its layout. You can
get this information by running 'cat /proc/mtd' on your target.

4.1.2 Deployment
----------------

After loading the kernel, pass kernel arguments as shown:

	root=/dev/mtdblockx rw rootfstype=jffs2 console=ttyPS0,115200 earlycon=cdns,mmio,0xFF000000,115200n8 clk_ignore_unused

4.2 Boot from SD card
---------------------

4.2.1 Deploy kernel, DTB image and file system image into your SD card
-----------------------------------------------------------

Refer to the bootloader/README for information on how to make an SD
bootable card. Deploy the kernel image, DTB image and file system image as follows:

	# mount /dev/mmcblk0p2 /mnt/sd
	# tar xfj wrlinux-image-glibc-std-xilinx-zynqmp.tar.bz2 --numeric-owner -C /mnt/sd
	# umount /mnt/sd
	# mount /dev/mmcblk0p1 /mnt/sd
	# cp path_to_Image /mnt/sd/boot
	# cp path_to_zynqmp-zcu102-rev1.0.dtb /mnt/sd/boot
	# umount /mnt/sd

4.2.2 Set the u-boot environment variables and boot from SD card
------------------------------------------------------------

Run the following command to load the kernel image and DTB image:

	=> setenv bootargs console=ttyPS0,115200 root=/dev/mmcblk0p2 rw rootwait earlycon=cdns,mmio,0xFF000000,115200n8 clk_ignore_unused
	=> mmc rescan
	=> fatload mmc 0 0x10000000 Image
	=> fatload mmc 0 0x11800000 zynqmp-zcu102-rev1.0.dtb
	=> booti 0x10000000 - 0x11800000


5. Features
===========

5.1. Multilib
-------------

By default, this BSP is configured as a 64-bit kernel and 64-bit userspace.
If a full 32-bit filesystem is necessary, use the prefix "lib32-" before
the expected target image as follows:

	# bitbake lib32-wrlinux-image-glibc-std


6. WIC Notes
============

User can use the OpenEmbedded Image Creator to create the properly partitioned
image on a SD card. It generates partitioned images from existing OpenEmbedded
build artifacts. Please refer to the following URL for more detailed partition
information about WIC:

https://www.yoctoproject.org/docs/2.6/mega-manual/mega-manual.html#creating-partitioned-images-using-wic

After having built your project, a partitioned WIC image will be created in the
deploy folder as follows:

  path_to_your_project/build/tmp-glibc/deploy/images/xilinx-zynqmp/wrlinux-image-glic-<rootfs_type>-xilinx-zynqmp.wic

There are two partitions in this WIC images, the first one is to hold the boot
images, the second is the related root file system.

6.1 An example to deploy bootloader into the first partition
------------------------------------------------------------

1) Deploy the created WIC image into SD card(/dev/sdx) in your host machine.

   $ sudo dd if=wrlinux-image-glibc-<rootfs_type>-xilinx-zynqmp.wic of=/dev/sdx

2) Download binary bootloader from the vendor website, and deploy BOOT.BIN into
   /dev/sdx1

   $ sudo mount /dev/sdx1 path_to_sdx1
   $ cp -r path_to_your_bootloader/BOOT.BIN path_to_sdx1
   $ sync; sudo umount path_to_sdx1

6.2 Boot the board from the WIC SD card
---------------------------------------

Insert the SD card into the board and power on, then set the proper u-boot
environment parameters to boot the board, please refer to section 4 for more
information.


7. CAN
======

# configure can0 in the speed of 800000
   $ ip link set can0 up type can bitrate 800000
   $ ip -details link show can0

# send out a single frame
   $ cansend can0 1F334455#1122334455667788
   $ ip link set can0 down


8. DP monitor operations
========================

8.1 Show and adjust screen resolution, some draw examples
---------------------------------------------------------
   root@xilinx-zynqmp:~# export DISPLAY=:0.0
   root@xilinx-zynqmp:~# xrandr
   Screen 0: minimum 320 x 200, current 1024 x 768, maximum 4096 x 4096
   DP-1 connected primary 1024x768+0+0 518mm x 324mm
      1920x1080     24.00    23.98
      1280x720      60.00    50.00    59.94
      1024x768      75.03*   60.00
      800x600       75.00    60.32
      720x576       50.00
      720x480       60.00    59.94
      640x480       75.00    60.00    59.94
      720x400       70.08
   root@xilinx-zynqmp:~# xrandr -s 1920x1080
   PLL: shutdown
   PLL: enable
   root@xilinx-zynqmp:~# eglinfo
   EGL API version: 1.4
   EGL vendor string: ARM
   EGL version string: 1.4 Linux-r7p0-00rel0
   EGL client APIs: OpenGL_ES
   EGL extensions string:
       EGL_KHR_image EGL_KHR_image_base EGL_KHR_image_pixmap
       EGL_EXT_image_dma_buf_import EGL_KHR_gl_texture_2D_image
       EGL_KHR_gl_texture_cubemap_image EGL_KHR_gl_renderbuffer_image
       EGL_KHR_reusable_sync EGL_KHR_fence_sync
       EGL_KHR_swap_buffers_with_damage EGL_EXT_swap_buffers_with_damage
       EGL_KHR_lock_surface EGL_KHR_lock_surface2
       EGL_EXT_create_context_robustness EGL_ANDROID_blob_cache
       EGL_KHR_create_context EGL_KHR_partial_update
       EGL_KHR_create_context_no_error
   EGL client extensions string:
       EGL_EXT_client_extensions EGL_EXT_platform_base EGL_KHR_platform_x11
   Configurations:
        bf lv colorbuffer dp st  ms    vis   cav bi  renderable  supported
     id sz  l  r  g  b  a th cl ns b    id   eat nd gl es es2 vg surfaces
   ---------------------------------------------------------------------
   0x05 16  0  5  6  5  0 24  8  0 0 0x21SG      y     y  y     win,pb,pix
   0x03 16  0  5  6  5  0 24  8  4 1 0x21SG      y     y  y     win,pb,pix
   0x04 16  0  5  6  5  0 24  8 16 1 0x21SG   y  y     y  y     win,pb,pix
   0x13 16  0  5  5  5  1 24  8  0 0 0x00SG      a     y  y     pb
   0x12 16  0  5  5  5  1 24  8  4 1 0x00SG      a     y  y     pb
   0x14 16  0  5  5  5  1 24  8 16 1 0x00SG   y  a     y  y     pb
   0x15 16  0  4  4  4  4 24  8  0 0 0x00SG      a     y  y     pb
   0x16 16  0  4  4  4  4 24  8  4 1 0x00SG      a     y  y     pb
   0x17 16  0  4  4  4  4 24  8 16 1 0x00SG   y  a     y  y     pb
   0x09 32  0  8  8  8  8 24  8  0 0 0x54SG   y  a     y  y     win,pb,pix
   0x26 24  0  8  8  8  0 24  8  0 0 0x00SG   y  a     y  y     pb,pix
   0x29 24  0  8  8  8  0 24  8  4 1 0x00SG   y  a     y  y     pb,pix
   0x2a 24  0  8  8  8  0 24  8 16 1 0x00SG   y  a     y  y     pb,pix
   0x0c 32  0  8  8  8  8 24  8  4 1 0x54SG   y  a     y  y     win,pb,pix
   0x0f 32  0  8  8  8  8 24  8 16 1 0x54SG   y  a     y  y     win,pb,pix
   0x0d  8  0  0  0  0  0  0  0  0 0 0x00SG   y                 pix
   0x0e 16  0  0  0  0  8  0  0  0 0 0x00SG   y                 pix
   0x1c 16  0  5  6  5  0  0  0  1 0 0x21SG                     win
   0x23 16  0  5  5  5  1  0  0  1 0 0x00SG
   0x22 32  0  8  8  8  8  0  0  1 0 0x54SG   y                 win
   0x1b 32  0  8  8  8  8  0  0  1 0 0x54SG   y                 win
   0x27 32  0  8  8  8  8 24  8  0 0 0x00SG   y  a     y  y     pix

   root@xilinx-zynqmp:~# msaa
   EGL_VERSION = 1.4 Linux-r7p0-00rel0
   EGL_VENDOR = ARM
   EGL_EXTENSIONS = EGL_KHR_image EGL_KHR_image_base EGL_KHR_image_pixmap EGL_EXT_image_dma_buf_import EGL_KHR_gl_texture_2D_image EGL_KHR_gl_texture_cubemap_image EGL_KHR_gl_renderbuffer_image EGL_KHR_reusable_sy
   EGL_CLIENT_APIS = OpenGL_ES
   Press 'a' to toggle multisample antialiasing
   Press 'Esc' to exit
   MSAA disabled

   root@xilinx-zynqmp:~# tri_x11
   EGL_VERSION = 1.4 Linux-r7p0-00rel0

8.2 Audio Play
--------------
Connect loudspeaker or headset with display monitor, and then run below commands:
 # aplay -l
 # speaker-test -c2 -twav

8.3 Notes:
---------
It seems mesa-demos are not compatible with libmali-xlnx, so not all test cases
can be passed, and we'll keep them as-is since debugging binary lib has not too
much meanings to the end user.


9 lib32 note
============

lib32-wrlinux-image-glibc-std-sato can be built and boot, but the graphics
output will not be available since the related graphics libs elg libgles1,
and libgles2 provided by libmali-xlnx can not be re-built into lib32 mode
because of its binary-provider only.


10 Kernel command line settings
==============================

As observed from the rev1.0 and rev1.1 board, "clk_ignore_unused" is a mandatory
set in kernel command line, which also shown in zynqmp BSP setting on both vendor
SDK 2017.4 and 2018.1, otherwise it might incur the sudden crash.


11 FPGA Bitstream File Update
=============================
On xilinx-zynqmp platform, customer is able to update their own FPGA design image
from linux side in running time. Detail example as below:

11.1. Prepare FPGA bitstream file
---------------------------------
Download a xilinx prebuilt bitstream file with below link:
https://www.xilinx.com/member/forms/download/xef.html?filename=2018.2-zcu102-release.tar.xz
Then, extract the .bit file from package 2018.2-zcu102-release.tar.xz and rename it into system.bit

11.2. Generate binary file
--------------------------
Because xilinx-zynqmp platform only supports binary format for updating FPGA, it is need
to change the .bit file into binary format with below commands:
 - set environment variable
 # source xxx/Vivado/Vivado/2017.4/settings64.sh

 - generate the .bin from .bit file using Bootgen
 # bootgen -image Bitstream.bif -arch zynqmp -process_bitstream bin	(For 2017.4 and earlier releases)
 or
 # bootgen -image Bitstream.bif -arch zynqmp -o ./system.bit.bin -w	(For newer releases than 2017.4)

 - Bitstream.bif file content as below:
 all:
 {
	[destination_device = pl] system.bit	/* Bitstream file name */
 }

 - The output bin file is system.bit.bin

11.3. Deploy required files
---------------------------
Deploy system.bit.bin and zynqmp-zcu102-fpga-update.dtb file in SD card or other storage medium.
The dtb is generated in below directory:
<ProjectPath>/build/tmp-glibc/work/xilinx_zynqmp-wrs-linux/linux-yocto/<kernel-version>/linux-xilinx_zynqmp-standard-build/arch/arm64/boot/dts/xilinx

11.4. Update FPGA bitstream file
--------------------------------
11.4.1 Update FPGA by using device tree overlay
Boot up kernel and login, then run below commands in terminal.
1) Set flags for Full Bitstream.
	# echo 0 > /sys/class/fpga_manager/fpga0/flags

2) Copy the Full Bitstream (.bin) and pl.dtbo files into firmware folder
	# mkdir -p /lib/firmware
	# cp xxx/system.bit.bin /lib/firmware/system.bit.bin
	# cp xxx/zynqmp-zcu102-fpga-update.dtb /lib/firmware/zynqmp-zcu102-fpga-update.dtb

3) Apply overlay DTB(zynqmp-zcu102-fpga-update.dtb) to add live device nodes
	# mkdir /sys/kernel/config/device-tree/overlays/system
	# cd /lib/firmware/
	# echo zynqmp-zcu102-fpga-update.dtb > /sys/kernel/config/device-tree/overlays/system/path

4) Steps to remove device nodes
	# rmdir /sys/kernel/config/device-tree/overlays/system

11.4.2 Update FPGA by using sysfs interface
Boot up kernel and login, then run below commands in terminal.
# echo 0 > /sys/class/fpga_manager/fpga0/flags
# mkdir -p /lib/firmware
# cp xxx/system.bit.bin /lib/firmware/system.bit.bin
# cd /lib/firmware
# echo system.bit.bin > /sys/class/fpga_manager/fpga0/firmware

11.5 Note
---------
If customer wants to enable new peripherals that reside in the new FPGA bitstream from linux side,
overlay solution is able to implement the requirement. Detail description, please refer to below link.
https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18841847/Solution+ZynqMP+PL+Programming#x-Programming+the+PL+through+Linux


12. kexec and kdump
===================

You need to add feature/kexec support as follow:

	./wrlinux-x/setup.sh --machines xilinx-zynqmp --templates feature/kexec,feature/kdump

12.1 kexec
---------

	kexec -l  /root/Image.gz --append="`cat /proc/cmdline`"
	kexec -e

12.2 kdump
---------

Add crashkernel=512M to the kernel cmdline
   kexec -p /root/Image.gz --append="$your-bootcmd"
   echo c > /proc/sysrq-trigger


13. suspend/resume
==================

"Suspend-To-RAM" is supportted by running below command:

	# echo mem > /sys/power/state

Wakeup system, customer can use network, rtc, console and so on, it depends on concrete scenario.
Below is an example of wakeing up by console.
Run below command before entering suspend status.
	# echo enabled > /sys/devices/platform/amba/ff000000.serial/tty/ttyPS0/power/wakeup
And then, press Enter key in console window.

14. System Monitor
==================

System monitor includes PL monitor and PS monitor.
Each system monitor measures voltage and temperature to provide information and alarms
to other parts of the system including the PMU, RPU, and APU processors.

Customer could check the detail system monitor interfaces with below command:
	# ls -la /sys/bus/iio/devices/iio:device0