~ahs3/+junk/cq-qemu

@item Since only root can access to the USB devices directly, you can either launch QEMU as root or change the permissions of the USB devices you want to use. For testing, the following suffices:

1006

@example

1007

chown -R myuid /proc/bus/usb

1008

@end example

1009

1010

@item Launch QEMU and do in the monitor:

1011

@example

1012

info usbhost

1013

Device 1.2, speed 480 Mb/s

1014

Class 00: USB device 1234:5678, USB DISK

1015

@end example

1016

You should see the list of the devices you can use (Never try to use

1017

hubs, it won't work).

1018

1019

@item Add the device in QEMU by using:

1020

@example

1021

usb_add host:1234:5678

1022

@end example

1023

1024

Normally the guest OS should report that a new USB device is

1025

plugged. You can use the option @option{-usbdevice} to do the same.

1026

1027

@item Now you can try to use the host USB device in QEMU.

1028

1029

@end enumerate

1030

1031

When relaunching QEMU, you may have to unplug and plug again the USB

1032

device to make it work again (this is a bug).

1033

1034

@node vnc_security

1035

@section VNC security

1036

1037

The VNC server capability provides access to the graphical console

1038

of the guest VM across the network. This has a number of security

1039

considerations depending on the deployment scenarios.

1040

1041

@menu

1042

* vnc_sec_none::

1043

* vnc_sec_password::

1044

* vnc_sec_certificate::

1045

* vnc_sec_certificate_verify::

1046

* vnc_sec_certificate_pw::

1047

* vnc_sec_sasl::

1048

* vnc_sec_certificate_sasl::

1049

* vnc_generate_cert::

1050

* vnc_setup_sasl::

1051

@end menu

1052

@node vnc_sec_none

1053

@subsection Without passwords

1054

1055

The simplest VNC server setup does not include any form of authentication.

1056

For this setup it is recommended to restrict it to listen on a UNIX domain

1057

socket only. For example

1058

1059

@example

1060

qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc

1061

@end example

1062

1063

This ensures that only users on local box with read/write access to that

1064

path can access the VNC server. To securely access the VNC server from a

1065

remote machine, a combination of netcat+ssh can be used to provide a secure

1066

tunnel.

1067

1068

@node vnc_sec_password

1069

@subsection With passwords

1070

1071

The VNC protocol has limited support for password based authentication. Since

1072

the protocol limits passwords to 8 characters it should not be considered

1073

to provide high security. The password can be fairly easily brute-forced by

1074

a client making repeat connections. For this reason, a VNC server using password

1075

authentication should be restricted to only listen on the loopback interface

1076

or UNIX domain sockets. Password authentication is requested with the @code{password}

1077

option, and then once QEMU is running the password is set with the monitor. Until

1078

the monitor is used to set the password all clients will be rejected.

1079

1080

@example

1081

qemu [...OPTIONS...] -vnc :1,password -monitor stdio

1082

(qemu) change vnc password

1083

Password: ********

1084

(qemu)

1085

@end example

1086

1087

@node vnc_sec_certificate

1088

@subsection With x509 certificates

1089

1090

The QEMU VNC server also implements the VeNCrypt extension allowing use of

1091

TLS for encryption of the session, and x509 certificates for authentication.

1092

The use of x509 certificates is strongly recommended, because TLS on its

1093

own is susceptible to man-in-the-middle attacks. Basic x509 certificate

1094

support provides a secure session, but no authentication. This allows any

1095

client to connect, and provides an encrypted session.

1096

1097

@example

1098

qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio

1099

@end example

1100

1101

In the above example @code{/etc/pki/qemu} should contain at least three files,

1102

@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged

1103

users will want to use a private directory, for example @code{$HOME/.pki/qemu}.

1104

NB the @code{server-key.pem} file should be protected with file mode 0600 to

1105

only be readable by the user owning it.

1106

1107

@node vnc_sec_certificate_verify

1108

@subsection With x509 certificates and client verification

1109

1110

Certificates can also provide a means to authenticate the client connecting.

1111

The server will request that the client provide a certificate, which it will

1112

then validate against the CA certificate. This is a good choice if deploying

1113

in an environment with a private internal certificate authority.

1114

1115

@example

1116

qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio

1117

@end example

1118

1119

1120

@node vnc_sec_certificate_pw

1121

@subsection With x509 certificates, client verification and passwords

1122

1123

Finally, the previous method can be combined with VNC password authentication

1124

to provide two layers of authentication for clients.

1125

1126

@example

1127

qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio

1128

(qemu) change vnc password

1129

Password: ********

1130

(qemu)

1131

@end example

1132

1133

1134

@node vnc_sec_sasl

1135

@subsection With SASL authentication

1136

1137

The SASL authentication method is a VNC extension, that provides an

1138

easily extendable, pluggable authentication method. This allows for

1139

integration with a wide range of authentication mechanisms, such as

1140

PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.

1141

The strength of the authentication depends on the exact mechanism

1142

configured. If the chosen mechanism also provides a SSF layer, then

1143

it will encrypt the datastream as well.

1144

1145

Refer to the later docs on how to choose the exact SASL mechanism

1146

used for authentication, but assuming use of one supporting SSF,

1147

then QEMU can be launched with:

1148

1149

@example

1150

qemu [...OPTIONS...] -vnc :1,sasl -monitor stdio

1151

@end example

1152

1153

@node vnc_sec_certificate_sasl

1154

@subsection With x509 certificates and SASL authentication

1155

1156

If the desired SASL authentication mechanism does not supported

1157

SSF layers, then it is strongly advised to run it in combination

1158

with TLS and x509 certificates. This provides securely encrypted

1159

data stream, avoiding risk of compromising of the security

1160

credentials. This can be enabled, by combining the 'sasl' option

1161

with the aforementioned TLS + x509 options:

1162

1163

@example

1164

qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio

1165

@end example

1166

1167

1168

@node vnc_generate_cert

1169

@subsection Generating certificates for VNC

1170

1171

The GNU TLS packages provides a command called @code{certtool} which can

1172

be used to generate certificates and keys in PEM format. At a minimum it

1173

is necessary to setup a certificate authority, and issue certificates to

1174

each server. If using certificates for authentication, then each client

1175

will also need to be issued a certificate. The recommendation is for the

1176

server to keep its certificates in either @code{/etc/pki/qemu} or for

1177

unprivileged users in @code{$HOME/.pki/qemu}.

1178

1179

@menu

1180

* vnc_generate_ca::

1181

* vnc_generate_server::

1182

* vnc_generate_client::

1183

@end menu

1184

@node vnc_generate_ca

1185

@subsubsection Setup the Certificate Authority

1186

1187

This step only needs to be performed once per organization / organizational

1188

unit. First the CA needs a private key. This key must be kept VERY secret

1189

and secure. If this key is compromised the entire trust chain of the certificates

1190

issued with it is lost.

1191

1192

@example

1193

# certtool --generate-privkey > ca-key.pem

1194

@end example

1195

1196

A CA needs to have a public certificate. For simplicity it can be a self-signed

1197

certificate, or one issue by a commercial certificate issuing authority. To

1198

generate a self-signed certificate requires one core piece of information, the

1199

name of the organization.

1200

1201

@example

1202

# cat > ca.info <<EOF

1203

cn = Name of your organization

1204

1205

cert_signing_key

1206

EOF

1207

# certtool --generate-self-signed \

1208

--load-privkey ca-key.pem

1209

--template ca.info \

1210

--outfile ca-cert.pem

1211

@end example

1212

1213

The @code{ca-cert.pem} file should be copied to all servers and clients wishing to utilize

1214

TLS support in the VNC server. The @code{ca-key.pem} must not be disclosed/copied at all.

1215

1216

@node vnc_generate_server

1217

@subsubsection Issuing server certificates

1218

1219

Each server (or host) needs to be issued with a key and certificate. When connecting

1220

the certificate is sent to the client which validates it against the CA certificate.

1221

The core piece of information for a server certificate is the hostname. This should

1222

be the fully qualified hostname that the client will connect with, since the client

1223

will typically also verify the hostname in the certificate. On the host holding the

1224

secure CA private key:

1225

1226

@example

1227

# cat > server.info <<EOF

1228

organization = Name of your organization

1229

cn = server.foo.example.com

1230

tls_www_server

1231

encryption_key

1232

signing_key

1233

EOF

1234

# certtool --generate-privkey > server-key.pem

1235

# certtool --generate-certificate \

1236

--load-ca-certificate ca-cert.pem \

1237

--load-ca-privkey ca-key.pem \

1238

--load-privkey server server-key.pem \

1239

--template server.info \

1240

--outfile server-cert.pem

1241

@end example

1242

1243

The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied

1244

to the server for which they were generated. The @code{server-key.pem} is security

1245

sensitive and should be kept protected with file mode 0600 to prevent disclosure.

1246

1247

@node vnc_generate_client

1248

@subsubsection Issuing client certificates

1249

1250

If the QEMU VNC server is to use the @code{x509verify} option to validate client

1251

certificates as its authentication mechanism, each client also needs to be issued

1252

a certificate. The client certificate contains enough metadata to uniquely identify

1253

the client, typically organization, state, city, building, etc. On the host holding

1254

the secure CA private key:

1255

1256

@example

1257

# cat > client.info <<EOF

1258

country = GB

1259

state = London

1260

locality = London

1261

organiazation = Name of your organization

1262

cn = client.foo.example.com

1263

tls_www_client

1264

encryption_key

1265

signing_key

1266

EOF

1267

# certtool --generate-privkey > client-key.pem

1268

# certtool --generate-certificate \

1269

--load-ca-certificate ca-cert.pem \

1270

--load-ca-privkey ca-key.pem \

1271

--load-privkey client-key.pem \

1272

--template client.info \

1273

--outfile client-cert.pem

1274

@end example

1275

1276

The @code{client-key.pem} and @code{client-cert.pem} files should now be securely

1277

copied to the client for which they were generated.

1278

1279

1280

@node vnc_setup_sasl

1281

1282

@subsection Configuring SASL mechanisms

1283

1284

The following documentation assumes use of the Cyrus SASL implementation on a

1285

Linux host, but the principals should apply to any other SASL impl. When SASL

1286

is enabled, the mechanism configuration will be loaded from system default

1287

SASL service config /etc/sasl2/qemu.conf. If running QEMU as an

1288

unprivileged user, an environment variable SASL_CONF_PATH can be used

1289

to make it search alternate locations for the service config.

1290

1291

The default configuration might contain

1292

1293

@example

1294

mech_list: digest-md5

1295

sasldb_path: /etc/qemu/passwd.db

1296

@end example

1297

1298

This says to use the 'Digest MD5' mechanism, which is similar to the HTTP

1299

Digest-MD5 mechanism. The list of valid usernames & passwords is maintained

1300

in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2

1301

command. While this mechanism is easy to configure and use, it is not

1302

considered secure by modern standards, so only suitable for developers /

1303

ad-hoc testing.

1304

1305

A more serious deployment might use Kerberos, which is done with the 'gssapi'

1306

mechanism

1307

1308

@example

1309

mech_list: gssapi

1310

keytab: /etc/qemu/krb5.tab

1311

@end example

1312

1313

For this to work the administrator of your KDC must generate a Kerberos

1314

principal for the server, with a name of 'qemu/somehost.example.com@@EXAMPLE.COM'

1315

replacing 'somehost.example.com' with the fully qualified host name of the

1316

machine running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.

1317

1318

Other configurations will be left as an exercise for the reader. It should

1319

be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data

1320

encryption. For all other mechanisms, VNC should always be configured to

1321

use TLS and x509 certificates to protect security credentials from snooping.

1322

1323

@node gdb_usage

1324

@section GDB usage

1325

1326

QEMU has a primitive support to work with gdb, so that you can do

1327

'Ctrl-C' while the virtual machine is running and inspect its state.

1328

1329

In order to use gdb, launch qemu with the '-s' option. It will wait for a

1330

gdb connection:

1331

@example

1332

> qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \

1333

-append "root=/dev/hda"

1334

Connected to host network interface: tun0

1335

Waiting gdb connection on port 1234

1336

@end example

1337

1338

Then launch gdb on the 'vmlinux' executable:

1339

@example

1340

> gdb vmlinux

1341

@end example

1342

1343

In gdb, connect to QEMU:

1344

@example

1345

(gdb) target remote localhost:1234

1346

@end example

1347

1348

Then you can use gdb normally. For example, type 'c' to launch the kernel:

1349

@example

1350

(gdb) c

1351

@end example

1352

1353

Here are some useful tips in order to use gdb on system code:

1354

1355

@enumerate

1356

@item

1357

Use @code{info reg} to display all the CPU registers.

1358

@item

1359

Use @code{x/10i $eip} to display the code at the PC position.

1360

@item

1361

Use @code{set architecture i8086} to dump 16 bit code. Then use

1362

@code{x/10i $cs*16+$eip} to dump the code at the PC position.

1363

@end enumerate

1364

1365

Advanced debugging options:

1366

1367

The default single stepping behavior is step with the IRQs and timer service routines off. It is set this way because when gdb executes a single step it expects to advance beyond the current instruction. With the IRQs and and timer service routines on, a single step might jump into the one of the interrupt or exception vectors instead of executing the current instruction. This means you may hit the same breakpoint a number of times before executing the instruction gdb wants to have executed. Because there are rare circumstances where you want to single step into an interrupt vector the behavior can be controlled from GDB. There are three commands you can query and set the single step behavior:

1368

@table @code

1369

@item maintenance packet qqemu.sstepbits

1370

1371

This will display the MASK bits used to control the single stepping IE:

1372

@example

1373

(gdb) maintenance packet qqemu.sstepbits

1374

sending: "qqemu.sstepbits"

1375

received: "ENABLE=1,NOIRQ=2,NOTIMER=4"

1376

@end example

1377

@item maintenance packet qqemu.sstep

1378

1379

This will display the current value of the mask used when single stepping IE:

1380

@example

1381

(gdb) maintenance packet qqemu.sstep

1382

sending: "qqemu.sstep"

1383

received: "0x7"

1384

@end example

1385

@item maintenance packet Qqemu.sstep=HEX_VALUE

1386

1387

This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:

1388

@example

1389

(gdb) maintenance packet Qqemu.sstep=0x5

1390

sending: "qemu.sstep=0x5"

1391

received: "OK"

1392

@end example

1393

@end table

1394

1395

@node pcsys_os_specific

1396

@section Target OS specific information

1397

1398

@subsection Linux

1399

1400

To have access to SVGA graphic modes under X11, use the @code{vesa} or

1401

the @code{cirrus} X11 driver. For optimal performances, use 16 bit

1402

color depth in the guest and the host OS.

1403

1404

When using a 2.6 guest Linux kernel, you should add the option

1405

@code{clock=pit} on the kernel command line because the 2.6 Linux

1406

kernels make very strict real time clock checks by default that QEMU

1407

cannot simulate exactly.

1408

1409

When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is

1410

not activated because QEMU is slower with this patch. The QEMU

1411

Accelerator Module is also much slower in this case. Earlier Fedora

1412

Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this

1413

patch by default. Newer kernels don't have it.

1414

1415

@subsection Windows

1416

1417

If you have a slow host, using Windows 95 is better as it gives the

1418

best speed. Windows 2000 is also a good choice.

1419

1420

@subsubsection SVGA graphic modes support

1421

1422

QEMU emulates a Cirrus Logic GD5446 Video

1423

card. All Windows versions starting from Windows 95 should recognize

1424

and use this graphic card. For optimal performances, use 16 bit color

1425

depth in the guest and the host OS.

1426

1427

If you are using Windows XP as guest OS and if you want to use high

1428

resolution modes which the Cirrus Logic BIOS does not support (i.e. >=

1429

1280x1024x16), then you should use the VESA VBE virtual graphic card

1430

(option @option{-std-vga}).

1431

1432

@subsubsection CPU usage reduction

1433

1434

Windows 9x does not correctly use the CPU HLT

1435

instruction. The result is that it takes host CPU cycles even when

1436

idle. You can install the utility from

1437

@url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this

1438

problem. Note that no such tool is needed for NT, 2000 or XP.

1439

1440

@subsubsection Windows 2000 disk full problem

1441

1442

Windows 2000 has a bug which gives a disk full problem during its

1443

installation. When installing it, use the @option{-win2k-hack} QEMU

1444

option to enable a specific workaround. After Windows 2000 is

1445

installed, you no longer need this option (this option slows down the

1446

IDE transfers).

1447

1448

@subsubsection Windows 2000 shutdown

1449

1450

Windows 2000 cannot automatically shutdown in QEMU although Windows 98

1451

can. It comes from the fact that Windows 2000 does not automatically

1452

use the APM driver provided by the BIOS.

1453

1454

In order to correct that, do the following (thanks to Struan

1455

Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>

1456

Add/Troubleshoot a device => Add a new device & Next => No, select the

1457

hardware from a list & Next => NT Apm/Legacy Support & Next => Next

1458

(again) a few times. Now the driver is installed and Windows 2000 now

1459

correctly instructs QEMU to shutdown at the appropriate moment.

1460

1461

@subsubsection Share a directory between Unix and Windows

1462

1463

See @ref{sec_invocation} about the help of the option @option{-smb}.

1464

1465

@subsubsection Windows XP security problem

1466

1467

Some releases of Windows XP install correctly but give a security

1468

error when booting:

1469

@example

1470

A problem is preventing Windows from accurately checking the

1471

license for this computer. Error code: 0x800703e6.

1472

@end example

1473

1474

The workaround is to install a service pack for XP after a boot in safe

1475

mode. Then reboot, and the problem should go away. Since there is no

1476

network while in safe mode, its recommended to download the full

1477

installation of SP1 or SP2 and transfer that via an ISO or using the

1478

vvfat block device ("-hdb fat:directory_which_holds_the_SP").

1479

1480

@subsection MS-DOS and FreeDOS

1481

1482

@subsubsection CPU usage reduction

1483

1484

DOS does not correctly use the CPU HLT instruction. The result is that

1485

it takes host CPU cycles even when idle. You can install the utility

1486

from @url{http://www.vmware.com/software/dosidle210.zip} to solve this

1487

problem.

1488

1489

@node QEMU System emulator for non PC targets

1490

@chapter QEMU System emulator for non PC targets

1491

1492

QEMU is a generic emulator and it emulates many non PC

1493

machines. Most of the options are similar to the PC emulator. The

1494

differences are mentioned in the following sections.

1495

1496

@menu

1497

* PowerPC System emulator::

1498

* Sparc32 System emulator::

1499

* Sparc64 System emulator::

1500

* MIPS System emulator::

1501

* ARM System emulator::

1502

* ColdFire System emulator::

1503

* Cris System emulator::

1504

* Microblaze System emulator::

1505

* SH4 System emulator::

1506

* Xtensa System emulator::

1507

@end menu

1508

1509

@node PowerPC System emulator

1510

@section PowerPC System emulator

1511

@cindex system emulation (PowerPC)

1512

1513

Use the executable @file{qemu-system-ppc} to simulate a complete PREP

1514

or PowerMac PowerPC system.

1515

1516

QEMU emulates the following PowerMac peripherals:

1517

1518

@itemize @minus

1519

@item

1520

UniNorth or Grackle PCI Bridge

1521

@item

1522

PCI VGA compatible card with VESA Bochs Extensions

1523

@item

1524

2 PMAC IDE interfaces with hard disk and CD-ROM support

1525

@item

1526

NE2000 PCI adapters

1527

@item

1528

Non Volatile RAM

1529

@item

1530

VIA-CUDA with ADB keyboard and mouse.

1531

@end itemize

1532

1533

QEMU emulates the following PREP peripherals:

1534

1535

@itemize @minus

1536

@item

1537

PCI Bridge

1538

@item

1539

PCI VGA compatible card with VESA Bochs Extensions

1540

@item

1541

2 IDE interfaces with hard disk and CD-ROM support

1542

@item

1543

Floppy disk

1544

@item

1545

NE2000 network adapters

1546

@item

1547

Serial port

1548

@item

1549

PREP Non Volatile RAM

1550

@item

1551

PC compatible keyboard and mouse.

1552

@end itemize

1553

1554

QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at

1555

@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.

1556

1557

Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/}

1558

for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL

1559

v2) portable firmware implementation. The goal is to implement a 100%

1560

IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.

1561

1562

@c man begin OPTIONS

1563

1564

The following options are specific to the PowerPC emulation:

1565

1566

@table @option

1567

1568

@item -g @var{W}x@var{H}[x@var{DEPTH}]

1569

1570

Set the initial VGA graphic mode. The default is 800x600x15.

1571

1572

@item -prom-env @var{string}

1573

1574

Set OpenBIOS variables in NVRAM, for example:

1575

1576

@example

1577

qemu-system-ppc -prom-env 'auto-boot?=false' \

1578

-prom-env 'boot-device=hd:2,\yaboot' \

1579

-prom-env 'boot-args=conf=hd:2,\yaboot.conf'

1580

@end example

1581

1582

These variables are not used by Open Hack'Ware.

1583

1584

@end table

1585

1586

@c man end

1587

1588

1589

More information is available at

1590

@url{http://perso.magic.fr/l_indien/qemu-ppc/}.

1591

1592

@node Sparc32 System emulator

1593

@section Sparc32 System emulator

1594

@cindex system emulation (Sparc32)

1595

1596

Use the executable @file{qemu-system-sparc} to simulate the following

1597

Sun4m architecture machines:

1598

@itemize @minus

1599

@item

1600

SPARCstation 4

1601

@item

1602

SPARCstation 5

1603

@item

1604

SPARCstation 10

1605

@item

1606

SPARCstation 20

1607

@item

1608

SPARCserver 600MP

1609

@item

1610

SPARCstation LX

1611

@item

1612

SPARCstation Voyager

1613

@item

1614

SPARCclassic

1615

@item

1616

SPARCbook

1617

@end itemize

1618

1619

The emulation is somewhat complete. SMP up to 16 CPUs is supported,

1620

but Linux limits the number of usable CPUs to 4.

1621

1622

It's also possible to simulate a SPARCstation 2 (sun4c architecture),

1623

SPARCserver 1000, or SPARCcenter 2000 (sun4d architecture), but these

1624

emulators are not usable yet.

1625

1626

QEMU emulates the following sun4m/sun4c/sun4d peripherals:

1627

1628

@itemize @minus

1629

@item

1630

IOMMU or IO-UNITs

1631

@item

1632

TCX Frame buffer

1633

@item

1634

Lance (Am7990) Ethernet

1635

@item

1636

Non Volatile RAM M48T02/M48T08

1637

@item

1638

Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard

1639

and power/reset logic

1640

@item

1641

ESP SCSI controller with hard disk and CD-ROM support

1642

@item

1643

Floppy drive (not on SS-600MP)

1644

@item

1645

CS4231 sound device (only on SS-5, not working yet)

1646

@end itemize

1647

1648

The number of peripherals is fixed in the architecture. Maximum

1649

memory size depends on the machine type, for SS-5 it is 256MB and for

1650

others 2047MB.

1651

1652

Since version 0.8.2, QEMU uses OpenBIOS

1653

@url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable

1654

firmware implementation. The goal is to implement a 100% IEEE

1655

1275-1994 (referred to as Open Firmware) compliant firmware.

1656

1657

A sample Linux 2.6 series kernel and ram disk image are available on

1658

the QEMU web site. There are still issues with NetBSD and OpenBSD, but

1659

some kernel versions work. Please note that currently Solaris kernels

1660

don't work probably due to interface issues between OpenBIOS and

1661

Solaris.

1662

1663

@c man begin OPTIONS

1664

1665

The following options are specific to the Sparc32 emulation:

1666

1667

@table @option

1668

1669

@item -g @var{W}x@var{H}x[x@var{DEPTH}]

1670

1671

Set the initial TCX graphic mode. The default is 1024x768x8, currently

1672

the only other possible mode is 1024x768x24.

1673

1674

@item -prom-env @var{string}

1675

1676

Set OpenBIOS variables in NVRAM, for example:

1677

1678

@example

1679

qemu-system-sparc -prom-env 'auto-boot?=false' \

1680

-prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'

1681

@end example

1682

1683

@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook|SS-2|SS-1000|SS-2000]

1684

1685

Set the emulated machine type. Default is SS-5.

1686

1687

@end table

1688

1689

@c man end

1690

1691

@node Sparc64 System emulator

1692

@section Sparc64 System emulator

1693

@cindex system emulation (Sparc64)

1694

1695

Use the executable @file{qemu-system-sparc64} to simulate a Sun4u

1696

(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic

1697

Niagara (T1) machine. The emulator is not usable for anything yet, but

1698

it can launch some kernels.

1699

1700

QEMU emulates the following peripherals:

1701

1702

@itemize @minus

1703

@item

1704

UltraSparc IIi APB PCI Bridge

1705

@item

1706

PCI VGA compatible card with VESA Bochs Extensions

1707

@item

1708

PS/2 mouse and keyboard

1709

@item

1710

Non Volatile RAM M48T59

1711

@item

1712

PC-compatible serial ports

1713

@item

1714

2 PCI IDE interfaces with hard disk and CD-ROM support

1715

@item

1716

Floppy disk

1717

@end itemize

1718

1719

@c man begin OPTIONS

1720

1721

The following options are specific to the Sparc64 emulation:

1722

1723

@table @option

1724

1725

@item -prom-env @var{string}

1726

1727

Set OpenBIOS variables in NVRAM, for example:

1728

1729

@example

1730

qemu-system-sparc64 -prom-env 'auto-boot?=false'

1731

@end example

1732

1733

@item -M [sun4u|sun4v|Niagara]

1734

1735

Set the emulated machine type. The default is sun4u.

1736

1737

@end table

1738

1739

@c man end

1740

1741

@node MIPS System emulator

1742

@section MIPS System emulator

1743

@cindex system emulation (MIPS)

1744

1745

Four executables cover simulation of 32 and 64-bit MIPS systems in

1746

both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}

1747

@file{qemu-system-mips64} and @file{qemu-system-mips64el}.

1748

Five different machine types are emulated:

1749

1750

@itemize @minus

1751

@item

1752

A generic ISA PC-like machine "mips"

1753

@item

1754

The MIPS Malta prototype board "malta"

1755

@item

1756

An ACER Pica "pica61". This machine needs the 64-bit emulator.

1757

@item

1758

MIPS emulator pseudo board "mipssim"

1759

@item

1760

A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.

1761

@end itemize

1762

1763

The generic emulation is supported by Debian 'Etch' and is able to

1764

install Debian into a virtual disk image. The following devices are

1765

emulated:

1766

1767

@itemize @minus

1768

@item

1769

A range of MIPS CPUs, default is the 24Kf

1770

@item

1771

PC style serial port

1772

@item

1773

PC style IDE disk

1774

@item

1775

NE2000 network card

1776

@end itemize

1777

1778

The Malta emulation supports the following devices:

1779

1780

@itemize @minus

1781

@item

1782

Core board with MIPS 24Kf CPU and Galileo system controller

1783

@item

1784

PIIX4 PCI/USB/SMbus controller

1785

@item

1786

The Multi-I/O chip's serial device

1787

@item

1788

PCI network cards (PCnet32 and others)

1789

@item

1790

Malta FPGA serial device

1791

@item

1792

Cirrus (default) or any other PCI VGA graphics card

1793

@end itemize

1794

1795

The ACER Pica emulation supports:

1796

1797

@itemize @minus

1798

@item

1799

MIPS R4000 CPU

1800

@item

1801

PC-style IRQ and DMA controllers

1802

@item

1803

PC Keyboard

1804

@item

1805

IDE controller

1806

@end itemize

1807

1808

The mipssim pseudo board emulation provides an environment similar

1809

to what the proprietary MIPS emulator uses for running Linux.

1810

It supports:

1811

1812

@itemize @minus

1813

@item

1814

A range of MIPS CPUs, default is the 24Kf

1815

@item

1816

PC style serial port

1817

@item

1818

MIPSnet network emulation

1819

@end itemize

1820

1821

The MIPS Magnum R4000 emulation supports:

1822

1823

@itemize @minus

1824

@item

1825

MIPS R4000 CPU

1826

@item

1827

PC-style IRQ controller

1828

@item

1829

PC Keyboard

1830

@item

1831

SCSI controller

1832

@item

1833

G364 framebuffer

1834

@end itemize

1835

1836

1837

@node ARM System emulator

1838

@section ARM System emulator

1839

@cindex system emulation (ARM)

1840

1841

Use the executable @file{qemu-system-arm} to simulate a ARM

1842

machine. The ARM Integrator/CP board is emulated with the following

1843

devices:

1844

1845

@itemize @minus

1846

@item

1847

ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU

1848

@item

1849

Two PL011 UARTs

1850

@item

1851

SMC 91c111 Ethernet adapter

1852

@item

1853

PL110 LCD controller

1854

@item

1855

PL050 KMI with PS/2 keyboard and mouse.

1856

@item

1857

PL181 MultiMedia Card Interface with SD card.

1858

@end itemize

1859

1860

The ARM Versatile baseboard is emulated with the following devices:

1861

1862

@itemize @minus

1863

@item

1864

ARM926E, ARM1136 or Cortex-A8 CPU

1865

@item

1866

PL190 Vectored Interrupt Controller

1867

@item

1868

Four PL011 UARTs

1869

@item

1870

SMC 91c111 Ethernet adapter

1871

@item

1872

PL110 LCD controller

1873

@item

1874

PL050 KMI with PS/2 keyboard and mouse.

1875

@item

1876

PCI host bridge. Note the emulated PCI bridge only provides access to

1877

PCI memory space. It does not provide access to PCI IO space.

1878

This means some devices (eg. ne2k_pci NIC) are not usable, and others

1879

(eg. rtl8139 NIC) are only usable when the guest drivers use the memory

1880

mapped control registers.

1881

@item

1882

PCI OHCI USB controller.

1883

@item

1884

LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.

1885

@item

1886

PL181 MultiMedia Card Interface with SD card.

1887

@end itemize

1888

1889

Several variants of the ARM RealView baseboard are emulated,

1890

including the EB, PB-A8 and PBX-A9. Due to interactions with the

1891

bootloader, only certain Linux kernel configurations work out

1892

of the box on these boards.

1893

1894

Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET

1895

enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board

1896

should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET

1897

disabled and expect 1024M RAM.

1898

1899

The following devices are emulated:

1900

1901

@itemize @minus

1902

@item

1903

ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU

1904

@item

1905

ARM AMBA Generic/Distributed Interrupt Controller

1906

@item

1907

Four PL011 UARTs

1908

@item

1909

SMC 91c111 or SMSC LAN9118 Ethernet adapter

1910

@item

1911

PL110 LCD controller

1912

@item

1913

PL050 KMI with PS/2 keyboard and mouse

1914

@item

1915

PCI host bridge

1916

@item

1917

PCI OHCI USB controller

1918

@item

1919

LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices

1920

@item

1921

PL181 MultiMedia Card Interface with SD card.

1922

@end itemize

1923

1924

The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"

1925

and "Terrier") emulation includes the following peripherals:

