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- 2 CANFDs
38
39QEMU does not yet model any other devices, including the PL and the AI Engine.
40
41Other differences between the hardware and the QEMU model:
42
43- QEMU allows the amount of DDR memory provided to be specified with the
44  ``-m`` argument. If a DTB is provided on the command line then QEMU will
45  edit it to include suitable entries describing the Versal DDR memory ranges.
46
47- QEMU provides 8 virtio-mmio virtio transports; these start at
48  address ``0xa0000000`` and have IRQs from 111 and upwards.
49
50Running
51"""""""
52If the user provides an Operating System to be loaded, we expect users
53to use the ``-kernel`` command line option.
54
55Users can load firmware or boot-loaders with the ``-device loader`` options.
56
57When loading an OS, QEMU generates a DTB and selects an appropriate address
58where it gets loaded. This DTB will be passed to the kernel in register x0.
59
60If there's no ``-kernel`` option, we generate a DTB and place it at 0x1000
61for boot-loaders or firmware to pick it up.
62
63If users want to provide their own DTB, they can use the ``-dtb`` option.
64These DTBs will have their memory nodes modified to match QEMU's
65selected ram_size option before they get passed to the kernel or FW.
66
67When loading an OS, we turn on QEMU's PSCI implementation with SMC
68as the PSCI conduit. When there's no ``-kernel`` option, we assume the user
69provides EL3 firmware to handle PSCI.
70
71A few examples:
72
73Direct Linux boot of a generic ARM64 upstream Linux kernel:
74
75.. code-block:: bash
76
77  $ qemu-system-aarch64 -M xlnx-versal-virt -m 2G \
78      -serial mon:stdio -display none \
79      -kernel arch/arm64/boot/Image \
80      -nic user -nic user \
81      -device virtio-rng-device,bus=virtio-mmio-bus.0 \
82      -drive if=none,index=0,file=hd0.qcow2,id=hd0,snapshot \
83      -drive file=qemu_sd.qcow2,if=sd,index=0,snapshot \
84      -device virtio-blk-device,drive=hd0 -append root=/dev/vda
85
86Direct Linux boot of PetaLinux 2019.2:
87
88.. code-block:: bash
89
90  $ qemu-system-aarch64  -M xlnx-versal-virt -m 2G \
91      -serial mon:stdio -display none \
92      -kernel petalinux-v2019.2/Image \
93      -append "rdinit=/sbin/init console=ttyAMA0,115200n8 earlycon=pl011,mmio,0xFF000000,115200n8" \
94      -net nic,model=cadence_gem,netdev=net0 -netdev user,id=net0 \
95      -device virtio-rng-device,bus=virtio-mmio-bus.0,rng=rng0 \
96      -object rng-random,filename=/dev/urandom,id=rng0
97
98Boot PetaLinux 2019.2 via ARM Trusted Firmware (2018.3 because the 2019.2
99version of ATF tries to configure the CCI which we don't model) and U-boot:
100
101.. code-block:: bash
102
103  $ qemu-system-aarch64 -M xlnx-versal-virt -m 2G \
104      -serial stdio -display none \
105      -device loader,file=petalinux-v2018.3/bl31.elf,cpu-num=0 \
106      -device loader,file=petalinux-v2019.2/u-boot.elf \
107      -device loader,addr=0x20000000,file=petalinux-v2019.2/Image \
108      -nic user -nic user \
109      -device virtio-rng-device,bus=virtio-mmio-bus.0,rng=rng0 \
110      -object rng-random,filename=/dev/urandom,id=rng0
111
112Run the following at the U-Boot prompt:
113
114.. code-block:: bash
115
116  Versal>
117  fdt addr $fdtcontroladdr
118  fdt move $fdtcontroladdr 0x40000000
119  fdt set /timer clock-frequency <0x3dfd240>
120  setenv bootargs "rdinit=/sbin/init maxcpus=1 console=ttyAMA0,115200n8 earlycon=pl011,mmio,0xFF000000,115200n8"
121  booti 20000000 - 40000000
122  fdt addr $fdtcontroladdr
123
124Boot Linux as DOM0 on Xen via U-Boot:
125
126.. code-block:: bash
127
128  $ qemu-system-aarch64 -M xlnx-versal-virt -m 4G \
129      -serial stdio -display none \
130      -device loader,file=petalinux-v2019.2/u-boot.elf,cpu-num=0 \
131      -device loader,addr=0x30000000,file=linux/2018-04-24/xen \
132      -device loader,addr=0x40000000,file=petalinux-v2019.2/Image \
133      -nic user -nic user \
134      -device virtio-rng-device,bus=virtio-mmio-bus.0,rng=rng0 \
135      -object rng-random,filename=/dev/urandom,id=rng0
136
137Run the following at the U-Boot prompt:
138
139.. code-block:: bash
140
141  Versal>
142  fdt addr $fdtcontroladdr
143  fdt move $fdtcontroladdr 0x20000000
144  fdt set /timer clock-frequency <0x3dfd240>
145  fdt set /chosen xen,xen-bootargs "console=dtuart dtuart=/uart@ff000000 dom0_mem=640M bootscrub=0 maxcpus=1 timer_slop=0"
146  fdt set /chosen xen,dom0-bootargs "rdinit=/sbin/init clk_ignore_unused console=hvc0 maxcpus=1"
147  fdt mknode /chosen dom0
148  fdt set /chosen/dom0 compatible "xen,multiboot-module"
149  fdt set /chosen/dom0 reg <0x00000000 0x40000000 0x0 0x03100000>
150  booti 30000000 - 20000000
151
152Boot Linux as Dom0 on Xen via ARM Trusted Firmware and U-Boot:
153
154.. code-block:: bash
155
156  $ qemu-system-aarch64 -M xlnx-versal-virt -m 4G \
157      -serial stdio -display none \
158      -device loader,file=petalinux-v2018.3/bl31.elf,cpu-num=0 \
159      -device loader,file=petalinux-v2019.2/u-boot.elf \
160      -device loader,addr=0x30000000,file=linux/2018-04-24/xen \
161      -device loader,addr=0x40000000,file=petalinux-v2019.2/Image \
162      -nic user -nic user \
163      -device virtio-rng-device,bus=virtio-mmio-bus.0,rng=rng0 \
164      -object rng-random,filename=/dev/urandom,id=rng0
165
166Run the following at the U-Boot prompt:
167
168.. code-block:: bash
169
170  Versal>
171  fdt addr $fdtcontroladdr
172  fdt move $fdtcontroladdr 0x20000000
173  fdt set /timer clock-frequency <0x3dfd240>
174  fdt set /chosen xen,xen-bootargs "console=dtuart dtuart=/uart@ff000000 dom0_mem=640M bootscrub=0 maxcpus=1 timer_slop=0"
175  fdt set /chosen xen,dom0-bootargs "rdinit=/sbin/init clk_ignore_unused console=hvc0 maxcpus=1"
176  fdt mknode /chosen dom0
177  fdt set /chosen/dom0 compatible "xen,multiboot-module"
178  fdt set /chosen/dom0 reg <0x00000000 0x40000000 0x0 0x03100000>
179  booti 30000000 - 20000000
180
181BBRAM File Backend
182""""""""""""""""""
183BBRAM can have an optional file backend, which must be a seekable
184binary file with a size of 36 bytes or larger. A file with all
185binary 0s is a 'blank'.
186
187To add a file-backend for the BBRAM:
188
189.. code-block:: bash
190
191  -drive if=pflash,index=0,file=versal-bbram.bin,format=raw
192
193To use a different index value, N, from default of 0, add:
194
195.. code-block:: bash
196
197  -global xlnx,bbram-ctrl.drive-index=N
198
199eFUSE File Backend
200""""""""""""""""""
201eFUSE can have an optional file backend, which must be a seekable
202binary file with a size of 3072 bytes or larger. A file with all
203binary 0s is a 'blank'.
204
205To add a file-backend for the eFUSE:
206
207.. code-block:: bash
208
209  -drive if=pflash,index=1,file=versal-efuse.bin,format=raw
210
211To use a different index value, N, from default of 1, add:
212
213.. code-block:: bash
214
215  -global xlnx,efuse.drive-index=N
216
217.. warning::
218  In actual physical Versal, BBRAM and eFUSE contain sensitive data.
219  The QEMU device models do **not** encrypt nor obfuscate any data
220  when holding them in models' memory or when writing them to their
221  file backends.
222
223  Thus, a file backend should be used with caution, and 'format=luks'
224  is highly recommended (albeit with usage complexity).
225
226  Better yet, do not use actual product data when running guest image
227  on this Xilinx Versal Virt board.
228
229Using CANFDs for Versal Virt
230""""""""""""""""""""""""""""
231Versal CANFD controller is developed based on SocketCAN and QEMU CAN bus
232implementation. Bus connection and socketCAN connection for each CAN module
233can be set through command lines.
234
235To connect both CANFD0 and CANFD1 on the same bus:
236
237.. code-block:: bash
238
239    -object can-bus,id=canbus -machine canbus0=canbus -machine canbus1=canbus
240
241To connect CANFD0 and CANFD1 to separate buses:
242
243.. code-block:: bash
244
245    -object can-bus,id=canbus0 -object can-bus,id=canbus1 \
246    -machine canbus0=canbus0 -machine canbus1=canbus1
247
248The SocketCAN interface can connect to a Physical or a Virtual CAN interfaces on
249the host machine. Please check this document to learn about CAN interface on
250Linux: docs/system/devices/can.rst
251
252To connect CANFD0 and CANFD1 to host machine's CAN interface can0:
253
254.. code-block:: bash
255
256    -object can-bus,id=canbus -machine canbus0=canbus -machine canbus1=canbus
257    -object can-host-socketcan,id=canhost0,if=can0,canbus=canbus
258