1Xilinx Versal Virt (``xlnx-versal-virt``)
2=========================================
3
4Xilinx Versal is a family of heterogeneous multi-core SoCs
5(System on Chip) that combine traditional hardened CPUs and I/O
6peripherals in a Processing System (PS) with runtime programmable
7FPGA logic (PL) and an Artificial Intelligence Engine (AIE).
8
9More details here:
10https://www.xilinx.com/products/silicon-devices/acap/versal.html
11
12The family of Versal SoCs share a single architecture but come in
13different parts with different speed grades, amounts of PL and
14other differences.
15
16The Xilinx Versal Virt board in QEMU is a model of a virtual board
17(does not exist in reality) with a virtual Versal SoC without I/O
18limitations. Currently, we support the following cores and devices:
19
20Implemented CPU cores:
21
22- 2 ACPUs (ARM Cortex-A72)
23
24Implemented devices:
25
26- Interrupt controller (ARM GICv3)
27- 2 UARTs (ARM PL011)
28- An RTC (Versal built-in)
29- 2 GEMs (Cadence MACB Ethernet MACs)
30- 8 ADMA (Xilinx zDMA) channels
31- 2 SD Controllers
32- OCM (256KB of On Chip Memory)
33- XRAM (4MB of on chip Accelerator RAM)
34- DDR memory
35- BBRAM (36 bytes of Battery-backed RAM)
36- eFUSE (3072 bytes of one-time field-programmable bit array)
37
38QEMU does not yet model any other devices, including the PL and the AI Engine.
39
40Other differences between the hardware and the QEMU model:
41
42- QEMU allows the amount of DDR memory provided to be specified with the
43  ``-m`` argument. If a DTB is provided on the command line then QEMU will
44  edit it to include suitable entries describing the Versal DDR memory ranges.
45
46- QEMU provides 8 virtio-mmio virtio transports; these start at
47  address ``0xa0000000`` and have IRQs from 111 and upwards.
48
49Running
50"""""""
51If the user provides an Operating System to be loaded, we expect users
52to use the ``-kernel`` command line option.
53
54Users can load firmware or boot-loaders with the ``-device loader`` options.
55
56When loading an OS, QEMU generates a DTB and selects an appropriate address
57where it gets loaded. This DTB will be passed to the kernel in register x0.
58
59If there's no ``-kernel`` option, we generate a DTB and place it at 0x1000
60for boot-loaders or firmware to pick it up.
61
62If users want to provide their own DTB, they can use the ``-dtb`` option.
63These DTBs will have their memory nodes modified to match QEMU's
64selected ram_size option before they get passed to the kernel or FW.
65
66When loading an OS, we turn on QEMU's PSCI implementation with SMC
67as the PSCI conduit. When there's no ``-kernel`` option, we assume the user
68provides EL3 firmware to handle PSCI.
69
70A few examples:
71
72Direct Linux boot of a generic ARM64 upstream Linux kernel:
73
74.. code-block:: bash
75
76  $ qemu-system-aarch64 -M xlnx-versal-virt -m 2G \
77      -serial mon:stdio -display none \
78      -kernel arch/arm64/boot/Image \
79      -nic user -nic user \
80      -device virtio-rng-device,bus=virtio-mmio-bus.0 \
81      -drive if=none,index=0,file=hd0.qcow2,id=hd0,snapshot \
82      -drive file=qemu_sd.qcow2,if=sd,index=0,snapshot \
83      -device virtio-blk-device,drive=hd0 -append root=/dev/vda
84
85Direct Linux boot of PetaLinux 2019.2:
86
87.. code-block:: bash
88
89  $ qemu-system-aarch64  -M xlnx-versal-virt -m 2G \
90      -serial mon:stdio -display none \
91      -kernel petalinux-v2019.2/Image \
92      -append "rdinit=/sbin/init console=ttyAMA0,115200n8 earlycon=pl011,mmio,0xFF000000,115200n8" \
93      -net nic,model=cadence_gem,netdev=net0 -netdev user,id=net0 \
94      -device virtio-rng-device,bus=virtio-mmio-bus.0,rng=rng0 \
95      -object rng-random,filename=/dev/urandom,id=rng0
96
97Boot PetaLinux 2019.2 via ARM Trusted Firmware (2018.3 because the 2019.2
98version of ATF tries to configure the CCI which we don't model) and U-boot:
99
100.. code-block:: bash
101
102  $ qemu-system-aarch64 -M xlnx-versal-virt -m 2G \
103      -serial stdio -display none \
104      -device loader,file=petalinux-v2018.3/bl31.elf,cpu-num=0 \
105      -device loader,file=petalinux-v2019.2/u-boot.elf \
106      -device loader,addr=0x20000000,file=petalinux-v2019.2/Image \
107      -nic user -nic user \
108      -device virtio-rng-device,bus=virtio-mmio-bus.0,rng=rng0 \
109      -object rng-random,filename=/dev/urandom,id=rng0
110
111Run the following at the U-Boot prompt:
112
113.. code-block:: bash
114
115  Versal>
116  fdt addr $fdtcontroladdr
117  fdt move $fdtcontroladdr 0x40000000
118  fdt set /timer clock-frequency <0x3dfd240>
119  setenv bootargs "rdinit=/sbin/init maxcpus=1 console=ttyAMA0,115200n8 earlycon=pl011,mmio,0xFF000000,115200n8"
120  booti 20000000 - 40000000
121  fdt addr $fdtcontroladdr
122
123Boot Linux as DOM0 on Xen via U-Boot:
124
125.. code-block:: bash
126
127  $ qemu-system-aarch64 -M xlnx-versal-virt -m 4G \
128      -serial stdio -display none \
129      -device loader,file=petalinux-v2019.2/u-boot.elf,cpu-num=0 \
130      -device loader,addr=0x30000000,file=linux/2018-04-24/xen \
131      -device loader,addr=0x40000000,file=petalinux-v2019.2/Image \
132      -nic user -nic user \
133      -device virtio-rng-device,bus=virtio-mmio-bus.0,rng=rng0 \
134      -object rng-random,filename=/dev/urandom,id=rng0
135
136Run the following at the U-Boot prompt:
137
138.. code-block:: bash
139
140  Versal>
141  fdt addr $fdtcontroladdr
142  fdt move $fdtcontroladdr 0x20000000
143  fdt set /timer clock-frequency <0x3dfd240>
144  fdt set /chosen xen,xen-bootargs "console=dtuart dtuart=/uart@ff000000 dom0_mem=640M bootscrub=0 maxcpus=1 timer_slop=0"
145  fdt set /chosen xen,dom0-bootargs "rdinit=/sbin/init clk_ignore_unused console=hvc0 maxcpus=1"
146  fdt mknode /chosen dom0
147  fdt set /chosen/dom0 compatible "xen,multiboot-module"
148  fdt set /chosen/dom0 reg <0x00000000 0x40000000 0x0 0x03100000>
149  booti 30000000 - 20000000
150
151Boot Linux as Dom0 on Xen via ARM Trusted Firmware and U-Boot:
152
153.. code-block:: bash
154
155  $ qemu-system-aarch64 -M xlnx-versal-virt -m 4G \
156      -serial stdio -display none \
157      -device loader,file=petalinux-v2018.3/bl31.elf,cpu-num=0 \
158      -device loader,file=petalinux-v2019.2/u-boot.elf \
159      -device loader,addr=0x30000000,file=linux/2018-04-24/xen \
160      -device loader,addr=0x40000000,file=petalinux-v2019.2/Image \
161      -nic user -nic user \
162      -device virtio-rng-device,bus=virtio-mmio-bus.0,rng=rng0 \
163      -object rng-random,filename=/dev/urandom,id=rng0
164
165Run the following at the U-Boot prompt:
166
167.. code-block:: bash
168
169  Versal>
170  fdt addr $fdtcontroladdr
171  fdt move $fdtcontroladdr 0x20000000
172  fdt set /timer clock-frequency <0x3dfd240>
173  fdt set /chosen xen,xen-bootargs "console=dtuart dtuart=/uart@ff000000 dom0_mem=640M bootscrub=0 maxcpus=1 timer_slop=0"
174  fdt set /chosen xen,dom0-bootargs "rdinit=/sbin/init clk_ignore_unused console=hvc0 maxcpus=1"
175  fdt mknode /chosen dom0
176  fdt set /chosen/dom0 compatible "xen,multiboot-module"
177  fdt set /chosen/dom0 reg <0x00000000 0x40000000 0x0 0x03100000>
178  booti 30000000 - 20000000
179
180BBRAM File Backend
181""""""""""""""""""
182BBRAM can have an optional file backend, which must be a seekable
183binary file with a size of 36 bytes or larger. A file with all
184binary 0s is a 'blank'.
185
186To add a file-backend for the BBRAM:
187
188.. code-block:: bash
189
190  -drive if=pflash,index=0,file=versal-bbram.bin,format=raw
191
192To use a different index value, N, from default of 0, add:
193
194.. code-block:: bash
195
196  -global xlnx,bbram-ctrl.drive-index=N
197
198eFUSE File Backend
199""""""""""""""""""
200eFUSE can have an optional file backend, which must be a seekable
201binary file with a size of 3072 bytes or larger. A file with all
202binary 0s is a 'blank'.
203
204To add a file-backend for the eFUSE:
205
206.. code-block:: bash
207
208  -drive if=pflash,index=1,file=versal-efuse.bin,format=raw
209
210To use a different index value, N, from default of 1, add:
211
212.. code-block:: bash
213
214  -global xlnx,efuse.drive-index=N
215
216.. warning::
217  In actual physical Versal, BBRAM and eFUSE contain sensitive data.
218  The QEMU device models do **not** encrypt nor obfuscate any data
219  when holding them in models' memory or when writing them to their
220  file backends.
221
222  Thus, a file backend should be used with caution, and 'format=luks'
223  is highly recommended (albeit with usage complexity).
224
225  Better yet, do not use actual product data when running guest image
226  on this Xilinx Versal Virt board.
227