xref: /openbmc/qemu/docs/system/ppc/ppce500.rst (revision b14df228)
1ppce500 generic platform (``ppce500``)
2======================================
3
4QEMU for PPC supports a special ``ppce500`` machine designed for emulation and
5virtualization purposes.
6
7Supported devices
8-----------------
9
10The ``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
24Hardware configuration information
25----------------------------------
26
27The ``ppce500`` machine automatically generates a device tree blob ("dtb")
28which it passes to the guest, if there is no ``-dtb`` option. This provides
29information about the addresses, interrupt lines and other configuration of
30the various devices in the system.
31
32If users want to provide their own DTB, they can use the ``-dtb`` option.
33These 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
38Both ``qemu-system-ppc`` and ``qemu-system-ppc64`` provide emulation for the
39following 32-bit PowerPC CPUs:
40
41* e500v2
42* e500mc
43
44Additionally ``qemu-system-ppc64`` provides support for the following 64-bit
45PowerPC CPUs:
46
47* e5500
48* e6500
49
50The CPU type can be specified via the ``-cpu`` command line. If not specified,
51it creates a machine with e500v2 core. The following example shows an e6500
52based machine creation:
53
54.. code-block:: bash
55
56  $ qemu-system-ppc64 -nographic -M ppce500 -cpu e6500
57
58Boot options
59------------
60
61The ``ppce500`` machine can start using the standard -kernel functionality
62for loading a payload like an OS kernel (e.g.: Linux), or U-Boot firmware.
63
64When -bios is omitted, the default pc-bios/u-boot.e500 firmware image is used
65as 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
75When both -bios and -kernel are present, QEMU loads U-Boot and U-Boot in turns
76automatically loads the kernel image specified by the -kernel parameter via
77U-Boot's built-in "bootm" command, hence a legacy uImage format is required in
78such scenario.
79
80Running Linux kernel
81--------------------
82
83Linux mainline v5.11 release is tested at the time of writing. To build a
84Linux mainline kernel that can be booted by the ``ppce500`` machine in
8564-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
94then manually select the following configuration:
95
96  Platform support > Freescale Book-E Machine Type > QEMU generic e500 platform
97
98To 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
108To build a Linux mainline kernel that can be booted by the ``ppce500`` machine
109in 32-bit mode, use the same 64-bit configuration steps except the defconfig
110file should use corenet32_smp_defconfig.
111
112To 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
122Running U-Boot
123--------------
124
125U-Boot mainline v2021.07 release is tested at the time of writing. To build a
126U-Boot mainline bootloader that can be booted by the ``ppce500`` machine, use
127the 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
134You will get u-boot file in the build tree.
135
136When 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
143This is because we only specified a core name to QEMU and it does not have a
144meaningful SVR value which represents an actual SoC that integrates such core.
145You can specify a real world SoC device that QEMU has built-in support but all
146these SoCs are e500v2 based MPC85xx series, hence you cannot test anything
147built for P4080 (e500mc), P5020 (e5500) and T2080 (e6500).
148
149By default a VirtIO standard PCI networking device is connected as an ethernet
150interface 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
159The QEMU ``ppce500`` machine can also dynamically instantiate an eTSEC device
160if “-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
165