1926

1927

@itemize @minus

1928

@item

1929

Intel PXA270 System-on-chip (ARM V5TE core)

1930

@item

1931

NAND Flash memory

1932

@item

1933

IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"

1934

@item

1935

On-chip OHCI USB controller

1936

@item

1937

On-chip LCD controller

1938

@item

1939

On-chip Real Time Clock

1940

@item

1941

TI ADS7846 touchscreen controller on SSP bus

1942

@item

1943

Maxim MAX1111 analog-digital converter on I@math{^2}C bus

1944

@item

1945

GPIO-connected keyboard controller and LEDs

1946

@item

1947

Secure Digital card connected to PXA MMC/SD host

1948

@item

1949

Three on-chip UARTs

1950

@item

1951

WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses

1952

@end itemize

1953

1954

The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the

1955

following elements:

1956

1957

@itemize @minus

1958

@item

1959

Texas Instruments OMAP310 System-on-chip (ARM 925T core)

1960

@item

1961

ROM and RAM memories (ROM firmware image can be loaded with -option-rom)

1962

@item

1963

On-chip LCD controller

1964

@item

1965

On-chip Real Time Clock

1966

@item

1967

TI TSC2102i touchscreen controller / analog-digital converter / Audio

1968

CODEC, connected through MicroWire and I@math{^2}S busses

