Blame - poky/documentation/dev-manual/dev-manual-qemu.xml - stefanberger/openbmc

Andrew Geissler

4873add

2020-11-02 18:44:49 -0600

[diff] [blame]

1

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

2

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

3

[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

4

<title>Using the Quick EMUlator (QEMU)</title>

9

10

<para>

11

The Yocto Project uses an implementation of the Quick EMUlator (QEMU)

12

Open Source project as part of the Yocto Project development "tool

13

set".

14

This chapter provides both procedures that show you how to use the

15

Quick EMUlator (QEMU) and other QEMU information helpful for

16

development purposes.

</para>

<title>Overview</title>

21

22

<para>

23

Within the context of the Yocto Project, QEMU is an

24

emulator and virtualization machine that allows you to run a

25

complete image you have built using the Yocto Project as just

26

another task on your build system.

27

QEMU is useful for running and testing images and applications on

28

supported Yocto Project architectures without having actual

29

hardware.

30

Among other things, the Yocto Project uses QEMU to run automated

31

Quality Assurance (QA) tests on final images shipped with each

32

release.

33

<note>

34

This implementation is not the same as QEMU in general.

35

</note>

36

This section provides a brief reference for the Yocto Project

37

implementation of QEMU.

</para>

<para>

For official information and documentation on QEMU in general, see

42

the following references:

43

44

45

<emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>

46

The official website for the QEMU Open Source project.

47

</para></listitem>

48

49

<emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>

50

The QEMU user manual.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Running QEMU</title>

58

59

<para>

60

To use QEMU, you need to have QEMU installed and initialized as

61

well as have the proper artifacts (i.e. image files and root

62

filesystems) available.

63

Follow these general steps to run QEMU:

64

65

66

<emphasis>Install QEMU:</emphasis>

67

QEMU is made available with the Yocto Project a number of

68

ways.

69

One method is to install a Software Development Kit (SDK).

70

See

71

"<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"

72

section in the Yocto Project Application Development and

73

the Extensible Software Development Kit (eSDK) manual

74

for information on how to install QEMU.

75

</para></listitem>

76

77

<emphasis>Setting Up the Environment:</emphasis>

78

How you set up the QEMU environment depends on how you

installed QEMU:

If you cloned the <filename>poky</filename>

83

repository or you downloaded and unpacked a

84

Yocto Project release tarball, you can source

85

the build environment script (i.e.

86

<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>):

87

88

$ cd ~/poky

89

$ source oe-init-build-env

</literallayout>

</para></listitem>

If you installed a cross-toolchain, you can

94

run the script that initializes the toolchain.

95

For example, the following commands run the

96

initialization script from the default

97

<filename>poky_sdk</filename> directory:

98

99

. ~/poky_sdk/environment-setup-core2-64-poky-linux

</literallayout>

</para></listitem>

</itemizedlist>

</para></listitem>

<emphasis>Ensure the Artifacts are in Place:</emphasis>

106

You need to be sure you have a pre-built kernel that

107

will boot in QEMU.

108

You also need the target root filesystem for your target

109

machine's architecture:

110

111

112

If you have previously built an image for QEMU

113

(e.g. <filename>qemux86</filename>,

114

<filename>qemuarm</filename>, and so forth),

115

then the artifacts are in place in your

116

<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.

117

</para></listitem>

118

119

If you have not built an image, you can go to the

120

<ulink url='&YOCTO_MACHINES_DL_URL;'>machines/qemu</ulink>

121

area and download a pre-built image that matches

122

your architecture and can be run on QEMU.

123

</para></listitem>

124

</itemizedlist></para>

125

126

<para>See the

127

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>"

128

section in the Yocto Project Application Development and

129

the Extensible Software Development Kit (eSDK) manual

130

for information on how to extract a root filesystem.

</para></listitem>

The basic <filename>runqemu</filename> command syntax is as

135

follows:

136

137

$ runqemu [<replaceable>option</replaceable> ] [...]

138

</literallayout>

139

Based on what you provide on the command line,

140

<filename>runqemu</filename> does a good job of figuring

141

out what you are trying to do.

142

For example, by default, QEMU looks for the most recently

143

built image according to the timestamp when it needs to

144

look for an image.

145

Minimally, through the use of options, you must provide

146

either a machine name, a virtual machine image

147

(<filename>*wic.vmdk</filename>), or a kernel image

148

(<filename>*.bin</filename>).</para>

149

150

<para>Here are some additional examples to help illustrate

further QEMU:

This example starts QEMU with

155

<replaceable>MACHINE</replaceable> set to "qemux86-64".

156

Assuming a standard

157

<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,

158

<filename>runqemu</filename> automatically finds the

159

<filename>bzImage-qemux86-64.bin</filename> image file and

160

the

161

<filename>core-image-minimal-qemux86-64-20200218002850.rootfs.ext4</filename>

162

(assuming the current build created a

163

<filename>core-image-minimal</filename> image).

164

<note>

165

When more than one image with the same name exists, QEMU finds

166

and uses the most recently built image according to the

timestamp.

</note>

$ runqemu qemux86-64

</literallayout>

</para></listitem>

This example produces the exact same results as the

175

previous example.

176

This command, however, specifically provides the image

177

and root filesystem type.

178

179

$ runqemu qemux86-64 core-image-minimal ext4

</literallayout>

</para></listitem>

This example specifies to boot an initial RAM disk image

184

and to enable audio in QEMU.

185

For this case, <filename>runqemu</filename> set the

186

internal variable <filename>FSTYPE</filename> to

187

"cpio.gz".

188

Also, for audio to be enabled, an appropriate driver must

189

be installed (see the previous description for the

190

<filename>audio</filename> option for more information).

191

192

$ runqemu qemux86-64 ramfs audio

</literallayout>

</para></listitem>

This example does not provide enough information for

197

QEMU to launch.

198

While the command does provide a root filesystem type, it

199

must also minimally provide a

200

<replaceable>MACHINE</replaceable>,

201

<replaceable>KERNEL</replaceable>, or

202

<replaceable>VM</replaceable> option.

$ runqemu ext4

</literallayout>

</para></listitem>

This example specifies to boot a virtual machine

209

image (<filename>.wic.vmdk</filename> file).

210

From the <filename>.wic.vmdk</filename>,

211

<filename>runqemu</filename> determines the QEMU

212

architecture (<replaceable>MACHINE</replaceable>) to be

213

"qemux86-64" and the root filesystem type to be "vmdk".

214

215

$ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk

</literallayout>

</para></listitem>

</itemizedlist>

</para></listitem>

</orderedlist>

</para>

</section>

<title>Switching Between Consoles</title>

226

227

<para>

228

When booting or running QEMU, you can switch between

229

supported consoles by using

230

Ctrl+Alt+<replaceable>number</replaceable>.

231

For example, Ctrl+Alt+3 switches you to the serial console

232

as long as that console is enabled.

233

Being able to switch consoles is helpful, for example, if

234

the main QEMU console breaks for some reason.

235

<note>

236

Usually, "2" gets you to the main console and "3"

237

gets you to the serial console.

</note>

</para>

</section>

<title>Removing the Splash Screen</title>

244

245

<para>

246

You can remove the splash screen when QEMU is booting by

247

using Alt+left.

248

Removing the splash screen allows you to see what is

249

happening in the background.

</para>

</section>

<title>Disabling the Cursor Grab</title>

255

256

<para>

257

The default QEMU integration captures the cursor within the

258

main window.

259

It does this since standard mouse devices only provide

260

relative input and not absolute coordinates.

261

You then have to break out of the grab using the "Ctrl+Alt"

262

key combination.

263

However, the Yocto Project's integration of QEMU enables

264

the wacom USB touch pad driver by default to allow input

265

of absolute coordinates.

266

This default means that the mouse can enter and leave the

267

main window without the grab taking effect leading to a

268

better user experience.

</para>

</section>

<title>Running Under a Network File System (NFS) Server</title>

274

275

<para>

276

One method for running QEMU is to run it on an NFS server.

277

This is useful when you need to access the same file system

278

from both the build and the emulated system at the same time.

279

It is also worth noting that the system does not need root

280

privileges to run.

281

It uses a user space NFS server to avoid that.

282

Follow these steps to set up for running QEMU using an NFS

server.

<emphasis>Extract a Root Filesystem:</emphasis>

287

Once you are able to run QEMU in your environment, you can

288

use the <filename>runqemu-extract-sdk</filename> script,

289

which is located in the <filename>scripts</filename>

290

directory along with the <filename>runqemu</filename>

291

script.</para>

292

293

<para>The <filename>runqemu-extract-sdk</filename> takes a

294

root filesystem tarball and extracts it into a location

295

that you specify.

296

Here is an example that takes a file system and

297

extracts it to a directory named

298

<filename>test-nfs</filename>:

299

300

runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs

</literallayout>

</para></listitem>

<emphasis>Start QEMU:</emphasis>

305

Once you have extracted the file system, you can run

306

<filename>runqemu</filename> normally with the additional

307

location of the file system.

308

You can then also make changes to the files within

309

<filename>./test-nfs</filename> and see those changes

310

appear in the image in real time.

311

Here is an example using the <filename>qemux86</filename>

312

image:

313

314

runqemu qemux86-64 ./test-nfs

</literallayout>

</para></listitem>

</orderedlist>

<note>

<para>

Should you need to start, stop, or restart the NFS share,

321

you can use the following commands:

322

323

324

The following command starts the NFS share:

325

326

runqemu-export-rootfs start <replaceable>file-system-location</replaceable>

</literallayout>

</para></listitem>

The following command stops the NFS share:

331

332

runqemu-export-rootfs stop <replaceable>file-system-location</replaceable>

</literallayout>

</para></listitem>

The following command restarts the NFS share:

337

338

runqemu-export-rootfs restart <replaceable>file-system-location</replaceable>

</literallayout>

</para></listitem>

</itemizedlist>

</para>

</note>

</para>

</section>

<title>QEMU CPU Compatibility Under KVM</title>

349

350

<para>

351

By default, the QEMU build compiles for and targets 64-bit and x86

352

<trademark class='registered'>Intel</trademark> <trademark class='trademark'>Core</trademark>2

353

Duo processors and 32-bit x86

354

<trademark class='registered'>Intel</trademark> <trademark class='registered'>Pentium</trademark>

355

II processors.

356

QEMU builds for and targets these CPU types because they display

357

a broad range of CPU feature compatibility with many commonly

used CPUs.

</para>

<para>

Despite this broad range of compatibility, the CPUs could support

363

a feature that your host CPU does not support.

364

Although this situation is not a problem when QEMU uses software

365

emulation of the feature, it can be a problem when QEMU is

366

running with KVM enabled.

367

Specifically, software compiled with a certain CPU feature crashes

368

when run on a CPU under KVM that does not support that feature.

369

To work around this problem, you can override QEMU's runtime CPU

370

setting by changing the <filename>QB_CPU_KVM</filename>

371

variable in <filename>qemuboot.conf</filename> in the

372

<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>

373

<filename>deploy/image</filename> directory.

374

This setting specifies a <filename>-cpu</filename> option

375

passed into QEMU in the <filename>runqemu</filename> script.

376

Running <filename>qemu -cpu help</filename> returns a list of

377

available supported CPU types.

</para>

</section>

<title>QEMU Performance</title>

383

384

<para>

385

Using QEMU to emulate your hardware can result in speed issues

386

depending on the target and host architecture mix.

387

For example, using the <filename>qemux86</filename> image in the

388

emulator on an Intel-based 32-bit (x86) host machine is fast

389

because the target and host architectures match.

390

On the other hand, using the <filename>qemuarm</filename> image

391

on the same Intel-based host can be slower.

392

But, you still achieve faithful emulation of ARM-specific issues.

</para>

<para>

To speed things up, the QEMU images support using

397

<filename>distcc</filename> to call a cross-compiler outside the

398

emulated system.

399

If you used <filename>runqemu</filename> to start QEMU, and the

400

<filename>distccd</filename> application is present on the host

401

system, any BitBake cross-compiling toolchain available from the

402

build system is automatically used from within QEMU simply by

403

calling <filename>distcc</filename>.

404

You can accomplish this by defining the cross-compiler variable

405

(e.g. <filename>export CC="distcc"</filename>).

406

Alternatively, if you are using a suitable SDK image or the

407

appropriate stand-alone toolchain is present, the toolchain is

408

also automatically used.

409

<note>

410

Several mechanisms exist that let you connect to the system

411

running on the QEMU emulator:

412

413

414

QEMU provides a framebuffer interface that makes

415

standard consoles available.

416

</para></listitem>

417

418

Generally, headless embedded devices have a serial port.

419

If so, you can configure the operating system of the

420

running image to use that port to run a console.

421

The connection uses standard IP networking.

422

</para></listitem>

423

424

SSH servers exist in some QEMU images.

425

The <filename>core-image-sato</filename> QEMU image

426

has a Dropbear secure shell (SSH) server that runs

427

with the root password disabled.

428

The <filename>core-image-full-cmdline</filename> and

429

<filename>core-image-lsb</filename> QEMU images

430

have OpenSSH instead of Dropbear.

431

Including these SSH servers allow you to use standard

432

433

commands.

434

The <filename>core-image-minimal</filename> QEMU image,

435

however, contains no SSH server.

436

</para></listitem>

437

438

You can use a provided, user-space NFS server to boot

439

the QEMU session using a local copy of the root

440

filesystem on the host.

441

In order to make this connection, you must extract a

442

root filesystem tarball by using the

443

<filename>runqemu-extract-sdk</filename> command.

444

After running the command, you must then point the

445

<filename>runqemu</filename>

446

script to the extracted directory instead of a root

447

filesystem image file.

448

See the

449

"<link linkend='qemu-running-under-a-network-file-system-nfs-server'>Running Under a Network File System (NFS) Server</link>"

450

section for more information.

</para></listitem>

</itemizedlist>

</note>

</para>

</section>

<title>QEMU Command-Line Syntax</title>

459

460

<para>

461

The basic <filename>runqemu</filename> command syntax is as

462

follows:

463

464

$ runqemu [<replaceable>option</replaceable> ] [...]

465

</literallayout>

466

Based on what you provide on the command line,

467

<filename>runqemu</filename> does a good job of figuring out what

468

you are trying to do.

469

For example, by default, QEMU looks for the most recently built

470

image according to the timestamp when it needs to look for an

471

image.

472

Minimally, through the use of options, you must provide either

473

a machine name, a virtual machine image

474

(<filename>*wic.vmdk</filename>), or a kernel image

475

(<filename>*.bin</filename>).

</para>

<para>

Following is the command-line help output for the

480

<filename>runqemu</filename> command:

$ runqemu --help

Usage: you can run this script with any valid combination

485

of the following environment variables (in any order):

486

KERNEL - the kernel image file to use

487

ROOTFS - the rootfs image file or nfsroot directory to use

488

MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)

