docs/system/ppc/ppce500.rst - third_party/qemu - Git at Google

 ppce500 generic platform (``ppce500``)
 ======================================

 QEMU for PPC supports a special ``ppce500`` machine designed for emulation and
 virtualization purposes.

 Supported devices
 -----------------

 The ``ppce500`` machine supports the following devices:

 * PowerPC e500 series core (e500v2/e500mc/e5500/e6500)
 * Configuration, Control, and Status Register (CCSR)
 * Multicore Programmable Interrupt Controller (MPIC) with MSI support
 * 1 16550A UART device
 * 1 Freescale MPC8xxx I2C controller
 * 1 Pericom pt7c4338 RTC via I2C
 * 1 Freescale MPC8xxx GPIO controller
 * Power-off functionality via one GPIO pin
 * 1 Freescale MPC8xxx PCI host controller
 * VirtIO devices via PCI bus
 * 1 Freescale Enhanced Secure Digital Host controller (eSDHC)
 * 1 Freescale Enhanced Triple Speed Ethernet controller (eTSEC)

 Hardware configuration information
 ----------------------------------

 The ``ppce500`` machine automatically generates a device tree blob ("dtb")
 which it passes to the guest, if there is no ``-dtb`` option. This provides
 information about the addresses, interrupt lines and other configuration of
 the various devices in the system.

 If users want to provide their own DTB, they can use the ``-dtb`` option.
 These DTBs should have the following requirements:

 * The number of subnodes under /cpus node should match QEMU's ``-smp`` option
 * The /memory reg size should match QEMU’s selected ram_size via ``-m``

 Both ``qemu-system-ppc`` and ``qemu-system-ppc64`` provide emulation for the
 following 32-bit PowerPC CPUs:

 * e500v2
 * e500mc

 Additionally ``qemu-system-ppc64`` provides support for the following 64-bit
 PowerPC CPUs:

 * e5500
 * e6500

 The CPU type can be specified via the ``-cpu`` command line. If not specified,
 it creates a machine with e500v2 core. The following example shows an e6500
 based machine creation:

 .. code-block:: bash

   $ qemu-system-ppc64 -nographic -M ppce500 -cpu e6500

 Boot options
 ------------

 The ``ppce500`` machine can start using the standard -kernel functionality
 for loading a payload like an OS kernel (e.g.: Linux), or U-Boot firmware.

 When -bios is omitted, the default pc-bios/u-boot.e500 firmware image is used
 as the BIOS. QEMU follows below truth table to select which payload to execute:

 ===== ========== =======
 -bios    -kernel payload
 ===== ========== =======
     N          N  u-boot
     N          Y  kernel
     Y don't care  u-boot
 ===== ========== =======

 When both -bios and -kernel are present, QEMU loads U-Boot and U-Boot in turns
 automatically loads the kernel image specified by the -kernel parameter via
 U-Boot's built-in "bootm" command, hence a legacy uImage format is required in
 such scenario.

 Running Linux kernel
 --------------------

 Linux mainline v5.11 release is tested at the time of writing. To build a
 Linux mainline kernel that can be booted by the ``ppce500`` machine in
 64-bit mode, simply configure the kernel using the defconfig configuration:

 .. code-block:: bash

   $ export ARCH=powerpc
   $ export CROSS_COMPILE=powerpc-linux-
   $ make corenet64_smp_defconfig
   $ make menuconfig

 then manually select the following configuration:

   Platform support > Freescale Book-E Machine Type > QEMU generic e500 platform

 To boot the newly built Linux kernel in QEMU with the ``ppce500`` machine:

 .. code-block:: bash

   $ qemu-system-ppc64 -M ppce500 -cpu e5500 -smp 4 -m 2G \
       -display none -serial stdio \
       -kernel vmlinux \
       -initrd /path/to/rootfs.cpio \
       -append "root=/dev/ram"

 To build a Linux mainline kernel that can be booted by the ``ppce500`` machine
 in 32-bit mode, use the same 64-bit configuration steps except the defconfig
 file should use corenet32_smp_defconfig.

 To boot the 32-bit Linux kernel:

 .. code-block:: bash

   $ qemu-system-ppc64 -M ppce500 -cpu e500mc -smp 4 -m 2G \
       -display none -serial stdio \
       -kernel vmlinux \
       -initrd /path/to/rootfs.cpio \
       -append "root=/dev/ram"

 Running U-Boot
 --------------

 U-Boot mainline v2021.07 release is tested at the time of writing. To build a
 U-Boot mainline bootloader that can be booted by the ``ppce500`` machine, use
 the qemu-ppce500_defconfig with similar commands as described above for Linux:

 .. code-block:: bash

   $ export CROSS_COMPILE=powerpc-linux-
   $ make qemu-ppce500_defconfig

 You will get u-boot file in the build tree.

 When U-Boot boots, you will notice the following if using with ``-cpu e6500``:

 .. code-block:: none

   CPU:   Unknown, Version: 0.0, (0x00000000)
   Core:  e6500, Version: 2.0, (0x80400020)

 This is because we only specified a core name to QEMU and it does not have a
 meaningful SVR value which represents an actual SoC that integrates such core.
 You can specify a real world SoC device that QEMU has built-in support but all
 these SoCs are e500v2 based MPC85xx series, hence you cannot test anything
 built for P4080 (e500mc), P5020 (e5500) and T2080 (e6500).

 Networking
 ----------

 By default a VirtIO standard PCI networking device is connected as an ethernet
 interface at PCI address 0.1.0, but we can switch that to an e1000 NIC by:

 .. code-block:: bash

   $ qemu-system-ppc64 -M ppce500 -smp 4 -m 2G \
                       -display none -serial stdio \
                       -bios u-boot \
                       -nic tap,ifname=tap0,script=no,downscript=no,model=e1000

 The QEMU ``ppce500`` machine can also dynamically instantiate an eTSEC device
 if “-device eTSEC” is given to QEMU:

 .. code-block:: bash

   -netdev tap,ifname=tap0,script=no,downscript=no,id=net0 -device eTSEC,netdev=net0

 Root file system on flash drive
 -------------------------------

 Rather than using a root file system on ram disk, it is possible to have it on
 CFI flash. Given an ext2 image whose size must be a power of two, it can be used
 as follows:

 .. code-block:: bash

   $ qemu-system-ppc64 -M ppce500 -cpu e500mc -smp 4 -m 2G \
       -display none -serial stdio \
       -kernel vmlinux \
       -drive if=pflash,file=/path/to/rootfs.ext2,format=raw \
       -append "rootwait root=/dev/mtdblock0"

 Alternatively, the root file system can also reside on an emulated SD card
 whose size must again be a power of two:

 .. code-block:: bash

   $ qemu-system-ppc64 -M ppce500 -cpu e500mc -smp 4 -m 2G \
       -display none -serial stdio \
       -kernel vmlinux \
       -device sd-card,drive=mydrive \
       -drive id=mydrive,if=none,file=/path/to/rootfs.ext2,format=raw \
       -append "rootwait root=/dev/mmcblk0"
	ppce500 generic platform (``ppce500``)
	======================================

	QEMU for PPC supports a special ``ppce500`` machine designed for emulation and
	virtualization purposes.

	Supported devices
	-----------------

	The ``ppce500`` machine supports the following devices:

	* PowerPC e500 series core (e500v2/e500mc/e5500/e6500)
	* Configuration, Control, and Status Register (CCSR)
	* Multicore Programmable Interrupt Controller (MPIC) with MSI support
	* 1 16550A UART device
	* 1 Freescale MPC8xxx I2C controller
	* 1 Pericom pt7c4338 RTC via I2C
	* 1 Freescale MPC8xxx GPIO controller
	* Power-off functionality via one GPIO pin
	* 1 Freescale MPC8xxx PCI host controller
	* VirtIO devices via PCI bus
	* 1 Freescale Enhanced Secure Digital Host controller (eSDHC)
	* 1 Freescale Enhanced Triple Speed Ethernet controller (eTSEC)

	Hardware configuration information
	----------------------------------

	The ``ppce500`` machine automatically generates a device tree blob ("dtb")
	which it passes to the guest, if there is no ``-dtb`` option. This provides
	information about the addresses, interrupt lines and other configuration of
	the various devices in the system.

	If users want to provide their own DTB, they can use the ``-dtb`` option.
	These DTBs should have the following requirements:

	* The number of subnodes under /cpus node should match QEMU's ``-smp`` option
	* The /memory reg size should match QEMU’s selected ram_size via ``-m``

	Both ``qemu-system-ppc`` and ``qemu-system-ppc64`` provide emulation for the
	following 32-bit PowerPC CPUs:

	* e500v2
	* e500mc

	Additionally ``qemu-system-ppc64`` provides support for the following 64-bit
	PowerPC CPUs:

	* e5500
	* e6500

	The CPU type can be specified via the ``-cpu`` command line. If not specified,
	it creates a machine with e500v2 core. The following example shows an e6500
	based machine creation:

	.. code-block:: bash

	$ qemu-system-ppc64 -nographic -M ppce500 -cpu e6500

	Boot options
	------------

	The ``ppce500`` machine can start using the standard -kernel functionality
	for loading a payload like an OS kernel (e.g.: Linux), or U-Boot firmware.

	When -bios is omitted, the default pc-bios/u-boot.e500 firmware image is used
	as the BIOS. QEMU follows below truth table to select which payload to execute:

	===== ========== =======
	-bios -kernel payload
	===== ========== =======
	N N u-boot
	N Y kernel
	Y don't care u-boot
	===== ========== =======

	When both -bios and -kernel are present, QEMU loads U-Boot and U-Boot in turns
	automatically loads the kernel image specified by the -kernel parameter via
	U-Boot's built-in "bootm" command, hence a legacy uImage format is required in
	such scenario.

	Running Linux kernel
	--------------------

	Linux mainline v5.11 release is tested at the time of writing. To build a
	Linux mainline kernel that can be booted by the ``ppce500`` machine in
	64-bit mode, simply configure the kernel using the defconfig configuration:

	.. code-block:: bash

	$ export ARCH=powerpc
	$ export CROSS_COMPILE=powerpc-linux-
	$ make corenet64_smp_defconfig
	$ make menuconfig

	then manually select the following configuration:

	Platform support > Freescale Book-E Machine Type > QEMU generic e500 platform

	To boot the newly built Linux kernel in QEMU with the ``ppce500`` machine:

	.. code-block:: bash

	$ qemu-system-ppc64 -M ppce500 -cpu e5500 -smp 4 -m 2G \
	-display none -serial stdio \
	-kernel vmlinux \
	-initrd /path/to/rootfs.cpio \
	-append "root=/dev/ram"

	To build a Linux mainline kernel that can be booted by the ``ppce500`` machine
	in 32-bit mode, use the same 64-bit configuration steps except the defconfig
	file should use corenet32_smp_defconfig.

	To boot the 32-bit Linux kernel:

	.. code-block:: bash

	$ qemu-system-ppc64 -M ppce500 -cpu e500mc -smp 4 -m 2G \
	-display none -serial stdio \
	-kernel vmlinux \
	-initrd /path/to/rootfs.cpio \
	-append "root=/dev/ram"

	Running U-Boot
	--------------

	U-Boot mainline v2021.07 release is tested at the time of writing. To build a
	U-Boot mainline bootloader that can be booted by the ``ppce500`` machine, use
	the qemu-ppce500_defconfig with similar commands as described above for Linux:

	.. code-block:: bash

	$ export CROSS_COMPILE=powerpc-linux-
	$ make qemu-ppce500_defconfig

	You will get u-boot file in the build tree.

	When U-Boot boots, you will notice the following if using with ``-cpu e6500``:

	.. code-block:: none

	CPU: Unknown, Version: 0.0, (0x00000000)
	Core: e6500, Version: 2.0, (0x80400020)

	This is because we only specified a core name to QEMU and it does not have a
	meaningful SVR value which represents an actual SoC that integrates such core.
	You can specify a real world SoC device that QEMU has built-in support but all
	these SoCs are e500v2 based MPC85xx series, hence you cannot test anything
	built for P4080 (e500mc), P5020 (e5500) and T2080 (e6500).

	Networking
	----------

	By default a VirtIO standard PCI networking device is connected as an ethernet
	interface at PCI address 0.1.0, but we can switch that to an e1000 NIC by:

	.. code-block:: bash

	$ qemu-system-ppc64 -M ppce500 -smp 4 -m 2G \
	-display none -serial stdio \
	-bios u-boot \
	-nic tap,ifname=tap0,script=no,downscript=no,model=e1000

	The QEMU ``ppce500`` machine can also dynamically instantiate an eTSEC device
	if “-device eTSEC” is given to QEMU:

	.. code-block:: bash

	-netdev tap,ifname=tap0,script=no,downscript=no,id=net0 -device eTSEC,netdev=net0

	Root file system on flash drive
	-------------------------------

	Rather than using a root file system on ram disk, it is possible to have it on
	CFI flash. Given an ext2 image whose size must be a power of two, it can be used
	as follows:

	.. code-block:: bash

	$ qemu-system-ppc64 -M ppce500 -cpu e500mc -smp 4 -m 2G \
	-display none -serial stdio \
	-kernel vmlinux \
	-drive if=pflash,file=/path/to/rootfs.ext2,format=raw \
	-append "rootwait root=/dev/mtdblock0"

	Alternatively, the root file system can also reside on an emulated SD card
	whose size must again be a power of two:

	.. code-block:: bash

	$ qemu-system-ppc64 -M ppce500 -cpu e500mc -smp 4 -m 2G \
	-display none -serial stdio \
	-kernel vmlinux \
	-device sd-card,drive=mydrive \
	-drive id=mydrive,if=none,file=/path/to/rootfs.ext2,format=raw \
	-append "rootwait root=/dev/mmcblk0"