1969

@item

1970

GPIO-connected matrix keypad

1971

@item

1972

Secure Digital card connected to OMAP MMC/SD host

1973

@item

1974

Three on-chip UARTs

1975

@end itemize

1976

1977

Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)

1978

emulation supports the following elements:

1979

1980

@itemize @minus

1981

@item

1982

Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)

1983

@item

1984

RAM and non-volatile OneNAND Flash memories

1985

@item

1986

Display connected to EPSON remote framebuffer chip and OMAP on-chip

1987

display controller and a LS041y3 MIPI DBI-C controller

1988

@item

1989

TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers

1990

driven through SPI bus

1991

@item

1992

National Semiconductor LM8323-controlled qwerty keyboard driven

1993

through I@math{^2}C bus

1994

@item

1995

Secure Digital card connected to OMAP MMC/SD host

1996

@item

1997

Three OMAP on-chip UARTs and on-chip STI debugging console

1998

@item

1999

A Bluetooth(R) transceiver and HCI connected to an UART

2000

@item

2001

Mentor Graphics "Inventra" dual-role USB controller embedded in a TI

2002

TUSB6010 chip - only USB host mode is supported

2003

@item

2004

TI TMP105 temperature sensor driven through I@math{^2}C bus

2005

@item

2006

TI TWL92230C power management companion with an RTC on I@math{^2}C bus