489

Simplified QEMU command-line options can be passed with:

490

nographic - disable video console

491

serial - enable a serial console on /dev/ttyS0

492

slirp - enable user networking, no root privileges is required

493

kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)

494

kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)

495

publicvnc - enable a VNC server open to all hosts

496

audio - enable audio

497

[*/]ovmf* - OVMF firmware file or base name for booting with UEFI

498

tcpserial=<port> - specify tcp serial port number

499

biosdir=<dir> - specify custom bios dir

500

biosfilename=<filename> - specify bios filename

501

qemuparams=<xyz> - specify custom parameters to QEMU

502

bootparams=<xyz> - specify custom kernel parameters during boot

503

help, -h, --help: print this text

Examples:

runqemu

runqemu qemuarm

runqemu tmp/deploy/images/qemuarm

509

runqemu tmp/deploy/images/qemux86/<qemuboot.conf>

510

runqemu qemux86-64 core-image-sato ext4

511

runqemu qemux86-64 wic-image-minimal wic

512

runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial

513

runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...

514

runqemu qemux86 qemuparams="-m 256"

515

runqemu qemux86 bootparams="psplash=false"

516

runqemu path/to/<image>-<machine>.wic

517

runqemu path/to/<image>-<machine>.wic.vmdk

</literallayout>

