README: Updated README files for meta-xilinx and BSPs

* Cleaned up some duplication
* Added README for meta-kc705
* Added additional information

Signed-off-by: Nathan Rossi <nathan.rossi@xilinx.com>

4 files changed, 253 insertions, 112 deletions

diff --git a/README b/README
index 792bbebe..ca641fbd 100644
--- a/README
+++ b/README
@@ -1,21 +1,137 @@
-This layer provides support for Xilinx microblaze and zynq platforms. 
+meta-xilinx
+===========
 
-Specific boards supported in this layer:
+This layer provides Official support for Xilinx MicroBlaze and Zynq architectures
+as well as evaluation boards.
 
- * kc705 microblaze TRD
- * zc702 Zynq evaluation board
- * zedboard Avnet Digilent evaluation board
+Supported Boards/Machines
+=========================
 
-End users should create a layer and use bbappends to extend
-the recipes in this layer to support their boards.
+Boards Supported by this layer and sub-layers:
+        * Xilinx KC705 Embedded TRD (MicroBlaze)
+        * Xilinx ZC702 (Zynq)
+        * Avnet/Digilent ZedBoard (Zynq)
 
-Patches for this layer should be sent to meta-xilinx@lists.yoctoproject.org.
+Patches
+=======
 
-You can submit single patches with this command:
+Please submit any patches for this layer to: meta-xilinx@lists.yoctoproject.org.
 
-'git send-email -M -1 --to meta-xilinx@lists.yoctoproject.org --subject-prefix=PATCH'
+Please see the MAINTAINERS file for more details.
 
-For longer sets fork the meta-xilinx repo on github and push to a branch.
+Dependencies
+============
 