2007

@item

2008

Nokia RETU and TAHVO multi-purpose chips with an RTC, connected

2009

through CBUS

2010

@end itemize

2011

2012

The Luminary Micro Stellaris LM3S811EVB emulation includes the following

2013

devices:

2014

2015

@itemize @minus

2016

@item

2017

Cortex-M3 CPU core.

2018

@item

2019

64k Flash and 8k SRAM.

2020

@item

2021

Timers, UARTs, ADC and I@math{^2}C interface.

2022

@item

2023

OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.

2024

@end itemize

2025

2026

The Luminary Micro Stellaris LM3S6965EVB emulation includes the following

2027

devices:

2028

2029

@itemize @minus

2030

@item

2031

Cortex-M3 CPU core.

2032

@item

2033

256k Flash and 64k SRAM.

2034

@item

2035

Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.

2036

@item

2037

OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.

2038

@end itemize

2039

2040

The Freecom MusicPal internet radio emulation includes the following

2041

elements:

2042

2043

@itemize @minus

2044

@item

2045

Marvell MV88W8618 ARM core.

2046

@item

2047

32 MB RAM, 256 KB SRAM, 8 MB flash.

2048

@item

2049

Up to 2 16550 UARTs

2050

@item

2051

MV88W8xx8 Ethernet controller