</para>

</section>

<title><filename>runqemu</filename> Command-Line Options</title>

524

525

<para>

526

Following is a description of <filename>runqemu</filename>

527

options you can provide on the command line:

528

529

If you do provide some "illegal" option combination or perhaps

530

you do not provide enough in the way of options,

531

<filename>runqemu</filename> provides appropriate error

532

messaging to help you correct the problem.

</note>

<replaceable>QEMUARCH</replaceable>:

537

The QEMU machine architecture, which must be "qemuarm",

538

"qemuarm64", "qemumips", "qemumips64", "qemuppc",

539

"qemux86", or "qemux86-64".

540

</para></listitem>

541

542

<filename><replaceable>VM</replaceable></filename>:

543

The virtual machine image, which must be a

544

<filename>.wic.vmdk</filename> file.

545

Use this option when you want to boot a

546

<filename>.wic.vmdk</filename> image.

547

The image filename you provide must contain one of the

548

following strings: "qemux86-64", "qemux86", "qemuarm",

549

"qemumips64", "qemumips", "qemuppc", or "qemush4".

550

</para></listitem>

551

552

<replaceable>ROOTFS</replaceable>:

553

A root filesystem that has one of the following

554

filetype extensions: "ext2", "ext3", "ext4", "jffs2",

555

