/
qemu-options.hx
5186 lines (4220 loc) · 216 KB
/
qemu-options.hx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
HXCOMM Use DEFHEADING() to define headings in both help text and rST.
HXCOMM Text between SRST and ERST is copied to the rST version and
HXCOMM discarded from C version.
HXCOMM DEF(option, HAS_ARG/0, opt_enum, opt_help, arch_mask) is used to
HXCOMM construct option structures, enums and help message for specified
HXCOMM architectures.
HXCOMM HXCOMM can be used for comments, discarded from both rST and C.
DEFHEADING(Standard options:)
DEF("help", 0, QEMU_OPTION_h,
"-h or -help display this help and exit\n", QEMU_ARCH_ALL)
SRST
``-h``
Display help and exit
ERST
DEF("version", 0, QEMU_OPTION_version,
"-version display version information and exit\n", QEMU_ARCH_ALL)
SRST
``-version``
Display version information and exit
ERST
DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
"-machine [type=]name[,prop[=value][,...]]\n"
" selects emulated machine ('-machine help' for list)\n"
" property accel=accel1[:accel2[:...]] selects accelerator\n"
" supported accelerators are kvm, xen, hax, hvf, whpx or tcg (default: tcg)\n"
" vmport=on|off|auto controls emulation of vmport (default: auto)\n"
" dump-guest-core=on|off include guest memory in a core dump (default=on)\n"
" mem-merge=on|off controls memory merge support (default: on)\n"
" aes-key-wrap=on|off controls support for AES key wrapping (default=on)\n"
" dea-key-wrap=on|off controls support for DEA key wrapping (default=on)\n"
" suppress-vmdesc=on|off disables self-describing migration (default=off)\n"
" nvdimm=on|off controls NVDIMM support (default=off)\n"
" memory-encryption=@var{} memory encryption object to use (default=none)\n"
" hmat=on|off controls ACPI HMAT support (default=off)\n"
" memory-backend='backend-id' specifies explicitly provided backend for main RAM (default=none)\n",
QEMU_ARCH_ALL)
SRST
``-machine [type=]name[,prop=value[,...]]``
Select the emulated machine by name. Use ``-machine help`` to list
available machines.
For architectures which aim to support live migration compatibility
across releases, each release will introduce a new versioned machine
type. For example, the 2.8.0 release introduced machine types
"pc-i440fx-2.8" and "pc-q35-2.8" for the x86\_64/i686 architectures.
To allow live migration of guests from QEMU version 2.8.0, to QEMU
version 2.9.0, the 2.9.0 version must support the "pc-i440fx-2.8"
and "pc-q35-2.8" machines too. To allow users live migrating VMs to
skip multiple intermediate releases when upgrading, new releases of
QEMU will support machine types from many previous versions.
Supported machine properties are:
``accel=accels1[:accels2[:...]]``
This is used to enable an accelerator. Depending on the target
architecture, kvm, xen, hax, hvf, whpx or tcg can be available.
By default, tcg is used. If there is more than one accelerator
specified, the next one is used if the previous one fails to
initialize.
``vmport=on|off|auto``
Enables emulation of VMWare IO port, for vmmouse etc. auto says
to select the value based on accel. For accel=xen the default is
off otherwise the default is on.
``dump-guest-core=on|off``
Include guest memory in a core dump. The default is on.
``mem-merge=on|off``
Enables or disables memory merge support. This feature, when
supported by the host, de-duplicates identical memory pages
among VMs instances (enabled by default).
``aes-key-wrap=on|off``
Enables or disables AES key wrapping support on s390-ccw hosts.
This feature controls whether AES wrapping keys will be created
to allow execution of AES cryptographic functions. The default
is on.
``dea-key-wrap=on|off``
Enables or disables DEA key wrapping support on s390-ccw hosts.
This feature controls whether DEA wrapping keys will be created
to allow execution of DEA cryptographic functions. The default
is on.
``nvdimm=on|off``
Enables or disables NVDIMM support. The default is off.
``memory-encryption=``
Memory encryption object to use. The default is none.
``hmat=on|off``
Enables or disables ACPI Heterogeneous Memory Attribute Table
(HMAT) support. The default is off.
``memory-backend='id'``
An alternative to legacy ``-mem-path`` and ``mem-prealloc`` options.
Allows to use a memory backend as main RAM.
For example:
::
-object memory-backend-file,id=pc.ram,size=512M,mem-path=/hugetlbfs,prealloc=on,share=on
-machine memory-backend=pc.ram
-m 512M
Migration compatibility note:
a) as backend id one shall use value of 'default-ram-id', advertised by
machine type (available via ``query-machines`` QMP command), if migration
to/from old QEMU (<5.0) is expected.
b) for machine types 4.0 and older, user shall
use ``x-use-canonical-path-for-ramblock-id=off`` backend option
if migration to/from old QEMU (<5.0) is expected.
For example:
::
-object memory-backend-ram,id=pc.ram,size=512M,x-use-canonical-path-for-ramblock-id=off
-machine memory-backend=pc.ram
-m 512M
ERST
HXCOMM Deprecated by -machine
DEF("M", HAS_ARG, QEMU_OPTION_M, "", QEMU_ARCH_ALL)
DEF("cpu", HAS_ARG, QEMU_OPTION_cpu,
"-cpu cpu select CPU ('-cpu help' for list)\n", QEMU_ARCH_ALL)
SRST
``-cpu model``
Select CPU model (``-cpu help`` for list and additional feature
selection)
ERST
DEF("accel", HAS_ARG, QEMU_OPTION_accel,
"-accel [accel=]accelerator[,prop[=value][,...]]\n"
" select accelerator (kvm, xen, hax, hvf, whpx or tcg; use 'help' for a list)\n"
" igd-passthru=on|off (enable Xen integrated Intel graphics passthrough, default=off)\n"
" kernel-irqchip=on|off|split controls accelerated irqchip support (default=on)\n"
" kvm-shadow-mem=size of KVM shadow MMU in bytes\n"
" split-wx=on|off (enable TCG split w^x mapping)\n"
" tb-size=n (TCG translation block cache size)\n"
" thread=single|multi (enable multi-threaded TCG)\n", QEMU_ARCH_ALL)
SRST
``-accel name[,prop=value[,...]]``
This is used to enable an accelerator. Depending on the target
architecture, kvm, xen, hax, hvf, whpx or tcg can be available. By
default, tcg is used. If there is more than one accelerator
specified, the next one is used if the previous one fails to
initialize.
``igd-passthru=on|off``
When Xen is in use, this option controls whether Intel
integrated graphics devices can be passed through to the guest
(default=off)
``kernel-irqchip=on|off|split``
Controls KVM in-kernel irqchip support. The default is full
acceleration of the interrupt controllers. On x86, split irqchip
reduces the kernel attack surface, at a performance cost for
non-MSI interrupts. Disabling the in-kernel irqchip completely
is not recommended except for debugging purposes.
``kvm-shadow-mem=size``
Defines the size of the KVM shadow MMU.
``split-wx=on|off``
Controls the use of split w^x mapping for the TCG code generation
buffer. Some operating systems require this to be enabled, and in
such a case this will default on. On other operating systems, this
will default off, but one may enable this for testing or debugging.
``tb-size=n``
Controls the size (in MiB) of the TCG translation block cache.
``thread=single|multi``
Controls number of TCG threads. When the TCG is multi-threaded
there will be one thread per vCPU therefor taking advantage of
additional host cores. The default is to enable multi-threading
where both the back-end and front-ends support it and no
incompatible TCG features have been enabled (e.g.
icount/replay).
ERST
DEF("smp", HAS_ARG, QEMU_OPTION_smp,
"-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,dies=dies][,sockets=sockets]\n"
" set the number of CPUs to 'n' [default=1]\n"
" maxcpus= maximum number of total cpus, including\n"
" offline CPUs for hotplug, etc\n"
" cores= number of CPU cores on one socket (for PC, it's on one die)\n"
" threads= number of threads on one CPU core\n"
" dies= number of CPU dies on one socket (for PC only)\n"
" sockets= number of discrete sockets in the system\n",
QEMU_ARCH_ALL)
SRST
``-smp [cpus=]n[,cores=cores][,threads=threads][,dies=dies][,sockets=sockets][,maxcpus=maxcpus]``
Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs
are supported. On Sparc32 target, Linux limits the number of usable
CPUs to 4. For the PC target, the number of cores per die, the
number of threads per cores, the number of dies per packages and the
total number of sockets can be specified. Missing values will be
computed. If any on the three values is given, the total number of
CPUs n can be omitted. maxcpus specifies the maximum number of
hotpluggable CPUs.
ERST
DEF("numa", HAS_ARG, QEMU_OPTION_numa,
"-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
"-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=node]\n"
"-numa dist,src=source,dst=destination,val=distance\n"
"-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]\n"
"-numa hmat-lb,initiator=node,target=node,hierarchy=memory|first-level|second-level|third-level,data-type=access-latency|read-latency|write-latency[,latency=lat][,bandwidth=bw]\n"
"-numa hmat-cache,node-id=node,size=size,level=level[,associativity=none|direct|complex][,policy=none|write-back|write-through][,line=size]\n",
QEMU_ARCH_ALL)
SRST
``-numa node[,mem=size][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
\
``-numa node[,memdev=id][,cpus=firstcpu[-lastcpu]][,nodeid=node][,initiator=initiator]``
\
``-numa dist,src=source,dst=destination,val=distance``
\
``-numa cpu,node-id=node[,socket-id=x][,core-id=y][,thread-id=z]``
\
``-numa hmat-lb,initiator=node,target=node,hierarchy=hierarchy,data-type=tpye[,latency=lat][,bandwidth=bw]``
\
``-numa hmat-cache,node-id=node,size=size,level=level[,associativity=str][,policy=str][,line=size]``
Define a NUMA node and assign RAM and VCPUs to it. Set the NUMA
distance from a source node to a destination node. Set the ACPI
Heterogeneous Memory Attributes for the given nodes.
Legacy VCPU assignment uses '\ ``cpus``\ ' option where firstcpu and
lastcpu are CPU indexes. Each '\ ``cpus``\ ' option represent a
contiguous range of CPU indexes (or a single VCPU if lastcpu is
omitted). A non-contiguous set of VCPUs can be represented by
providing multiple '\ ``cpus``\ ' options. If '\ ``cpus``\ ' is
omitted on all nodes, VCPUs are automatically split between them.
For example, the following option assigns VCPUs 0, 1, 2 and 5 to a
NUMA node:
::
-numa node,cpus=0-2,cpus=5
'\ ``cpu``\ ' option is a new alternative to '\ ``cpus``\ ' option
which uses '\ ``socket-id|core-id|thread-id``\ ' properties to
assign CPU objects to a node using topology layout properties of
CPU. The set of properties is machine specific, and depends on used
machine type/'\ ``smp``\ ' options. It could be queried with
'\ ``hotpluggable-cpus``\ ' monitor command. '\ ``node-id``\ '
property specifies node to which CPU object will be assigned, it's
required for node to be declared with '\ ``node``\ ' option before
it's used with '\ ``cpu``\ ' option.
For example:
::
-M pc \
-smp 1,sockets=2,maxcpus=2 \
-numa node,nodeid=0 -numa node,nodeid=1 \
-numa cpu,node-id=0,socket-id=0 -numa cpu,node-id=1,socket-id=1
Legacy '\ ``mem``\ ' assigns a given RAM amount to a node (not supported
for 5.1 and newer machine types). '\ ``memdev``\ ' assigns RAM from
a given memory backend device to a node. If '\ ``mem``\ ' and
'\ ``memdev``\ ' are omitted in all nodes, RAM is split equally between them.
'\ ``mem``\ ' and '\ ``memdev``\ ' are mutually exclusive.
Furthermore, if one node uses '\ ``memdev``\ ', all of them have to
use it.
'\ ``initiator``\ ' is an additional option that points to an
initiator NUMA node that has best performance (the lowest latency or
largest bandwidth) to this NUMA node. Note that this option can be
set only when the machine property 'hmat' is set to 'on'.
Following example creates a machine with 2 NUMA nodes, node 0 has
CPU. node 1 has only memory, and its initiator is node 0. Note that
because node 0 has CPU, by default the initiator of node 0 is itself
and must be itself.
::
-machine hmat=on \
-m 2G,slots=2,maxmem=4G \
-object memory-backend-ram,size=1G,id=m0 \
-object memory-backend-ram,size=1G,id=m1 \
-numa node,nodeid=0,memdev=m0 \
-numa node,nodeid=1,memdev=m1,initiator=0 \
-smp 2,sockets=2,maxcpus=2 \
-numa cpu,node-id=0,socket-id=0 \
-numa cpu,node-id=0,socket-id=1
source and destination are NUMA node IDs. distance is the NUMA
distance from source to destination. The distance from a node to
itself is always 10. If any pair of nodes is given a distance, then
all pairs must be given distances. Although, when distances are only
given in one direction for each pair of nodes, then the distances in
the opposite directions are assumed to be the same. If, however, an
asymmetrical pair of distances is given for even one node pair, then
all node pairs must be provided distance values for both directions,
even when they are symmetrical. When a node is unreachable from
another node, set the pair's distance to 255.
Note that the -``numa`` option doesn't allocate any of the specified
resources, it just assigns existing resources to NUMA nodes. This
means that one still has to use the ``-m``, ``-smp`` options to
allocate RAM and VCPUs respectively.
Use '\ ``hmat-lb``\ ' to set System Locality Latency and Bandwidth
Information between initiator and target NUMA nodes in ACPI
Heterogeneous Attribute Memory Table (HMAT). Initiator NUMA node can
create memory requests, usually it has one or more processors.
Target NUMA node contains addressable memory.
In '\ ``hmat-lb``\ ' option, node are NUMA node IDs. hierarchy is
the memory hierarchy of the target NUMA node: if hierarchy is
'memory', the structure represents the memory performance; if
hierarchy is 'first-level\|second-level\|third-level', this
structure represents aggregated performance of memory side caches
for each domain. type of 'data-type' is type of data represented by
this structure instance: if 'hierarchy' is 'memory', 'data-type' is
'access\|read\|write' latency or 'access\|read\|write' bandwidth of
the target memory; if 'hierarchy' is
'first-level\|second-level\|third-level', 'data-type' is
'access\|read\|write' hit latency or 'access\|read\|write' hit
bandwidth of the target memory side cache.
lat is latency value in nanoseconds. bw is bandwidth value, the
possible value and units are NUM[M\|G\|T], mean that the bandwidth
value are NUM byte per second (or MB/s, GB/s or TB/s depending on
used suffix). Note that if latency or bandwidth value is 0, means
the corresponding latency or bandwidth information is not provided.
In '\ ``hmat-cache``\ ' option, node-id is the NUMA-id of the memory
belongs. size is the size of memory side cache in bytes. level is
the cache level described in this structure, note that the cache
level 0 should not be used with '\ ``hmat-cache``\ ' option.
associativity is the cache associativity, the possible value is
'none/direct(direct-mapped)/complex(complex cache indexing)'. policy
is the write policy. line is the cache Line size in bytes.
For example, the following options describe 2 NUMA nodes. Node 0 has
2 cpus and a ram, node 1 has only a ram. The processors in node 0
access memory in node 0 with access-latency 5 nanoseconds,
access-bandwidth is 200 MB/s; The processors in NUMA node 0 access
memory in NUMA node 1 with access-latency 10 nanoseconds,
access-bandwidth is 100 MB/s. And for memory side cache information,
NUMA node 0 and 1 both have 1 level memory cache, size is 10KB,
policy is write-back, the cache Line size is 8 bytes:
::
-machine hmat=on \
-m 2G \
-object memory-backend-ram,size=1G,id=m0 \
-object memory-backend-ram,size=1G,id=m1 \
-smp 2 \
-numa node,nodeid=0,memdev=m0 \
-numa node,nodeid=1,memdev=m1,initiator=0 \
-numa cpu,node-id=0,socket-id=0 \
-numa cpu,node-id=0,socket-id=1 \
-numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-latency,latency=5 \
-numa hmat-lb,initiator=0,target=0,hierarchy=memory,data-type=access-bandwidth,bandwidth=200M \
-numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-latency,latency=10 \
-numa hmat-lb,initiator=0,target=1,hierarchy=memory,data-type=access-bandwidth,bandwidth=100M \
-numa hmat-cache,node-id=0,size=10K,level=1,associativity=direct,policy=write-back,line=8 \
-numa hmat-cache,node-id=1,size=10K,level=1,associativity=direct,policy=write-back,line=8
ERST
DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd,
"-add-fd fd=fd,set=set[,opaque=opaque]\n"
" Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL)
SRST
``-add-fd fd=fd,set=set[,opaque=opaque]``
Add a file descriptor to an fd set. Valid options are:
``fd=fd``
This option defines the file descriptor of which a duplicate is
added to fd set. The file descriptor cannot be stdin, stdout, or
stderr.
``set=set``
This option defines the ID of the fd set to add the file
descriptor to.
``opaque=opaque``
This option defines a free-form string that can be used to
describe fd.
You can open an image using pre-opened file descriptors from an fd
set:
.. parsed-literal::
|qemu_system| \\
-add-fd fd=3,set=2,opaque="rdwr:/path/to/file" \\
-add-fd fd=4,set=2,opaque="rdonly:/path/to/file" \\
-drive file=/dev/fdset/2,index=0,media=disk
ERST
DEF("set", HAS_ARG, QEMU_OPTION_set,
"-set group.id.arg=value\n"
" set <arg> parameter for item <id> of type <group>\n"
" i.e. -set drive.$id.file=/path/to/image\n", QEMU_ARCH_ALL)
SRST
``-set group.id.arg=value``
Set parameter arg for item id of type group
ERST
DEF("global", HAS_ARG, QEMU_OPTION_global,
"-global driver.property=value\n"
"-global driver=driver,property=property,value=value\n"
" set a global default for a driver property\n",
QEMU_ARCH_ALL)
SRST
``-global driver.prop=value``
\
``-global driver=driver,property=property,value=value``
Set default value of driver's property prop to value, e.g.:
.. parsed-literal::
|qemu_system_x86| -global ide-hd.physical_block_size=4096 disk-image.img
In particular, you can use this to set driver properties for devices
which are created automatically by the machine model. To create a
device which is not created automatically and set properties on it,
use -``device``.
-global driver.prop=value is shorthand for -global
driver=driver,property=prop,value=value. The longhand syntax works
even when driver contains a dot.
ERST
DEF("boot", HAS_ARG, QEMU_OPTION_boot,
"-boot [order=drives][,once=drives][,menu=on|off]\n"
" [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n"
" 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n"
" 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n"
" 'sp_time': the period that splash picture last if menu=on, unit is ms\n"
" 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n",
QEMU_ARCH_ALL)
SRST
``-boot [order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_timeout][,strict=on|off]``
Specify boot order drives as a string of drive letters. Valid drive
letters depend on the target architecture. The x86 PC uses: a, b
(floppy 1 and 2), c (first hard disk), d (first CD-ROM), n-p
(Etherboot from network adapter 1-4), hard disk boot is the default.
To apply a particular boot order only on the first startup, specify
it via ``once``. Note that the ``order`` or ``once`` parameter
should not be used together with the ``bootindex`` property of
devices, since the firmware implementations normally do not support
both at the same time.
Interactive boot menus/prompts can be enabled via ``menu=on`` as far
as firmware/BIOS supports them. The default is non-interactive boot.
A splash picture could be passed to bios, enabling user to show it
as logo, when option splash=sp\_name is given and menu=on, If
firmware/BIOS supports them. Currently Seabios for X86 system
support it. limitation: The splash file could be a jpeg file or a
BMP file in 24 BPP format(true color). The resolution should be
supported by the SVGA mode, so the recommended is 320x240, 640x480,
800x640.
A timeout could be passed to bios, guest will pause for rb\_timeout
ms when boot failed, then reboot. If rb\_timeout is '-1', guest will
not reboot, qemu passes '-1' to bios by default. Currently Seabios
for X86 system support it.
Do strict boot via ``strict=on`` as far as firmware/BIOS supports
it. This only effects when boot priority is changed by bootindex
options. The default is non-strict boot.
.. parsed-literal::
# try to boot from network first, then from hard disk
|qemu_system_x86| -boot order=nc
# boot from CD-ROM first, switch back to default order after reboot
|qemu_system_x86| -boot once=d
# boot with a splash picture for 5 seconds.
|qemu_system_x86| -boot menu=on,splash=/root/boot.bmp,splash-time=5000
Note: The legacy format '-boot drives' is still supported but its
use is discouraged as it may be removed from future versions.
ERST
DEF("m", HAS_ARG, QEMU_OPTION_m,
"-m [size=]megs[,slots=n,maxmem=size]\n"
" configure guest RAM\n"
" size: initial amount of guest memory\n"
" slots: number of hotplug slots (default: none)\n"
" maxmem: maximum amount of guest memory (default: none)\n"
"NOTE: Some architectures might enforce a specific granularity\n",
QEMU_ARCH_ALL)
SRST
``-m [size=]megs[,slots=n,maxmem=size]``
Sets guest startup RAM size to megs megabytes. Default is 128 MiB.
Optionally, a suffix of "M" or "G" can be used to signify a value in
megabytes or gigabytes respectively. Optional pair slots, maxmem
could be used to set amount of hotpluggable memory slots and maximum
amount of memory. Note that maxmem must be aligned to the page size.
For example, the following command-line sets the guest startup RAM
size to 1GB, creates 3 slots to hotplug additional memory and sets
the maximum memory the guest can reach to 4GB:
.. parsed-literal::
|qemu_system| -m 1G,slots=3,maxmem=4G
If slots and maxmem are not specified, memory hotplug won't be
enabled and the guest startup RAM will never increase.
ERST
DEF("mem-path", HAS_ARG, QEMU_OPTION_mempath,
"-mem-path FILE provide backing storage for guest RAM\n", QEMU_ARCH_ALL)
SRST
``-mem-path path``
Allocate guest RAM from a temporarily created file in path.
ERST
DEF("mem-prealloc", 0, QEMU_OPTION_mem_prealloc,
"-mem-prealloc preallocate guest memory (use with -mem-path)\n",
QEMU_ARCH_ALL)
SRST
``-mem-prealloc``
Preallocate memory when using -mem-path.
ERST
DEF("k", HAS_ARG, QEMU_OPTION_k,
"-k language use keyboard layout (for example 'fr' for French)\n",
QEMU_ARCH_ALL)
SRST
``-k language``
Use keyboard layout language (for example ``fr`` for French). This
option is only needed where it is not easy to get raw PC keycodes
(e.g. on Macs, with some X11 servers or with a VNC or curses
display). You don't normally need to use it on PC/Linux or
PC/Windows hosts.
The available layouts are:
::
ar de-ch es fo fr-ca hu ja mk no pt-br sv
da en-gb et fr fr-ch is lt nl pl ru th
de en-us fi fr-be hr it lv nl-be pt sl tr
The default is ``en-us``.
ERST
HXCOMM Deprecated by -audiodev
DEF("audio-help", 0, QEMU_OPTION_audio_help,
"-audio-help show -audiodev equivalent of the currently specified audio settings\n",
QEMU_ARCH_ALL)
SRST
``-audio-help``
Will show the -audiodev equivalent of the currently specified
(deprecated) environment variables.
ERST
DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
"-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
" specifies the audio backend to use\n"
" id= identifier of the backend\n"
" timer-period= timer period in microseconds\n"
" in|out.mixing-engine= use mixing engine to mix streams inside QEMU\n"
" in|out.fixed-settings= use fixed settings for host audio\n"
" in|out.frequency= frequency to use with fixed settings\n"
" in|out.channels= number of channels to use with fixed settings\n"
" in|out.format= sample format to use with fixed settings\n"
" valid values: s8, s16, s32, u8, u16, u32, f32\n"
" in|out.voices= number of voices to use\n"
" in|out.buffer-length= length of buffer in microseconds\n"
"-audiodev none,id=id,[,prop[=value][,...]]\n"
" dummy driver that discards all output\n"
#ifdef CONFIG_AUDIO_ALSA
"-audiodev alsa,id=id[,prop[=value][,...]]\n"
" in|out.dev= name of the audio device to use\n"
" in|out.period-length= length of period in microseconds\n"
" in|out.try-poll= attempt to use poll mode\n"
" threshold= threshold (in microseconds) when playback starts\n"
#endif
#ifdef CONFIG_AUDIO_COREAUDIO
"-audiodev coreaudio,id=id[,prop[=value][,...]]\n"
" in|out.buffer-count= number of buffers\n"
#endif
#ifdef CONFIG_AUDIO_DSOUND
"-audiodev dsound,id=id[,prop[=value][,...]]\n"
" latency= add extra latency to playback in microseconds\n"
#endif
#ifdef CONFIG_AUDIO_OSS
"-audiodev oss,id=id[,prop[=value][,...]]\n"
" in|out.dev= path of the audio device to use\n"
" in|out.buffer-count= number of buffers\n"
" in|out.try-poll= attempt to use poll mode\n"
" try-mmap= try using memory mapped access\n"
" exclusive= open device in exclusive mode\n"
" dsp-policy= set timing policy (0..10), -1 to use fragment mode\n"
#endif
#ifdef CONFIG_AUDIO_PA
"-audiodev pa,id=id[,prop[=value][,...]]\n"
" server= PulseAudio server address\n"
" in|out.name= source/sink device name\n"
" in|out.latency= desired latency in microseconds\n"
#endif
#ifdef CONFIG_AUDIO_SDL
"-audiodev sdl,id=id[,prop[=value][,...]]\n"
" in|out.buffer-count= number of buffers\n"
#endif
#ifdef CONFIG_SPICE
"-audiodev spice,id=id[,prop[=value][,...]]\n"
#endif
"-audiodev wav,id=id[,prop[=value][,...]]\n"
" path= path of wav file to record\n",
QEMU_ARCH_ALL)
SRST
``-audiodev [driver=]driver,id=id[,prop[=value][,...]]``
Adds a new audio backend driver identified by id. There are global
and driver specific properties. Some values can be set differently
for input and output, they're marked with ``in|out.``. You can set
the input's property with ``in.prop`` and the output's property with
``out.prop``. For example:
::
-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
NOTE: parameter validation is known to be incomplete, in many cases
specifying an invalid option causes QEMU to print an error message
and continue emulation without sound.
Valid global options are:
``id=identifier``
Identifies the audio backend.
``timer-period=period``
Sets the timer period used by the audio subsystem in
microseconds. Default is 10000 (10 ms).
``in|out.mixing-engine=on|off``
Use QEMU's mixing engine to mix all streams inside QEMU and
convert audio formats when not supported by the backend. When
off, fixed-settings must be off too. Note that disabling this
option means that the selected backend must support multiple
streams and the audio formats used by the virtual cards,
otherwise you'll get no sound. It's not recommended to disable
this option unless you want to use 5.1 or 7.1 audio, as mixing
engine only supports mono and stereo audio. Default is on.
``in|out.fixed-settings=on|off``
Use fixed settings for host audio. When off, it will change
based on how the guest opens the sound card. In this case you
must not specify frequency, channels or format. Default is on.
``in|out.frequency=frequency``
Specify the frequency to use when using fixed-settings. Default
is 44100Hz.
``in|out.channels=channels``
Specify the number of channels to use when using fixed-settings.
Default is 2 (stereo).
``in|out.format=format``
Specify the sample format to use when using fixed-settings.
Valid values are: ``s8``, ``s16``, ``s32``, ``u8``, ``u16``,
``u32``, ``f32``. Default is ``s16``.
``in|out.voices=voices``
Specify the number of voices to use. Default is 1.
``in|out.buffer-length=usecs``
Sets the size of the buffer in microseconds.
``-audiodev none,id=id[,prop[=value][,...]]``
Creates a dummy backend that discards all outputs. This backend has
no backend specific properties.
``-audiodev alsa,id=id[,prop[=value][,...]]``
Creates backend using the ALSA. This backend is only available on
Linux.
ALSA specific options are:
``in|out.dev=device``
Specify the ALSA device to use for input and/or output. Default
is ``default``.
``in|out.period-length=usecs``
Sets the period length in microseconds.
``in|out.try-poll=on|off``
Attempt to use poll mode with the device. Default is on.
``threshold=threshold``
Threshold (in microseconds) when playback starts. Default is 0.
``-audiodev coreaudio,id=id[,prop[=value][,...]]``
Creates a backend using Apple's Core Audio. This backend is only
available on Mac OS and only supports playback.
Core Audio specific options are:
``in|out.buffer-count=count``
Sets the count of the buffers.
``-audiodev dsound,id=id[,prop[=value][,...]]``
Creates a backend using Microsoft's DirectSound. This backend is
only available on Windows and only supports playback.
DirectSound specific options are:
``latency=usecs``
Add extra usecs microseconds latency to playback. Default is
10000 (10 ms).
``-audiodev oss,id=id[,prop[=value][,...]]``
Creates a backend using OSS. This backend is available on most
Unix-like systems.
OSS specific options are:
``in|out.dev=device``
Specify the file name of the OSS device to use. Default is
``/dev/dsp``.
``in|out.buffer-count=count``
Sets the count of the buffers.
``in|out.try-poll=on|of``
Attempt to use poll mode with the device. Default is on.
``try-mmap=on|off``
Try using memory mapped device access. Default is off.
``exclusive=on|off``
Open the device in exclusive mode (vmix won't work in this
case). Default is off.
``dsp-policy=policy``
Sets the timing policy (between 0 and 10, where smaller number
means smaller latency but higher CPU usage). Use -1 to use
buffer sizes specified by ``buffer`` and ``buffer-count``. This
option is ignored if you do not have OSS 4. Default is 5.
``-audiodev pa,id=id[,prop[=value][,...]]``
Creates a backend using PulseAudio. This backend is available on
most systems.
PulseAudio specific options are:
``server=server``
Sets the PulseAudio server to connect to.
``in|out.name=sink``
Use the specified source/sink for recording/playback.
``in|out.latency=usecs``
Desired latency in microseconds. The PulseAudio server will try
to honor this value but actual latencies may be lower or higher.
``-audiodev sdl,id=id[,prop[=value][,...]]``
Creates a backend using SDL. This backend is available on most
systems, but you should use your platform's native backend if
possible.
SDL specific options are:
``in|out.buffer-count=count``
Sets the count of the buffers.
``-audiodev spice,id=id[,prop[=value][,...]]``
Creates a backend that sends audio through SPICE. This backend
requires ``-spice`` and automatically selected in that case, so
usually you can ignore this option. This backend has no backend
specific properties.
``-audiodev wav,id=id[,prop[=value][,...]]``
Creates a backend that writes audio to a WAV file.
Backend specific options are:
``path=path``
Write recorded audio into the specified file. Default is
``qemu.wav``.
ERST
DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
"-soundhw c1,... enable audio support\n"
" and only specified sound cards (comma separated list)\n"
" use '-soundhw help' to get the list of supported cards\n"
" use '-soundhw all' to enable all of them\n", QEMU_ARCH_ALL)
SRST
``-soundhw card1[,card2,...] or -soundhw all``
Enable audio and selected sound hardware. Use 'help' to print all
available sound hardware. For example:
.. parsed-literal::
|qemu_system_x86| -soundhw sb16,adlib disk.img
|qemu_system_x86| -soundhw es1370 disk.img
|qemu_system_x86| -soundhw ac97 disk.img
|qemu_system_x86| -soundhw hda disk.img
|qemu_system_x86| -soundhw all disk.img
|qemu_system_x86| -soundhw help
Note that Linux's i810\_audio OSS kernel (for AC97) module might
require manually specifying clocking.
::
modprobe i810_audio clocking=48000
ERST
DEF("device", HAS_ARG, QEMU_OPTION_device,
"-device driver[,prop[=value][,...]]\n"
" add device (based on driver)\n"
" prop=value,... sets driver properties\n"
" use '-device help' to print all possible drivers\n"
" use '-device driver,help' to print all possible properties\n",
QEMU_ARCH_ALL)
SRST
``-device driver[,prop[=value][,...]]``
Add device driver. prop=value sets driver properties. Valid
properties depend on the driver. To get help on possible drivers and
properties, use ``-device help`` and ``-device driver,help``.
Some drivers are:
``-device ipmi-bmc-sim,id=id[,prop[=value][,...]]``
Add an IPMI BMC. This is a simulation of a hardware management
interface processor that normally sits on a system. It provides a
watchdog and the ability to reset and power control the system. You
need to connect this to an IPMI interface to make it useful
The IPMI slave address to use for the BMC. The default is 0x20. This
address is the BMC's address on the I2C network of management
controllers. If you don't know what this means, it is safe to ignore
it.
``id=id``
The BMC id for interfaces to use this device.
``slave_addr=val``
Define slave address to use for the BMC. The default is 0x20.
``sdrfile=file``
file containing raw Sensor Data Records (SDR) data. The default
is none.
``fruareasize=val``
size of a Field Replaceable Unit (FRU) area. The default is
1024.
``frudatafile=file``
file containing raw Field Replaceable Unit (FRU) inventory data.
The default is none.
``guid=uuid``
value for the GUID for the BMC, in standard UUID format. If this
is set, get "Get GUID" command to the BMC will return it.
Otherwise "Get GUID" will return an error.
``-device ipmi-bmc-extern,id=id,chardev=id[,slave_addr=val]``
Add a connection to an external IPMI BMC simulator. Instead of
locally emulating the BMC like the above item, instead connect to an
external entity that provides the IPMI services.
A connection is made to an external BMC simulator. If you do this,
it is strongly recommended that you use the "reconnect=" chardev
option to reconnect to the simulator if the connection is lost. Note
that if this is not used carefully, it can be a security issue, as
the interface has the ability to send resets, NMIs, and power off
the VM. It's best if QEMU makes a connection to an external
simulator running on a secure port on localhost, so neither the
simulator nor QEMU is exposed to any outside network.
See the "lanserv/README.vm" file in the OpenIPMI library for more
details on the external interface.
``-device isa-ipmi-kcs,bmc=id[,ioport=val][,irq=val]``
Add a KCS IPMI interafce on the ISA bus. This also adds a
corresponding ACPI and SMBIOS entries, if appropriate.
``bmc=id``
The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern
above.
``ioport=val``
Define the I/O address of the interface. The default is 0xca0
for KCS.
``irq=val``
Define the interrupt to use. The default is 5. To disable
interrupts, set this to 0.
``-device isa-ipmi-bt,bmc=id[,ioport=val][,irq=val]``
Like the KCS interface, but defines a BT interface. The default port
is 0xe4 and the default interrupt is 5.
``-device pci-ipmi-kcs,bmc=id``
Add a KCS IPMI interafce on the PCI bus.
``bmc=id``
The BMC to connect to, one of ipmi-bmc-sim or ipmi-bmc-extern above.
``-device pci-ipmi-bt,bmc=id``
Like the KCS interface, but defines a BT interface on the PCI bus.
ERST
DEF("name", HAS_ARG, QEMU_OPTION_name,
"-name string1[,process=string2][,debug-threads=on|off]\n"
" set the name of the guest\n"
" string1 sets the window title and string2 the process name\n"
" When debug-threads is enabled, individual threads are given a separate name\n"
" NOTE: The thread names are for debugging and not a stable API.\n",
QEMU_ARCH_ALL)
SRST
``-name name``
Sets the name of the guest. This name will be displayed in the SDL
window caption. The name will also be used for the VNC server. Also
optionally set the top visible process name in Linux. Naming of
individual threads can also be enabled on Linux to aid debugging.
ERST
DEF("uuid", HAS_ARG, QEMU_OPTION_uuid,
"-uuid %08x-%04x-%04x-%04x-%012x\n"
" specify machine UUID\n", QEMU_ARCH_ALL)
SRST
``-uuid uuid``
Set system UUID.
ERST
DEFHEADING()
DEFHEADING(Block device options:)
DEF("fda", HAS_ARG, QEMU_OPTION_fda,
"-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL)
DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL)
SRST
``-fda file``
\
``-fdb file``
Use file as floppy disk 0/1 image (see the :ref:`disk images` chapter in
the System Emulation Users Guide).
ERST
DEF("hda", HAS_ARG, QEMU_OPTION_hda,
"-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL)
DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL)
DEF("hdc", HAS_ARG, QEMU_OPTION_hdc,
"-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL)
DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL)
SRST
``-hda file``
\
``-hdb file``
\
``-hdc file``
\
``-hdd file``
Use file as hard disk 0, 1, 2 or 3 image (see the :ref:`disk images`
chapter in the System Emulation Users Guide).
ERST
DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom,
"-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n",
QEMU_ARCH_ALL)
SRST
``-cdrom file``
Use file as CD-ROM image (you cannot use ``-hdc`` and ``-cdrom`` at
the same time). You can use the host CD-ROM by using ``/dev/cdrom``
as filename.
ERST
DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
"-blockdev [driver=]driver[,node-name=N][,discard=ignore|unmap]\n"
" [,cache.direct=on|off][,cache.no-flush=on|off]\n"
" [,read-only=on|off][,auto-read-only=on|off]\n"
" [,force-share=on|off][,detect-zeroes=on|off|unmap]\n"
" [,driver specific parameters...]\n"
" configure a block backend\n", QEMU_ARCH_ALL)
SRST
``-blockdev option[,option[,option[,...]]]``
Define a new block driver node. Some of the options apply to all
block drivers, other options are only accepted for a specific block
driver. See below for a list of generic options and options for the
most common block drivers.
Options that expect a reference to another node (e.g. ``file``) can
be given in two ways. Either you specify the node name of an already