2052

@item

2053

MV88W8618 audio controller, WM8750 CODEC and mixer

2054

@item

2055

128×64 display with brightness control

2056

@item

2057

2 buttons, 2 navigation wheels with button function

2058

@end itemize

2059

2060

The Siemens SX1 models v1 and v2 (default) basic emulation.

2061

The emulation includes the following elements:

2062

2063

@itemize @minus

2064

@item

2065

Texas Instruments OMAP310 System-on-chip (ARM 925T core)

2066

@item

2067

ROM and RAM memories (ROM firmware image can be loaded with -pflash)

2068

2069

1 Flash of 16MB and 1 Flash of 8MB

2070

2071

1 Flash of 32MB

2072

@item

2073

On-chip LCD controller

2074

@item

2075

On-chip Real Time Clock

2076

@item

2077

Secure Digital card connected to OMAP MMC/SD host

2078

@item

2079

Three on-chip UARTs

2080

@end itemize

2081

2082

The "Syborg" Symbian Virtual Platform base model includes the following

2083

elements:

2084

2085

@itemize @minus

2086

@item

2087

ARM Cortex-A8 CPU

2088

@item

2089

Interrupt controller

2090

@item

2091

Timer

2092

@item

2093

Real Time Clock

2094

@item

2095

Keyboard

2096

@item

2097

Framebuffer

2098

@item

2099

Touchscreen

2100

@item

2101

UARTs

2102

@end itemize

2103

2104

A Linux 2.6 test image is available on the QEMU web site. More

2105

