README.Xilinx

#################################################################################
# I.   Main Contents of Prebuilt						#
# II.  BSP generation steps 							#
# 	II.a Create and Configure a project					#
#	II.b Get openamp,qemu and xen device tree				#
#	II.c Enable openamp and its examples in rootfs				#
#	II.d Configuring BSP							#
#	II.e Project Build							#
#	II.f Clean up of configurations						#
#	II.g Packageing a BSP							#
# III. Software Images								#
# IV.  Hardware Images								#
# V.   Software Projects							#
#################################################################################

I. Main Contents of Prebuilt
================================================================================
|-- pre-built/ 	# Pre-built images directory
| |-- linux/ 	# Pre-built Linux system images
| | |-- images/
| | | |-- zynqmp_fsbl.elf 	# First stage bootloader
| | | |-- System.map.linux 	# Linux kernel system map
| | | |-- pmufw.elf 		# pmu firmware
| | | |-- image.ub 		# FIT image including the kernel and DTB
| | | |-- Image 		# kernel image
| | | |-- system.dtb 		# DTB used for A53 Linux kernel
| | | |-- u-boot.elf 		# u-boot ELF
| | | |-- BOOT.BIN 		# zynqmp boot BIN file
| | | |-- bl31.elf 		# atf ELF
| | |-- implementation/
| | | |-- download.bit 		# FPGA bitstream

II. BSP generation steps
================================================================================
This section explain about BSP generation steps.

Note:	While building bsps, we use some openAMP, Xen and QEMU files from internal repos
	If you want to use openAMP, Xen or QEMU, Please copy the files from published bsp's
	While copying files please maintain same directory structure.

	II.a Creation and configuration of project

		$ petalinux-create -t project --template zynqMP --force -n <name of project>
		$ petalinux-config --get-hw-description=<path to hdf directory> --oldconfig

	II.b Get openamp,qemu and xen device trees

		$ cp -r <any-zynqMP-BSP>/project-spec/meta-user/recipes-bsp/device-tree/files/{openamp-overlay.dtsi,xen-overlay.dtsi,zynqmp-qemu-arm.dts,multi-arch/} <project root>/project-spec/meta-user/recipes-bsp/device-tree/files


		$ echo '/include/ "openamp-overlay.dtsi"' >>  <project root>/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi

		$ echo 'SRC_URI += "file://openamp-overlay.dtsi"' >> project-spec/meta-user/recipes-bsp/device-tree/device-tree_%.bbappend

	II.c Enable openamp and its examples in rootfs

		$ petalinux-config -c rootfs
			Select following packages and save it
				openamp-fw-echo-testd
				openamp-fw-mat-muld
				openamp-fw-rpc-demo
				packagegroup-petalinux-openamp
	II.d Configuring BSP

		1. zcu102 production and zcu102 rev1.0 boards
		2. zcu102 es2 and zcu102 revD board
		3. zcu102 warm restart board
		4. zcu106 es2, zcu106 and zcu104 production boards ( Multimedia boards )
		5. ultra96 board.

		Choose any desired board and follow steps in it.

		1.zcu102 production and es2 rev1.0 board
			$ petalinux-config
				Add  xilinx_zynqmp_zcu102_rev1_0_defconfig to SUBSYSTEM_UBOOT_CONFIG_TARGET
				Enter zcu102-rev1.0 for MACHINE_NAME option ( DTG board parameter)
				Enter zcu102-zynqmp for YOCTO_MACHINE_NAME option

		2.zcu102 es2 and revD board
			$ petalinux-config
				Add  xilinx_zynqmp_zcu102_revB_defconfig to SUBSYSTEM_UBOOT_CONFIG_TARGET
				Enter zcu102-revb for MACHINE_NAME option ( DTG board parameter)
				Enter zcu102-zynqmp for YOCTO_MACHINE_NAME option

		3.zcu102 warm restart board
			$ cat >>  project-spec/meta-user/recipes-core/images/petalinux-image.bbappend <<EOF
