summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-07-17 08:21:39 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-07-22 09:19:25 +0100
commit88c188f9905f30361c67d51fcf989b30ebdb8bbc (patch)
tree231c4fa323f3d596fde8eb688c6cb145d0e7a7d8
parentda066d8cdffefee2d3ddd92e14a5b4091f3d4967 (diff)
downloadpoky-88c188f9905f30361c67d51fcf989b30ebdb8bbc.tar.gz
ref-manual: Added QEMU reference section
Fixes [YOCTO #11630] The dev-manual had a section on QEMU that combined a lot of reference information and usage information. I took the reference information out and moved it to the ref-manual into a new section in the second chapter, "Using YP". (From yocto-docs rev: 188596c576e357925383d0cc3bd2b0cdf41926ec) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/ref-manual/usingpoky.xml281
1 files changed, 281 insertions, 0 deletions
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index c81818840a..5517a7541c 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -1049,6 +1049,287 @@
1049 </section> 1049 </section>
1050</section> 1050</section>
1051 1051
1052<section id='ref-quick-emulator-qemu'>
1053 <title>Quick EMUlator (QEMU)</title>
1054
1055 <para>
1056 The Yocto Project uses an implementation of the Quick EMUlator (QEMU)
1057 Open Source project as part of the Yocto Project development "tool
1058 set".
1059 <note>
1060 This implementation is not the same as QEMU in general.
1061 </note>
1062 This section provides a brief reference for the Yocto Project
1063 implementation of QEMU.
1064 </para>
1065
1066 <para>
1067 For official information and documentation on QEMU in general, see the
1068 following references:
1069 <itemizedlist>
1070 <listitem><para>
1071 <emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis>
1072 The official website for the QEMU Open Source project.
1073 </para></listitem>
1074 <listitem><para>
1075 <emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis>
1076 The QEMU user manual.
1077 </para></listitem>
1078 </itemizedlist>
1079 </para>
1080
1081 <para>
1082 For information on how to use the Yocto Project implementation of
1083 QEMU, see the
1084 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
1085 chapter in the Yocto Project Development Manual.
1086 </para>
1087
1088 <section id='qemu-availability'>
1089 <title>QEMU Availability</title>
1090
1091 <para>
1092 QEMU is made available with the Yocto Project a number of ways.
1093 One method is to install a Software Development Kit (SDK).
1094 For more information on how to make sure you have
1095 QEMU available, see
1096 "<ulink url='&YOCTO_DOCS_SDK_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>"
1097 section in the Yocto Project Software Development Kit (SDK)
1098 Developer's Guide.
1099 </para>
1100 </section>
1101
1102 <section id='qemu-command-line-syntax'>
1103 <title>QEMU Command-Line Syntax</title>
1104
1105 <para>
1106 The basic <filename>runqemu</filename> command syntax is as
1107 follows:
1108 <literallayout class='monospaced'>
1109 $ runqemu [<replaceable>option</replaceable> ] [...]
1110 </literallayout>
1111 Based on what you provide on the command line,
1112 <filename>runqemu</filename> does a good job of figuring out what
1113 you are trying to do.
1114 For example, by default, QEMU looks for the most recently built
1115 image according to the timestamp when it needs to look for an
1116 image.
1117 Minimally, through the use of options, you must provide either
1118 a machine name, a virtual machine image
1119 (<filename>*.vmdk</filename>), or a kernel image
1120 (<filename>*.bin</filename>).
1121 </para>
1122
1123 <para>
1124 Following is the command-line help output for the
1125 <filename>runqemu</filename> command:
1126 <literallayout class='monospaced'>
1127 $ runqemu --help
1128
1129 Usage: you can run this script with any valid combination
1130 of the following environment variables (in any order):
1131 KERNEL - the kernel image file to use
1132 ROOTFS - the rootfs image file or nfsroot directory to use
1133 MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
1134 Simplified QEMU command-line options can be passed with:
1135 nographic - disable video console
1136 serial - enable a serial console on /dev/ttyS0
1137 slirp - enable user networking, no root privileges is required
1138 kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
1139 kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
1140 publicvnc - enable a VNC server open to all hosts
1141 audio - enable audio
1142 [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
1143 tcpserial=&lt;port&gt; - specify tcp serial port number
1144 biosdir=&lt;dir&gt; - specify custom bios dir
1145 biosfilename=&lt;filename&gt; - specify bios filename
1146 qemuparams=&lt;xyz&gt; - specify custom parameters to QEMU
1147 bootparams=&lt;xyz&gt; - specify custom kernel parameters during boot
1148 help, -h, --help: print this text
1149
1150 Examples:
1151 runqemu
1152 runqemu qemuarm
1153 runqemu tmp/deploy/images/qemuarm
1154 runqemu tmp/deploy/images/qemux86/&lt;qemuboot.conf&gt;
1155 runqemu qemux86-64 core-image-sato ext4
1156 runqemu qemux86-64 wic-image-minimal wic
1157 runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
1158 runqemu qemux86 iso/hddimg/vmdk/qcow2/vdi/ramfs/cpio.gz...
1159 runqemu qemux86 qemuparams="-m 256"
1160 runqemu qemux86 bootparams="psplash=false"
1161 runqemu path/to/&lt;image&gt;-&lt;machine&gt;.vmdk
1162 runqemu path/to/&lt;image&gt;-&lt;machine&gt;.wic
1163 </literallayout>
1164 </para>
1165 </section>
1166
1167 <section id='runqemu-command-line-options'>
1168 <title><filename>runqemu</filename> Command-Line Options</title>
1169
1170 <para>
1171 Following is a description of <filename>runqemu</filename>
1172 options you can provide on the command line:
1173 <note><title>Tip</title>
1174 If you do provide some "illegal" option combination or perhaps
1175 you do not provide enough in the way of options,
1176 <filename>runqemu</filename> provides appropriate error
1177 messaging to help you correct the problem.
1178 </note>
1179 <itemizedlist>
1180 <listitem><para>
1181 <replaceable>QEMUARCH</replaceable>:
1182 The QEMU machine architecture, which must be "qemuarm",
1183 "qemuarm64", "qemumips", "qemumips64", "qemuppc",
1184 "qemux86", or "qemux86-64".
1185 </para></listitem>
1186 <listitem><para>
1187 <filename><replaceable>VM</replaceable></filename>:
1188 The virtual machine image, which must be a
1189 <filename>.vmdk</filename> file.
1190 Use this option when you want to boot a
1191 <filename>.vmdk</filename> image.
1192 The image filename you provide must contain one of the
1193 following strings: "qemux86-64", "qemux86", "qemuarm",
1194 "qemumips64", "qemumips", "qemuppc", or "qemush4".
1195 </para></listitem>
1196 <listitem><para>
1197 <replaceable>ROOTFS</replaceable>:
1198 A root filesystem that has one of the following
1199 filetype extensions: "ext2", "ext3", "ext4", "jffs2",
1200 "nfs", or "btrfs".
1201 If the filename you provide for this option uses “nfs”, it
1202 must provide an explicit root filesystem path.
1203 </para></listitem>
1204 <listitem><para>
1205 <replaceable>KERNEL</replaceable>:
1206 A kernel image, which is a <filename>.bin</filename> file.
1207 When you provide a <filename>.bin</filename> file,
1208 <filename>runqemu</filename> detects it and assumes the
1209 file is a kernel image.
1210 </para></listitem>
1211 <listitem><para>
1212 <replaceable>MACHINE</replaceable>:
1213 The architecture of the QEMU machine, which must be one
1214 of the following: "qemux86",
1215 "qemux86", "qemux86-64", "qemuarm", "qemuarm64",
1216 "qemumips", “qemumips64", or "qemuppc".
1217 The <replaceable>MACHINE</replaceable> and
1218 <replaceable>QEMUARCH</replaceable> options are basically
1219 identical.
1220 If you do not provide a <replaceable>MACHINE</replaceable>
1221 option, <filename>runqemu</filename> tries to determine
1222 it based on other options.
1223 </para></listitem>
1224 <listitem><para>
1225 <filename>ramfs</filename>:
1226 Indicates you are booting an initial RAM disk (initramfs)
1227 image, which means the <filename>FSTYPE</filename> is
1228 <filename>cpio.gz</filename>.
1229 </para></listitem>
1230 <listitem><para>
1231 <filename>iso</filename>:
1232 Indicates you are booting an ISO image, which means the
1233 <filename>FSTYPE</filename> is
1234 <filename>.iso</filename>.
1235 </para></listitem>
1236 <listitem><para>
1237 <filename>nographic</filename>:
1238 Disables the video console, which sets the console to
1239 "ttys0".
1240 </para></listitem>
1241 <listitem><para>
1242 <filename>serial</filename>:
1243 Enables a serial console on
1244 <filename>/dev/ttyS0</filename>.
1245 </para></listitem>
1246 <listitem><para>
1247 <filename>biosdir</filename>:
1248 Establishes a custom directory for BIOS, VGA BIOS and
1249 keymaps.
1250 </para></listitem>
1251 <listitem><para>
1252 <filename>biosfilename</filename>:
1253 Establishes a custom BIOS name.
1254 </para></listitem>
1255 <listitem><para>
1256 <filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>:
1257 Specifies custom QEMU parameters.
1258 Use this option to pass options other than the simple
1259 "kvm" and "serial" options.
1260 </para></listitem>
1261 <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>:
1262 Specifies custom boot parameters for the kernel.
1263 </para></listitem>
1264 <listitem><para>
1265 <filename>audio</filename>:
1266 Enables audio in QEMU.
1267 The <replaceable>MACHINE</replaceable> option must be
1268 either "qemux86" or "qemux86-64" in order for audio to be
1269 enabled.
1270 Additionally, the <filename>snd_intel8x0</filename>
1271 or <filename>snd_ens1370</filename> driver must be
1272 installed in linux guest.
1273 </para></listitem>
1274 <listitem><para>
1275 <filename>slirp</filename>:
1276 Enables "slirp" networking, which is a different way
1277 of networking that does not need root access
1278 but also is not as easy to use or comprehensive
1279 as the default.
1280 </para></listitem>
1281 <listitem><para id='kvm-cond'>
1282 <filename>kvm</filename>:
1283 Enables KVM when running "qemux86" or "qemux86-64"
1284 QEMU architectures.
1285 For KVM to work, all the following conditions must be met:
1286 <itemizedlist>
1287 <listitem><para>
1288 Your <replaceable>MACHINE</replaceable> must be either
1289qemux86" or "qemux86-64".
1290 </para></listitem>
1291 <listitem><para>
1292 Your build host has to have the KVM modules
1293 installed, which are
1294 <filename>/dev/kvm</filename>.
1295 </para></listitem>
1296 <listitem><para>
1297 The build host <filename>/dev/kvm</filename>
1298 directory has to be both writable and readable.
1299 </para></listitem>
1300 </itemizedlist>
1301 </para></listitem>
1302 <listitem><para>
1303 <filename>kvm-vhost</filename>:
1304 Enables KVM with VHOST support when running "qemux86"
1305 or "qemux86-64" QEMU architectures.
1306 For KVM with VHOST to work, the following conditions must
1307 be met:
1308 <itemizedlist>
1309 <listitem><para>
1310 <link linkend='kvm-cond'>kvm</link> option
1311 conditions must be met.
1312 </para></listitem>
1313 <listitem><para>
1314 Your build host has to have virtio net device, which
1315 are <filename>/dev/vhost-net</filename>.
1316 </para></listitem>
1317 <listitem><para>
1318 The build host <filename>/dev/vhost-net</filename>
1319 directory has to be either readable or writable
1320 and “slirp-enabled”.
1321 </para></listitem>
1322 </itemizedlist>
1323 </para></listitem>
1324 <listitem><para>
1325 <filename>publicvnc</filename>:
1326 Enables a VNC server open to all hosts.
1327 </para></listitem>
1328 </itemizedlist>
1329 </para>
1330 </section>
1331</section>
1332
1052<section id='maintaining-build-output-quality'> 1333<section id='maintaining-build-output-quality'>
1053 <title>Maintaining Build Output Quality</title> 1334 <title>Maintaining Build Output Quality</title>
1054 1335