information is available in the QEMU mailing-list archive.

2106

2107

@c man begin OPTIONS

2108

2109

The following options are specific to the ARM emulation:

2110

2111

@table @option

2112

2113

@item -semihosting

2114

Enable semihosting syscall emulation.

2115

2116

On ARM this implements the "Angel" interface.

2117

2118

Note that this allows guest direct access to the host filesystem,

2119

so should only be used with trusted guest OS.

2120

2121

@end table

2122

2123

@node ColdFire System emulator

2124

@section ColdFire System emulator

2125

@cindex system emulation (ColdFire)

2126

@cindex system emulation (M68K)

2127

2128

Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.

2129

The emulator is able to boot a uClinux kernel.

2130

2131

The M5208EVB emulation includes the following devices:

2132

2133

@itemize @minus

2134

@item

2135

MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).

2136

@item

2137

Three Two on-chip UARTs.

2138

@item

2139

Fast Ethernet Controller (FEC)

2140

@end itemize

2141

2142

The AN5206 emulation includes the following devices:

2143

2144

@itemize @minus

2145

@item

2146

MCF5206 ColdFire V2 Microprocessor.

2147

@item

2148

Two on-chip UARTs.

2149

@end itemize

2150

2151

@c man begin OPTIONS

2152

2153

The following options are specific to the ColdFire emulation:

2154

2155

@table @option

2156

2157

@item -semihosting

2158

Enable semihosting syscall emulation.

2159

2160

On M68K this implements the "ColdFire GDB" interface used by libgloss.

2161

2162

Note that this allows guest direct access to the host filesystem,

2163

so should only be used with trusted guest OS.

2164

2165

@end table

2166

2167

@node Cris System emulator

2168

@section Cris System emulator

2169

@cindex system emulation (Cris)

2170

2171

TODO

2172

2173

@node Microblaze System emulator

2174

@section Microblaze System emulator

2175

@cindex system emulation (Microblaze)

2176

2177

TODO

2178

2179

@node SH4 System emulator

2180

@section SH4 System emulator

2181

@cindex system emulation (SH4)

2182

2183

TODO

2184

2185

@node Xtensa System emulator

2186

@section Xtensa System emulator

2187

@cindex system emulation (Xtensa)

2188

2189

Two executables cover simulation of both Xtensa endian options,

2190

@file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.

2191

Two different machine types are emulated:

2192

2193

@itemize @minus

2194

@item

2195

Xtensa emulator pseudo board "sim"

2196

@item

2197

Avnet LX60/LX110/LX200 board

2198

@end itemize

2199

2200

The sim pseudo board emulation provides an environment similar

2201

to one provided by the proprietary Tensilica ISS.

2202

It supports:

2203

2204

@itemize @minus

2205

@item

2206

A range of Xtensa CPUs, default is the DC232B

2207

@item

2208

Console and filesystem access via semihosting calls

2209

@end itemize

2210

2211

The Avnet LX60/LX110/LX200 emulation supports:

2212

2213

@itemize @minus

2214

@item

2215

A range of Xtensa CPUs, default is the DC232B

2216

@item

2217

16550 UART

2218

@item

2219

OpenCores 10/100 Mbps Ethernet MAC

2220

@end itemize

2221

2222

@c man begin OPTIONS

2223

2224

The following options are specific to the Xtensa emulation:

2225

2226

@table @option

2227

2228

@item -semihosting

2229

Enable semihosting syscall emulation.

2230

2231

Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.

2232

Tensilica baremetal libc for ISS and linux platform "sim" use this interface.

2233

2234

Note that this allows guest direct access to the host filesystem,

2235

so should only be used with trusted guest OS.

2236

2237

@end table

2238

@node QEMU User space emulator

2239

@chapter QEMU User space emulator

2240

2241

@menu

2242

* Supported Operating Systems ::

2243

* Linux User space emulator::

2244

* Mac OS X/Darwin User space emulator ::

2245

* BSD User space emulator ::

2246

@end menu

2247

2248

@node Supported Operating Systems

2249

@section Supported Operating Systems

2250

2251

The following OS are supported in user space emulation:

2252

2253

@itemize @minus

2254

@item

2255

Linux (referred as qemu-linux-user)

2256

@item

2257

Mac OS X/Darwin (referred as qemu-darwin-user)

2258

@item

2259

BSD (referred as qemu-bsd-user)

2260

@end itemize

2261

2262

@node Linux User space emulator

2263

@section Linux User space emulator

2264

2265

@menu

2266

* Quick Start::

2267

* Wine launch::

2268

* Command line options::

2269

* Other binaries::

2270

@end menu

2271

2272

@node Quick Start

2273

@subsection Quick Start

2274

2275

In order to launch a Linux process, QEMU needs the process executable

2276

itself and all the target (x86) dynamic libraries used by it.

2277

2278

@itemize

2279

2280

@item On x86, you can just try to launch any process by using the native

2281

libraries:

2282

2283

@example

2284

qemu-i386 -L / /bin/ls

2285

@end example

2286

2287

@code{-L /} tells that the x86 dynamic linker must be searched with a

2288

@file{/} prefix.

2289

2290

@item Since QEMU is also a linux process, you can launch qemu with

2291

qemu (NOTE: you can only do that if you compiled QEMU from the sources):

2292

2293

@example

2294

qemu-i386 -L / qemu-i386 -L / /bin/ls

2295

@end example

2296

2297

@item On non x86 CPUs, you need first to download at least an x86 glibc

2298

(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that

2299

@code{LD_LIBRARY_PATH} is not set:

2300

2301

@example

2302

unset LD_LIBRARY_PATH

2303

@end example

2304

2305

Then you can launch the precompiled @file{ls} x86 executable:

2306

2307

@example

2308

qemu-i386 tests/i386/ls

2309

@end example

2310

You can look at @file{scripts/qemu-binfmt-conf.sh} so that

2311

QEMU is automatically launched by the Linux kernel when you try to

2312

launch x86 executables. It requires the @code{binfmt_misc} module in the

2313

Linux kernel.

2314

2315

@item The x86 version of QEMU is also included. You can try weird things such as:

2316

@example

2317

qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \

2318

/usr/local/qemu-i386/bin/ls-i386

2319

@end example

2320

2321

@end itemize

2322

2323

@node Wine launch

2324

@subsection Wine launch

2325

2326

@itemize

2327

2328

@item Ensure that you have a working QEMU with the x86 glibc

2329

distribution (see previous section). In order to verify it, you must be

2330

able to do:

2331

2332

@example

2333

qemu-i386 /usr/local/qemu-i386/bin/ls-i386

2334

@end example

2335

2336

@item Download the binary x86 Wine install

2337

(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).

2338

2339

@item Configure Wine on your account. Look at the provided script

2340

@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous

2341

@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.

2342

2343

@item Then you can try the example @file{putty.exe}:

2344

2345

@example

2346

qemu-i386 /usr/local/qemu-i386/wine/bin/wine \

2347

/usr/local/qemu-i386/wine/c/Program\ Files/putty.exe

2348

@end example

2349

2350

@end itemize

2351

2352

@node Command line options

2353

@subsection Command line options

2354

2355

@example

2356

usage: qemu-i386 [-h] [-d] [-L path] [-s size] [-cpu model] [-g port] [-B offset] [-R size] program [arguments...]

2357

@end example

2358

2359

@table @option

2360

@item -h

2361

Print the help

2362

@item -L path

2363

Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)

2364

