Re: [Xen-devel] [PATCH DOCDAY v3] docs: improve documentation of Xen command line parameters

[Matt Wilson <msw@xxxxxxxxxx>]

On Tue, Jul 31, 2012 at 08:36:40AM -0700, 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.
> 
> Changes since v2:
>  * Change *bi prefixes to GiB, MiB, KiB
> 
> Signed-off-by: Matt Wilson <msw@xxxxxxxxxx>
> Acked-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>

George's concerns were adressed in this version, and Andrew gave an
Ack. Anything else keeping this from landing in staging?

Matt

> diff -r bf922651da96 -r 1809175cdc9b 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`: GiB (2^30)
> +* `M` or `m`: MiB (2^20)
> +* `K` or `k`: KiB (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@xxxxxxxxxxxxx
> http://lists.xen.org/xen-devel

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel