-
Notifications
You must be signed in to change notification settings - Fork 195
/
qemu-options.hx
5871 lines (4766 loc) · 252 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 See docs/devel/docs.rst for the format of this file.
HXCOMM
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, hvf, nvmm, 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"
" cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]\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, hvf, nvmm, 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:
* 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.
* 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
``cxl-fmw.0.targets.0=firsttarget,cxl-fmw.0.targets.1=secondtarget,cxl-fmw.0.size=size[,cxl-fmw.0.interleave-granularity=granularity]``
Define a CXL Fixed Memory Window (CFMW).
Described in the CXL 2.0 ECN: CEDT CFMWS & QTG _DSM.
They are regions of Host Physical Addresses (HPA) on a system which
may be interleaved across one or more CXL host bridges. The system
software will assign particular devices into these windows and
configure the downstream Host-managed Device Memory (HDM) decoders
in root ports, switch ports and devices appropriately to meet the
interleave requirements before enabling the memory devices.
``targets.X=target`` provides the mapping to CXL host bridges
which may be identified by the id provided in the -device entry.
Multiple entries are needed to specify all the targets when
the fixed memory window represents interleaved memory. X is the
target index from 0.
``size=size`` sets the size of the CFMW. This must be a multiple of
256MiB. The region will be aligned to 256MiB but the location is
platform and configuration dependent.
``interleave-granularity=granularity`` sets the granularity of
interleave. Default 256 (bytes). Only 256, 512, 1k, 2k,
4k, 8k and 16k granularities supported.
Example:
::
-machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.targets.1=cxl.1,cxl-fmw.0.size=128G,cxl-fmw.0.interleave-granularity=512
ERST
DEF("M", HAS_ARG, QEMU_OPTION_M,
" sgx-epc.0.memdev=memid,sgx-epc.0.node=numaid\n",
QEMU_ARCH_ALL)
SRST
``sgx-epc.0.memdev=@var{memid},sgx-epc.0.node=@var{numaid}``
Define an SGX EPC section.
ERST
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, hvf, nvmm, 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"
" one-insn-per-tb=on|off (one guest instruction per TCG translation block)\n"
" split-wx=on|off (enable TCG split w^x mapping)\n"
" tb-size=n (TCG translation block cache size)\n"
" dirty-ring-size=n (KVM dirty ring GFN count, default 0)\n"
" eager-split-size=n (KVM Eager Page Split chunk size, default 0, disabled. ARM only)\n"
" notify-vmexit=run|internal-error|disable,notify-window=n (enable notify VM exit and set notify window, x86 only)\n"
" thread=single|multi (enable multi-threaded TCG)\n"
" device=path (KVM device path, default /dev/kvm)\n", QEMU_ARCH_ALL)
SRST
``-accel name[,prop=value[,...]]``
This is used to enable an accelerator. Depending on the target
architecture, kvm, xen, hvf, nvmm, 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.
``one-insn-per-tb=on|off``
Makes the TCG accelerator put only one guest instruction into
each translation block. This slows down emulation a lot, but
can be useful in some situations, such as when trying to analyse
the logs produced by the ``-d`` option.
``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 therefore 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).
``dirty-ring-size=n``
When the KVM accelerator is used, it controls the size of the per-vCPU
dirty page ring buffer (number of entries for each vCPU). It should
be a value that is power of two, and it should be 1024 or bigger (but
still less than the maximum value that the kernel supports). 4096
could be a good initial value if you have no idea which is the best.
Set this value to 0 to disable the feature. By default, this feature
is disabled (dirty-ring-size=0). When enabled, KVM will instead
record dirty pages in a bitmap.
``eager-split-size=n``
KVM implements dirty page logging at the PAGE_SIZE granularity and
enabling dirty-logging on a huge-page requires breaking it into
PAGE_SIZE pages in the first place. KVM on ARM does this splitting
lazily by default. There are performance benefits in doing huge-page
split eagerly, especially in situations where TLBI costs associated
with break-before-make sequences are considerable and also if guest
workloads are read intensive. The size here specifies how many pages
to break at a time and needs to be a valid block size which is
1GB/2MB/4KB, 32MB/16KB and 512MB/64KB for 4KB/16KB/64KB PAGE_SIZE
respectively. Be wary of specifying a higher size as it will have an
impact on the memory. By default, this feature is disabled
(eager-split-size=0).
``notify-vmexit=run|internal-error|disable,notify-window=n``
Enables or disables notify VM exit support on x86 host and specify
the corresponding notify window to trigger the VM exit if enabled.
``run`` option enables the feature. It does nothing and continue
if the exit happens. ``internal-error`` option enables the feature.
It raises a internal error. ``disable`` option doesn't enable the feature.
This feature can mitigate the CPU stuck issue due to event windows don't
open up for a specified of time (i.e. notify-window).
Default: notify-vmexit=run,notify-window=0.
``device=path``
Sets the path to the KVM device node. Defaults to ``/dev/kvm``. This
option can be used to pass the KVM device to use via a file descriptor
by setting the value to ``/dev/fdset/NN``.
ERST
DEF("smp", HAS_ARG, QEMU_OPTION_smp,
"-smp [[cpus=]n][,maxcpus=maxcpus][,drawers=drawers][,books=books][,sockets=sockets]\n"
" [,dies=dies][,clusters=clusters][,cores=cores][,threads=threads]\n"
" set the number of initial CPUs to 'n' [default=1]\n"
" maxcpus= maximum number of total CPUs, including\n"
" offline CPUs for hotplug, etc\n"
" drawers= number of drawers on the machine board\n"
" books= number of books in one drawer\n"
" sockets= number of sockets in one book\n"
" dies= number of dies in one socket\n"
" clusters= number of clusters in one die\n"
" cores= number of cores in one cluster\n"
" threads= number of threads in one core\n"
"Note: Different machines may have different subsets of the CPU topology\n"
" parameters supported, so the actual meaning of the supported parameters\n"
" will vary accordingly. For example, for a machine type that supports a\n"
" three-level CPU hierarchy of sockets/cores/threads, the parameters will\n"
" sequentially mean as below:\n"
" sockets means the number of sockets on the machine board\n"
" cores means the number of cores in one socket\n"
" threads means the number of threads in one core\n"
" For a particular machine type board, an expected CPU topology hierarchy\n"
" can be defined through the supported sub-option. Unsupported parameters\n"
" can also be provided in addition to the sub-option, but their values\n"
" must be set as 1 in the purpose of correct parsing.\n",
QEMU_ARCH_ALL)
SRST
``-smp [[cpus=]n][,maxcpus=maxcpus][,sockets=sockets][,dies=dies][,clusters=clusters][,cores=cores][,threads=threads]``
Simulate a SMP system with '\ ``n``\ ' CPUs initially present on
the machine type board. On boards supporting CPU hotplug, the optional
'\ ``maxcpus``\ ' parameter can be set to enable further CPUs to be
added at runtime. When both parameters are omitted, the maximum number
of CPUs will be calculated from the provided topology members and the
initial CPU count will match the maximum number. When only one of them
is given then the omitted one will be set to its counterpart's value.
Both parameters may be specified, but the maximum number of CPUs must
be equal to or greater than the initial CPU count. Product of the
CPU topology hierarchy must be equal to the maximum number of CPUs.
Both parameters are subject to an upper limit that is determined by
the specific machine type chosen.
To control reporting of CPU topology information, values of the topology
parameters can be specified. Machines may only support a subset of the
parameters and different machines may have different subsets supported
which vary depending on capacity of the corresponding CPU targets. So
for a particular machine type board, an expected topology hierarchy can
be defined through the supported sub-option. Unsupported parameters can
also be provided in addition to the sub-option, but their values must be
set as 1 in the purpose of correct parsing.
Either the initial CPU count, or at least one of the topology parameters
must be specified. The specified parameters must be greater than zero,
explicit configuration like "cpus=0" is not allowed. Values for any
omitted parameters will be computed from those which are given.
For example, the following sub-option defines a CPU topology hierarchy
(2 sockets totally on the machine, 2 cores per socket, 2 threads per
core) for a machine that only supports sockets/cores/threads.
Some members of the option can be omitted but their values will be
automatically computed:
::
-smp 8,sockets=2,cores=2,threads=2,maxcpus=8
The following sub-option defines a CPU topology hierarchy (2 sockets
totally on the machine, 2 dies per socket, 2 cores per die, 2 threads
per core) for PC machines which support sockets/dies/cores/threads.
Some members of the option can be omitted but their values will be
automatically computed:
::
-smp 16,sockets=2,dies=2,cores=2,threads=2,maxcpus=16
The following sub-option defines a CPU topology hierarchy (2 sockets
totally on the machine, 2 clusters per socket, 2 cores per cluster,
2 threads per core) for ARM virt machines which support sockets/clusters
/cores/threads. Some members of the option can be omitted but their values
will be automatically computed:
::
-smp 16,sockets=2,clusters=2,cores=2,threads=2,maxcpus=16
Historically preference was given to the coarsest topology parameters
when computing missing values (ie sockets preferred over cores, which
were preferred over threads), however, this behaviour is considered
liable to change. Prior to 6.2 the preference was sockets over cores
over threads. Since 6.2 the preference is cores over sockets over threads.
For example, the following option defines a machine board with 2 sockets
of 1 core before 6.2 and 1 socket of 2 cores after 6.2:
::
-smp 2
Note: The cluster topology will only be generated in ACPI and exposed
to guest if it's explicitly specified in -smp.
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=type[,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
'\ ``memdev``\ ' option assigns RAM from a given memory backend
device to a node. It is recommended to use '\ ``memdev``\ ' option
over legacy '\ ``mem``\ ' option. This is because '\ ``memdev``\ '
option provides better performance and more control over the
backend's RAM (e.g. '\ ``prealloc``\ ' parameter of
'\ ``-memory-backend-ram``\ ' allows memory preallocation).
For compatibility reasons, legacy '\ ``mem``\ ' option is
supported in 5.0 and older machine types. Note that '\ ``mem``\ '
and '\ ``memdev``\ ' are mutually exclusive. If one node uses
'\ ``memdev``\ ', the rest nodes have to use '\ ``memdev``\ '
option, and vice versa.
Users must specify memory for all NUMA nodes by '\ ``memdev``\ '
(or legacy '\ ``mem``\ ' if available). In QEMU 5.2, the support
for '\ ``-numa node``\ ' without memory specified was removed.
'\ ``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,sockets=2,maxcpus=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
DEF("audio", HAS_ARG, QEMU_OPTION_audio,
"-audio [driver=]driver[,prop[=value][,...]]\n"
" specifies default audio backend when `audiodev` is not\n"
" used to create a machine or sound device;"
" options are the same as for -audiodev\n"
"-audio [driver=]driver,model=value[,prop[=value][,...]]\n"
" specifies the audio backend and device to use;\n"
" apart from 'model', options are the same as for -audiodev.\n"
" use '-audio model=help' to show possible devices.\n",
QEMU_ARCH_ALL)
SRST
``-audio [driver=]driver[,model=value][,prop[=value][,...]]``
If the ``model`` option is specified, ``-audio`` is a shortcut
for configuring both the guest audio hardware and the host audio
backend in one go. The guest hardware model can be set with
``model=modelname``. Use ``model=help`` to list the available
device types.
The following two example do exactly the same, to show how ``-audio``
can be used to shorten the command line length:
.. parsed-literal::
|qemu_system| -audiodev pa,id=pa -device sb16,audiodev=pa
|qemu_system| -audio pa,model=sb16
If the ``model`` option is not specified, ``-audio`` is used to
configure a default audio backend that will be used whenever the
``audiodev`` property is not set on a device or machine. In
particular, ``-audio none`` ensures that no audio is produced even
for machines that have embedded sound hardware.
In both cases, the driver option is the same as with the corresponding
``-audiodev`` option below. Use ``driver=help`` to list the available
drivers.
ERST
DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
"-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
" specifies the audio backend to use\n"
" Use ``-audiodev help`` to list the available drivers\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_PIPEWIRE
"-audiodev pipewire,id=id[,prop[=value][,...]]\n"
" in|out.name= source/sink device name\n"
" in|out.stream-name= name of pipewire stream\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_AUDIO_SNDIO
"-audiodev sndio,id=id[,prop[=value][,...]]\n"
#endif
#ifdef CONFIG_SPICE
"-audiodev spice,id=id[,prop[=value][,...]]\n"
#endif
#ifdef CONFIG_DBUS_DISPLAY
"-audiodev dbus,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 pipewire,id=id[,prop[=value][,...]]``
Creates a backend using PipeWire. This backend is available on
most systems.
PipeWire specific options are:
``in|out.latency=usecs``