@item -s size

2365

Set the x86 stack size in bytes (default=524288)

2366

@item -cpu model

2367

Select CPU model (-cpu ? for list and additional feature selection)

2368

@item -ignore-environment

2369

Start with an empty environment. Without this option,

2370

the initial environment is a copy of the caller's environment.

2371

@item -E @var{var}=@var{value}

2372

Set environment @var{var} to @var{value}.

2373

@item -U @var{var}

2374

Remove @var{var} from the environment.

2375

@item -B offset

2376

Offset guest address by the specified number of bytes. This is useful when

2377

the address region required by guest applications is reserved on the host.

2378

This option is currently only supported on some hosts.

2379

@item -R size

2380

Pre-allocate a guest virtual address space of the given size (in bytes).

2381

"G", "M", and "k" suffixes may be used when specifying the size.

2382

@end table

2383

2384

Debug options:

2385

2386

@table @option

2387

@item -d

2388

Activate log (logfile=/tmp/qemu.log)

2389

@item -p pagesize

2390

Act as if the host page size was 'pagesize' bytes

2391

@item -g port

2392

Wait gdb connection to port

2393

@item -singlestep

2394

Run the emulation in single step mode.

2395

@end table

2396

2397

Environment variables:

2398

2399

@table @env

2400

@item QEMU_STRACE

2401

Print system calls and arguments similar to the 'strace' program

2402

(NOTE: the actual 'strace' program will not work because the user

2403

space emulator hasn't implemented ptrace). At the moment this is

2404

incomplete. All system calls that don't have a specific argument

2405

format are printed with information for six arguments. Many

2406

flag-style arguments don't have decoders and will show up as numbers.

2407

@end table

2408

2409

@node Other binaries

2410

@subsection Other binaries

2411

2412

@cindex user mode (Alpha)

2413

@command{qemu-alpha} TODO.

2414

2415

@cindex user mode (ARM)

2416

@command{qemu-armeb} TODO.

2417

2418

@cindex user mode (ARM)

2419

@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF

2420

binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB

2421

configurations), and arm-uclinux bFLT format binaries.

2422

2423

@cindex user mode (ColdFire)

2424

@cindex user mode (M68K)

2425

@command{qemu-m68k} is capable of running semihosted binaries using the BDM

2426

(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and

2427

coldfire uClinux bFLT format binaries.

2428

2429

The binary format is detected automatically.

2430

2431

@cindex user mode (Cris)

2432

@command{qemu-cris} TODO.

2433

2434

@cindex user mode (i386)

2435

@command{qemu-i386} TODO.

2436

@command{qemu-x86_64} TODO.

2437

2438

@cindex user mode (Microblaze)

2439

@command{qemu-microblaze} TODO.

2440

2441

@cindex user mode (MIPS)

2442

@command{qemu-mips} TODO.

2443

@command{qemu-mipsel} TODO.

2444

2445

@cindex user mode (PowerPC)

2446

@command{qemu-ppc64abi32} TODO.

2447

@command{qemu-ppc64} TODO.

2448

@command{qemu-ppc} TODO.

2449

2450

@cindex user mode (SH4)

2451

@command{qemu-sh4eb} TODO.

2452

@command{qemu-sh4} TODO.

2453

2454

@cindex user mode (SPARC)

2455

@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).

2456

2457

@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries

2458

(Sparc64 CPU, 32 bit ABI).

2459

2460

@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and

2461

SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).

2462

2463

@node Mac OS X/Darwin User space emulator

2464

@section Mac OS X/Darwin User space emulator

2465

2466

@menu

2467

* Mac OS X/Darwin Status::

2468

* Mac OS X/Darwin Quick Start::

2469

* Mac OS X/Darwin Command line options::

2470

@end menu

2471

2472

@node Mac OS X/Darwin Status

2473

@subsection Mac OS X/Darwin Status

2474

2475

@itemize @minus

2476

@item

2477

target x86 on x86: Most apps (Cocoa and Carbon too) works. [1]

2478

@item

2479

target PowerPC on x86: Not working as the ppc commpage can't be mapped (yet!)

2480

@item

2481

target PowerPC on PowerPC: Most apps (Cocoa and Carbon too) works. [1]

2482

@item

2483

target x86 on PowerPC: most utilities work. Cocoa and Carbon apps are not yet supported.

2484

@end itemize

2485

2486

[1] If you're host commpage can be executed by qemu.

2487

2488

@node Mac OS X/Darwin Quick Start

2489

@subsection Quick Start

2490

2491

In order to launch a Mac OS X/Darwin process, QEMU needs the process executable

2492

itself and all the target dynamic libraries used by it. If you don't have the FAT

2493

libraries (you're running Mac OS X/ppc) you'll need to obtain it from a Mac OS X

2494

CD or compile them by hand.

2495

2496

@itemize

2497

2498

@item On x86, you can just try to launch any process by using the native

2499

libraries:

2500

2501

@example

2502

qemu-i386 /bin/ls

2503

@end example

2504

2505

or to run the ppc version of the executable:

2506

2507

@example

2508

qemu-ppc /bin/ls

2509

@end example

2510

2511

@item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker)

2512

are installed:

2513

2514

@example

2515

qemu-i386 -L /opt/x86_root/ /bin/ls

2516

@end example

2517

2518

@code{-L /opt/x86_root/} tells that the dynamic linker (dyld) path is in

2519

@file{/opt/x86_root/usr/bin/dyld}.

2520

2521

@end itemize

2522

2523

@node Mac OS X/Darwin Command line options

2524

@subsection Command line options

2525

2526

@example

2527

usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]

2528

@end example

2529

2530

@table @option

2531

@item -h

2532

Print the help

2533

@item -L path

2534

Set the library root path (default=/)

2535

@item -s size

2536

Set the stack size in bytes (default=524288)

2537

@end table

2538

2539

Debug options:

2540

2541

@table @option

2542

@item -d

2543

Activate log (logfile=/tmp/qemu.log)

2544

@item -p pagesize

2545

Act as if the host page size was 'pagesize' bytes

2546

@item -singlestep

2547

Run the emulation in single step mode.

2548

@end table

2549

2550

@node BSD User space emulator

2551

@section BSD User space emulator

2552

2553

@menu

2554

* BSD Status::

2555

* BSD Quick Start::

2556

* BSD Command line options::

2557

@end menu

2558

2559

@node BSD Status

2560

@subsection BSD Status

2561

2562

@itemize @minus

2563

@item

2564

target Sparc64 on Sparc64: Some trivial programs work.

2565

@end itemize

2566

2567

@node BSD Quick Start

2568

@subsection Quick Start

2569

2570

In order to launch a BSD process, QEMU needs the process executable

2571

itself and all the target dynamic libraries used by it.

2572

2573

@itemize

2574

2575

@item On Sparc64, you can just try to launch any process by using the native

2576

libraries:

2577

2578

@example

2579

qemu-sparc64 /bin/ls

2580

@end example

2581

2582

@end itemize

2583

2584

@node BSD Command line options

2585

@subsection Command line options

2586

2587

@example

2588

usage: qemu-sparc64 [-h] [-d] [-L path] [-s size] [-bsd type] program [arguments...]

2589

@end example

2590

2591

@table @option

2592

@item -h

2593

Print the help

2594

@item -L path

2595

Set the library root path (default=/)

2596

@item -s size

2597

Set the stack size in bytes (default=524288)

2598

@item -ignore-environment