-Refer to the README in each meta-<bsp> layer for building and booting 
-information.
\ No newline at end of file
+This layer depends on:
+
+        URI: git://git.openembedded.org/bitbake
+
+        URI: git://git.openembedded.org/openembedded-core
+        layers: meta
+
+        (for external toolchains only)
+        URI: git://github.com/MentorEmbedded/meta-sourcery.git
+        layers: meta-sourcery
+
+This repository also contains sub-layers which depend on this layer.
+
+Sub-Layers
+==========
+
+This repository contains the meta-xilinx layer as well as additional board
+specific layers. Each of these board specific layers provide additional
+configuration for the associated board. Please refer to the associated README
+in each sub-layer for more details.
+
+Note: sub-layers have no dependency between each other, all sub-layers can be
+used at the same time without conflicts.
+
+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 as
+well as any or all of the sub-layers of this repository, e.g.:
+
+        meta-xilinx \
+        meta-xilinx/meta-kc705 \
+        meta-xilinx/meta-zc702 \
+        meta-xilinx/meta-zedboard \
+
+To build a specific target BSP configure the associated machine in local.conf:
+(See associated sub-layers for available machines and additional details)
+
+        MACHINE ?= "zc702"
+
+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>.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 for the target machine, located in the
+associated sub-layer.
+
+Configuring External Toolchain
+==============================
+
+In order to build with an external toolchain some additional configuration must
+be set in the build environments local.conf. The 'meta-sourcery' layer must also
+be setup in your bblayers.conf
+
+First configure the use of an external toolchain, including the location to the
+toolchain (this example is for a microblazeel toolchain, ensure that you insert
+the relevant information for your target machine and target toolchain):
+
+        TCMODE = "external-csl"
+        CSL_TARGET_SYS_<machine name> = "microblazeel-xilinx-linux-gnu"
+        EXTERNAL_TOOLCHAIN = "<path to toolchain>/microblazeel-xilinx-linux-gnu"
+        EXTERNAL_TOOLCHAIN_SYSROOT = "<path to toolchain>/microblazeel-xilinx-linux-gnu/microblazeel-xilinx-linux-gnu/libc"
+        INSANE_SKIP_external-sourcery-toolchain-dev += "ldflags"
+
+Additionally the preferred provider for various packages must be configured to
+use the external toolchain:
+
+        PREFERRED_PROVIDER_linux-libc-headers = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_linux-libc-headers-dev = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/${TARGET_PREFIX}gcc = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/${TARGET_PREFIX}gcc-initial = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/${TARGET_PREFIX}gcc-intermediate = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/${TARGET_PREFIX}g++ = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/${TARGET_PREFIX}binutils = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/${TARGET_PREFIX}libc-initial = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/${TARGET_PREFIX}libc-for-gcc = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/${TARGET_PREFIX}compilerlibs = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_libgcc = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_eglibc = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/libc = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/libintl = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/libiconv = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_glibc-thread-db = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/linux-libc-headers = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_virtual/linux-libc-headers-dev = "external-sourcery-toolchain"
+        PREFERRED_PROVIDER_gdbserver = "external-sourcery-toolchain"
diff --git a/meta-kc705/README b/meta-kc705/README
new file mode 100644
index 00000000..538d2a2c
--- /dev/null
+++ b/meta-kc705/README
@@ -0,0 +1,65 @@
+meta-kc705
+==========
+
+This README file contains information on using the meta-kc705 BSP layer.
+
+The KC705 is an evaluation board by Xilinx for the MicroBlaze architecture:
+        http://www.xilinx.com/products/boards-and-kits/DK-K7-EMBD-G.htm
+
+Please refer to the meta-xilinx/README for details regarding patch submission,
+layer dependencies, build process, etc.
+
+Supported Boards/Machines
+=========================
+
+Xilinx KC705 Embedded TRD (MicroBlaze) - 'kc705-trd'
+        The 'KC705_System' or 'BIST system' as described in the documentation.
+
+        Note: this design contains the 'Xylon logiSDHC' additional IP cores, this is
+        not supported by this BSP.
+
+Reference files and documents
+=============================
+
+For details on the TRD and Evaluation board:
+        http://www.xilinx.com/products/boards-and-kits/DK-K7-EMBD-G.htm
+
+For documentation and design files for the TRD:
+        http://www.xilinx.com/support/index.html/content/xilinx/en/supportNav/boards_and_kits/kintex-7_boards_and_kits/kintex-7_fpga_embedded_kit.html
+
+Additional information on MicroBlaze architecture can be found at:
+        http://www.xilinx.com/support/index.htm
+
+RAMFS/INITRD Boot (via JTAG/TFTP)
+=================================
+
+Note: This boot flow requires a TFTP server as well as access to Xilinx tools
+(for JTAG programming).
+
+Place the following images into the root of the TFTP server directory:
+        * core-image-minimal-<machine name>.ext2.gz.u-boot (RootFS)
+        * linux.bin.ub (Linux Kernel)
+        * linux.bin.ub-<machine name>.dtb (DTB)
+
+Download the bitstream for the target machine using JTAG (The pre-built
+bitstream provided in the reference design files should be used).
+
+Download the 'u-boot.elf' to the target CPU via the use of XMD.
+        $ xmd
+        XMD% connect mb mdm
+        XMD% rst
+        XMD% dow u-boot.elf
+        XMD% con
+
+The serial console of the KC705 board (the USB-UART interface) will display the
+U-Boot console. Configure the 'ipaddr' and 'serverip' of the U-Boot environment.
+        U-Boot> set serverip <server ip>
+        U-Boot> set ipaddr <board ip>
+
+Using the U-Boot console; load the Kernel (at 0x86000000), RootFS
+(at 0x85000000) and the DTB (at 0x84000000) into memory. And then boot Linux
+using the 'bootm' command.
+        U-Boot> tftp 0x86000000 linux.bin.ub
+        U-Boot> tftp 0x85000000 core-image-minimal-<machine name>.ext2.gz.u-boot
+        U-Boot> tftp 0x84000000 linux.bin.ub-<machine name>.dtb
+        U-Boot> bootm 0x86000000 0x85000000 0x84000000
diff --git a/meta-zc702/README b/meta-zc702/README
index 868c2b74..cf3b57d8 100644
--- a/meta-zc702/README
+++ b/meta-zc702/README
@@ -1,65 +1,46 @@
-This README file contains information on building the meta-zc702
-BSP layer.
+meta-zc702
+==========
 