IMAGE_INSTALL_append = " wdt-heartbeat"
IMAGE_INSTALL_append = " mpsrm-init"
IMAGE_INSTALL_append = " openamp-fw"
EOF
			$ petalinux-config --oldconfig
			$ petalinux-config -c rootfs
				Select following packages and save it
					wdt-heartbeat
					mpsrm-init
					openamp-fw

			$ echo 'SIGGEN_UNLOCKED_RECIPES += "initscripts"' >> <project root>/build/conf/local.conf

			$ petalinux-config -c kernel
				Select following configs and save it
					IRQ_DOMAIN_DEBUG
					GCOV_KERNEL
					FREEZER
					SUSPEND
					PM
					SRAM

			$ petalinux-config
				Add xilinx_zynqmp_zcu102_rev1_0_defconfig to SUBSYSTEM_UBOOT_CONFIG_TARGET
				Enter zcu102-rev1.0 for MACHINE_NAME option ( DTG board parameter)
				Enter zcu102-zynqmp for YOCTO_MACHINE_NAME option

			NOTE:copy wdt-heartbeat,mpsrm-init,openamp-fw recipes from the warm restart BSP at project-spec/meta-user/recipes-apps/{openamp-fw,wdt-heartbeat}, project-spec/meta-user/recipes-core/mpsrm-init

		4.zcu106 es2 ,zcu106 and zcu104 boards
			$ echo 'IMAGE_INSTALL_append = " gstreamer-vcu-examples"' >> <project root>/project-spec/meta-user/recipes-core/images/petalinux-image.bbappend
			$ petalinux-config --oldconfig
			$ petalinux-config -c rootfs
				Select following packages and save it
					packagegroup-petalinux-gstreamer
					packagegroup-petalinux-matchbox
					packagegroup-petalinux-x11
					libdrm
					libdrm-kms
					libdrm-tests
					gstreamer-vcu-examples
			$ petalinux-config
				Add xilinx_zynqmp_zcu106_revA_defconfig to SUBSYSTEM_UBOOT_CONFIG_TARGET for zcu106 boards
				Enter zcu106-reva for MACHINE_NAME option for zcu106 boards ( DTG board parameter)
				Enter zcu106-zynqmp for YOCTO_MACHINE_NAME option for zcu106 boards

				Add xilinx_zynqmp_zcu104_revC_defconfig to SUBSYSTEM_UBOOT_CONFIG_TARGET for zcu104 board
				Enter zcu104-revc for MACHINE_NAME option for zcu104 board ( DTG board parameter)
				Enter zcu104-zynqmp for YOCTO_MACHINE_NAME option for zcu104 board
		5. ultra96 board
			$ cat >>  project-spec/meta-user/recipes-core/images/petalinux-image.bbappend <<EOF
