1.. SPDX-License-Identifier: GPL-2.0+
2.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com>
3
4QEMU x86
5========
6
7Build instructions for bare mode
8--------------------------------
9
10To build u-boot.rom for QEMU x86 targets, just simply run::
11
12   $ make qemu-x86_defconfig (for 32-bit)
13   $ make qemu-x86_64_defconfig (for 64-bit)
14   $ make all
15
16Note this default configuration will build a U-Boot for the QEMU x86 i440FX
17board. To build a U-Boot against QEMU x86 Q35 board, you can change the build
18configuration during the 'make menuconfig' process like below::
19
20   Device Tree Control  --->
21       ...
22       (qemu-x86_q35) Default Device Tree for DT control
23
24Test with QEMU for bare mode
25----------------------------
26
27QEMU is a fancy emulator that can enable us to test U-Boot without access to
28a real x86 board. Please make sure your QEMU version is 2.3.0 or above test
29U-Boot. To launch QEMU with u-boot.rom, call QEMU as follows::
30
31   $ qemu-system-i386 -nographic -bios path/to/u-boot.rom
32
33This will instantiate an emulated x86 board with i440FX and PIIX chipset. QEMU
34also supports emulating an x86 board with Q35 and ICH9 based chipset, which is
35also supported by U-Boot. To instantiate such a machine, call QEMU with::
36
37   $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -M q35
38
39Note by default QEMU instantiated boards only have 128 MiB system memory. But
40it is enough to have U-Boot boot and function correctly. You can increase the
41system memory by pass '-m' parameter to QEMU if you want more memory::
42
43   $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024
44
45This creates a board with 1 GiB system memory. Currently U-Boot for QEMU only
46supports 3 GiB maximum system memory and reserves the last 1 GiB address space
47for PCI device memory-mapped I/O and other stuff, so the maximum value of '-m'
48would be 3072.
49
50QEMU emulates a graphic card which U-Boot supports. Removing '-nographic' will
51show QEMU's VGA console window. Note this will disable QEMU's serial output.
52If you want to check both consoles, use '-serial stdio'.
53
54Multicore is also supported by QEMU via '-smp n' where n is the number of cores
55to instantiate. Note, the maximum supported CPU number in QEMU is 255.
56
57U-Boot uses 'distro_bootcmd' by default when booting on x86 QEMU. This tries to
58load a boot script, kernel, and ramdisk from several different interfaces. For
59the default boot order, see 'qemu-x86.h'. For more information, see
60'README.distro'. Most Linux distros can be booted by writing a uboot script.
61For example, Debian (stretch) can be booted by creating a script file named
62'boot.txt' with the contents::
63
64   setenv bootargs root=/dev/sda1 ro
65   load ${devtype} ${devnum}:${distro_bootpart} ${kernel_addr_r} /vmlinuz
66   load ${devtype} ${devnum}:${distro_bootpart} ${ramdisk_addr_r} /initrd.img
67   zboot ${kernel_addr_r} - ${ramdisk_addr_r} ${filesize}
68
69Then compile and install it with::
70
71   $ apt install u-boot-tools && \
72     mkimage -T script -C none -n "Boot script" -d boot.txt /boot/boot.scr
73
74The fw_cfg interface in QEMU also provides information about kernel data,
75initrd, command-line arguments and more. U-Boot supports directly accessing
76these informtion from fw_cfg interface, which saves the time of loading them
77from hard disk or network again, through emulated devices. To use it , simply
78providing them in QEMU command line::
79
80   $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024 \
81     -kernel /path/to/bzImage -append 'root=/dev/ram console=ttyS0' \
82     -initrd /path/to/initrd -smp 8
83
84Note: -initrd and -smp are both optional
85
86Then start QEMU, in U-Boot command line use the following U-Boot command to
87setup kernel::
88
89   => qfw
90   qfw - QEMU firmware interface
91
92   Usage:
93   qfw <command>
94       - list                             : print firmware(s) currently loaded
95       - cpus                             : print online cpu number
96       - load <kernel addr> <initrd addr> : load kernel and initrd (if any) and setup for zboot
97
98   => qfw load
99   loading kernel to address 01000000 size 5d9d30 initrd 04000000 size 1b1ab50
100
101Here the kernel (bzImage) is loaded to 01000000 and initrd is to 04000000. Then,
102'zboot' can be used to boot the kernel::
103
104   => zboot 01000000 - 04000000 1b1ab50
105
106To run 64-bit U-Boot, qemu-system-x86_64 should be used instead, e.g.::
107
108   $ qemu-system-x86_64 -nographic -bios path/to/u-boot.rom
109
110A specific CPU can be specified via the '-cpu' parameter but please make
111sure the specified CPU supports 64-bit like '-cpu core2duo'. Conversely
112'-cpu pentium' won't work for obvious reasons that the processor only
113supports 32-bit.
114
115Note 64-bit support is very preliminary at this point. Lots of features
116are missing in the 64-bit world. One notable feature is the VGA console
117support which is currently missing, so that you must specify '-nographic'
118to get 64-bit U-Boot up and running.
119