-The zc702 is an evaluation board by Xilinx for Zynq architecture:
-  http://www.xilinx.com/
+This README file contains information on using the meta-zc702 BSP layer.
 
-Dependencies
-============
+The zc702 is an evaluation board by Xilinx for Zynq architecture:
+        http://www.xilinx.com/
 
-This layer depends on:
+Please refer to the meta-xilinx/README for details regarding patch submission,
+layer dependencies, build process, etc.
 
-  URI: git://git.yoctoproject.org/poky
-  branch: master
+Supported Boards/Machines
+=========================
 
-  URI: git://github.com/Xilinx/meta-xilinx
-  branch: master
+Xilinx ZC702 (Zynq) - 'zc702'
 
+Reference files and documents
+=============================
 
-Patches
-=======
+For details on the Evaluation board:
+        http://www.xilinx.com/products/boards-and-kits/EK-Z7-ZC702-G.htm
 
-Refer meta-xilinx/README for patch submission details
+For documentation and design files for the ZC702:
+        http://www.xilinx.com/support/index.html/content/xilinx/en/supportNav/boards_and_kits/zynq-7000_soc_boards_and_kits/zynq-7000_soc_zc702_evaluation_kit.html
 
-Build Instructions
-==================
+For the FSBL 'zynq_fsbl_0.elf' refer to UG873 and the associated design files.
 
-Setup a Yocto Poky installation
- - http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html
-Clone the meta-xilinx layer into your installation
-Add meta-xilinx and meta-xilinx/meta-zc702 to your bblayers.conf file
-Add MACHINE="zc702" to your local.conf file
-Build
- > bitbake core-image-minimal
- > bitbake u-boot-xlnx
-Images can be found in 'tmp/deploy/images' of your build directory
-   kernel - uImage*.bin
-   rootfs - core-image-minimal-zc702-*.rootfs.ext2.gz.u-boot
-   uboot  - u-boot-zc702-v*.elf
-   device tree - uImage-*-zynq-zc702-*.dtb
+Additional information on Zynq architecture can be found at:
+        http://www.xilinx.com/support/index.htm
 
-SD Card boot
+SD Card Boot
 ============
 
-Copy and rename files as follows. Multiple builds will result in multiple
-images, so choose the correct files (see above for image file name formats)
-   kernel - uImage
-   rootfs - uramdisk.image.gz
-   uboot  - u-boot.elf
-   device tree - devicetree.dtb
+Note: This boot flow requires access to Xilinx tools (for BOOT.BIN generation).
 
-Use Xilinx tools to pack zynq_fsbl_0.elf and u-boot.elf into BOOT.BIN.
- - You can use Webpack or licensed Xilinx tools
-Copy BOOT.BIN, devicetree.dtb, uImage and uramdisk.image.gz to the SD Card.
-Insert SD Card, connect UART to Terminal program and boot board.
+Copy the following to the SD card (ensure to rename the files where appropriate):
+        Kernel: uImage
+        RootFS: uramdisk.image.gz (core-image-minimal-<machine name>.ext2.gz.u-boot)
+        DTB:    devicetree.dtb (uImage-<machine name>.dtb)
 