IMAGE_INSTALL_append = " peekpoke"
IMAGE_INSTALL_append = " gpio-demo"
IMAGE_INSTALL_append = " packagegroup-base-extended"
IMAGE_INSTALL_append = " cmake"
IMAGE_INSTALL_append = " lmsensors-sensorsdetect"
IMAGE_INSTALL_append = " python-pyserial"
IMAGE_INSTALL_append = " libftdi"
IMAGE_INSTALL_append = " python3-pip"
IMAGE_INSTALL_append = " iperf3"
IMAGE_INSTALL_append = " packagegroup-petalinux-ultra96-webapp"
IMAGE_INSTALL_append = " packagegroup-petalinux-v4lutils"
IMAGE_INSTALL_append = " packagegroup-petalinux-96boards-sensors"
IMAGE_INSTALL_append = " packagegroup-petalinux-x11"
IMAGE_INSTALL_append = " packagegroup-petalinux-matchbox"
EOF

			$ petalinux-config -c rootfs
				Select following packages and save it
				packagegroup-base-extended
				cmake
				lmsensors-sensorsdetect
				packagegroup-petalinux-self-hosted
				packagegroup-petalinux
				git
				python-pyserial
				libftdi
				python3-pip
				iperf3
				packagegroup-petalinux-ultra96-webapp
				packagegroup-petalinux-v4lutils
				packagegroup-petalinux-96boards-sensors
				packagegroup-petalinux-x11
				packagegroup-petalinux-matchbox
			$petalinux-config
				Select CONFIG_SUBSYSTEM_SERIAL_PSU_UART_1_SELECT
				Select CONFIG_SUBSYSTEM_ROOTFS_SD
				Enter xilinx_zynqmp_zcu100_revB_defconfig to SUBSYSTEM_UBOOT_CONFIG_TARGET for ultra96 boards
				Enter zcu100-revc for MACHINE_NAME option  ( DTG board paramater)
				Enter "ultra96-zynqmp" for YOCTO_MACHINE_NAME option.
			$ petalinux-config -c u-boot
				Change CONFIG_BOOTDELAY to 2 and then enable below configs and save.
				CONFIG_NET
				CONFIG_NET_TFTP_VARS
				CONFIG_NET_RANDOM_ETHADDR
				CONFIG_CMD_NET
				CONFIG_CMD_PING
				CONFIG_CMD_DHCP
				CONFIG_CMD_TFTPPUT
				CONFIG_CMD_NFS

	$ Optional configurations.
				If prebuilt kernel image is more than 128M, jtag boot command "petalinux-boot --jtag/--qemu --prebuilt 3 would not work due to overlap between kernel image & linux-boot.elf (bl33 used in jtag mode). So, to overcome this issue, BL33 entry address (U-boot and linux-boot.elf start/load address) is changed to 0x10080000. This is done through:
				$petalinux-config
					Enter 0x10080000 to CONFIG_SUBSYSTEM_ZYNQMP_PRELOADED_BL33_BASE.
				$petalinux-config -c u-boot
					Enter 0x10080000 to CONFIG_SYS_TEXT_BASE.


	II.e. Project Build

		1. Build regular images
			$ petalinux-build
			$ mkdir -p pre-built/linux/images
			$ cp <project root>/images/linux/* <project root>/pre-built/linux/images/

		2. Build xen images
			$ echo '/include/ "xen-overlay.dtsi"' >> <project root>/project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi
			$ echo 'SRC_URI += "file://xen-overlay.dtsi \"' >> project-spec/meta-user/recipes-bsp/device-tree/device-tree_%.bbappend
			$ petalinux-config
				Select following config and save it.
					Image Packaging Configuration
						Root filesystem type (INITRD)
			$ petalinux-config -c rootfs
				Select following package and save it
					packagegroup-petalinux-xen
			$ petalinux-build
			$ cp -L <project root>/images/linux/Image <project root>/pre-built/linux/images/xen-Image
			$ cp -L <project root>/images/linux/system.dtb <project root>/pre-built/linux/images/xen.dtb
			$ cp -L <project root>/images/linux/xen.ub <project root>/pre-built/linux/images/xen.ub
			$ cp -L <project root>/images/linux/rootfs.cpio.gz.u-boot <project root>/pre-built/linux/images/xen-rootfs.cpio.gz.u-boot

	II.f. Clean up of configurations

		Bydefault few configurations are enabled to generate prebuilt images. These configurations are cleaned up while packaging a bsp. However you can keep them if you need them in project.

		$ petalinux-config -c rootfs
			disable following packages and save it
				openamp-fw-echo-testd
				openamp-fw-mat-muld
				openamp-fw-rpc-demo
				packagegroup-petalinux-openamp
				packagegroup-petalinux-xen
		$ petalinux-config
			Select following config and save it.
				Image Packaging Configuration
					Root filesystem type (INITRAMFS)


	II.g. Packageing a BSP
		Package the BSP with files generated with following command
		$  petalinux-package --bsp -p <plnx-proj-root> --hwsource <hw-project-root> --output <name of the BSP>

                NOTE: --hwsource is optional and can be removed

III. Software Images
================================================================================
You can run the following command to rebuild the software images:
 * zynqmp_fsbl.elf
 * image.ub
 * Image
 * u-boot.elf
 * system.dtb
 * pmufw.elf
 * bl31.elf

   $ petalinux-build

You can also rebuild some of the images alone as follows:
 * zynqmp_fsbl.elf
   $ petalinux-build -c bootloader

 * u-boot.elf
   $ petalinux-build -c u-boot

 * system.dtb
   $ petalinux-build -c device-tree

 * kernel only:
   $ petalinux-build -c kernel

For more info regarding how to build images run "petalinux-build --help" command

You can generate BOOT.BIN file with "petalinux-package --boot" command:
 $ petalinux-package --boot --fpga pre-built/linux/images/design_1_wrapper.bit \
   --fsbl pre-built/linux/images/zynqmp_fsbl.elf \
   --u-boot pre-built/linux/images/u-boot.elf	\
   --pmufw prebuilt/linux/images/pmufw.elf	\
   --atf pre-built/linux/images/bl31.elf

IV. Hardware Images
================================================================================
 * design_1_wrapper.bit
   The hardware project source files are in "hardware/" directory. You can
   open the hardware project with vivado, and rebuild it.

V. Software Projects
================================================================================
 * fsbl, pmufw, device-tree
   All xsct software projects and corresponding bsp & hardware projects can be found at "components/plnx_workspace/" directory