Xilinx ZYNQ Board Support Package

1. About this document
======================

This document describes 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 wr-kernel layer.


Maintenance
-----------
This layer is maintained by Wind River Systems, Inc.
Contact <[email protected]> or your support representative for more
information on submitting changes.


Building the xilinx-zynq layer
------------------------------
This layer and the wr-kernel layer should be added to bblayers.conf. This
is done automatically when using the Wind River configure wrapper.


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

The right to copy, distribute or otherwise make use of this software may
be licensed only pursuant to the terms of an applicable Wind River license
agreement. No license to Wind River intellectual properly rights is granted
herein. All rights not licensed by Wind River are reserved by Wind River.

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


2. 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 build/linux-windriver-<version>/linux
	# git whatchanged standard/base..HEAD


3. Boot Instructions
====================

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

	# make kds
	# make zynq-<Board Name>.dtb

Note: <Board Name> can be one of the ZYNQ boards' name, such as zc706, zc702,
zynq-zed or zynq-mini-itx-adv7511.

The DTB can then be found in the
  build/linux-windriver/linux-<board>-<kernel type>-build/arch/arm/boot/dts/
directory.

Copy DTB image to MMC/SD or QSPI Flash, and use u-boot's fatload command
to transfer it to the board before booting along with kernel image.


3.1 Boot from MMC/SD card
-------------------------

MMC/SD can be set as the default booting device for this board and two
partitions have been created on the MMC/SD card by default, the first one
is booting partition while the second is root filesystem, which can be
created by the fdisk command on the host machine.

Note: please refer to the README.hardware for further details about the
switches configuration for setting MMC/SD as the first boot device.

3.1.1 Create two partitions and store the u-boot image
------------------------------------------------------
(1) Create two partitions on the MMC/SD card.

	# fdisk /dev/mmcblk0

Suppose the device node for MMC/SD card on the host machine is the
/dev/mmcblk0.

(2) Create VFAT filesystem on the first partition.

	# mkfs.vfat /dev/mmcblk0p1

(3) Copy BOOT.BIN file to /dev/mmcblk0p1.

The BOOT.BIN file can be downloaded from the XILINX's website at
http://www.wiki.xilinx.com/Zynq+14.7-2013.3+Release

The BOOT.BIN for the mini-itx can be found at
http://zedboard.org/support/design/2056/17. Since the bitstream for
PCIe support is different from non-PCIe features, both the BOOT.BIN
must be replaced and the jumpers set. Please see the bootloader's
README for additional details.

	# mkdir /mnt/sd
	# mount -t vfat /dev/mmcblk0p1 /mnt/sd
	# cp BOOT.BIN /mnt/sd
	# umount /mnt/sd


3.1.2 Copy kernel image and DTB image to /dev/mmcblk0p1
-------------------------------------------------------

	# mkdir /mnt/sd
	# mount /dev/mmcblk0p1 /mnt/sd
	# cd <buildprj>/export/images/
	# cp uImage-xilinx-zynq.bin  /mnt/sd/uImage
	# cp uImage-zynq-<Board Name>.dtb /mnt/sd/devicetree.dtb
	# umount /mnt/sd


3.1.3 Decompress MMC/SD root filesystem
---------------------------------------

Assuming the second partition is used for the root filesystem, format it
with one of the most popular filesystem types supported by Linux, for
instance, ext3 and mount it and deploy the root filesystem image there:

	# mkfs.ext3 /dev/mmcblk0p2
	# mount /dev/mmcblk0p2 /mnt/sd
	# cd <buildprj>/export/images/
	# tar -C /mnt/sd -jxf wrlinux-image-glibc-std-xilinx-zynq.tar.bz2 --numeric-owner
	# umount /mnt/sd


3.1.4 Boot from MMC/SD card
---------------------------

To boot from MMC/SD card, please use u-boot's commands as follows:

	# mmcinfo
	# fatload mmc 0 0x2a00000 devicetree.dtb
	# fatload mmc 0 0x3000000 uImage
	# setenv bootargs console=ttyPS0,115200 earlyprintk root=/dev/mmcblk0p2 ro rootwait
	# bootm 0x3000000 - 0x2a00000


3.2 Boot kernel from QSPI Flash
-------------------------------

Since not all uboot versions support QSPI flash, use
<build project>layers/wr-bsps/xilinx-zynq/bootloader/boot_mini-itx-pcie.bin
to ensure that the mini-itx board can boot from QSPI.

