Hardware components | ||||||
| × | 1 | ||||
| × | 1 | ||||
| × | 1 | ||||
Software apps and online services | ||||||
 |
| |||||
 |
| |||||
| ||||||
| ||||||
Whether it is a bare-metal or an OS-based embedded system, booting it up from scratch is one of the key steps to start the development cycle in our projects. When it comes to working with a more complex and hierarchical boot as we do in booting Embedded Linux images, things can become more complicated and frustrating.
When I started to learn the Embedded Linux development, I was using the SD Card booting only. It was slow and required me to plug/unplug the memory card thousands of times. Then, I discovered the TFTP and NFS booting methods. I was more than happy since, thanks to the Ethernet interface, I only had to modify the SD card content when I need to change the bootloader, i.e. FSBL, U-Boot, etc. Even the modifications on the SD card could be done by using the target itself with a proper SSH connection, or similar.
After a while, in one of the projects that I’m currently working on at Meteksan Defense, a disastrous moment came and I realized that I don’t have access to either the Ethernet ports or the SD card. It was the moment when I understood that my comfort zone had its own limitations :)
Thanks to what I learned from that challenging booting process, I’m now able to boot Xilinx FPGA SoCs using only the JTAG interface. So, in this article, you will see how you can boot your Embedded Linux image on a Zynq SoC using only the JTAG interface. As the Linux image is the final step of booting and we will be booting the bootloaders prior to it, you will also be able to boot any other application using similar methods.
This article will only cover the scenario for the Zynq-7000 SoC. For the Zynq-UltraScale+, the scenario is similar but it has different challenges. I’m planning to cover it in another article, hold tight :)What is the XSDB/XSCT server?
Before starting, let’s take a look at what these strangely named utilities actually are. The XSCT and the XSDB servers are nearly the same. The XSCT is the successor of the XSDB, i.e. it has been replaced by XSCT in Xilinx tools as of 2016.
The XSCT, i.e. Xilinx® Software Command-line Tool, is an interactive and scriptable command-line interface that helps you to use many of the Xilinx utilities without requiring a GUI. It has descriptive documentation (UG-1400) provided by Xilinx, see this page.
The XSCT has many powerful abilities. In this article, you will see only the ones that you can utilize to manage the targets on a JTAG chain. I suggest you discover the other abilities by playing with the tool. You will definitely enjoy it.
The XSCT server is installed to your system implicitly when you were installing the main Xilinx Tools such as Vivado, Vitis, or PetaLinux.
Hardware RequirementsTo handle the JTAG operations on the target hardware, there are some strict requirements. The first and most important of all is that your hardware must support the JTAG access. Unfortunately, I’m not able to explain how you can build your hardware to have JTAG access as I’m just a poor embedded software developer :)
In addition, the connection between the development PC and the target board can be established using JTAG cables. Currently, Xilinx provides two different kits, i.e. Platform Cable and SmartLynq.
I prefer using the SmartLynq as it provides higher JTAG chain frequencies compared to the Platform Cable. Also, by using the SmartLynq, you will be able to connect to your target board with a remote connection as the SmartLynq has an Ethernet connection in addition to its USB.
Step-by-step JTAG BootingThis section is the heart of this article. By following the steps I provide below, you will be able to rule your target easily. Try not to make arbitrary moves initially as the booting process is quite sensitive to modifications. After booting your target a few times, you will get used to using the utility and be able to try your crazy ideas :)
While following the tutorial, try to understand the reason and the result of each move we will be executing. This way, you can easily adapt the process to any other hardware you have.
Launching the XSCT ServerThe XSCT server and any other Xilinx utility can be found under your Xilinx Tools installation path. In my case, I launch it from <INSTALLATION_PATH>/Xilinx/Vitis/2021.1/bin/xsct. When launched, the prompt appears on the command line waiting for you to interact with it. It’s also possible to launch the utility with a properly prepared TCL script. We will talk about it later.
11:38:24 ~ > /opt/Xilinx/Vitis/2021.1/bin/xsct
****** Xilinx Software Commandline Tool (XSCT) v2021.1
**** SW Build 3246112 on 2021-06-09-14:19:56
** Copyright 1986-2021 Xilinx, Inc. All Rights Reserved.
xsct% help
Available Help Categories
breakpoints - Target Breakpoints/Watchpoints.
connections - Target Connection Management.
device - Device Configuration System.
download - Target Download FPGA/BINARY.
hsi - HSI commands.
ipi - IPI commands to Versal PMC.
jtag - JTAG Access.
memory - Target Memory.
miscellaneous - Miscellaneous.
petalinux - Petalinux commands.
projects - Vitis Projects.
registers - Target Registers.
reset - Target Reset.
running - Program Execution.
streams - Jtag UART.
svf - SVF Operations.
tfile - Target File System.
Type "help" followed by above "category" for more details or
help" followed by the keyword "commands" to list all the commands
xsct%The XSCT isn’t the only utility that Xilinx provides. There are other utilities that serve different purposes. Any utility can utilize the other by making proper calls. The XSCT and other utilities call the Hardware Server to connect to the JTAG kits. In XSCT, you can do it by calling the connect command as below.
connect -url tcp:<DEVICE_IP>:3121The device IP varies according to the JTAG kit that you use for the connection.
- When using the SmartLynq, the server IP appears on the device.
- The SmartLynq can also be connected via USB, in that case, 10.0.0.2 can be used.
- When using the Platform Cable, you can use 127.0.0.1 to connect.
The default port for each connection is 3121, I never saw a case in which I had to use another port.
Listing the JTAG TargetsAfter connecting to the JTAG cable, we are able to list the targets connected to our JTAG chain. A simple call to targets will list your devices on the JTAG chain.
xsct% targets
1 APU
2 ARM Cortex-A9 MPCore #0 (Running)
3 ARM Cortex-A9 MPCore #1 (Running)
4 xc7z020The list you see when you invoke the targets command represents each device connected to the JTAG chain. You can manage each one by selecting it explicitly. There can be times when you cannot establish a reliable connection between your target and the JTAG cable. In such cases, you should inspect the error messages and take an action according to them. For instance, when either there is no JTAG connection or the board power is off, the error prompt appears as below.
xsct% targets
1 whole scan chain (board power off)The most common issue that you will face will be related to the JTAG frequency that you use. Some physical properties of a JTAG chain might affect the suitable JTAG frequency such as the cable length, number of targets, etc. In that case, the XSCT utility creates some error messages indicating an unreliable connection with the target. You can see some of them below.
xsct% targets
1 whole scan chain (Unknown device configuration)
xsct% targets
1 whole scan chain (Unknown IR length)
xsct% targets
1 whole scan chain (too many devices)When such outputs are seen, you should readjust your JTAG frequency to establish a reliable, robust connection. Supported JTAG frequencies for a JTAG cable can be found by calling the jtag frequency -list as below. You can then select a proper frequency from the given list. An arbitrary frequency can also be chosen, the utility handles the rounding in that case.
xsct% jtag targets 1
xsct% jtag frequency -list
125000 250000 500000 1000000 2000000 3000000 4000000 6000000 7500000 10000000 12000000 13000000 15000000 20000000 30000000 40000000 50000000 60000000 70000000 80000000 90000000 100000000
xsct% jtag frequency 7500000
7500000
xsct% jtag frequency 7000000
7017543As the Zynq-7000 SoC is actually an FPGA, it requires a hardware image to provide access to its underlying resources and interfaces like the DDR, Ethernet, serial interfaces, etc. Downloading a full FPGA image via JTAG is quite simple. You just need to use the fpga command as below.
xsct% targets
1 APU
2 ARM Cortex-A9 MPCore #0 (Running)
3 ARM Cortex-A9 MPCore #1 (Running)
4 xc7z020
xsct% targets 4
xsct% fpga "<PATH_TO_IMAGE>/system.bit"
00% 0MB 0.0MB/s 00:00
33% 1MB 0.9MB/s 00:01
66% 2MB 0.9MB/s 00:02
100% 3MB 0.9MB/s 00:03Downloading the FPGA image clears the existing programmable logic image and replaces it with the given one immediately. You can also manage the programmable logic by providing options to the same command. Enter help fpga to inspect further. Downloading the FPGA image to the hardware is enough for now, the rest is out of the scope of this tutorial.
Downloading the FSBLThe FSBL (First Stage Boot Loader) is the first (actually the second, BootROM first) program to be called when booting a Zynq-7000 SoC. It’s responsible for configuring the hardware and initializing some components prior to invoking either the SSBL (Second Stage Boot Loader) or the Bare-Metal application you want. You can either use an auto-generated FSBL or write your own. To download and run the FSBL, call the dow command below. Note that the FSBL must be run on the first Cortex-A9 core of the Zynq Processing System. So, we choose the target accordingly.
xsct% targets -set -nocase -filter {name =~ "arm*#0"}
xsct% dow "${imagesPath}/zynq_fsbl.elf"
Downloading Program -- zynq_fsbl.elf
section, .text: 0x00000000 - 0x0000e753
section, .handoff: 0x0000e754 - 0x0000e79f
section, .init: 0x0000e7a0 - 0x0000e7ab
section, .fini: 0x0000e7ac - 0x0000e7b7
section, .rodata: 0x0000e7b8 - 0x0000eacf
section, .data: 0x0000ead0 - 0x000116bf
section, .mmu_tbl: 0x00014000 - 0x00017fff
section, .init_array: 0x00018000 - 0x00018003
section, .fini_array: 0x00018004 - 0x00018007
section, .rsa_ac: 0x00018008 - 0x0001903f
section, .bss: 0x00019040 - 0x0001b29f
section, .heap: 0x0001b2a0 - 0x0001d29f
section, .stack: 0xffff0000 - 0xffffd3ff
100% 0MB 0.4MB/s 00:00
Setting PC to Program Start Address 0x00000000
Successfully downloaded zynq_fsbl.elf
Info: ARM Cortex-A9 MPCore #0 (target 2) Stopped at 0x3ff67154 (Suspended)
xsct% con; after 5000; stop
Info: ARM Cortex-A9 MPCore #0 (target 2) Running
Info: ARM Cortex-A9 MPCore #0 (target 2) Stopped at 0xfaf0 (Suspended)The dow command is responsible for downloading the given executable binary file to the target and setting the program counter to its entry point. After setting the program counter, the CPU halts immediately. To make the FSBL complete its operations, you should let it run for a few seconds and then stop it manually. By doing it, you are preparing your hardware for an incoming JTAG boot.
- Prior to downloading the FSBL to the target, the MMU (Memory Management Unit) must have been disabled as it virtualizes the memory access and prevents direct read/write on the memory. If your target was running any Linux image, interrupt it before booting. Otherwise, you will not be able to download and run your FSBL.
- The FSBL completes its operations according to the boot pin configuration. If your boot pins are adjustable, adjust them as JTAG boot. In my case, the boot pins were hard set and I had to force the FSBL to JTAG boot mode by modifying its source code.
The hardware platform images generated by using the Xilinx Vivado include not only the BIT files. They also include a Tickle script that you can use to initialize the hardware. After running the FSBL, we need to configure the rest of the hardware to access the peripherals, memory, IO pins, etc. An exported XSA file includes the following files:
$> cd hw-description && ls -l
... system.bit
... ps7_init.c
... ps7_init.h
... ps7_init.tcl
<The rest is stripped>To initialize the hardware we must call the initialization methods provided in the ps7_init.tcl file. Do it as below. The initialization is successful if no output is provided.
xsct% targets
1 APU
2* ARM Cortex-A9 MPCore #0 (Suspended)
3 ARM Cortex-A9 MPCore #1 (Running)
4 xc7z020
xsct% targets 1
xsct% source ps7_init.tcl
xsct% ps7_initIf you inspect the Tickle file, you will see how it initializes the hardware step-by-step. It might give you an insight into how things are correlated in an SoC.
proc ps7_init {} {
variable PCW_SILICON_VER_1_0
variable PCW_SILICON_VER_2_0
variable PCW_SILICON_VER_3_0
set sil_ver [ps_version]
if { $sil_ver == $PCW_SILICON_VER_1_0} {
ps7_mio_init_data_1_0
ps7_pll_init_data_1_0
ps7_clock_init_data_1_0
ps7_ddr_init_data_1_0
ps7_peripherals_init_data_1_0
puts "PCW Silicon Version : 1.0"
} elseif { $sil_ver == $PCW_SILICON_VER_2_0 } {
ps7_mio_init_data_2_0
ps7_pll_init_data_2_0
ps7_clock_init_data_2_0
ps7_ddr_init_data_2_0
ps7_peripherals_init_data_2_0
puts "PCW Silicon Version : 2.0"
} else {
ps7_mio_init_data_3_0
ps7_pll_init_data_3_0
ps7_clock_init_data_3_0
ps7_ddr_init_data_3_0
ps7_peripherals_init_data_3_0
puts "PCW Silicon Version : 3.0"
}
}The device tree binary is an essential requirement for U-Boot. Without it, same as the Linux kernel, the U-Boot wouldn’t be able to recognize the devices that appear both in or out of the chip. By using it, the U-Boot binds the matching drivers to the supported hardware targets/components. To download the device tree binary to a pre-determined address on the DDR memory, we will use dow command again. See below.
xsct% targets -set -nocase -filter {name =~ "arm*#0"}
xsct% set deviceTreeOffset 0x100000
xsct% dow -data "system.dtb" ${deviceTreeOffset}
100% 0MB 0.4MB/s 00:00
Successfully downloaded system.dtb- The -data option is mandatory as the given file isn't a regular ELF binary. It should only be downloaded to the main memory and nothing else.
The offset of the device tree is hardcoded into the U-Boot during compilation. For Petalinux projects, you can find it in your project configuration file <PLNX_PRJ_PATH>/project-spec/configs/config. The tag for the corresponding configuration is CONFIG_SUBSYSTEM_UBOOT_DEVICETREE_OFFSET. Below is a bash script you can use to extract it from the configuration file.
DEVICE_TREE_OFFSET="$(grep "CONFIG_SUBSYSTEM_UBOOT_DEVICETREE_OFFSET" "<PLNX_PRJ_PATH>/project-spec/configs/config" | cut -d'=' -f 2)"
echo ${DEVICE_TREE_OFFSET}Similar to the FSBL, the U-Boot is also a boot loader, but a more sophisticated one. It stands for the second stage boot loader. We already satisfied the prerequisites to boot the U-Boot. Downloading it to the main memory and releasing the CPU from the entry point is enough to see some output on the serial terminal.
xsct% targets -set -nocase -filter {name =~ "arm*#0"}
xsct% dow "u-boot.elf"
Downloading Program -- u-boot.elf
section, .text: 0x04000000 - 0x040003a7
section, .efi_runtime: 0x040003a8 - 0x040011ef
section, .text_rest: 0x04001200 - 0x0409dbff
section, .rodata: 0x0409dc00 - 0x040c0ea8
section, .hash: 0x040c0eac - 0x040c0ec3
section, .data: 0x040c0ec8 - 0x040cc4cf
section, .got.plt: 0x040cc4d0 - 0x040cc4db
section, .u_boot_list: 0x040cc4dc - 0x040ce30f
section, .efi_runtime_rel: 0x040ce310 - 0x040ce3df
section, .rel.dyn: 0x040ce3e0 - 0x040e22e7
section, .bss_start: 0x040ce3e0 - 0x040ce3df
section, .bss: 0x040ce3e0 - 0x040e1397
section, .bss_end: 0x040e1398 - 0x040e1397
100% 0MB 0.4MB/s 00:02
Setting PC to Program Start Address 0x04000000
Successfully downloaded u-boot.elf
xsct% con
Info: ARM Cortex-A9 MPCore #0 (target 2) RunningAfter calling the con to release the halted CPU, you will immediately see the output of the U-Boot on the serial terminal if you configured your hardware image properly. Note that the Zynq-7000 SoC has two UART interfaces connected to the Processing System. You should choose carefully which port you will use to interact with it. My terminal screen has the following output.
U-Boot 2021.01 (Jun 01 2021 - 11:54:06 +0000)
CPU: Zynq 7z020
Silicon: v3.1
DRAM: ECC disabled 1 GiB
Flash: 0 Bytes
NAND: 0 MiB
MMC: mmc@e0101000: 0
Loading Environment from SPIFlash... SF: Detected s25fl256s1 with page size 256 Bytes, erase size 64 KiB,
total 32 MiB
*** Warning - bad CRC, using default environment
In: serial@e0000000
Out: serial@e0000000
Err: serial@e0000000
Net:
ZYNQ GEM: e000b000, mdio bus e000b000, phyaddr -1, interface rgmii-id
eth0: ethernet@e000b000
Hit any key to stop autoboot: 0
Zynq >The last step of this tutorial is to download the Linux kernel image into the DDR memory and boot it via U-Boot. After booting the U-Boot without any problem, you have multiple ways to boot your Linux kernel such as JTAG, TFTP, QSPI, eMMC, etc. We will choose the JTAG, as this article is aimed at the JTAG boot particularly. Some of the methods might not be applicable depending on the ability of your hardware.
- Note that the Linux Kernel requires a device tree binary and a mountable root file system to complete its boot process. For a quick demonstration, I prepared an INITRAMFS image and packed the Kernel, RootFS, and Device Tree Binary into a single image file using PetaLinux tools. You can choose other methods arbitrarily.
The address to be used to download the image has some limitations.
- You must place the image into an empty section of the DDR.
- It mustn’t corrupt any other image residing in the memory. If you’ve created a PetaLinux project, you can find a suitable address in the configuration file with the tag CONFIG_SUBSYSTEM_UBOOT_FIT_IMAGE_OFFSET.
- It must match the alignment of your U-Boot executable.
xsct% targets
1 APU
2* ARM Cortex-A9 MPCore #0 (Running)
3 ARM Cortex-A9 MPCore #1 (Running)
4 xc7z020
xsct% stop
Info: ARM Cortex-A9 MPCore #0 (target 2) Stopped at 0x3ff67154 (Suspended)
xsct% dow -data "image.ub" 0x10000000
100% 104MB 0.4MB/s 04:49
Successfully downloaded image.ub
xsct% conThe download takes a while as the packed kernel is quite big to transfer via the JTAG. After completing, we can release the CPU. The rest of the operations will be done on the U-Boot terminal. If everything is well, you can easily boot up your Linux image by calling the bootm command with the downloaded kernel image address. Below is a successful boot output of my Linux image.
Zynq> bootm 0x10000000
## Loading kernel from FIT Image at 10000000 ...
Using 'conf-system-top.dtb' configuration
Verifying Hash Integrity ... OK
Trying 'kernel-1' kernel subimage
Description: Linux kernel
Type: Kernel Image
Compression: uncompressed
Data Start: 0x100000f8
Data Size: 56678904 Bytes = 54.1 MiB
Architecture: ARM
OS: Linux
Load Address: 0x00200000
Entry Point: 0x00200000
Hash algo: sha256
Hash value: a6b9da747c32596a2818145ac499b124900effba9552aa23483fe758574c1003
Verifying Hash Integrity ... sha256+ OK
## Loading ramdisk from FIT Image at 10000000 ...
Using 'conf-system-top.dtb' configuration
Verifying Hash Integrity ... OK
Trying 'ramdisk-1' ramdisk subimage
Description: petalinux-image-minimal
Type: RAMDisk Image
Compression: uncompressed
Data Start: 0x13612bb4
Data Size: 52367968 Bytes = 49.9 MiB
Architecture: ARM
OS: Linux
Load Address: unavailable
Entry Point: unavailable
Hash algo: sha256
Hash value: d77edbad8b69e33e1885c32edbc89c9e8085028a44593a8e5ece09c0b356a797
Verifying Hash Integrity ... sha256+ OK
## Loading fdt from FIT Image at 10000000 ...
Using 'conf-system-top.dtb' configuration
Verifying Hash Integrity ... OK
Trying 'fdt-system-top.dtb' fdt subimage
Description: Flattened Device Tree blob
Type: Flat Device Tree
Compression: uncompressed
Data Start: 0x1360dbfc
Data Size: 20202 Bytes = 19.7 KiB
Architecture: ARM
Hash algo: sha256
Hash value: f440bd81389f4e984d78d8baba23f93118ce9562bfcce6c47a741b1ef01cb238
Verifying Hash Integrity ... sha256+ OK
Booting using the fdt blob at 0x1360dbfc
Loading Kernel Image
Loading Ramdisk to 2ce0e000, end 2ffff260 ... OK
Loading Device Tree to 2ce06000, end 2ce0dee9 ... OK
Starting kernel ...
Booting Linux on physical CPU 0x0
Linux version 5.10.0-xilinx-v2021.1 (oe-user@oe-host) (arm-xilinx-linux-gnueabi-gcc (GCC) 10.2.0, GNU ld (GNU Binutils) 2.35.1) #1 SMP PREEMPT Fri Jun 4 15:57:16 UTC 2021
CPU: ARMv7 Processor [413fc090] revision 0 (ARMv7), cr=18c5387d
...............
<Skipped for readability>
...............
PetaLinux 2021.1 ZynqLinux ttyPS0
root@ZynqLinux:~ > uname -r
5.10.0-xilinx-v2021.1To conclude, booting hardware may be the most repeated action of our daily development routine as embedded software engineers. There are many ways of doing it, but most of them require human interaction. Like most things in a development cycle, the booting process can also be automated. Even if you have a solidified boot sequence, you might need to boot using other methods. This situation can occur when you need to update your images on the persistent memory or try out a few things without modifying the actual boot images. Although the JTAG booting has a steep learning curve, it is worth all the effort.
As always, this article is open to suggestions and criticism. Feel free to ask, comment, or contribute.
Comments
Please log in or sign up to comment.