meta-xilinx
===========

This layer provides Official support for Xilinx MicroBlaze and Zynq
architectures as well as evaluation boards.

Supported Boards/Machines
=========================

Boards Supported by this layer (Please refer to the associate .conf for more
information):
	* Xilinx KC705 Embedded TRD (MicroBlaze)
	* Xilinx ZC702 (Zynq)
	* Avnet/Digilent ZedBoard (Zynq)

Additional information on the MicroBlaze or Zynq architectures can be found at:
	http://www.xilinx.com/support/index.htm

Patches
=======

Please submit any patches for this layer to: meta-xilinx@lists.yoctoproject.org.

Please see the MAINTAINERS file for more details.

Dependencies
============

This layer depends on:

	URI: git://git.openembedded.org/bitbake

	URI: git://git.openembedded.org/openembedded-core
	layers: meta

Build Instructions
==================

The following instructions require a Poky installation (or equivalent).

Initialize a build using the 'oe-init-build-env' script in Poky. Once
initialized configure bblayers.conf by adding the 'meta-xilinx' layer. e.g.:

	BBLAYERS ?= " \
		<path to layer>/oe-core/meta \
		<path to layer>/meta-xilinx \
		"

To build a specific target BSP configure the associated machine in local.conf:

	MACHINE ?= "zc702-zynq7"

Note: Currently MicroBlaze targets only support being built with an External
toolchain, please see the section below 'Configuring External Toolchain'.

Build the target file system image using bitbake:

	$ bitbake core-image-minimal

Build additional targets include Linux and U-Boot:

	$ bitbake linux-xlnx u-boot-xlnx

Once complete the images for the target machine will be available in the output
directory 'tmp/deploy/images'.

Images generated:
	* core-image-minimal-<machine name>.tar.gz (rootfs tar+GZIP)
	* core-image-minimal-<machine name>.cpio (rootfs in CPIO format)
	* core-image-minimal-<machine name>.ext2.gz.u-boot (rootfs in EXT2+GZIP, u-boot wrapped format)
	* u-boot.elf (U-Boot ELF)
	* For Zynq:
		* uImage (Linux Kernel binary, in u-boot wrapped format)
		* uImage-<machine name>.dtb (DTB for target machine)
	* For MicroBlaze:
		* linux.bin.ub (Linux Kernel binary, in u-boot wrapped format)
		* linux.bin.ub-<machine name>.dtb (DTB for target machine)

Booting
=======

Please see the associated README file for each avaliable boot method in the
'docs/BOOT.*' files of this layer.

Known Issues
============

MicroBlaze Yocto Built Toolchain fails to compile shadow
--------------------------------------------------------
There is an issue with the GCC 4.8 toolchain built by Yocto which fails to
correctly built the 'shadow' package due to an assembler error.

{standard input}: Assembler messages:
{standard input}:754: Error: operation combines symbols in different segments

The current workaround for this issue is to build the entire repository
without debug symbols, or to disable debug symbols only for shadow.

e.g. Add the following to local.conf:
	DEBUG_FLAGS_pn-shadow = ""

MicroBlaze Linux Kernel 3.8+ and GCC 4.8+ fails to boot
-------------------------------------------------------
There is a regression in GCC 4.8 that causes a race condition in the kernel. It
occurs due to changes in the optimization and improper handling of certain
branch optimization where delay slots are used.

The error during kernel boot looks similar to:
	------------[ cut here ]------------
	WARNING: at mm/mmap.c:2657 exit_mmap+0x158/0x178()

There are two work arounds for this issue, the first which is recommended is to
use the MicroBlaze external toolchain that is provided by Xilinx SDK or
PetaLinux.

The the second workaround applies to the linux-xlnx only, disable the kernel
configuration "CONFIG_OPTIMIZE_FOR_SIZE". This prevents the compiler from trying
to optimize the delay slots incorrectly.

Configuring External Toolchain
==============================

In order to build with an external toolchain some additional configuration must
be set in the build environments local.conf. First configure the use of an
external toolchain, including the location to the toolchain:

	TCMODE = "external-xilinx"
	EXTERNAL_TOOLCHAIN = "<path to toolchain>"