+Using the Xilinx tools, package 'zynq_fsbl_0.elf' and 'u-boot.elf' into a 
+'BOOT.BIN' (See http://www.wiki.xilinx.com/Prepare+Boot+Image for details). Once
+created copy 'BOOT.BIN' onto the SD Card.
 
-Reference files and documents
-=============================
-http://www.xilinx.com/support/download/index.htm
- - Search for ug873
- - "Zynq-7000 All Programmable SoC: Concepts, Tools, and Techniques (CTT)"
- - Design files ug873-design-files.zip for zynq_fsbl_0.elf
-
-Additional information on Zynq architecture can be found at:
-  http://www.xilinx.com/support/index.htm
+Insert SD Card, connect UART to Terminal program and boot board (Ensure the
+board is configured for SD Boot).
diff --git a/meta-zedboard/README b/meta-zedboard/README
index 3651cccb..20771eb9 100644
--- a/meta-zedboard/README
+++ b/meta-zedboard/README
@@ -1,65 +1,44 @@
-This README file contains information on building the meta-zedboard
-BSP layer.
+meta-zedboard
+==========
 
-The zedboard is an evaluation board by Avnet-Digilent for Xilinx Zynq
-architecture:
-  http://www.zedboard.org/
+This README file contains information on using the meta-zedboard BSP layer.
 
-Dependencies
-============
-
-This layer depends on:
+The ZedBoard is an evaluation board by Avnet/Digilent for the Zynq architecture:
+        http://www.zedboard.org/
 
-  URI: git://git.yoctoproject.org/poky
-  branch: master
+Please refer to the meta-xilinx/README for details regarding patch submission,
+layer dependencies, build process, etc.
 
-  URI: git://github.com/Xilinx/meta-xilinx
-  branch: master
+Supported Boards/Machines
+=========================
 
+Avnet/Digilent ZedBoard (Zynq) - 'zedboard'
 
-Patches
-=======
+Reference files and documents
+=============================
 
-Refer meta-xilinx/README for patch submission details
+For details on the Evaluation board:
+        http://www.zedboard.org/content/overview
 
-Build Instructions 
-==================
+For design files (including 'zynq_fsbl_0.elf') for the ZedBoard:
+        http://www.zedboard.org/reference-designs-categories/zynq-concepts-tools-and-techniques-zedboard
 
-Setup a Yocto Poky installation 
- - http://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html
-Clone the meta-xilinx layer into your installation
-Add meta-xilinx and meta-xilinx/meta-zedboard to your bblayers.conf file
-Add MACHINE="zedboard" to your local.conf file
-Build
- > bitbake core-image-minimal
- > bitbake u-boot-xlnx
-Images can be found in 'tmp/deploy/images' of your build directory
-   kernel - uImage*.bin
-   rootfs - core-image-minimal-zedboard-*.rootfs.ext2.gz.u-boot
-   uboot  - u-boot-zedboard-v*.elf 
-   device tree - uImage-*-zynq-zed-*.dtb
+Additional information on Zynq architecture can be found at:
+        http://www.xilinx.com/support/index.htm
 
-SD Card boot
+SD Card Boot
 ============
 
-Copy and rename files as follows. Multiple builds will result in multiple 
-images, so choose the correct files (see above for image file name formats)
-   kernel - uImage
-   rootfs - uramdisk.image.gz
-   uboot  - u-boot.elf
-   device tree - devicetree.dtb
+Note: This boot flow requires access to Xilinx tools (for BOOT.BIN generation).
 
-Use Xilinx tools to pack zynq_fsbl_0.elf and u-boot.elf into BOOT.BIN.
- - You can use Webpack or licensed Xilinx tools
-Copy BOOT.BIN, devicetree.dtb, uImage and uramdisk.image.gz to the SD Card.
-Insert SD Card, connect UART to Terminal program and boot board
+Copy the following to the SD card (ensure to rename the files where appropriate):
+        Kernel: uImage
+        RootFS: uramdisk.image.gz (core-image-minimal-<machine name>.ext2.gz.u-boot)
+        DTB:    devicetree.dtb (uImage-<machine name>.dtb)
 
+Using the Xilinx tools, package 'zynq_fsbl_0.elf' and 'u-boot.elf' into a 
+'BOOT.BIN' (See http://www.wiki.xilinx.com/Prepare+Boot+Image for details). Once
+created copy 'BOOT.BIN' onto the SD Card.
 
-Reference files and documents 
-=============================
-http://www.zedboard.org/reference-designs-categories/zynq-concepts-tools-and-techniques-zedboard
- - "Zynq Concepts, Tools, and Techniques on ZedBoard"
-  - contains both PDF file and design files including zynq_fsbl_0.elf
-
-Additional information on Zynq architecture can be found at:
-  http://www.xilinx.com/support/index.htm
+Insert SD Card, connect UART to Terminal program and boot board (Ensure the
+board is configured for SD Boot).