3.2.1 QSPI Flash layout
-----------------------

The storage capacity of the QSPI flash on ZYNQ board is 16MB, by default following
partitions have been created on it:

	Start			End		Definition
	0x0			0x100000	qspi-fsbl-uboot
	0x100000		0x600000	qspi-linux
	0x600000		0x620000	qspi-device-tree
	0x620000		0xc00000	qspi-rootfs
	0xc00000		0x1000000	qspi-bitstream

Note: The Mini-ITX board has a 32MB QSPI flash with the bootloader requiring
a 16MB partition for BOOT.BIN.

	Start			End		Definition
	0x0			0x1000000	qspi-fsbl-uboot
	0x1000000		0x1500000	qspi-linux
	0x1500000		0x1600000	qspi-device-tree
	0x1600000		0x2000000	qspi-rootfs

Be extra careful not to touch bootloader partition about FSBL and u-boot. If
needed, you can alter the layout of the rest of QSPI Flash. In addition, you
also need to modify the QSPI Flash device node in the below DTB source file to
reflect such changes accordingly:

	linux/arch/arm/boot/dts/zynq-<Board Name>.dts

Then re-generate the DTB image as described previously.


3.2.2 Save bootloader image to the bootloader partitions
--------------------------------------------------------

	# mmcinfo
	# fatload mmc 0 0x100000 BOOT.BIN
	# sf probe 0
	For the Mini-ITX board:
	# sf erase 0 0x1000000
	# sf write 0x100000 0 ${filesize}
	Others board:
	# sf erase 0 0x100000
	# sf write 0x100000 0 ${filesize}

Before writing the flash you need to know its current layout. Fortunately, you
can get this information by running the 'cat /proc/mtd' command once booting up
from MMC/SD device or NFS server. When loading the BOOT.BIN image from MMC/SD
card, its file size will be automatically recorded in u-boot's "filesize"
variable, which can be leveraged later.


3.2.3 Update DTB to support to boot from QSPI flash
---------------------------------------------------

	# mmcinfo
	# fatload mmc 0 0x2a00000 devicetree.dtb
	# sf probe 0
	For the Mini-ITX board:
	# sf erase 0x1600000 0x100000
	# sf write 0x2a00000 0x1600000 ${filesize}
	Others board:
	# sf erase 0x600000 0x20000
	# sf write 0x2a00000 0x600000 ${filesize}


3.2.4 Copy kernel image
-----------------------

	# mmcinfo
	# fatload mmc 0 0x3000000 uImage
	# sf probe 0
	For the Mini-ITX board:
	# sf erase 0x1100000 0x500000
	# sf write 0x3000000 0x1100000 ${filesize}
	Others board:
	# sf erase 0x100000 0x500000
	# sf write 0x3000000 0x100000 ${filesize}


3.2.5 Booting the kernel image
-----------------------------

	For the Mini-ITX board:
	# sf probe 0
	# sf read 0x2a00000 0x1600000 0x100000
	# sf read 0x3000000 0x1100000 0x500000
	# bootm 0x3000000 - 0x2a00000

	Others board:
	# sf probe 0
	# sf read 0x2a00000 0x600000 0x20000
	# sf read 0x3000000 0x100000 0x500000
	# bootm 0x3000000 - 0x2a00000


3.2.6 Target Note
-----------------

Since the size of the qspi-rootfs partition is no more than 8MB, unable to
accommodate a reasonable jffs2 filesystem which can be as large as 60MB,
therefore we cannot deploy jffs2 filesystem on QSPI flash, and the DTB defaults
to mount the root filesystem from MMC/SD card.


3.3 NFS Root File System
------------------------

3.3.1 Prepare NFS and TFTP servers
----------------------------------

The files in above example can be found in <buildprj>/export/images and
are copied to the directory of the NFS/TFTP server.


3.3.2 Boot from NFS root filesystem
-----------------------------------

To boot from NFS rootfs, please use u-boot's commands as follows:

	# setenv ipaddr 192.168.1.10
	# setenv serverip 192.168.1.1
	# setenv rootpath /nfsexport
	# setenv bootargs console=ttyPS0,115200 earlyprintk root=/dev/nfs rw nfsroot=$serverip:$rootpath ip=dhcp
	# tftpboot 0x3000000 uImage-xilinx-zynq.bin
	# tftpboot 0x2a00000 uImage-zynq-<Board Name>.dtb
	# bootm 0x3000000 - 0x2a00000


