docs/system/arm/xlnx-versal-virt.rst

   1 Xilinx Versal Virt (``xlnx-versal-virt``)
   2 =========================================
   3
   4 Xilinx Versal is a family of heterogeneous multi-core SoCs
   5 (System on Chip) that combine traditional hardened CPUs and I/O
   6 peripherals in a Processing System (PS) with runtime programmable
   7 FPGA logic (PL) and an Artificial Intelligence Engine (AIE).
   8
   9 More details here:
  10 https://www.xilinx.com/products/silicon-devices/acap/versal.html
  11
  12 The family of Versal SoCs share a single architecture but come in
  13 different parts with different speed grades, amounts of PL and
  14 other differences.
  15
  16 The 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
  18 limitations. Currently, we support the following cores and devices:
  19
  20 Implemented CPU cores:
  21
  22 - 2 ACPUs (ARM Cortex-A72)
  23
  24 Implemented 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
  39 QEMU does not yet model any other devices, including the PL and the AI Engine.
  40
  41 Other 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
  50 Running
  51 """""""
  52 If the user provides an Operating System to be loaded, we expect users
  53 to use the ``-kernel`` command line option.
  54
  55 Users can load firmware or boot-loaders with the ``-device loader`` options.
  56
  57 When loading an OS, QEMU generates a DTB and selects an appropriate address
  58 where it gets loaded. This DTB will be passed to the kernel in register x0.
  59
  60 If there's no ``-kernel`` option, we generate a DTB and place it at 0x1000
  61 for boot-loaders or firmware to pick it up.
  62
  63 If users want to provide their own DTB, they can use the ``-dtb`` option.
  64 These DTBs will have their memory nodes modified to match QEMU's
  65 selected ram_size option before they get passed to the kernel or FW.
  66
  67 When loading an OS, we turn on QEMU's PSCI implementation with SMC
  68 as the PSCI conduit. When there's no ``-kernel`` option, we assume the user
  69 provides EL3 firmware to handle PSCI.
  70
  71 A few examples:
  72
  73 Direct 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
  86 Direct 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
  98 Boot PetaLinux 2019.2 via ARM Trusted Firmware (2018.3 because the 2019.2
  99 version 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
 112 Run 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
 124 Boot 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
 137 Run 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
 152 Boot 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
 166 Run 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
 181 BBRAM File Backend
 182 """"""""""""""""""
 183 BBRAM can have an optional file backend, which must be a seekable
 184 binary file with a size of 36 bytes or larger. A file with all
 185 binary 0s is a 'blank'.
 186
 187 To 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
 193 To use a different index value, N, from default of 0, add:
 194
 195 .. code-block:: bash
 196
 197   -global driver=xlnx.bbram-ctrl,property=drive-index,value=N
 198
 199 eFUSE File Backend
 200 """"""""""""""""""
 201 eFUSE can have an optional file backend, which must be a seekable
 202 binary file with a size of 3072 bytes or larger. A file with all
 203 binary 0s is a 'blank'.
 204
 205 To 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
 211 To 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
 229 Using CANFDs for Versal Virt
 230 """"""""""""""""""""""""""""
 231 Versal CANFD controller is developed based on SocketCAN and QEMU CAN bus
 232 implementation. Bus connection and socketCAN connection for each CAN module
 233 can be set through command lines.
 234
 235 To 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
 241 To 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
 248 The SocketCAN interface can connect to a Physical or a Virtual CAN interfaces on
 249 the host machine. Please check this document to learn about CAN interface on
 250 Linux: docs/system/devices/can.rst
 251
 252 To 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