"nfs", or "btrfs".

556

If the filename you provide for this option uses "nfs", it

557

must provide an explicit root filesystem path.

558

</para></listitem>

559

560

<replaceable>KERNEL</replaceable>:

561

A kernel image, which is a <filename>.bin</filename> file.

562

When you provide a <filename>.bin</filename> file,

563

<filename>runqemu</filename> detects it and assumes the

564

file is a kernel image.

565

</para></listitem>

566

567

<replaceable>MACHINE</replaceable>:

568

The architecture of the QEMU machine, which must be one

569

of the following: "qemux86", "qemux86-64", "qemuarm",

570

"qemuarm64", "qemumips", "qemumips64", or "qemuppc".

571

The <replaceable>MACHINE</replaceable> and

572

<replaceable>QEMUARCH</replaceable> options are basically

573

identical.

574

If you do not provide a <replaceable>MACHINE</replaceable>

575

option, <filename>runqemu</filename> tries to determine

576

it based on other options.

577

</para></listitem>

578

579

<filename>ramfs</filename>:

580

Indicates you are booting an initial RAM disk (initramfs)

581

image, which means the <filename>FSTYPE</filename> is

582

<filename>cpio.gz</filename>.

583

</para></listitem>

584

585

<filename>iso</filename>:

586

Indicates you are booting an ISO image, which means the