4. Features
===========

4.1 USB feature
---------------

4.1.1 Introduction
------------------

The Xilinx ZYNQ board supports USB OTG, USB host and USB device modes.
They share one common interface, therefore any mode can only be activated
exclusively. Jumpers can be used to switch among different modes, please
refer to README.hardware for the detailed information.


4.1.2 Usage and verification
----------------------------

USB host mode is supported by DTB by default, no extra changes to DTB is
needed. However, in order to enable other USB modes, DTB needs to be shifted
accordingly. One convenient approach is to alter it on-line. Alternatively,
you can directly modify its source code and re-generate a new DTB image.

Refer to the 4.1.3 section of the README.hardware file for jumper settings
for various USB modes.

1. Enable OTG host mode

Modify dtb for OTG mode in booting step

	# tftp 0x2a00000 devicetree.dtb
	# fdt addr 0x2a00000
	# fdt set /amba/ps7-usb dr_mode otg

Plug in a B cable and connect to the host machine to verify the OTG device mode.

Then replace the B cable with the A cable and enable OTG VBUS in linux as follows:

	# cd /sys/devices/amba.0/e0002000.ps7-usb/zynq-otg.0/inputs
	# echo 1 > a_bus_req

2. Enable USB Device mode

Change the board's DTB source file and modify following line from:

	dr_mode = "host";

to:

	dr_mode = "peripheral";

Then re-generate the DTB image as described previously. Use the new DTB image
to boot the board and plug in a B cable and connect to the host machine
to verify the device mode.


4.2 PCIE(Mini-ITX)
------------------

1. Get the BOOT.bin

The Mini-ITX board needs an special BOOT.BIN to support the PCIe support, which can be
downloaded from the Mini-ITX's website at:

http://zedboard.org/support/design/2056/17

Or

${build project}/layers/wr-bsps/xilinx-zynq/bootloader/

2. Setting the jumper

	JP1  1-2
	JP7  3-4
	JP12 2-3

3. Enter the following command to copy the BOOT.bin image to the SD/MMC card:

	$ sudo cp -rf boot_mini-itx-pcie.bin /mnt/sd/boot.bin

4. Using uImage-zynq-mini-itx-adv7511-pcie.dtb for the boot dtb


4.3 RTC, Audio for mini-itx
---------------------------

Please refer to bootloader/README


4.4 Audio
---------

4.4.1 Audio playback(ADAU1761)
------------------------------

Headphone out:
	# amixer cset name='Headphone Playback Volume' 57,57 -c1
	# amixer cset name='DAC Playback Mux' 0 -c1
	# amixer cset name='Right Playback Mixer Left DAC Switch' 1 -c1
	# amixer cset name='Right Playback Mixer Right DAC Switch' 1 -c1
	# amixer cset name='Left Playback Mixer Left DAC Switch' 1 -c1
	# amixer cset name='Left Playback Mixer Right DAC Switch' 1 -c1
        # speaker-test -c2 -twav -Dplughw:ADAU1761

Line out:

	# amixer cset name='DAC Playback Mux' 0 -c1
	# amixer cset name='Right Playback Mixer Left DAC Switch' 1 -c1
	# amixer cset name='Right Playback Mixer Right DAC Switch' 1 -c1
	# amixer cset name='Left Playback Mixer Left DAC Switch' 1 -c1
	# amixer cset name='Left Playback Mixer Right DAC Switch' 1 -c1
	# amixer cset name='Left LR Playback Mixer Left Volume' 2 -c1
	# amixer cset name='Left LR Playback Mixer Right Volume' 2 -c1
	# amixer cset name='Right LR Playback Mixer Left Volume' 2 -c1
	# amixer cset name='Right LR Playback Mixer Right Volume' 2 -c1
	# amixer cset name='Lineout Playback Volume' 57,57 -c1
	# speaker-test -c2 -twav -Dplughw:ADAU1761

Note:

There are two items for DAC Playback, make sure AIFIN for both above.

4.4.2 Audio HDMI playback
-------------------------

Connect the board and a HDMI display with a HDMI cable,
then enable fbdev HDMI.

Play the recorded audio messages:

        # speaker-test -c2 -twav