docs/system/ppc/ppce500.rst

   1 ppce500 generic platform (``ppce500``)
   2 ======================================
   3
   4 QEMU for PPC supports a special ``ppce500`` machine designed for emulation and
   5 virtualization purposes.
   6
   7 Supported devices
   8 -----------------
   9
  10 The ``ppce500`` machine supports the following devices:
  11
  12 * PowerPC e500 series core (e500v2/e500mc/e5500/e6500)
  13 * Configuration, Control, and Status Register (CCSR)
  14 * Multicore Programmable Interrupt Controller (MPIC) with MSI support
  15 * 1 16550A UART device
  16 * 1 Freescale MPC8xxx I2C controller
  17 * 1 Pericom pt7c4338 RTC via I2C
  18 * 1 Freescale MPC8xxx GPIO controller
  19 * Power-off functionality via one GPIO pin
  20 * 1 Freescale MPC8xxx PCI host controller
  21 * VirtIO devices via PCI bus
  22 * 1 Freescale Enhanced Triple Speed Ethernet controller (eTSEC)
  23
  24 Hardware configuration information
  25 ----------------------------------
  26
  27 The ``ppce500`` machine automatically generates a device tree blob ("dtb")
  28 which it passes to the guest, if there is no ``-dtb`` option. This provides
  29 information about the addresses, interrupt lines and other configuration of
  30 the various devices in the system.
  31
  32 If users want to provide their own DTB, they can use the ``-dtb`` option.
  33 These DTBs should have the following requirements:
  34
  35 * The number of subnodes under /cpus node should match QEMU's ``-smp`` option
  36 * The /memory reg size should match QEMU’s selected ram_size via ``-m``
  37
  38 Both ``qemu-system-ppc`` and ``qemu-system-ppc64`` provide emulation for the
  39 following 32-bit PowerPC CPUs:
  40
  41 * e500v2
  42 * e500mc
  43
  44 Additionally ``qemu-system-ppc64`` provides support for the following 64-bit
  45 PowerPC CPUs:
  46
  47 * e5500
  48 * e6500
  49
  50 The CPU type can be specified via the ``-cpu`` command line. If not specified,
  51 it creates a machine with e500v2 core. The following example shows an e6500
  52 based machine creation:
  53
  54 .. code-block:: bash
  55
  56   $ qemu-system-ppc64 -nographic -M ppce500 -cpu e6500
  57
  58 Boot options
  59 ------------
  60
  61 The ``ppce500`` machine can start using the standard -kernel functionality
  62 for loading a payload like an OS kernel (e.g.: Linux), or U-Boot firmware.
  63
  64 When -bios is omitted, the default pc-bios/u-boot.e500 firmware image is used
  65 as the BIOS. QEMU follows below truth table to select which payload to execute:
  66
  67 ===== ========== =======
  68 -bios    -kernel payload
  69 ===== ========== =======
  70     N          N  u-boot
  71     N          Y  kernel
  72     Y don't care  u-boot
  73 ===== ========== =======
  74
  75 When both -bios and -kernel are present, QEMU loads U-Boot and U-Boot in turns
  76 automatically loads the kernel image specified by the -kernel parameter via
  77 U-Boot's built-in "bootm" command, hence a legacy uImage format is required in
  78 such senario.
  79
  80 Running Linux kernel
  81 --------------------
  82
  83 Linux mainline v5.11 release is tested at the time of writing. To build a
  84 Linux mainline kernel that can be booted by the ``ppce500`` machine in
  85 64-bit mode, simply configure the kernel using the defconfig configuration:
  86
  87 .. code-block:: bash
  88
  89   $ export ARCH=powerpc
  90   $ export CROSS_COMPILE=powerpc-linux-
  91   $ make corenet64_smp_defconfig
  92   $ make menuconfig
  93
  94 then manually select the following configuration:
  95
  96   Platform support > Freescale Book-E Machine Type > QEMU generic e500 platform
  97
  98 To boot the newly built Linux kernel in QEMU with the ``ppce500`` machine:
  99
 100 .. code-block:: bash
 101
 102   $ qemu-system-ppc64 -M ppce500 -cpu e5500 -smp 4 -m 2G \
 103       -display none -serial stdio \
 104       -kernel vmlinux \
 105       -initrd /path/to/rootfs.cpio \
 106       -append "root=/dev/ram"
 107
 108 To build a Linux mainline kernel that can be booted by the ``ppce500`` machine
 109 in 32-bit mode, use the same 64-bit configuration steps except the defconfig
 110 file should use corenet32_smp_defconfig.
 111
 112 To boot the 32-bit Linux kernel:
 113
 114 .. code-block:: bash
 115
 116   $ qemu-system-ppc{64|32} -M ppce500 -cpu e500mc -smp 4 -m 2G \
 117       -display none -serial stdio \
 118       -kernel vmlinux \
 119       -initrd /path/to/rootfs.cpio \
 120       -append "root=/dev/ram"
 121
 122 Running U-Boot
 123 --------------
 124
 125 U-Boot mainline v2021.07 release is tested at the time of writing. To build a
 126 U-Boot mainline bootloader that can be booted by the ``ppce500`` machine, use
 127 the qemu-ppce500_defconfig with similar commands as described above for Linux:
 128
 129 .. code-block:: bash
 130
 131   $ export CROSS_COMPILE=powerpc-linux-
 132   $ make qemu-ppce500_defconfig
 133
 134 You will get u-boot file in the build tree.
 135
 136 When U-Boot boots, you will notice the following if using with ``-cpu e6500``:
 137
 138 .. code-block:: none
 139
 140   CPU:   Unknown, Version: 0.0, (0x00000000)
 141   Core:  e6500, Version: 2.0, (0x80400020)
 142
 143 This is because we only specified a core name to QEMU and it does not have a
 144 meaningful SVR value which represents an actual SoC that integrates such core.
 145 You can specify a real world SoC device that QEMU has built-in support but all
 146 these SoCs are e500v2 based MPC85xx series, hence you cannot test anything
 147 built for P4080 (e500mc), P5020 (e5500) and T2080 (e6500).
 148
 149 By default a VirtIO standard PCI networking device is connected as an ethernet
 150 interface at PCI address 0.1.0, but we can switch that to an e1000 NIC by:
 151
 152 .. code-block:: bash
 153
 154   $ qemu-system-ppc -M ppce500 -smp 4 -m 2G \
 155                     -display none -serial stdio \
 156                     -bios u-boot \
 157                     -nic tap,ifname=tap0,script=no,downscript=no,model=e1000
 158
 159 The QEMU ``ppce500`` machine can also dynamically instantiate an eTSEC device
 160 if “-device eTSEC” is given to QEMU:
 161
 162 .. code-block:: bash
 163
 164   -netdev tap,ifname=tap0,script=no,downscript=no,id=net0 -device eTSEC,netdev=net0