587

<filename>FSTYPE</filename> is

588

<filename>.iso</filename>.

589

</para></listitem>

590

591

<filename>nographic</filename>:

592

Disables the video console, which sets the console to

593

"ttys0".

594

This option is useful when you have logged into a server

595

and you do not want to disable forwarding from the

596

X Window System (X11) to your workstation or laptop.

597

</para></listitem>

598

599

<filename>serial</filename>:

600

Enables a serial console on

601

<filename>/dev/ttyS0</filename>.

602

</para></listitem>

603

604

<filename>biosdir</filename>:

605

Establishes a custom directory for BIOS, VGA BIOS and

keymaps.

</para></listitem>

<filename>biosfilename</filename>:

610

Establishes a custom BIOS name.

611

</para></listitem>

612

613

<filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:

614

Specifies custom QEMU parameters.

615

Use this option to pass options other than the simple

616

"kvm" and "serial" options.

617

</para></listitem>

618

<listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:

619

Specifies custom boot parameters for the kernel.

620

</para></listitem>

621

622

<filename>audio</filename>:

623

Enables audio in QEMU.

624

The <replaceable>MACHINE</replaceable> option must be

625

either "qemux86" or "qemux86-64" in order for audio to be

626

enabled.

627

Additionally, the <filename>snd_intel8x0</filename>

628

or <filename>snd_ens1370</filename> driver must be

629

installed in linux guest.

630

</para></listitem>

631

632

<filename>slirp</filename>:

633

Enables "slirp" networking, which is a different way

634

of networking that does not need root access

635

but also is not as easy to use or comprehensive

as the default.

</para></listitem>

<filename>kvm</filename>:

640

Enables KVM when running "qemux86" or "qemux86-64"

641

QEMU architectures.

642

For KVM to work, all the following conditions must be met:

643

644

645

Your <replaceable>MACHINE</replaceable> must be either

646

qemux86" or "qemux86-64".

647

</para></listitem>

648

649

Your build host has to have the KVM modules

650

installed, which are

651

<filename>/dev/kvm</filename>.

652

</para></listitem>

653

654

The build host <filename>/dev/kvm</filename>

655

directory has to be both writable and readable.

</para></listitem>

</itemizedlist>

</para></listitem>

<filename>kvm-vhost</filename>:

661

Enables KVM with VHOST support when running "qemux86"

662

or "qemux86-64" QEMU architectures.

663

For KVM with VHOST to work, the following conditions must

be met:

conditions must be met.

669

</para></listitem>

670

671

Your build host has to have virtio net device, which

672

are <filename>/dev/vhost-net</filename>.

673

</para></listitem>

674

675

The build host <filename>/dev/vhost-net</filename>

676

directory has to be either readable or writable

and "slirp-enabled".

</para></listitem>

</itemizedlist>

</para></listitem>

<filename>publicvnc</filename>:

683

Enables a VNC server open to all hosts.

</para></listitem>

</itemizedlist>

</para>

</section>

</chapter>

<!--

vim: expandtab tw=80 ts=4

691

-->