2599

Start with an empty environment. Without this option,

2600

the initial environment is a copy of the caller's environment.

2601

@item -E @var{var}=@var{value}

2602

Set environment @var{var} to @var{value}.

2603

@item -U @var{var}

2604

Remove @var{var} from the environment.

2605

@item -bsd type

2606

Set the type of the emulated BSD Operating system. Valid values are

2607

FreeBSD, NetBSD and OpenBSD (default).

2608

@end table

2609

2610

Debug options:

2611

2612

@table @option

2613

@item -d

2614

Activate log (logfile=/tmp/qemu.log)

2615

@item -p pagesize

2616

Act as if the host page size was 'pagesize' bytes

2617

@item -singlestep

2618

Run the emulation in single step mode.

2619

@end table

2620

2621

@node compilation

2622

@chapter Compilation from the sources

2623

2624

@menu

2625

* Linux/Unix::

2626

* Windows::

2627

* Cross compilation for Windows with Linux::

2628

* Mac OS X::

2629

* Make targets::

2630

@end menu

2631

2632

@node Linux/Unix

2633

@section Linux/Unix

2634

2635

@subsection Compilation

2636

2637

First you must decompress the sources:

2638

@example

2639

cd /tmp

2640

tar zxvf qemu-x.y.z.tar.gz

2641

cd qemu-x.y.z

2642

@end example

2643

2644

Then you configure QEMU and build it (usually no options are needed):

2645

@example

2646

./configure

2647

make

2648

@end example

2649

2650

Then type as root user:

2651

@example

2652

make install

2653

@end example

2654

to install QEMU in @file{/usr/local}.

2655

2656

@node Windows

2657

@section Windows

2658

2659

@itemize

2660

@item Install the current versions of MSYS and MinGW from

2661

@url{http://www.mingw.org/}. You can find detailed installation

2662

instructions in the download section and the FAQ.

2663

2664

@item Download

2665

the MinGW development library of SDL 1.2.x

2666

(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from

2667

@url{http://www.libsdl.org}. Unpack it in a temporary place and

2668

edit the @file{sdl-config} script so that it gives the

2669

correct SDL directory when invoked.

2670

2671

@item Install the MinGW version of zlib and make sure

2672

@file{zlib.h} and @file{libz.dll.a} are in

2673

MinGW's default header and linker search paths.

2674

2675

@item Extract the current version of QEMU.

2676

2677

@item Start the MSYS shell (file @file{msys.bat}).

2678

2679

@item Change to the QEMU directory. Launch @file{./configure} and

2680

@file{make}. If you have problems using SDL, verify that

2681

@file{sdl-config} can be launched from the MSYS command line.

2682

2683

@item You can install QEMU in @file{Program Files/Qemu} by typing

2684

@file{make install}. Don't forget to copy @file{SDL.dll} in

2685

@file{Program Files/Qemu}.

2686

2687

@end itemize

2688

2689

@node Cross compilation for Windows with Linux

2690

@section Cross compilation for Windows with Linux

2691

2692

@itemize

2693

@item

2694

Install the MinGW cross compilation tools available at

2695

@url{http://www.mingw.org/}.

2696

2697

@item Download

2698

the MinGW development library of SDL 1.2.x

2699

(@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from

2700

@url{http://www.libsdl.org}. Unpack it in a temporary place and

2701

edit the @file{sdl-config} script so that it gives the

2702

correct SDL directory when invoked. Set up the @code{PATH} environment

2703

variable so that @file{sdl-config} can be launched by

2704

the QEMU configuration script.

2705

2706

@item Install the MinGW version of zlib and make sure

2707

@file{zlib.h} and @file{libz.dll.a} are in

2708

MinGW's default header and linker search paths.

2709

2710

@item

2711

Configure QEMU for Windows cross compilation:

2712

@example

2713

PATH=/usr/i686-pc-mingw32/sys-root/mingw/bin:$PATH ./configure --cross-prefix='i686-pc-mingw32-'

2714

@end example

2715

The example assumes @file{sdl-config} is installed under @file{/usr/i686-pc-mingw32/sys-root/mingw/bin} and

2716

MinGW cross compilation tools have names like @file{i686-pc-mingw32-gcc} and @file{i686-pc-mingw32-strip}.

2717

We set the @code{PATH} environment variable to ensure the MinGW version of @file{sdl-config} is used and

2718

use --cross-prefix to specify the name of the cross compiler.

2719

You can also use --prefix to set the Win32 install path which defaults to @file{c:/Program Files/Qemu}.

2720

2721

Under Fedora Linux, you can run:

2722

@example

2723

yum -y install mingw32-gcc mingw32-SDL mingw32-zlib

2724

@end example

2725

to get a suitable cross compilation environment.

2726

2727

@item You can install QEMU in the installation directory by typing

2728

@code{make install}. Don't forget to copy @file{SDL.dll} and @file{zlib1.dll} into the

2729

installation directory.

2730

2731

@end itemize

2732

2733

Wine can be used to launch the resulting qemu.exe compiled for Win32.

2734

2735

@node Mac OS X

2736

@section Mac OS X

2737

2738

The Mac OS X patches are not fully merged in QEMU, so you should look

2739

at the QEMU mailing list archive to have all the necessary

2740

information.

2741

2742

@node Make targets

2743

@section Make targets

2744

2745

@table @code

2746

2747

@item make

2748

@item make all

2749

Make everything which is typically needed.

2750

2751

@item install

2752

TODO

2753

2754

@item install-doc

2755

TODO

2756

2757

@item make clean

2758

Remove most files which were built during make.

2759

2760

@item make distclean

2761

Remove everything which was built during make.

2762

2763

@item make dvi

2764

@item make html

2765

@item make info

2766

@item make pdf

2767

Create documentation in dvi, html, info or pdf format.

2768

2769

@item make cscope

2770

TODO

2771

2772

@item make defconfig

2773

(Re-)create some build configuration files.

2774

User made changes will be overwritten.

2775

2776

@item tar

2777

@item tarbin

2778

TODO

2779

2780

@end table

2781

2782

@node License

2783

@appendix License

2784

2785

QEMU is a trademark of Fabrice Bellard.

2786

2787

QEMU is released under the GNU General Public License (TODO: add link).

2788

Parts of QEMU have specific licenses, see file LICENSE.

2789

2790

TODO (refer to file LICENSE, include it, include the GPL?)

2791

2792

@node Index

2793

@appendix Index

2794

@menu

2795

* Concept Index::

2796

* Function Index::

2797

* Keystroke Index::

2798

* Program Index::

2799

* Data Type Index::

2800

* Variable Index::

2801

@end menu

2802

2803

@node Concept Index

2804

@section Concept Index

2805

This is the main index. Should we combine all keywords in one index? TODO

2806

@printindex cp

2807

2808

@node Function Index

2809

@section Function Index

2810

This index could be used for command line options and monitor functions.

2811

@printindex fn

2812

2813

@node Keystroke Index

2814

@section Keystroke Index

2815

2816

This is a list of all keystrokes which have a special function

2817

in system emulation.

2818

2819

@printindex ky

2820

2821

@node Program Index

2822

@section Program Index

2823

@printindex pg

2824

2825

@node Data Type Index

2826

@section Data Type Index

2827

2828

This index could be used for qdev device names and options.

2829

2830

@printindex tp

2831

2832

@node Variable Index

2833

@section Variable Index

2834

@printindex vr

2835

2836

@bye

Older »