Matt Wilson
2012-Jul-30 19:06 UTC
[PATCH DOCDAY] improve documentation of Xen command line paramters
This change improves documentation for several Xen command line
parameters. Some of the Itanium-specific options are now removed. A
more thorough check should be performed to remove any other remnants.
I''ve reformatted some of the entries to fit in 80 column terminals.
Options that are yet undocumented but accept standard boolean /
integer values are now annotated as such.
The size suffixes have been corrected to use the binary prefixes
instead of decimal prefixes.
Signed-off-by: Matt Wilson <msw@amazon.com>
diff -r bf922651da96 -r c3a6e679bdfa docs/misc/xen-command-line.markdown
--- a/docs/misc/xen-command-line.markdown Sat Jul 28 17:27:30 2012 +0000
+++ b/docs/misc/xen-command-line.markdown Mon Jul 30 19:04:59 2012 +0000
@@ -46,9 +46,9 @@ if a leading `0` is present.
A size parameter may be any integer, with a size suffix
-* `G` or `g`: Giga (2^30)
-* `M` or `m`: Mega (2^20)
-* `K` or `k`: Kilo (2^10)
+* `G` or `g`: Gibi (2^30)
+* `M` or `m`: Mibi (2^20)
+* `K` or `k`: Kibi (2^10)
* `B` or `b`: Bytes
Without a size suffix, the default will be kilo.
@@ -107,8 +107,10 @@ Specify which ACPI MADT table to parse f
than one is present.
### acpi\_pstate\_strict
+> `= <integer>`
### acpi\_skip\_timer\_override
+> `= <boolean>`
Instruct Xen to ignore timer-interrupt override.
@@ -117,6 +119,8 @@ the domain 0 kernel this option is autom
domain 0 command line
### acpi\_sleep
+> `= s3_bios | s3_mode`
+
### allowsuperpage
> `= <boolean>`
@@ -136,12 +140,12 @@ there are more than 8 CPUs, Xen will swi
> Default: `false`
-Force boot on potentially unsafe systems. By default Xen will refuse to boot on
-systems with the following errata:
+Force boot on potentially unsafe systems. By default Xen will refuse
+to boot on systems with the following errata:
* AMD Erratum 121. Processors with this erratum are subject to a guest
- triggerable Denial of Service. Override only if you trust all of your PV
- guests.
+ triggerable Denial of Service. Override only if you trust all of
+ your PV guests.
### apic\_verbosity
> `= verbose | debug`
@@ -153,15 +157,16 @@ Increase the verbosity of the APIC code
> Default: `true`
-Permits Xen to set up and use PCI Address Translation Services, which is
required
-for PCI Passthrough.
+Permits Xen to set up and use PCI Address Translation Services, which
+is required for PCI Passthrough.
### availmem
> `= <size>`
> Default: `0` (no limit)
-Specify a maximum amount of available memory, to which Xen will clamp the e820
table.
+Specify a maximum amount of available memory, to which Xen will clamp
+the e820 table.
### badpage
> `= List of [ <integer> | <integer>-<integer> ]`
@@ -176,8 +181,9 @@ Xen''s command line.
> Default: `true`
-Scrub free RAM during boot. This is a safety feature to prevent accidentally
leaking
-sensitive VM data into other VMs if Xen crashes and reboots.
+Scrub free RAM during boot. This is a safety feature to prevent
+accidentally leaking sensitive VM data into other VMs if Xen crashes
+and reboots.
### cachesize
> `= <size>`
@@ -227,7 +233,6 @@ Both option `com1` and `com2` follow the
A typical setup for most situations might be `com1=115200,8n1`
-
### conring\_size
> `= <size>`
@@ -300,25 +305,30 @@ Indicate where the responsibility for dr
### cpuid\_mask\_cpu (AMD only)
> `= fam_0f_rev_c | fam_0f_rev_d | fam_0f_rev_e | fam_0f_rev_f |
fam_0f_rev_g | fam_10_rev_b | fam_10_rev_c | fam_11_rev_b`
-If the other **cpuid\_mask\_{,ext\_}e{c,d}x** options are fully set
(unspecified
-on the command line), specify a pre-canned cpuid mask to mask the current
-processor down to appear as the specified processor. It is important to ensure
-that all hosts in a pool appear the same to guests to allow successful live
-migration.
+If the other **cpuid\_mask\_{,ext\_}e{c,d}x** options are fully set
+(unspecified on the command line), specify a pre-canned cpuid mask to
+mask the current processor down to appear as the specified processor.
+It is important to ensure that all hosts in a pool appear the same to
+guests to allow successful live migration.
### cpuid\_mask\_ ecx,edx,ext\_ecx,ext\_edx,xsave_eax
> `= <integer>`
> Default: `~0` (all bits set)
-These five command line parameters are used to specify cpuid masks to help with
-cpuid levelling across a pool of hosts. Setting a bit in the mask indicates
that
-the feature should be enabled, while clearing a bit in the mask indicates that
-the feature should be disabled. It is important to ensure that all hosts in a
-pool appear the same to guests to allow successful live migration.
+These five command line parameters are used to specify cpuid masks to
+help with cpuid levelling across a pool of hosts. Setting a bit in
+the mask indicates that the feature should be enabled, while clearing
+a bit in the mask indicates that the feature should be disabled. It
+is important to ensure that all hosts in a pool appear the same to
+guests to allow successful live migration.
### cpuidle
+> `= <boolean>`
+
### cpuinfo
+> `= <boolean>`
+
### crashinfo_maxaddr
> `= <size>`
@@ -328,17 +338,42 @@ Specify the maximum address to allocate
combination with the `low_crashinfo` command line option.
### crashkernel
+> `= <ramsize-range>:<size>[,...][@<offset>]`
+
### credit2\_balance\_over
+> `= <integer>`
+
### credit2\_balance\_under
+> `= <integer>`
+
### credit2\_load\_window\_shift
+> `= <integer>`
+
### debug\_stack\_lines
+> `= <integer>`
+
+> Default: `20`
+
+Limits the number lines printed in Xen stack traces.
+
### debugtrace
+> `= <integer>`
+
+> Default: `128`
+
+Specify the size of the console debug trace buffer in KiB. The debug
+trace feature is only enabled in debugging builds of Xen.
+
### dma\_bits
> `= <integer>`
Specify the bit width of the DMA heap.
### dom0\_ioports\_disable
+> `= List of <hex>-<hex>`
+
+Specify a list of IO ports to be excluded from dom0 access.
+
### dom0\_max\_vcpus
> `= <integer>`
@@ -372,6 +407,8 @@ For example, to set dom0''s initial memor
allow it to balloon up as far as 1GB use `dom0_mem=512M,max:1G`
### dom0\_shadow
+> `= <boolean>`
+
### dom0\_vcpus\_pin
> `= <boolean>`
@@ -379,10 +416,21 @@ allow it to balloon up as far as 1GB use
Pin dom0 vcpus to their respective pcpus
-### dom0\_vhpt\_size\_log2
-### dom\_rid\_bits
### e820-mtrr-clip
+> `= <boolean>`
+
+Flag that specifies if RAM should be clipped to the highest cacheable
+MTRR.
+
+> Default: `true` on Intel CPUs, otherwise `false`
+
### e820-verbose
+> `= <boolean>`
+
+> Default: `false`
+
+Flag that enables verbose output when processing e820 information and
+applying clipping.
### edd (x86)
> `= off | on | skipmbr`
@@ -397,17 +445,32 @@ Either force retrieval of monitor EDID i
disable it (edid=no). This option should not normally be required
except for debugging purposes.
-### efi\_print
### extra\_guest\_irqs
> `= <number>`
Increase the number of PIRQs available for the guest. The default is 32.
### flask\_enabled
+> `= <integer>`
+
### flask\_enforcing
+> `= <integer>`
+
### font
+> `= <height>` where height is `8x8 | 8x14 | 8x16 ''`
+
+Specify the font size when using the VESA console driver.
+
### gdb
+> `=
<baud>[/<clock_hz>][,DPS[,<io-base>[,<irq>[,<port-bdf>[,<bridge-bdf>]]]]
| pci | amt ] `
+
+Specify the serial parameters for the GDB stub.
+
### gnttab\_max\_nr\_frames
+> `= <integer>`
+
+Specify the maximum number of frames per grant table operation.
+
### guest\_loglvl
> `= <level>[/<rate-limited level>]` where level is `none |
error | warning | info | debug | all`
@@ -420,15 +483,41 @@ The optional `<rate-limited level>` opti
should be rate limited.
### hap\_1gb
+> `= <boolean>`
+
+> Default: `true`
+
+Flag to enable 1 GB host page table support for Hardware Assisted
+Paging (HAP).
+
### hap\_2mb
+> `= <boolean>`
+
+> Default: `true`
+
+Flag to enable 1 GB host page table support for Hardware Assisted
+Paging (HAP).
+
### hpetbroadcast
+> `= <boolean>`
+
### hvm\_debug
+> `= <integer>`
+
### hvm\_port80
+> `= <boolean>`
+
### idle\_latency\_factor
+> `= <integer>`
+
### ioapic\_ack
### iommu
### iommu\_inclusive\_mapping
+> `= <boolean>`
+
### irq\_ratelimit
+> `= <integer>`
+
### irq\_vector\_map
### lapic
@@ -437,7 +526,11 @@ if left disabled by the BIOS. This opti
all.
### lapic\_timer\_c2\_ok
+> `= <boolean>`
+
### ler
+> `= <boolean>`
+
### loglvl
> `= <level>[/<rate-limited level>]` where level is `none |
error | warning | info | debug | all`
@@ -461,18 +554,38 @@ so the crash kernel may find find them.
with **crashinfo_maxaddr**.
### max\_cstate
+> `= <integer>`
+
### max\_gsi\_irqs
+> `= <integer>`
+
### maxcpus
+> `= <integer>`
+
### mce
+> `= <integer>`
+
### mce\_fb
+> `= <integer>`
+
### mce\_verbosity
+> `= verbose`
+
+Specify verbose machine check output.
+
### mem
> `= <size>`
-Specifies the maximum address of physical RAM. Any RAM beyond this
+Specify the maximum address of physical RAM. Any RAM beyond this
limit is ignored by Xen.
### mmcfg
+> `= <boolean>[,amd-fam10]`
+
+> Default: `1`
+
+Specify if the MMConfig space should be enabled.
+
### nmi
> `= ignore | dom0 | fatal`
@@ -493,6 +606,8 @@ domain 0 kernel this option is automatic
0 command line.
### nofxsr
+> `= <boolean>`
+
### noirqbalance
> `= <boolean>`
@@ -501,11 +616,15 @@ systems such as Dell 1850/2850 that have
IRQ routing issues.
### nolapic
+> `= <boolean>`
+
+> Default: `false`
Ignore the local APIC on a uniprocessor system, even if enabled by the
BIOS. This option will accept value.
### no-real-mode (x86)
+> `= <boolean>`
Do not execute real-mode bootstrap code when booting Xen. This option
should not be used except for debugging. It will effectively disable
@@ -519,6 +638,10 @@ catching debug output. Defaults to auto
seconds.
### noserialnumber
+> `= <boolean>`
+
+Disable CPU serial number reporting.
+
### nosmp
> `= <boolean>`
@@ -526,11 +649,39 @@ Disable SMP support. No secondary proce
Defaults to booting secondary processors.
### nr\_irqs
+> `= <integer>`
+
### numa
-### pervcpu\_vhpt
+> `= on | off | fake=<integer> | noacpi`
+
+Default: `on`
+
### ple\_gap
+> `= <integer>`
+
### ple\_window
+> `= <integer>`
+
### reboot
+> `= b[ios] | t[riple] | k[bd] | n[o] [, [w]arm | [c]old]`
+
+Default: `0`
+
+Specify the host reboot method.
+
+`warm` instructs Xen to not set the cold reboot flag.
+
+`cold` instructs Xen to set the cold reboot flag.
+
+`bios` instructs Xen to reboot the host by jumping to BIOS. This is
+only available on 32-bit x86 platforms.
+
+`triple` instructs Xen to reboot the host by causing a triple fault.
+
+`kbd` instructs Xen to reboot the host via the keyboard controller.
+
+`acpi` instructs Xen to reboot the host using RESET_REG in the ACPI FADT.
+
### sched
> `= credit | credit2 | sedf | arinc653`
@@ -539,10 +690,20 @@ Defaults to booting secondary processors
Choose the default scheduler.
### sched\_credit2\_migrate\_resist
+> `= <integer>`
+
### sched\_credit\_default\_yield
+> `= <boolean>`
+
### sched\_credit\_tslice\_ms
+> `= <integer>`
+
### sched\_ratelimit\_us
+> `= <integer>`
+
### sched\_smt\_power\_savings
+> `= <boolean>`
+
### serial\_tx\_buffer
> `= <size>`
@@ -551,7 +712,15 @@ Choose the default scheduler.
Set the serial transmit buffer size.
### smep
+> `= <boolean>`
+
+> Default: `true`
+
+Flag to enable Supervisor Mode Execution Protection
+
### snb\_igd\_quirk
+> `= <boolean>`
+
### sync\_console
> `= <boolean>`
@@ -561,28 +730,80 @@ Flag to force synchronous console output
not suitable for production environments due to incurred overhead.
### tboot
+> `= 0x<phys_addr>`
+
+Specify the physical address of the trusted boot shared page.
+
### tbuf\_size
> `= <integer>`
Specify the per-cpu trace buffer size in pages.
### tdt
+> `= <boolean>`
+
+> Default: `true`
+
+Flag to enable TSC deadline as the APIC timer mode.
+
### tevt\_mask
+> `= <integer>`
+
+Specify a mask for Xen event tracing. This allows Xen tracing to be
+enabled at boot. Refer to the xentrace(8) documentation for a list of
+valid event mask values. In order to enable tracing, a buffer size (in
+pages) must also be specified via the tbuf\_size parameter.
+
### tickle\_one\_idle\_cpu
+> `= <boolean>`
+
### timer\_slop
+> `= <integer>`
+
### tmem
+> `= <boolean>`
+
### tmem\_compress
+> `= <boolean>`
+
### tmem\_dedup
+> `= <boolean>`
+
### tmem\_lock
+> `= <integer>`
+
### tmem\_shared\_auth
+> `= <boolean>`
+
### tmem\_tze
+> `= <integer>`
+
### tsc
+> `= unstable | skewed`
+
### ucode
### unrestricted\_guest
+> `= <boolean>`
+
### vcpu\_migration\_delay
+> `= <integer>`
+
+> Default: `0`
+
+Specify a delay, in microseconds, between migrations of a VCPU between
+PCPUs when using the credit1 scheduler. This prevents rapid fluttering
+of a VCPU between CPUs, and reduces the implicit overheads such as
+cache-warming. 1ms (1000) has been measured as a good value.
+
### vesa-map
+> `= <integer>`
+
### vesa-mtrr
+> `= <integer>`
+
### vesa-ram
+> `= <integer>`
+
### vga
> `= ( ask | current | text-80x<rows> |
gfx-<width>x<height>x<depth> | mode-<mode> )[,keep]`
Andrew Cooper
2012-Jul-30 19:12 UTC
Re: [PATCH DOCDAY] improve documentation of Xen command line paramters
On 30/07/12 20:06, Matt Wilson wrote:> This change improves documentation for several Xen command line > parameters. Some of the Itanium-specific options are now removed. A > more thorough check should be performed to remove any other remnants. > > I''ve reformatted some of the entries to fit in 80 column terminals. > > Options that are yet undocumented but accept standard boolean / > integer values are now annotated as such. > > The size suffixes have been corrected to use the binary prefixes > instead of decimal prefixes. > > Signed-off-by: Matt Wilson <msw@amazon.com>Acked-by: Andrew Cooper <andrew.cooper3@citrix.com>> > diff -r bf922651da96 -r c3a6e679bdfa docs/misc/xen-command-line.markdown > --- a/docs/misc/xen-command-line.markdown Sat Jul 28 17:27:30 2012 +0000 > +++ b/docs/misc/xen-command-line.markdown Mon Jul 30 19:04:59 2012 +0000 > @@ -46,9 +46,9 @@ if a leading `0` is present. > > A size parameter may be any integer, with a size suffix > > -* `G` or `g`: Giga (2^30) > -* `M` or `m`: Mega (2^20) > -* `K` or `k`: Kilo (2^10) > +* `G` or `g`: Gibi (2^30) > +* `M` or `m`: Mibi (2^20) > +* `K` or `k`: Kibi (2^10) > * `B` or `b`: Bytes > > Without a size suffix, the default will be kilo. > @@ -107,8 +107,10 @@ Specify which ACPI MADT table to parse f > than one is present. > > ### acpi\_pstate\_strict > +> `= <integer>` > > ### acpi\_skip\_timer\_override > +> `= <boolean>` > > Instruct Xen to ignore timer-interrupt override. > > @@ -117,6 +119,8 @@ the domain 0 kernel this option is autom > domain 0 command line > > ### acpi\_sleep > +> `= s3_bios | s3_mode` > + > ### allowsuperpage > > `= <boolean>` > > @@ -136,12 +140,12 @@ there are more than 8 CPUs, Xen will swi > > > Default: `false` > > -Force boot on potentially unsafe systems. By default Xen will refuse to boot on > -systems with the following errata: > +Force boot on potentially unsafe systems. By default Xen will refuse > +to boot on systems with the following errata: > > * AMD Erratum 121. Processors with this erratum are subject to a guest > - triggerable Denial of Service. Override only if you trust all of your PV > - guests. > + triggerable Denial of Service. Override only if you trust all of > + your PV guests. > > ### apic\_verbosity > > `= verbose | debug` > @@ -153,15 +157,16 @@ Increase the verbosity of the APIC code > > > Default: `true` > > -Permits Xen to set up and use PCI Address Translation Services, which is required > -for PCI Passthrough. > +Permits Xen to set up and use PCI Address Translation Services, which > +is required for PCI Passthrough. > > ### availmem > > `= <size>` > > > Default: `0` (no limit) > > -Specify a maximum amount of available memory, to which Xen will clamp the e820 table. > +Specify a maximum amount of available memory, to which Xen will clamp > +the e820 table. > > ### badpage > > `= List of [ <integer> | <integer>-<integer> ]` > @@ -176,8 +181,9 @@ Xen''s command line. > > > Default: `true` > > -Scrub free RAM during boot. This is a safety feature to prevent accidentally leaking > -sensitive VM data into other VMs if Xen crashes and reboots. > +Scrub free RAM during boot. This is a safety feature to prevent > +accidentally leaking sensitive VM data into other VMs if Xen crashes > +and reboots. > > ### cachesize > > `= <size>` > @@ -227,7 +233,6 @@ Both option `com1` and `com2` follow the > > A typical setup for most situations might be `com1=115200,8n1` > > - > ### conring\_size > > `= <size>` > > @@ -300,25 +305,30 @@ Indicate where the responsibility for dr > ### cpuid\_mask\_cpu (AMD only) > > `= fam_0f_rev_c | fam_0f_rev_d | fam_0f_rev_e | fam_0f_rev_f | fam_0f_rev_g | fam_10_rev_b | fam_10_rev_c | fam_11_rev_b` > > -If the other **cpuid\_mask\_{,ext\_}e{c,d}x** options are fully set (unspecified > -on the command line), specify a pre-canned cpuid mask to mask the current > -processor down to appear as the specified processor. It is important to ensure > -that all hosts in a pool appear the same to guests to allow successful live > -migration. > +If the other **cpuid\_mask\_{,ext\_}e{c,d}x** options are fully set > +(unspecified on the command line), specify a pre-canned cpuid mask to > +mask the current processor down to appear as the specified processor. > +It is important to ensure that all hosts in a pool appear the same to > +guests to allow successful live migration. > > ### cpuid\_mask\_ ecx,edx,ext\_ecx,ext\_edx,xsave_eax > > `= <integer>` > > > Default: `~0` (all bits set) > > -These five command line parameters are used to specify cpuid masks to help with > -cpuid levelling across a pool of hosts. Setting a bit in the mask indicates that > -the feature should be enabled, while clearing a bit in the mask indicates that > -the feature should be disabled. It is important to ensure that all hosts in a > -pool appear the same to guests to allow successful live migration. > +These five command line parameters are used to specify cpuid masks to > +help with cpuid levelling across a pool of hosts. Setting a bit in > +the mask indicates that the feature should be enabled, while clearing > +a bit in the mask indicates that the feature should be disabled. It > +is important to ensure that all hosts in a pool appear the same to > +guests to allow successful live migration. > > ### cpuidle > +> `= <boolean>` > + > ### cpuinfo > +> `= <boolean>` > + > ### crashinfo_maxaddr > > `= <size>` > > @@ -328,17 +338,42 @@ Specify the maximum address to allocate > combination with the `low_crashinfo` command line option. > > ### crashkernel > +> `= <ramsize-range>:<size>[,...][@<offset>]` > + > ### credit2\_balance\_over > +> `= <integer>` > + > ### credit2\_balance\_under > +> `= <integer>` > + > ### credit2\_load\_window\_shift > +> `= <integer>` > + > ### debug\_stack\_lines > +> `= <integer>` > + > +> Default: `20` > + > +Limits the number lines printed in Xen stack traces. > + > ### debugtrace > +> `= <integer>` > + > +> Default: `128` > + > +Specify the size of the console debug trace buffer in KiB. The debug > +trace feature is only enabled in debugging builds of Xen. > + > ### dma\_bits > > `= <integer>` > > Specify the bit width of the DMA heap. > > ### dom0\_ioports\_disable > +> `= List of <hex>-<hex>` > + > +Specify a list of IO ports to be excluded from dom0 access. > + > ### dom0\_max\_vcpus > > `= <integer>` > > @@ -372,6 +407,8 @@ For example, to set dom0''s initial memor > allow it to balloon up as far as 1GB use `dom0_mem=512M,max:1G` > > ### dom0\_shadow > +> `= <boolean>` > + > ### dom0\_vcpus\_pin > > `= <boolean>` > > @@ -379,10 +416,21 @@ allow it to balloon up as far as 1GB use > > Pin dom0 vcpus to their respective pcpus > > -### dom0\_vhpt\_size\_log2 > -### dom\_rid\_bits > ### e820-mtrr-clip > +> `= <boolean>` > + > +Flag that specifies if RAM should be clipped to the highest cacheable > +MTRR. > + > +> Default: `true` on Intel CPUs, otherwise `false` > + > ### e820-verbose > +> `= <boolean>` > + > +> Default: `false` > + > +Flag that enables verbose output when processing e820 information and > +applying clipping. > > ### edd (x86) > > `= off | on | skipmbr` > @@ -397,17 +445,32 @@ Either force retrieval of monitor EDID i > disable it (edid=no). This option should not normally be required > except for debugging purposes. > > -### efi\_print > ### extra\_guest\_irqs > > `= <number>` > > Increase the number of PIRQs available for the guest. The default is 32. > > ### flask\_enabled > +> `= <integer>` > + > ### flask\_enforcing > +> `= <integer>` > + > ### font > +> `= <height>` where height is `8x8 | 8x14 | 8x16 ''` > + > +Specify the font size when using the VESA console driver. > + > ### gdb > +> `= <baud>[/<clock_hz>][,DPS[,<io-base>[,<irq>[,<port-bdf>[,<bridge-bdf>]]]] | pci | amt ] ` > + > +Specify the serial parameters for the GDB stub. > + > ### gnttab\_max\_nr\_frames > +> `= <integer>` > + > +Specify the maximum number of frames per grant table operation. > + > ### guest\_loglvl > > `= <level>[/<rate-limited level>]` where level is `none | error | warning | info | debug | all` > > @@ -420,15 +483,41 @@ The optional `<rate-limited level>` opti > should be rate limited. > > ### hap\_1gb > +> `= <boolean>` > + > +> Default: `true` > + > +Flag to enable 1 GB host page table support for Hardware Assisted > +Paging (HAP). > + > ### hap\_2mb > +> `= <boolean>` > + > +> Default: `true` > + > +Flag to enable 1 GB host page table support for Hardware Assisted > +Paging (HAP). > + > ### hpetbroadcast > +> `= <boolean>` > + > ### hvm\_debug > +> `= <integer>` > + > ### hvm\_port80 > +> `= <boolean>` > + > ### idle\_latency\_factor > +> `= <integer>` > + > ### ioapic\_ack > ### iommu > ### iommu\_inclusive\_mapping > +> `= <boolean>` > + > ### irq\_ratelimit > +> `= <integer>` > + > ### irq\_vector\_map > ### lapic > > @@ -437,7 +526,11 @@ if left disabled by the BIOS. This opti > all. > > ### lapic\_timer\_c2\_ok > +> `= <boolean>` > + > ### ler > +> `= <boolean>` > + > ### loglvl > > `= <level>[/<rate-limited level>]` where level is `none | error | warning | info | debug | all` > > @@ -461,18 +554,38 @@ so the crash kernel may find find them. > with **crashinfo_maxaddr**. > > ### max\_cstate > +> `= <integer>` > + > ### max\_gsi\_irqs > +> `= <integer>` > + > ### maxcpus > +> `= <integer>` > + > ### mce > +> `= <integer>` > + > ### mce\_fb > +> `= <integer>` > + > ### mce\_verbosity > +> `= verbose` > + > +Specify verbose machine check output. > + > ### mem > > `= <size>` > > -Specifies the maximum address of physical RAM. Any RAM beyond this > +Specify the maximum address of physical RAM. Any RAM beyond this > limit is ignored by Xen. > > ### mmcfg > +> `= <boolean>[,amd-fam10]` > + > +> Default: `1` > + > +Specify if the MMConfig space should be enabled. > + > ### nmi > > `= ignore | dom0 | fatal` > > @@ -493,6 +606,8 @@ domain 0 kernel this option is automatic > 0 command line. > > ### nofxsr > +> `= <boolean>` > + > ### noirqbalance > > `= <boolean>` > > @@ -501,11 +616,15 @@ systems such as Dell 1850/2850 that have > IRQ routing issues. > > ### nolapic > +> `= <boolean>` > + > +> Default: `false` > > Ignore the local APIC on a uniprocessor system, even if enabled by the > BIOS. This option will accept value. > > ### no-real-mode (x86) > +> `= <boolean>` > > Do not execute real-mode bootstrap code when booting Xen. This option > should not be used except for debugging. It will effectively disable > @@ -519,6 +638,10 @@ catching debug output. Defaults to auto > seconds. > > ### noserialnumber > +> `= <boolean>` > + > +Disable CPU serial number reporting. > + > ### nosmp > > `= <boolean>` > > @@ -526,11 +649,39 @@ Disable SMP support. No secondary proce > Defaults to booting secondary processors. > > ### nr\_irqs > +> `= <integer>` > + > ### numa > -### pervcpu\_vhpt > +> `= on | off | fake=<integer> | noacpi` > + > +Default: `on` > + > ### ple\_gap > +> `= <integer>` > + > ### ple\_window > +> `= <integer>` > + > ### reboot > +> `= b[ios] | t[riple] | k[bd] | n[o] [, [w]arm | [c]old]` > + > +Default: `0` > + > +Specify the host reboot method. > + > +`warm` instructs Xen to not set the cold reboot flag. > + > +`cold` instructs Xen to set the cold reboot flag. > + > +`bios` instructs Xen to reboot the host by jumping to BIOS. This is > +only available on 32-bit x86 platforms. > + > +`triple` instructs Xen to reboot the host by causing a triple fault. > + > +`kbd` instructs Xen to reboot the host via the keyboard controller. > + > +`acpi` instructs Xen to reboot the host using RESET_REG in the ACPI FADT. > + > ### sched > > `= credit | credit2 | sedf | arinc653` > > @@ -539,10 +690,20 @@ Defaults to booting secondary processors > Choose the default scheduler. > > ### sched\_credit2\_migrate\_resist > +> `= <integer>` > + > ### sched\_credit\_default\_yield > +> `= <boolean>` > + > ### sched\_credit\_tslice\_ms > +> `= <integer>` > + > ### sched\_ratelimit\_us > +> `= <integer>` > + > ### sched\_smt\_power\_savings > +> `= <boolean>` > + > ### serial\_tx\_buffer > > `= <size>` > > @@ -551,7 +712,15 @@ Choose the default scheduler. > Set the serial transmit buffer size. > > ### smep > +> `= <boolean>` > + > +> Default: `true` > + > +Flag to enable Supervisor Mode Execution Protection > + > ### snb\_igd\_quirk > +> `= <boolean>` > + > ### sync\_console > > `= <boolean>` > > @@ -561,28 +730,80 @@ Flag to force synchronous console output > not suitable for production environments due to incurred overhead. > > ### tboot > +> `= 0x<phys_addr>` > + > +Specify the physical address of the trusted boot shared page. > + > ### tbuf\_size > > `= <integer>` > > Specify the per-cpu trace buffer size in pages. > > ### tdt > +> `= <boolean>` > + > +> Default: `true` > + > +Flag to enable TSC deadline as the APIC timer mode. > + > ### tevt\_mask > +> `= <integer>` > + > +Specify a mask for Xen event tracing. This allows Xen tracing to be > +enabled at boot. Refer to the xentrace(8) documentation for a list of > +valid event mask values. In order to enable tracing, a buffer size (in > +pages) must also be specified via the tbuf\_size parameter. > + > ### tickle\_one\_idle\_cpu > +> `= <boolean>` > + > ### timer\_slop > +> `= <integer>` > + > ### tmem > +> `= <boolean>` > + > ### tmem\_compress > +> `= <boolean>` > + > ### tmem\_dedup > +> `= <boolean>` > + > ### tmem\_lock > +> `= <integer>` > + > ### tmem\_shared\_auth > +> `= <boolean>` > + > ### tmem\_tze > +> `= <integer>` > + > ### tsc > +> `= unstable | skewed` > + > ### ucode > ### unrestricted\_guest > +> `= <boolean>` > + > ### vcpu\_migration\_delay > +> `= <integer>` > + > +> Default: `0` > + > +Specify a delay, in microseconds, between migrations of a VCPU between > +PCPUs when using the credit1 scheduler. This prevents rapid fluttering > +of a VCPU between CPUs, and reduces the implicit overheads such as > +cache-warming. 1ms (1000) has been measured as a good value. > + > ### vesa-map > +> `= <integer>` > + > ### vesa-mtrr > +> `= <integer>` > + > ### vesa-ram > +> `= <integer>` > + > ### vga > > `= ( ask | current | text-80x<rows> | gfx-<width>x<height>x<depth> | mode-<mode> )[,keep]` > > > _______________________________________________ > Xen-devel mailing list > Xen-devel@lists.xen.org > http://lists.xen.org/xen-devel-- Andrew Cooper - Dom0 Kernel Engineer, Citrix XenServer T: +44 (0)1223 225 900, http://www.citrix.com
Matt Wilson
2012-Jul-30 19:41 UTC
Re: [PATCH DOCDAY] improve documentation of Xen command line paramters
On Mon, Jul 30, 2012 at 12:12:30PM -0700, Andrew Cooper wrote:> On 30/07/12 20:06, Matt Wilson wrote: > > This change improves documentation for several Xen command line > > parameters. Some of the Itanium-specific options are now removed. A > > more thorough check should be performed to remove any other remnants. > > > > I''ve reformatted some of the entries to fit in 80 column terminals. > > > > Options that are yet undocumented but accept standard boolean / > > integer values are now annotated as such. > > > > The size suffixes have been corrected to use the binary prefixes > > instead of decimal prefixes. > > > > Signed-off-by: Matt Wilson <msw@amazon.com> > > Acked-by: Andrew Cooper <andrew.cooper3@citrix.com>Unfortunately subject line has a horrible typo and doesn''t have docs: in front. Should I submit a fixed patch, or could someone fix it up if it''s committed? Sorry about that! Matt> > > > diff -r bf922651da96 -r c3a6e679bdfa docs/misc/xen-command-line.markdown > > --- a/docs/misc/xen-command-line.markdown Sat Jul 28 17:27:30 2012 +0000 > > +++ b/docs/misc/xen-command-line.markdown Mon Jul 30 19:04:59 2012 +0000 > > @@ -46,9 +46,9 @@ if a leading `0` is present. > > > > A size parameter may be any integer, with a size suffix > > > > -* `G` or `g`: Giga (2^30) > > -* `M` or `m`: Mega (2^20) > > -* `K` or `k`: Kilo (2^10) > > +* `G` or `g`: Gibi (2^30) > > +* `M` or `m`: Mibi (2^20) > > +* `K` or `k`: Kibi (2^10) > > * `B` or `b`: Bytes > > > > Without a size suffix, the default will be kilo. > > @@ -107,8 +107,10 @@ Specify which ACPI MADT table to parse f > > than one is present. > > > > ### acpi\_pstate\_strict > > +> `= <integer>` > > > > ### acpi\_skip\_timer\_override > > +> `= <boolean>` > > > > Instruct Xen to ignore timer-interrupt override. > > > > @@ -117,6 +119,8 @@ the domain 0 kernel this option is autom > > domain 0 command line > > > > ### acpi\_sleep > > +> `= s3_bios | s3_mode` > > + > > ### allowsuperpage > > > `= <boolean>` > > > > @@ -136,12 +140,12 @@ there are more than 8 CPUs, Xen will swi > > > > > Default: `false` > > > > -Force boot on potentially unsafe systems. By default Xen will refuse to boot on > > -systems with the following errata: > > +Force boot on potentially unsafe systems. By default Xen will refuse > > +to boot on systems with the following errata: > > > > * AMD Erratum 121. Processors with this erratum are subject to a guest > > - triggerable Denial of Service. Override only if you trust all of your PV > > - guests. > > + triggerable Denial of Service. Override only if you trust all of > > + your PV guests. > > > > ### apic\_verbosity > > > `= verbose | debug` > > @@ -153,15 +157,16 @@ Increase the verbosity of the APIC code > > > > > Default: `true` > > > > -Permits Xen to set up and use PCI Address Translation Services, which is required > > -for PCI Passthrough. > > +Permits Xen to set up and use PCI Address Translation Services, which > > +is required for PCI Passthrough. > > > > ### availmem > > > `= <size>` > > > > > Default: `0` (no limit) > > > > -Specify a maximum amount of available memory, to which Xen will clamp the e820 table. > > +Specify a maximum amount of available memory, to which Xen will clamp > > +the e820 table. > > > > ### badpage > > > `= List of [ <integer> | <integer>-<integer> ]` > > @@ -176,8 +181,9 @@ Xen''s command line. > > > > > Default: `true` > > > > -Scrub free RAM during boot. This is a safety feature to prevent accidentally leaking > > -sensitive VM data into other VMs if Xen crashes and reboots. > > +Scrub free RAM during boot. This is a safety feature to prevent > > +accidentally leaking sensitive VM data into other VMs if Xen crashes > > +and reboots. > > > > ### cachesize > > > `= <size>` > > @@ -227,7 +233,6 @@ Both option `com1` and `com2` follow the > > > > A typical setup for most situations might be `com1=115200,8n1` > > > > - > > ### conring\_size > > > `= <size>` > > > > @@ -300,25 +305,30 @@ Indicate where the responsibility for dr > > ### cpuid\_mask\_cpu (AMD only) > > > `= fam_0f_rev_c | fam_0f_rev_d | fam_0f_rev_e | fam_0f_rev_f | fam_0f_rev_g | fam_10_rev_b | fam_10_rev_c | fam_11_rev_b` > > > > -If the other **cpuid\_mask\_{,ext\_}e{c,d}x** options are fully set (unspecified > > -on the command line), specify a pre-canned cpuid mask to mask the current > > -processor down to appear as the specified processor. It is important to ensure > > -that all hosts in a pool appear the same to guests to allow successful live > > -migration. > > +If the other **cpuid\_mask\_{,ext\_}e{c,d}x** options are fully set > > +(unspecified on the command line), specify a pre-canned cpuid mask to > > +mask the current processor down to appear as the specified processor. > > +It is important to ensure that all hosts in a pool appear the same to > > +guests to allow successful live migration. > > > > ### cpuid\_mask\_ ecx,edx,ext\_ecx,ext\_edx,xsave_eax > > > `= <integer>` > > > > > Default: `~0` (all bits set) > > > > -These five command line parameters are used to specify cpuid masks to help with > > -cpuid levelling across a pool of hosts. Setting a bit in the mask indicates that > > -the feature should be enabled, while clearing a bit in the mask indicates that > > -the feature should be disabled. It is important to ensure that all hosts in a > > -pool appear the same to guests to allow successful live migration. > > +These five command line parameters are used to specify cpuid masks to > > +help with cpuid levelling across a pool of hosts. Setting a bit in > > +the mask indicates that the feature should be enabled, while clearing > > +a bit in the mask indicates that the feature should be disabled. It > > +is important to ensure that all hosts in a pool appear the same to > > +guests to allow successful live migration. > > > > ### cpuidle > > +> `= <boolean>` > > + > > ### cpuinfo > > +> `= <boolean>` > > + > > ### crashinfo_maxaddr > > > `= <size>` > > > > @@ -328,17 +338,42 @@ Specify the maximum address to allocate > > combination with the `low_crashinfo` command line option. > > > > ### crashkernel > > +> `= <ramsize-range>:<size>[,...][@<offset>]` > > + > > ### credit2\_balance\_over > > +> `= <integer>` > > + > > ### credit2\_balance\_under > > +> `= <integer>` > > + > > ### credit2\_load\_window\_shift > > +> `= <integer>` > > + > > ### debug\_stack\_lines > > +> `= <integer>` > > + > > +> Default: `20` > > + > > +Limits the number lines printed in Xen stack traces. > > + > > ### debugtrace > > +> `= <integer>` > > + > > +> Default: `128` > > + > > +Specify the size of the console debug trace buffer in KiB. The debug > > +trace feature is only enabled in debugging builds of Xen. > > + > > ### dma\_bits > > > `= <integer>` > > > > Specify the bit width of the DMA heap. > > > > ### dom0\_ioports\_disable > > +> `= List of <hex>-<hex>` > > + > > +Specify a list of IO ports to be excluded from dom0 access. > > + > > ### dom0\_max\_vcpus > > > `= <integer>` > > > > @@ -372,6 +407,8 @@ For example, to set dom0''s initial memor > > allow it to balloon up as far as 1GB use `dom0_mem=512M,max:1G` > > > > ### dom0\_shadow > > +> `= <boolean>` > > + > > ### dom0\_vcpus\_pin > > > `= <boolean>` > > > > @@ -379,10 +416,21 @@ allow it to balloon up as far as 1GB use > > > > Pin dom0 vcpus to their respective pcpus > > > > -### dom0\_vhpt\_size\_log2 > > -### dom\_rid\_bits > > ### e820-mtrr-clip > > +> `= <boolean>` > > + > > +Flag that specifies if RAM should be clipped to the highest cacheable > > +MTRR. > > + > > +> Default: `true` on Intel CPUs, otherwise `false` > > + > > ### e820-verbose > > +> `= <boolean>` > > + > > +> Default: `false` > > + > > +Flag that enables verbose output when processing e820 information and > > +applying clipping. > > > > ### edd (x86) > > > `= off | on | skipmbr` > > @@ -397,17 +445,32 @@ Either force retrieval of monitor EDID i > > disable it (edid=no). This option should not normally be required > > except for debugging purposes. > > > > -### efi\_print > > ### extra\_guest\_irqs > > > `= <number>` > > > > Increase the number of PIRQs available for the guest. The default is 32. > > > > ### flask\_enabled > > +> `= <integer>` > > + > > ### flask\_enforcing > > +> `= <integer>` > > + > > ### font > > +> `= <height>` where height is `8x8 | 8x14 | 8x16 ''` > > + > > +Specify the font size when using the VESA console driver. > > + > > ### gdb > > +> `= <baud>[/<clock_hz>][,DPS[,<io-base>[,<irq>[,<port-bdf>[,<bridge-bdf>]]]] | pci | amt ] ` > > + > > +Specify the serial parameters for the GDB stub. > > + > > ### gnttab\_max\_nr\_frames > > +> `= <integer>` > > + > > +Specify the maximum number of frames per grant table operation. > > + > > ### guest\_loglvl > > > `= <level>[/<rate-limited level>]` where level is `none | error | warning | info | debug | all` > > > > @@ -420,15 +483,41 @@ The optional `<rate-limited level>` opti > > should be rate limited. > > > > ### hap\_1gb > > +> `= <boolean>` > > + > > +> Default: `true` > > + > > +Flag to enable 1 GB host page table support for Hardware Assisted > > +Paging (HAP). > > + > > ### hap\_2mb > > +> `= <boolean>` > > + > > +> Default: `true` > > + > > +Flag to enable 1 GB host page table support for Hardware Assisted > > +Paging (HAP). > > + > > ### hpetbroadcast > > +> `= <boolean>` > > + > > ### hvm\_debug > > +> `= <integer>` > > + > > ### hvm\_port80 > > +> `= <boolean>` > > + > > ### idle\_latency\_factor > > +> `= <integer>` > > + > > ### ioapic\_ack > > ### iommu > > ### iommu\_inclusive\_mapping > > +> `= <boolean>` > > + > > ### irq\_ratelimit > > +> `= <integer>` > > + > > ### irq\_vector\_map > > ### lapic > > > > @@ -437,7 +526,11 @@ if left disabled by the BIOS. This opti > > all. > > > > ### lapic\_timer\_c2\_ok > > +> `= <boolean>` > > + > > ### ler > > +> `= <boolean>` > > + > > ### loglvl > > > `= <level>[/<rate-limited level>]` where level is `none | error | warning | info | debug | all` > > > > @@ -461,18 +554,38 @@ so the crash kernel may find find them. > > with **crashinfo_maxaddr**. > > > > ### max\_cstate > > +> `= <integer>` > > + > > ### max\_gsi\_irqs > > +> `= <integer>` > > + > > ### maxcpus > > +> `= <integer>` > > + > > ### mce > > +> `= <integer>` > > + > > ### mce\_fb > > +> `= <integer>` > > + > > ### mce\_verbosity > > +> `= verbose` > > + > > +Specify verbose machine check output. > > + > > ### mem > > > `= <size>` > > > > -Specifies the maximum address of physical RAM. Any RAM beyond this > > +Specify the maximum address of physical RAM. Any RAM beyond this > > limit is ignored by Xen. > > > > ### mmcfg > > +> `= <boolean>[,amd-fam10]` > > + > > +> Default: `1` > > + > > +Specify if the MMConfig space should be enabled. > > + > > ### nmi > > > `= ignore | dom0 | fatal` > > > > @@ -493,6 +606,8 @@ domain 0 kernel this option is automatic > > 0 command line. > > > > ### nofxsr > > +> `= <boolean>` > > + > > ### noirqbalance > > > `= <boolean>` > > > > @@ -501,11 +616,15 @@ systems such as Dell 1850/2850 that have > > IRQ routing issues. > > > > ### nolapic > > +> `= <boolean>` > > + > > +> Default: `false` > > > > Ignore the local APIC on a uniprocessor system, even if enabled by the > > BIOS. This option will accept value. > > > > ### no-real-mode (x86) > > +> `= <boolean>` > > > > Do not execute real-mode bootstrap code when booting Xen. This option > > should not be used except for debugging. It will effectively disable > > @@ -519,6 +638,10 @@ catching debug output. Defaults to auto > > seconds. > > > > ### noserialnumber > > +> `= <boolean>` > > + > > +Disable CPU serial number reporting. > > + > > ### nosmp > > > `= <boolean>` > > > > @@ -526,11 +649,39 @@ Disable SMP support. No secondary proce > > Defaults to booting secondary processors. > > > > ### nr\_irqs > > +> `= <integer>` > > + > > ### numa > > -### pervcpu\_vhpt > > +> `= on | off | fake=<integer> | noacpi` > > + > > +Default: `on` > > + > > ### ple\_gap > > +> `= <integer>` > > + > > ### ple\_window > > +> `= <integer>` > > + > > ### reboot > > +> `= b[ios] | t[riple] | k[bd] | n[o] [, [w]arm | [c]old]` > > + > > +Default: `0` > > + > > +Specify the host reboot method. > > + > > +`warm` instructs Xen to not set the cold reboot flag. > > + > > +`cold` instructs Xen to set the cold reboot flag. > > + > > +`bios` instructs Xen to reboot the host by jumping to BIOS. This is > > +only available on 32-bit x86 platforms. > > + > > +`triple` instructs Xen to reboot the host by causing a triple fault. > > + > > +`kbd` instructs Xen to reboot the host via the keyboard controller. > > + > > +`acpi` instructs Xen to reboot the host using RESET_REG in the ACPI FADT. > > + > > ### sched > > > `= credit | credit2 | sedf | arinc653` > > > > @@ -539,10 +690,20 @@ Defaults to booting secondary processors > > Choose the default scheduler. > > > > ### sched\_credit2\_migrate\_resist > > +> `= <integer>` > > + > > ### sched\_credit\_default\_yield > > +> `= <boolean>` > > + > > ### sched\_credit\_tslice\_ms > > +> `= <integer>` > > + > > ### sched\_ratelimit\_us > > +> `= <integer>` > > + > > ### sched\_smt\_power\_savings > > +> `= <boolean>` > > + > > ### serial\_tx\_buffer > > > `= <size>` > > > > @@ -551,7 +712,15 @@ Choose the default scheduler. > > Set the serial transmit buffer size. > > > > ### smep > > +> `= <boolean>` > > + > > +> Default: `true` > > + > > +Flag to enable Supervisor Mode Execution Protection > > + > > ### snb\_igd\_quirk > > +> `= <boolean>` > > + > > ### sync\_console > > > `= <boolean>` > > > > @@ -561,28 +730,80 @@ Flag to force synchronous console output > > not suitable for production environments due to incurred overhead. > > > > ### tboot > > +> `= 0x<phys_addr>` > > + > > +Specify the physical address of the trusted boot shared page. > > + > > ### tbuf\_size > > > `= <integer>` > > > > Specify the per-cpu trace buffer size in pages. > > > > ### tdt > > +> `= <boolean>` > > + > > +> Default: `true` > > + > > +Flag to enable TSC deadline as the APIC timer mode. > > + > > ### tevt\_mask > > +> `= <integer>` > > + > > +Specify a mask for Xen event tracing. This allows Xen tracing to be > > +enabled at boot. Refer to the xentrace(8) documentation for a list of > > +valid event mask values. In order to enable tracing, a buffer size (in > > +pages) must also be specified via the tbuf\_size parameter. > > + > > ### tickle\_one\_idle\_cpu > > +> `= <boolean>` > > + > > ### timer\_slop > > +> `= <integer>` > > + > > ### tmem > > +> `= <boolean>` > > + > > ### tmem\_compress > > +> `= <boolean>` > > + > > ### tmem\_dedup > > +> `= <boolean>` > > + > > ### tmem\_lock > > +> `= <integer>` > > + > > ### tmem\_shared\_auth > > +> `= <boolean>` > > + > > ### tmem\_tze > > +> `= <integer>` > > + > > ### tsc > > +> `= unstable | skewed` > > + > > ### ucode > > ### unrestricted\_guest > > +> `= <boolean>` > > + > > ### vcpu\_migration\_delay > > +> `= <integer>` > > + > > +> Default: `0` > > + > > +Specify a delay, in microseconds, between migrations of a VCPU between > > +PCPUs when using the credit1 scheduler. This prevents rapid fluttering > > +of a VCPU between CPUs, and reduces the implicit overheads such as > > +cache-warming. 1ms (1000) has been measured as a good value. > > + > > ### vesa-map > > +> `= <integer>` > > + > > ### vesa-mtrr > > +> `= <integer>` > > + > > ### vesa-ram > > +> `= <integer>` > > + > > ### vga > > > `= ( ask | current | text-80x<rows> | gfx-<width>x<height>x<depth> | mode-<mode> )[,keep]` > > > > > > _______________________________________________ > > Xen-devel mailing list > > Xen-devel@lists.xen.org > > http://lists.xen.org/xen-devel >
Andrew Cooper
2012-Jul-30 19:49 UTC
Re: [PATCH DOCDAY] improve documentation of Xen command line paramters
On 30/07/12 20:41, Matt Wilson wrote:> On Mon, Jul 30, 2012 at 12:12:30PM -0700, Andrew Cooper wrote: >> On 30/07/12 20:06, Matt Wilson wrote: >>> This change improves documentation for several Xen command line >>> parameters. Some of the Itanium-specific options are now removed. A >>> more thorough check should be performed to remove any other remnants. >>> >>> I''ve reformatted some of the entries to fit in 80 column terminals. >>> >>> Options that are yet undocumented but accept standard boolean / >>> integer values are now annotated as such. >>> >>> The size suffixes have been corrected to use the binary prefixes >>> instead of decimal prefixes. >>> >>> Signed-off-by: Matt Wilson <msw@amazon.com> >> Acked-by: Andrew Cooper <andrew.cooper3@citrix.com> > Unfortunately subject line has a horrible typo and doesn''t have docs: > in front. Should I submit a fixed patch, or could someone fix it up > if it''s committed? > > Sorry about that! > > MattI suggest a resend, as it will not have been committed in this short time. ~Andrew> >>> diff -r bf922651da96 -r c3a6e679bdfa docs/misc/xen-command-line.markdown >>> --- a/docs/misc/xen-command-line.markdown Sat Jul 28 17:27:30 2012 +0000 >>> +++ b/docs/misc/xen-command-line.markdown Mon Jul 30 19:04:59 2012 +0000 >>> @@ -46,9 +46,9 @@ if a leading `0` is present. >>> >>> A size parameter may be any integer, with a size suffix >>> >>> -* `G` or `g`: Giga (2^30) >>> -* `M` or `m`: Mega (2^20) >>> -* `K` or `k`: Kilo (2^10) >>> +* `G` or `g`: Gibi (2^30) >>> +* `M` or `m`: Mibi (2^20) >>> +* `K` or `k`: Kibi (2^10) >>> * `B` or `b`: Bytes >>> >>> Without a size suffix, the default will be kilo. >>> @@ -107,8 +107,10 @@ Specify which ACPI MADT table to parse f >>> than one is present. >>> >>> ### acpi\_pstate\_strict >>> +> `= <integer>` >>> >>> ### acpi\_skip\_timer\_override >>> +> `= <boolean>` >>> >>> Instruct Xen to ignore timer-interrupt override. >>> >>> @@ -117,6 +119,8 @@ the domain 0 kernel this option is autom >>> domain 0 command line >>> >>> ### acpi\_sleep >>> +> `= s3_bios | s3_mode` >>> + >>> ### allowsuperpage >>> > `= <boolean>` >>> >>> @@ -136,12 +140,12 @@ there are more than 8 CPUs, Xen will swi >>> >>> > Default: `false` >>> >>> -Force boot on potentially unsafe systems. By default Xen will refuse to boot on >>> -systems with the following errata: >>> +Force boot on potentially unsafe systems. By default Xen will refuse >>> +to boot on systems with the following errata: >>> >>> * AMD Erratum 121. Processors with this erratum are subject to a guest >>> - triggerable Denial of Service. Override only if you trust all of your PV >>> - guests. >>> + triggerable Denial of Service. Override only if you trust all of >>> + your PV guests. >>> >>> ### apic\_verbosity >>> > `= verbose | debug` >>> @@ -153,15 +157,16 @@ Increase the verbosity of the APIC code >>> >>> > Default: `true` >>> >>> -Permits Xen to set up and use PCI Address Translation Services, which is required >>> -for PCI Passthrough. >>> +Permits Xen to set up and use PCI Address Translation Services, which >>> +is required for PCI Passthrough. >>> >>> ### availmem >>> > `= <size>` >>> >>> > Default: `0` (no limit) >>> >>> -Specify a maximum amount of available memory, to which Xen will clamp the e820 table. >>> +Specify a maximum amount of available memory, to which Xen will clamp >>> +the e820 table. >>> >>> ### badpage >>> > `= List of [ <integer> | <integer>-<integer> ]` >>> @@ -176,8 +181,9 @@ Xen''s command line. >>> >>> > Default: `true` >>> >>> -Scrub free RAM during boot. This is a safety feature to prevent accidentally leaking >>> -sensitive VM data into other VMs if Xen crashes and reboots. >>> +Scrub free RAM during boot. This is a safety feature to prevent >>> +accidentally leaking sensitive VM data into other VMs if Xen crashes >>> +and reboots. >>> >>> ### cachesize >>> > `= <size>` >>> @@ -227,7 +233,6 @@ Both option `com1` and `com2` follow the >>> >>> A typical setup for most situations might be `com1=115200,8n1` >>> >>> - >>> ### conring\_size >>> > `= <size>` >>> >>> @@ -300,25 +305,30 @@ Indicate where the responsibility for dr >>> ### cpuid\_mask\_cpu (AMD only) >>> > `= fam_0f_rev_c | fam_0f_rev_d | fam_0f_rev_e | fam_0f_rev_f | fam_0f_rev_g | fam_10_rev_b | fam_10_rev_c | fam_11_rev_b` >>> >>> -If the other **cpuid\_mask\_{,ext\_}e{c,d}x** options are fully set (unspecified >>> -on the command line), specify a pre-canned cpuid mask to mask the current >>> -processor down to appear as the specified processor. It is important to ensure >>> -that all hosts in a pool appear the same to guests to allow successful live >>> -migration. >>> +If the other **cpuid\_mask\_{,ext\_}e{c,d}x** options are fully set >>> +(unspecified on the command line), specify a pre-canned cpuid mask to >>> +mask the current processor down to appear as the specified processor. >>> +It is important to ensure that all hosts in a pool appear the same to >>> +guests to allow successful live migration. >>> >>> ### cpuid\_mask\_ ecx,edx,ext\_ecx,ext\_edx,xsave_eax >>> > `= <integer>` >>> >>> > Default: `~0` (all bits set) >>> >>> -These five command line parameters are used to specify cpuid masks to help with >>> -cpuid levelling across a pool of hosts. Setting a bit in the mask indicates that >>> -the feature should be enabled, while clearing a bit in the mask indicates that >>> -the feature should be disabled. It is important to ensure that all hosts in a >>> -pool appear the same to guests to allow successful live migration. >>> +These five command line parameters are used to specify cpuid masks to >>> +help with cpuid levelling across a pool of hosts. Setting a bit in >>> +the mask indicates that the feature should be enabled, while clearing >>> +a bit in the mask indicates that the feature should be disabled. It >>> +is important to ensure that all hosts in a pool appear the same to >>> +guests to allow successful live migration. >>> >>> ### cpuidle >>> +> `= <boolean>` >>> + >>> ### cpuinfo >>> +> `= <boolean>` >>> + >>> ### crashinfo_maxaddr >>> > `= <size>` >>> >>> @@ -328,17 +338,42 @@ Specify the maximum address to allocate >>> combination with the `low_crashinfo` command line option. >>> >>> ### crashkernel >>> +> `= <ramsize-range>:<size>[,...][@<offset>]` >>> + >>> ### credit2\_balance\_over >>> +> `= <integer>` >>> + >>> ### credit2\_balance\_under >>> +> `= <integer>` >>> + >>> ### credit2\_load\_window\_shift >>> +> `= <integer>` >>> + >>> ### debug\_stack\_lines >>> +> `= <integer>` >>> + >>> +> Default: `20` >>> + >>> +Limits the number lines printed in Xen stack traces. >>> + >>> ### debugtrace >>> +> `= <integer>` >>> + >>> +> Default: `128` >>> + >>> +Specify the size of the console debug trace buffer in KiB. The debug >>> +trace feature is only enabled in debugging builds of Xen. >>> + >>> ### dma\_bits >>> > `= <integer>` >>> >>> Specify the bit width of the DMA heap. >>> >>> ### dom0\_ioports\_disable >>> +> `= List of <hex>-<hex>` >>> + >>> +Specify a list of IO ports to be excluded from dom0 access. >>> + >>> ### dom0\_max\_vcpus >>> > `= <integer>` >>> >>> @@ -372,6 +407,8 @@ For example, to set dom0''s initial memor >>> allow it to balloon up as far as 1GB use `dom0_mem=512M,max:1G` >>> >>> ### dom0\_shadow >>> +> `= <boolean>` >>> + >>> ### dom0\_vcpus\_pin >>> > `= <boolean>` >>> >>> @@ -379,10 +416,21 @@ allow it to balloon up as far as 1GB use >>> >>> Pin dom0 vcpus to their respective pcpus >>> >>> -### dom0\_vhpt\_size\_log2 >>> -### dom\_rid\_bits >>> ### e820-mtrr-clip >>> +> `= <boolean>` >>> + >>> +Flag that specifies if RAM should be clipped to the highest cacheable >>> +MTRR. >>> + >>> +> Default: `true` on Intel CPUs, otherwise `false` >>> + >>> ### e820-verbose >>> +> `= <boolean>` >>> + >>> +> Default: `false` >>> + >>> +Flag that enables verbose output when processing e820 information and >>> +applying clipping. >>> >>> ### edd (x86) >>> > `= off | on | skipmbr` >>> @@ -397,17 +445,32 @@ Either force retrieval of monitor EDID i >>> disable it (edid=no). This option should not normally be required >>> except for debugging purposes. >>> >>> -### efi\_print >>> ### extra\_guest\_irqs >>> > `= <number>` >>> >>> Increase the number of PIRQs available for the guest. The default is 32. >>> >>> ### flask\_enabled >>> +> `= <integer>` >>> + >>> ### flask\_enforcing >>> +> `= <integer>` >>> + >>> ### font >>> +> `= <height>` where height is `8x8 | 8x14 | 8x16 ''` >>> + >>> +Specify the font size when using the VESA console driver. >>> + >>> ### gdb >>> +> `= <baud>[/<clock_hz>][,DPS[,<io-base>[,<irq>[,<port-bdf>[,<bridge-bdf>]]]] | pci | amt ] ` >>> + >>> +Specify the serial parameters for the GDB stub. >>> + >>> ### gnttab\_max\_nr\_frames >>> +> `= <integer>` >>> + >>> +Specify the maximum number of frames per grant table operation. >>> + >>> ### guest\_loglvl >>> > `= <level>[/<rate-limited level>]` where level is `none | error | warning | info | debug | all` >>> >>> @@ -420,15 +483,41 @@ The optional `<rate-limited level>` opti >>> should be rate limited. >>> >>> ### hap\_1gb >>> +> `= <boolean>` >>> + >>> +> Default: `true` >>> + >>> +Flag to enable 1 GB host page table support for Hardware Assisted >>> +Paging (HAP). >>> + >>> ### hap\_2mb >>> +> `= <boolean>` >>> + >>> +> Default: `true` >>> + >>> +Flag to enable 1 GB host page table support for Hardware Assisted >>> +Paging (HAP). >>> + >>> ### hpetbroadcast >>> +> `= <boolean>` >>> + >>> ### hvm\_debug >>> +> `= <integer>` >>> + >>> ### hvm\_port80 >>> +> `= <boolean>` >>> + >>> ### idle\_latency\_factor >>> +> `= <integer>` >>> + >>> ### ioapic\_ack >>> ### iommu >>> ### iommu\_inclusive\_mapping >>> +> `= <boolean>` >>> + >>> ### irq\_ratelimit >>> +> `= <integer>` >>> + >>> ### irq\_vector\_map >>> ### lapic >>> >>> @@ -437,7 +526,11 @@ if left disabled by the BIOS. This opti >>> all. >>> >>> ### lapic\_timer\_c2\_ok >>> +> `= <boolean>` >>> + >>> ### ler >>> +> `= <boolean>` >>> + >>> ### loglvl >>> > `= <level>[/<rate-limited level>]` where level is `none | error | warning | info | debug | all` >>> >>> @@ -461,18 +554,38 @@ so the crash kernel may find find them. >>> with **crashinfo_maxaddr**. >>> >>> ### max\_cstate >>> +> `= <integer>` >>> + >>> ### max\_gsi\_irqs >>> +> `= <integer>` >>> + >>> ### maxcpus >>> +> `= <integer>` >>> + >>> ### mce >>> +> `= <integer>` >>> + >>> ### mce\_fb >>> +> `= <integer>` >>> + >>> ### mce\_verbosity >>> +> `= verbose` >>> + >>> +Specify verbose machine check output. >>> + >>> ### mem >>> > `= <size>` >>> >>> -Specifies the maximum address of physical RAM. Any RAM beyond this >>> +Specify the maximum address of physical RAM. Any RAM beyond this >>> limit is ignored by Xen. >>> >>> ### mmcfg >>> +> `= <boolean>[,amd-fam10]` >>> + >>> +> Default: `1` >>> + >>> +Specify if the MMConfig space should be enabled. >>> + >>> ### nmi >>> > `= ignore | dom0 | fatal` >>> >>> @@ -493,6 +606,8 @@ domain 0 kernel this option is automatic >>> 0 command line. >>> >>> ### nofxsr >>> +> `= <boolean>` >>> + >>> ### noirqbalance >>> > `= <boolean>` >>> >>> @@ -501,11 +616,15 @@ systems such as Dell 1850/2850 that have >>> IRQ routing issues. >>> >>> ### nolapic >>> +> `= <boolean>` >>> + >>> +> Default: `false` >>> >>> Ignore the local APIC on a uniprocessor system, even if enabled by the >>> BIOS. This option will accept value. >>> >>> ### no-real-mode (x86) >>> +> `= <boolean>` >>> >>> Do not execute real-mode bootstrap code when booting Xen. This option >>> should not be used except for debugging. It will effectively disable >>> @@ -519,6 +638,10 @@ catching debug output. Defaults to auto >>> seconds. >>> >>> ### noserialnumber >>> +> `= <boolean>` >>> + >>> +Disable CPU serial number reporting. >>> + >>> ### nosmp >>> > `= <boolean>` >>> >>> @@ -526,11 +649,39 @@ Disable SMP support. No secondary proce >>> Defaults to booting secondary processors. >>> >>> ### nr\_irqs >>> +> `= <integer>` >>> + >>> ### numa >>> -### pervcpu\_vhpt >>> +> `= on | off | fake=<integer> | noacpi` >>> + >>> +Default: `on` >>> + >>> ### ple\_gap >>> +> `= <integer>` >>> + >>> ### ple\_window >>> +> `= <integer>` >>> + >>> ### reboot >>> +> `= b[ios] | t[riple] | k[bd] | n[o] [, [w]arm | [c]old]` >>> + >>> +Default: `0` >>> + >>> +Specify the host reboot method. >>> + >>> +`warm` instructs Xen to not set the cold reboot flag. >>> + >>> +`cold` instructs Xen to set the cold reboot flag. >>> + >>> +`bios` instructs Xen to reboot the host by jumping to BIOS. This is >>> +only available on 32-bit x86 platforms. >>> + >>> +`triple` instructs Xen to reboot the host by causing a triple fault. >>> + >>> +`kbd` instructs Xen to reboot the host via the keyboard controller. >>> + >>> +`acpi` instructs Xen to reboot the host using RESET_REG in the ACPI FADT. >>> + >>> ### sched >>> > `= credit | credit2 | sedf | arinc653` >>> >>> @@ -539,10 +690,20 @@ Defaults to booting secondary processors >>> Choose the default scheduler. >>> >>> ### sched\_credit2\_migrate\_resist >>> +> `= <integer>` >>> + >>> ### sched\_credit\_default\_yield >>> +> `= <boolean>` >>> + >>> ### sched\_credit\_tslice\_ms >>> +> `= <integer>` >>> + >>> ### sched\_ratelimit\_us >>> +> `= <integer>` >>> + >>> ### sched\_smt\_power\_savings >>> +> `= <boolean>` >>> + >>> ### serial\_tx\_buffer >>> > `= <size>` >>> >>> @@ -551,7 +712,15 @@ Choose the default scheduler. >>> Set the serial transmit buffer size. >>> >>> ### smep >>> +> `= <boolean>` >>> + >>> +> Default: `true` >>> + >>> +Flag to enable Supervisor Mode Execution Protection >>> + >>> ### snb\_igd\_quirk >>> +> `= <boolean>` >>> + >>> ### sync\_console >>> > `= <boolean>` >>> >>> @@ -561,28 +730,80 @@ Flag to force synchronous console output >>> not suitable for production environments due to incurred overhead. >>> >>> ### tboot >>> +> `= 0x<phys_addr>` >>> + >>> +Specify the physical address of the trusted boot shared page. >>> + >>> ### tbuf\_size >>> > `= <integer>` >>> >>> Specify the per-cpu trace buffer size in pages. >>> >>> ### tdt >>> +> `= <boolean>` >>> + >>> +> Default: `true` >>> + >>> +Flag to enable TSC deadline as the APIC timer mode. >>> + >>> ### tevt\_mask >>> +> `= <integer>` >>> + >>> +Specify a mask for Xen event tracing. This allows Xen tracing to be >>> +enabled at boot. Refer to the xentrace(8) documentation for a list of >>> +valid event mask values. In order to enable tracing, a buffer size (in >>> +pages) must also be specified via the tbuf\_size parameter. >>> + >>> ### tickle\_one\_idle\_cpu >>> +> `= <boolean>` >>> + >>> ### timer\_slop >>> +> `= <integer>` >>> + >>> ### tmem >>> +> `= <boolean>` >>> + >>> ### tmem\_compress >>> +> `= <boolean>` >>> + >>> ### tmem\_dedup >>> +> `= <boolean>` >>> + >>> ### tmem\_lock >>> +> `= <integer>` >>> + >>> ### tmem\_shared\_auth >>> +> `= <boolean>` >>> + >>> ### tmem\_tze >>> +> `= <integer>` >>> + >>> ### tsc >>> +> `= unstable | skewed` >>> + >>> ### ucode >>> ### unrestricted\_guest >>> +> `= <boolean>` >>> + >>> ### vcpu\_migration\_delay >>> +> `= <integer>` >>> + >>> +> Default: `0` >>> + >>> +Specify a delay, in microseconds, between migrations of a VCPU between >>> +PCPUs when using the credit1 scheduler. This prevents rapid fluttering >>> +of a VCPU between CPUs, and reduces the implicit overheads such as >>> +cache-warming. 1ms (1000) has been measured as a good value. >>> + >>> ### vesa-map >>> +> `= <integer>` >>> + >>> ### vesa-mtrr >>> +> `= <integer>` >>> + >>> ### vesa-ram >>> +> `= <integer>` >>> + >>> ### vga >>> > `= ( ask | current | text-80x<rows> | gfx-<width>x<height>x<depth> | mode-<mode> )[,keep]` >>> >>> >>> _______________________________________________ >>> Xen-devel mailing list >>> Xen-devel@lists.xen.org >>> http://lists.xen.org/xen-devel-- Andrew Cooper - Dom0 Kernel Engineer, Citrix XenServer T: +44 (0)1223 225 900, http://www.citrix.com
George Dunlap
2012-Jul-31 09:26 UTC
Re: [PATCH DOCDAY] improve documentation of Xen command line paramters
On Mon, Jul 30, 2012 at 8:06 PM, Matt Wilson <msw@amazon.com> wrote:> This change improves documentation for several Xen command line > parameters. Some of the Itanium-specific options are now removed. A > more thorough check should be performed to remove any other remnants. > > I''ve reformatted some of the entries to fit in 80 column terminals. > > Options that are yet undocumented but accept standard boolean / > integer values are now annotated as such. > > The size suffixes have been corrected to use the binary prefixes > instead of decimal prefixes. > > Signed-off-by: Matt Wilson <msw@amazon.com> > > diff -r bf922651da96 -r c3a6e679bdfa docs/misc/xen-command-line.markdown > --- a/docs/misc/xen-command-line.markdown Sat Jul 28 17:27:30 2012 +0000 > +++ b/docs/misc/xen-command-line.markdown Mon Jul 30 19:04:59 2012 +0000 > @@ -46,9 +46,9 @@ if a leading `0` is present. > > A size parameter may be any integer, with a size suffix > > -* `G` or `g`: Giga (2^30) > -* `M` or `m`: Mega (2^20) > -* `K` or `k`: Kilo (2^10) > +* `G` or `g`: Gibi (2^30) > +* `M` or `m`: Mibi (2^20) > +* `K` or `k`: Kibi (2^10) > * `B` or `b`: BytesCan I strongly object to this part of the patch? I realize that the "bi" is an international standard; however, it''s a completely stupid one, and the people who came up with it are completely brain-dead. All of them sound silly; and "mebibyte" has three bilabial consontants in a row and is completely unpronouncable. When standards organizations try to make standards that are worse than useless, I think we have a duty to ignore them. :-) -George
George Dunlap
2012-Jul-31 09:29 UTC
Re: [PATCH DOCDAY] improve documentation of Xen command line paramters
On Tue, Jul 31, 2012 at 10:26 AM, George Dunlap <George.Dunlap@eu.citrix.com> wrote:> On Mon, Jul 30, 2012 at 8:06 PM, Matt Wilson <msw@amazon.com> wrote: >> This change improves documentation for several Xen command line >> parameters. Some of the Itanium-specific options are now removed. A >> more thorough check should be performed to remove any other remnants. >> >> I''ve reformatted some of the entries to fit in 80 column terminals. >> >> Options that are yet undocumented but accept standard boolean / >> integer values are now annotated as such. >> >> The size suffixes have been corrected to use the binary prefixes >> instead of decimal prefixes. >> >> Signed-off-by: Matt Wilson <msw@amazon.com> >> >> diff -r bf922651da96 -r c3a6e679bdfa docs/misc/xen-command-line.markdown >> --- a/docs/misc/xen-command-line.markdown Sat Jul 28 17:27:30 2012 +0000 >> +++ b/docs/misc/xen-command-line.markdown Mon Jul 30 19:04:59 2012 +0000 >> @@ -46,9 +46,9 @@ if a leading `0` is present. >> >> A size parameter may be any integer, with a size suffix >> >> -* `G` or `g`: Giga (2^30) >> -* `M` or `m`: Mega (2^20) >> -* `K` or `k`: Kilo (2^10) >> +* `G` or `g`: Gibi (2^30) >> +* `M` or `m`: Mibi (2^20) >> +* `K` or `k`: Kibi (2^10) >> * `B` or `b`: Bytes > > Can I strongly object to this part of the patch? I realize that the > "bi" is an international standard; however, it''s a completely stupid > one, and the people who came up with it are completely brain-dead. > All of them sound silly; and "mebibyte" has three bilabial consontants > in a row and is completely unpronouncable. > > When standards organizations try to make standards that are worse than > useless, I think we have a duty to ignore them. :-)I would be happy with GiB, MiB, and KiB, instead of Gibi, Mibi, and Kibi. Making the distinction between powers of 2 and powers of 10 makes sense; it''s just the particular pronunciation that I object to. :-) -George