1 files changed, 212 insertions, 0 deletions
diff --git a/docs/README.booting.zynqmp.md b/docs/README.booting.zynqmp.md
new file mode 100644
index 00000000..c8f8aa21
--- /dev/null
+++ b/docs/README.booting.zynqmp.md
@@ -0,0 +1,212 @@
+# Booting OS Images on ZynqMP target boards
+Booting OS images on ZynqMP boards can be done using JTAG, SD, eMMC, QSPI and 
+NAND boot modes.
+* [Setting Up the Target](#setting-up-the-target)
+* [Booting from JTAG](#booting-from-jtag)
+  * [Loading boot components using XSCT](#loading-boot-components-using-xsct)
+  * [Loading Kernel, Root Filesystem and U-boot boot script](#loading-kernel-root-filesystem-and-u-boot-boot-script)
+    * [Using XSCT](#using-xsct)
+    * [Using TFTP](#using-tftp)
+* [Booting from SD](#booting-from-sd)
+* [Booting from QSPI](#booting-from-qspi)
+## Setting Up the Target
+1. Connect a USB cable between the CP2180 USB-to-Quad-UART bridge USB Micro-B on
+   the target and the USB port on the host machine.
+2. Connect a micro USB cable from the ZCU102 board USB UART port (J83) to the USB
+   port on the host machine.
+3. Default UART terminal(serial port) settings is Speed `115200`, Data `8 bit`,
+   Parity `None`, Stop bits ` 1 bit` and Flow control `None`.
+4. Set the board to JTAG and other boot mode by setting the boot mode switch by 
+   referring to board user guide. For zynqmp-generic machine configuration
+   file zcu102 evaluation board is used as reference and below is the
+   configuration boot mode settings (SW6).
+> **Note:** Switch OFF = 1 = High; ON = 0 = Low
+| Boot Mode | Mode Pins [3:0] | Mode SW6 [3:0]    | Comments                  |
+|-----------|-----------------|-------------------|---------------------------|
+| JTAG      | 0000            | ON, ON, ON, ON    | PS JTAG                   |
+| QSPI      | 0010            | ON, ON, OFF, ON   | QSPI 32-bit addressing    |
+| SD        | 1110            | OFF, OFF, OFF, ON | SD 3.0 with level shifter |
+## Booting from JTAG
+This boot flow requires the use of the AMD Xilinx tools, specifically XSCT and 
+the associated JTAG device drivers. This also requires access to the JTAG interface
+on the board, a number of AMD Xilinx and third-party boards come with on-board JTAG
+modules.
+1. Source the Vivado or Vitis tools `settings.sh` scripts.
+2. Power on the board, Open the XSCT console in the Vitis IDE by clicking the
+   XSCT button. Alternatively, you can also open the XSCT console by selecting
+   Xilinx -> XSCT Console.
+```
+$ xsct
+```
+3. In the XSCT console, connect to the target over JTAG using the connect command.
+   Optionally user can use `-url` to specify the local/remote hw_server. The 
+   connect command returns the channel ID of the connection.
+```
+xsct% connect
+```
+4. The targets command lists the available targets and allows you to select a
+   target using its ID. The targets are assigned IDs as they are discovered on
+   the JTAG chain, so the IDs can change from session to session.
+```
+xsct% targets
+```
+> **Note:** For non-interactive usage such as scripting, you can use the `-filter`
+   option to select a target instead of selecting the target using its ID.
+### Loading boot components using XSCT
+1. Download the boot images for the target using XSCT with the `fpga` and `dow` 
+   command. ZyqnMP boot images will be located in the `${DEPLOY_DIR_IMAGE}`
+   directory. 
+> **Note:** In yocto by default, ${DEPLOY_DIR_IMAGE}/system.dtb is used for both
+> u-boot and kernel.
+2. Program the bitstream or skip this step if you are loading from u-boot or linux.
+```
+xsct% fpga -no-revision-check ${DEPLOY_DIR_IMAGE}/download.bit
+```
+3. By default, JTAG security gates are enabled. Disable the security gates for 
+   DAP, PL TAP, and PMU (this makes the PMU MB target visible to the debugger).
+```
+xsct% targets -set -nocase -filter {name =~ "*PSU*"}
+xsct% mask_write 0xFFCA0038 0x1C0 0x1C0
+```
+3. Verify if the PMU MB target is listed under the PMU device. Now, load the PMU
+   firmware.
+```
+xsct% targets -set -nocase -filter {name =~ "*MicroBlaze PMU*"}
+xsct% catch {stop}
+xsct% dow ${DEPLOY_DIR_IMAGE}/pmufw.elf
+xsct% con
+```
+5. Reset APU Cortex-A53 Core 0 to load and execute FSBL, This step is important, 
+   because when the ZynqMP boots up in JTAG boot mode, all the APU and RPU cores
+   are held in reset. You must clear the resets on each core before performing 
+   debugging on these cores. You can use the `rst` command in XSCT to clear the
+   resets.
+```
+xsct% targets -set -nocase -filter {name =~ "*A53*#0"}
+xsct% rst -processor -clear-registers
+```
+6. Download and run FSBL from APU Cortex-A53 Core 0
+```
+xsct% dow ${DEPLOY_DIR_IMAGE}/zynqmp_fsbl.elf
+xsct% con
+```
+7. Now download TF-A, U-boot.elf and Device tree to APU and execute.
+```
+xsct% stop
+xsct% dow ${DEPLOY_DIR_IMAGE}/bl31.elf
+xsct% dow ${DEPLOY_DIR_IMAGE}/u-boot.elf
+xsct% dow -data ${DEPLOY_DIR_IMAGE}/system.dtb 0x100000
+xsct% con
+```
+8. In the target Serial Terminal, press any key to stop the U-Boot auto-boot.
+```
+...
+Hit any key to stop autoboot: 0
+U-Boot>
+```
+### Loading Kernel, Root Filesystem and U-boot boot script
+Load the images into the target DDR/PL DRR load address i.e.,
+`DDR base address + <image_offset>`. 
+Below example uses base DDR address as 0x0 which matches in vivado address editor.
+| Image Type         | Base DDR Address | Image Offset | Load Address in DDR |
+|--------------------|------------------|--------------|---------------------|
+| Kernel             | 0x0              | 0x200000     | 0x200000            |
+| Device Tree        | 0x0              | 0x1000       | 0x1000              |
+| Rootfs             | 0x0              | 0x04000000   | 0x4000000           |
+| U-boot boot script | 0x0              | 0x20000000   | 0x20000000          |
+> **Note:** 
+> 1. `<target-image>` refers to core-image-minimal or petalinux-image-minimal
+> 2. For pxeboot boot create a symlink for `<target-image>-${MACHINE}-${DATETIME}.cpio.gz.u-boot`
+> as shown `$ ln -sf ${DEPLOY_DIR_IMAGE}/<target-image>-${MACHINE}-${DATETIME}.cpio.gz.u-boot ${DEPLOY_DIR_IMAGE}/rootfs.cpio.gz.u-boot`
+> to ensure the INITRD name in pxeboot.cfg matches with image name.
+> 3. Whilst it is possible to load the images via JTAG this connection is slow and
+this process can take a long time to execute (more than 10 minutes). If your
+system has ethernet it is recommended that you use TFTP to load these images
+using U-Boot. 
+> 4. If common ${DEPLOY_DIR_IMAGE}/system.dtb is used by u-boot and kernel, this
+> is already part of boot.bin we can skip loading dtb, else load kernel dtb.
+#### Using XSCT
+1. Suspend the execution of active target using `stop` command in XSCT.
+```
+xsct% stop
+```
+2. Using the `dow` command to load the images into the target DDR/PL DDR load 
+   address.
+```
+xsct% dow -data ${DEPLOY_DIR_IMAGE}/Image 0x200000
+xsct% dow -data ${DEPLOY_DIR_IMAGE}/system.dtb 0x100000
+xsct% dow -data ${DEPLOY_DIR_IMAGE}/core-image-minimal-${MACHINE}.cpio.gz.u-boot 0x4000000
+xsct% dow -data ${DEPLOY_DIR_IMAGE}/boot.scr 0x20000000
+```
+#### Using TFTP
+1. Configure the `ipaddr` and `serverip` of the U-Boot environment. 
+```
+Versal> set serverip <server ip>
+Versal> set ipaddr <board ip>
+```
+2. Load the images to DDR address. Make sure images are copied to tftp directory.
+```
+U-Boot> tftpboot 0x200000 ${TFTPDIR}/Image
+U-Boot> tftpboot 0x100000 ${TFTPDIR}/system.dtb
+U-Boot> tftpboot 0x4000000 ${TFTPDIR}/core-image-minimal-${MACHINE}.cpio.gz.u-boot
+U-Boot> tftpboot 0x20000000 ${TFTPDIR}/boot.scr
+```
+### Booting Linux
+Once the images are loaded continue the execution.
+1. After loading images resume the execution of active target using the `con`
+command in XSCT shell, Skip step 1 for if you have used TFTP to load images.
+```
+xsct% con
+```
+2. Terminate xsct shell.
+```
+xsct% exit
+```
+3. In the target Serial Terminal, from U-Boot prompt run `boot` command.
+```
+U-Boot> boot
+```
+## Booting from SD
+1. Load the SD card into the ZCU102 board in the J100 SD slot.
+2. Configure the ZCU102 board to boot in SD-Boot mode (1-ON, 2-OFF, 3-OFF, 4-OFF)
+   by setting the SW6. Refer [Setting Up the Target](#setting-up-the-target).
+3. Follow SD boot instructions [README](README.booting.storage.md) for more details.
+## Booting from QSPI
+1. To boot ZCU012 board in QSPI boot mode, Power on the ZCU102 board and boot 
+   using JTAG or SD boot mode, to ensure that U-Boot is running and also have 
+   boot.bin copied to DDR location using XSCT `dow` or `tftpboot` or `fatload`
+   command.
+2. Follow Flash boot instructions [README](README.booting.flash.md) for more details.
+3. After flashing the images, turn off the power switch on the board, and change
+   the SW6 boot mode pin settings to QSPI boot mode (1-ON, 2-ON, 3-OFF, 4-ON) by
+   setting the SW6. Refer [Setting Up the Target](#setting-up-the-target).
+\ No newline at end of file

diff --git a/docs/README.booting.zynqmp.md b/docs/README.booting.zynqmp.md new file mode 100644 index 00000000..c8f8aa21 --- /dev/null +++ b/docs/README.booting.zynqmp.md
@@ -0,0 +1,212 @@
	1	# Booting OS Images on ZynqMP target boards
	2
	3	Booting OS images on ZynqMP boards can be done using JTAG, SD, eMMC, QSPI and
	4	NAND boot modes.
	5
	6	* [Setting Up the Target](#setting-up-the-target)
	7	* [Booting from JTAG](#booting-from-jtag)
	8	* [Loading boot components using XSCT](#loading-boot-components-using-xsct)
	9	* [Loading Kernel, Root Filesystem and U-boot boot script](#loading-kernel-root-filesystem-and-u-boot-boot-script)
	10	* [Using XSCT](#using-xsct)
	11	* [Using TFTP](#using-tftp)
	12	* [Booting from SD](#booting-from-sd)
	13	* [Booting from QSPI](#booting-from-qspi)
	14
	15	## Setting Up the Target
	16	1. Connect a USB cable between the CP2180 USB-to-Quad-UART bridge USB Micro-B on
	17	the target and the USB port on the host machine.
	18	2. Connect a micro USB cable from the ZCU102 board USB UART port (J83) to the USB
	19	port on the host machine.
	20	3. Default UART terminal(serial port) settings is Speed `115200`, Data `8 bit`,
	21	Parity `None`, Stop bits ` 1 bit` and Flow control `None`.
	22	4. Set the board to JTAG and other boot mode by setting the boot mode switch by
	23	referring to board user guide. For zynqmp-generic machine configuration
	24	file zcu102 evaluation board is used as reference and below is the
	25	configuration boot mode settings (SW6).
	26
	27	> Note: Switch OFF = 1 = High; ON = 0 = Low
	28
	29	\| Boot Mode \| Mode Pins [3:0] \| Mode SW6 [3:0] \| Comments \|
	30	\|-----------\|-----------------\|-------------------\|---------------------------\|
	31	\| JTAG \| 0000 \| ON, ON, ON, ON \| PS JTAG \|
	32	\| QSPI \| 0010 \| ON, ON, OFF, ON \| QSPI 32-bit addressing \|
	33	\| SD \| 1110 \| OFF, OFF, OFF, ON \| SD 3.0 with level shifter \|
	34
	35	## Booting from JTAG
	36
	37	This boot flow requires the use of the AMD Xilinx tools, specifically XSCT and
	38	the associated JTAG device drivers. This also requires access to the JTAG interface
	39	on the board, a number of AMD Xilinx and third-party boards come with on-board JTAG
	40	modules.
	41
	42	1. Source the Vivado or Vitis tools `settings.sh` scripts.
	43	2. Power on the board, Open the XSCT console in the Vitis IDE by clicking the
	44	XSCT button. Alternatively, you can also open the XSCT console by selecting
	45	Xilinx -> XSCT Console.
	46	```
	47	$ xsct
	48	```
	49	3. In the XSCT console, connect to the target over JTAG using the connect command.
	50	Optionally user can use `-url` to specify the local/remote hw_server. The
	51	connect command returns the channel ID of the connection.
	52	```
	53	xsct% connect
	54	```
	55	4. The targets command lists the available targets and allows you to select a
	56	target using its ID. The targets are assigned IDs as they are discovered on
	57	the JTAG chain, so the IDs can change from session to session.
	58	```
	59	xsct% targets
	60	```
	61
	62	> Note: For non-interactive usage such as scripting, you can use the `-filter`
	63	option to select a target instead of selecting the target using its ID.
	64
	65	### Loading boot components using XSCT
	66
	67	1. Download the boot images for the target using XSCT with the `fpga` and `dow`
	68	command. ZyqnMP boot images will be located in the `${DEPLOY_DIR_IMAGE}`
	69	directory.
	70
	71	> Note: In yocto by default, ${DEPLOY_DIR_IMAGE}/system.dtb is used for both
	72	> u-boot and kernel.
	73
	74	2. Program the bitstream or skip this step if you are loading from u-boot or linux.
	75	```
	76	xsct% fpga -no-revision-check ${DEPLOY_DIR_IMAGE}/download.bit
	77	```
	78	3. By default, JTAG security gates are enabled. Disable the security gates for
	79	DAP, PL TAP, and PMU (this makes the PMU MB target visible to the debugger).
	80	```
	81	xsct% targets -set -nocase -filter {name =~ "PSU"}
	82	xsct% mask_write 0xFFCA0038 0x1C0 0x1C0
	83	```
	84	3. Verify if the PMU MB target is listed under the PMU device. Now, load the PMU
	85	firmware.
	86	```
	87	xsct% targets -set -nocase -filter {name =~ "MicroBlaze PMU"}
	88	xsct% catch {stop}
	89	xsct% dow ${DEPLOY_DIR_IMAGE}/pmufw.elf
	90	xsct% con
	91	```
	92	5. Reset APU Cortex-A53 Core 0 to load and execute FSBL, This step is important,
	93	because when the ZynqMP boots up in JTAG boot mode, all the APU and RPU cores
	94	are held in reset. You must clear the resets on each core before performing
	95	debugging on these cores. You can use the `rst` command in XSCT to clear the
	96	resets.
	97	```
	98	xsct% targets -set -nocase -filter {name =~ "A53#0"}
	99	xsct% rst -processor -clear-registers
	100	```
	101	6. Download and run FSBL from APU Cortex-A53 Core 0
	102	```
	103	xsct% dow ${DEPLOY_DIR_IMAGE}/zynqmp_fsbl.elf
	104	xsct% con
	105	```
	106	7. Now download TF-A, U-boot.elf and Device tree to APU and execute.
	107	```
	108	xsct% stop
	109	xsct% dow ${DEPLOY_DIR_IMAGE}/bl31.elf
	110	xsct% dow ${DEPLOY_DIR_IMAGE}/u-boot.elf
	111	xsct% dow -data ${DEPLOY_DIR_IMAGE}/system.dtb 0x100000
	112	xsct% con
	113	```
	114
	115	8. In the target Serial Terminal, press any key to stop the U-Boot auto-boot.
	116	```
	117	...
	118	Hit any key to stop autoboot: 0
	119	U-Boot>
	120	```
	121
	122	### Loading Kernel, Root Filesystem and U-boot boot script
	123
	124	Load the images into the target DDR/PL DRR load address i.e.,
	125	`DDR base address + <image_offset>`.
	126
	127	Below example uses base DDR address as 0x0 which matches in vivado address editor.
	128
	129	\| Image Type \| Base DDR Address \| Image Offset \| Load Address in DDR \|
	130	\|--------------------\|------------------\|--------------\|---------------------\|
	131	\| Kernel \| 0x0 \| 0x200000 \| 0x200000 \|
	132	\| Device Tree \| 0x0 \| 0x1000 \| 0x1000 \|
	133	\| Rootfs \| 0x0 \| 0x04000000 \| 0x4000000 \|
	134	\| U-boot boot script \| 0x0 \| 0x20000000 \| 0x20000000 \|
	135
	136	> Note:
	137	> 1. `<target-image>` refers to core-image-minimal or petalinux-image-minimal
	138	> 2. For pxeboot boot create a symlink for `<target-image>-${MACHINE}-${DATETIME}.cpio.gz.u-boot`
	139	> as shown `$ ln -sf ${DEPLOY_DIR_IMAGE}/<target-image>-${MACHINE}-${DATETIME}.cpio.gz.u-boot ${DEPLOY_DIR_IMAGE}/rootfs.cpio.gz.u-boot`
	140	> to ensure the INITRD name in pxeboot.cfg matches with image name.
	141	> 3. Whilst it is possible to load the images via JTAG this connection is slow and
	142	this process can take a long time to execute (more than 10 minutes). If your
	143	system has ethernet it is recommended that you use TFTP to load these images
	144	using U-Boot.
	145	> 4. If common ${DEPLOY_DIR_IMAGE}/system.dtb is used by u-boot and kernel, this
	146	> is already part of boot.bin we can skip loading dtb, else load kernel dtb.
	147
	148	#### Using XSCT
	149
	150	1. Suspend the execution of active target using `stop` command in XSCT.
	151	```
	152	xsct% stop
	153	```
	154	2. Using the `dow` command to load the images into the target DDR/PL DDR load
	155	address.
	156	```
	157	xsct% dow -data ${DEPLOY_DIR_IMAGE}/Image 0x200000
	158	xsct% dow -data ${DEPLOY_DIR_IMAGE}/system.dtb 0x100000
	159	xsct% dow -data ${DEPLOY_DIR_IMAGE}/core-image-minimal-${MACHINE}.cpio.gz.u-boot 0x4000000
	160	xsct% dow -data ${DEPLOY_DIR_IMAGE}/boot.scr 0x20000000
	161	```
	162
	163	#### Using TFTP
	164
	165	1. Configure the `ipaddr` and `serverip` of the U-Boot environment.
	166	```
	167	Versal> set serverip <server ip>
	168	Versal> set ipaddr <board ip>
	169	```
	170	2. Load the images to DDR address. Make sure images are copied to tftp directory.
	171	```
	172	U-Boot> tftpboot 0x200000 ${TFTPDIR}/Image
	173	U-Boot> tftpboot 0x100000 ${TFTPDIR}/system.dtb
	174	U-Boot> tftpboot 0x4000000 ${TFTPDIR}/core-image-minimal-${MACHINE}.cpio.gz.u-boot
	175	U-Boot> tftpboot 0x20000000 ${TFTPDIR}/boot.scr
	176
	177	```
	178	### Booting Linux
	179
	180	Once the images are loaded continue the execution.
	181
	182	1. After loading images resume the execution of active target using the `con`
	183	command in XSCT shell, Skip step 1 for if you have used TFTP to load images.
	184	```
	185	xsct% con
	186	```
	187	2. Terminate xsct shell.
	188	```
	189	xsct% exit
	190	```
	191	3. In the target Serial Terminal, from U-Boot prompt run `boot` command.
	192	```
	193	U-Boot> boot
	194	```
	195
	196	## Booting from SD
	197
	198	1. Load the SD card into the ZCU102 board in the J100 SD slot.
	199	2. Configure the ZCU102 board to boot in SD-Boot mode (1-ON, 2-OFF, 3-OFF, 4-OFF)
	200	by setting the SW6. Refer [Setting Up the Target](#setting-up-the-target).
	201	3. Follow SD boot instructions [README](README.booting.storage.md) for more details.
	202
	203	## Booting from QSPI
	204
	205	1. To boot ZCU012 board in QSPI boot mode, Power on the ZCU102 board and boot
	206	using JTAG or SD boot mode, to ensure that U-Boot is running and also have
	207	boot.bin copied to DDR location using XSCT `dow` or `tftpboot` or `fatload`
	208	command.
	209	2. Follow Flash boot instructions [README](README.booting.flash.md) for more details.
	210	3. After flashing the images, turn off the power switch on the board, and change
	211	the SW6 boot mode pin settings to QSPI boot mode (1-ON, 2-ON, 3-OFF, 4-ON) by
	212	setting the SW6. Refer [Setting Up the Target](#setting-up-the-target). \ No newline at end of file