[Xen-changelog] [xen-unstable] DOCS: Initial document regarding Xen's command line parameters

[Xen patchbot-unstable <patchbot@xxxxxxx>]

# HG changeset patch
# User Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
# Date 1331106273 0
# Node ID 39aff519e7d43dcc58273f6e62310e2cdffa1b1f
# Parent  9b152ebe9843c41b45953be7778c51d0e788594e
DOCS: Initial document regarding Xen's command line parameters

Still a work in progress, but submitted as a start.

Changes since v1:
  - Include all up to date information from the wiki.

Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
Acked-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
Committed-by: Keir Fraser <keir@xxxxxxx>
---


diff -r 9b152ebe9843 -r 39aff519e7d4 docs/misc/xen-command-line.markdown
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/misc/xen-command-line.markdown       Wed Mar 07 07:44:33 2012 +0000
@@ -0,0 +1,399 @@
+# Xen Hypervisor Command Line Options
+
+**This document is still a work in progress.  There are currently some command 
line options listed twice, and they are defined in separate arch trees, and 
some options are currently separate from their legacy versions.  Please remove 
this notice when complete.**
+
+This document coveres the command line options which the Xen Hypervisor.
+
+## Types of parameter
+
+Most parameters take the form `option=value`.  Different options on the 
command line should be space delimited.
+
+### Boolean
+
+All boolean option may be explicitly enabled using a `value` of
+> `yes`, `on`, `true`, `enable` or `1`
+
+They may be explicitly disabled using a `value` of
+> `no`, `off`, `false`, `disable` or `0`
+
+In addition, a boolean option may be enabled by simply stating its name, and 
may be disabled by prefixing its name with `no-`.
+
+####Examples
+
+Enable noreboot mode
+> `noreboot=true`
+
+Disable x2apic support (if present)
+> `x2apic=off`
+
+Enable synchronous console mode
+> `sync_console`
+
+### Integer
+
+An integer parameter will default to decimal and may be prefixed with a `-` 
for negative numbers.  Alternativly, a hexidecimal number may be used by 
prefixing the number with `0x`, or an octal number may be used if a leading `0` 
is present.
+
+### Size
+
+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)
+* `B` or `b`: Bytes
+
+Without a size suffix, the default will be kilo.
+
+### String
+
+Many parameters are more complicated and require more intricate configuration. 
 The detailed description of each individual paramter specify which values are 
valid.
+
+### List
+
+Some options take a comma separated list of values.
+
+### Combination
+
+Some parameters act as combinations of the above, most commonly a mix of 
Boolean and String.  These are noted in the relevant sections.
+
+## Parameter details
+
+### acpi
+> `= force | ht | noirq | <boolean>`
+
+**String**, or **Boolean** to disable.
+
+The `acpi` option is used to control a set of four related boolean flags; 
`acpi_force`, `acpi_ht`, `acpi_noirq` and `acpi_disabled`.
+
+By default, Xen will scan the DMI data and blacklist certain systems which are 
known to have broken ACPI setups.  Providing `acpi=force` will cause Xen to 
ignore the blacklist and attempt to use all ACPI features.
+
+Using `acpi=ht` causes Xen to parse the ACPI tables enough to enumerate all 
CPUs, but will not use other ACPI features.  This is not common, and only has 
an effect if your system is blacklisted.
+
+The `acpi=noirq` option causes Xen to not parse the ACPI MADT table looking 
for IO-APIC entries.  This is also not common, and any system which requries 
this option to function should be blacklisted.  Additionally, this will not 
prevent Xen from finding IO-APIC entries from the MP tables.
+
+Finally, any of the boolean false options can be used to disable ACPI usage 
entirely.
+
+### acpi\_apic\_instance
+> `= <integer>`
+
+Specify which ACPI MADT table to parse for APIC information, if more than one 
is present.
+
+### acpi\_pstate\_strict
+### acpi\_skip\_timer\_override
+### acpi\_sleep
+### additional\_cpus
+### allowsuperpage
+### apic
+> `= summit | bigsmp | default`
+
+Override Xen's logic for choosing the APIC driver.  By default, if there are 
more than 8 CPUs, Xen will switch to `bigsmp` over `default`.
+
+### apic\_verbosity
+> `= verbose | debug`
+
+Increase the verbosity of the APIC code from the default value.
+
+### ats
+### availmem
+### badpage
+> `= List of [ <integer> | <ingeter>-<integer> ]`
+
+Specify that certain pages, or certain ranges of pages contain bad bytes and 
should not be used.  For example, if your memory tester says that byte 
`0x12345678` is bad, you would place `badpage=0x12345` on Xen's command line.
+
+### bootscrub
+### cachesize
+### clocksource
+### com1,com2
+> `= <baud>[/<clock_hz>][,DPS[,<io-base>[,<irq>[,<port-bdf>[,<bridge-bdf>]]]] 
| pci | amt ] `
+
+Both option `com1` and `com2` follow the same format.
+
+* `<baud>` may be either an integer baud rate, or the string `auto` if the 
bootloader or other earlier firmware has already set it up.
+* Optionally, a clock speed measured in hz can be specified.
+* `DPS` represents the number of data bits, the parity, and the number of stop 
bits.
+
+  `D` is an integer between 5 and 8 for the number of data bits.
+
+  `P` is a single character representing the type of parity:
+
+   * `n` No
+   * `o` Odd
+   * `e` Even
+   * `m` Mark
+   * `s` Space
+
+  `S` is an integer 1 or 2 for the number of stop bits.
+
+* `<io-base>` is an integer which specifies the IO base port for UART 
registers.
+* `<irq> ` is the IRQ number to use, or `0` to use the UART in poll mode only.
+* `<port-bdf>` is the PCI location of the UART, in `<bus>:<device>.<function>` 
notation.
+* `<bridge-bdf>` is the PCI bridge behind which is the UART, in 
`<bus>:<device>.<function>` notation.
+* `pci` indicates that Xen should scan the PCI bus for the UART, avoiding 
Intel AMT devices.
+* `amt` indicated that Xen should scan the PCI bus for the UART, including 
Intel AMT devices if presetn.
+
+A typical setup for most situations might be `com1=115200,8n1`
+
+
+### conring\_size
+> `= <size>`
+
+> Default: `conring_size=16k`
+
+Specify the size of the console ring buffer.
+
+### console
+> `= List of [ vga | com1[H,L] | com2[H,L] | none ]`
+
+> Default: `console=com1,vga`
+
+Specify which console(s) Xen should use.
+
+`vga` indicates that Xen should try and use the vga graphics adapter.
+
+`com1` and `com2` indicates that Xen should use serial ports 1 and 2 
respectivly.  Optionally, these arguments may be followed by an `H` or `L`.  
`H` indicates that transmitted characters will have their MSB set, while 
recieved characters must have their MSB set.  `L` indicates the converse; 
transmitted and recieved characters will have their MSB cleared.  This allows a 
single port to be shared by two subsystems (e.g. console and debugger).
+
+`none` indicates that Xen should not use a console.  This option only makes 
sense on its own.
+
+### console\_timestamps
+> `= <boolean>`
+
+> Default: `false`
+
+Flag to indicate whether include a timestamp with each console line.
+
+### console\_to\_ring
+> `= <boolean>`
+
+> Default: `false`
+
+Flag to indicate whether all guest console output should be copied into the 
console ring buffer.
+
+### conswitch
+> `= <switch char>[,x]`
+
+> Default `conswitch=a`
+
+Specify which character should be used to switch serial input between Xen and 
dom0.  The required sequence is CTRL-&lt;switch char&gt; three times.
+
+The optional trailing `x` indicates that Xen should not automatically switch 
the console input to dom0 during boot.  Any other value, including omission, 
causes Xen to automatically switch to the dom0 console during dom0 boot.
+
+### contig\_mem
+### cpu\_type
+### cpufreq
+### cpuid\_mask\_cpu
+### cpuid\_mask\_ecx
+### cpuid\_mask\_edx
+### cpuid\_mask\_ext\_ecx
+### cpuid\_mask\_ext\_edx
+### cpuid\_mask\_xsave\_eax
+### cpuidle
+### cpuinfo
+### crashkernel
+### credit2\_balance\_over
+### credit2\_balance\_under
+### credit2\_load\_window\_shift
+### debug\_stack\_lines
+### debug\_stack\_lines
+### debugtrace
+### dma\_bits
+> `= <integer>`
+
+Specify the bit width of the DMA heap.
+
+### dom0\_ioports\_disable
+### dom0\_max\_vcpus
+> `= <integer>`
+
+Specifiy the maximum number of vcpus to give to dom0.  This defaults to the 
number of pcpus on the host.
+
+### dom0\_mem (ia64)
+> `= <size>`
+
+Specify the total size for dom0.
+
+### dom0\_mem (x86)
+> `= List of ( min:<value> | max: <value> | <value> )`
+
+each `<value>` is a size parameter.  If the size is positive, it represents an 
absolute value.  If the size is negative, the size specified is subtracted from 
the total available memory.
+
+* `min:<value>` specifies the minimum amount of memory allocated to dom0.
+* `max:<value>` specifies the maximum amount of memory allocated to dom0.
+* `<value>` specified the exact amount of memory allocated to dom0.
+
+### dom0\_shadow
+### dom0\_vcpus\_pin
+> `= <boolean>`
+
+> Default: `false`
+
+Pin dom0 vcpus to their respective pcpus
+
+### dom0\_vhpt\_size\_log2
+### dom\_rid\_bits
+### e820-mtrr-clip
+### e820-verbose
+### efi\_print
+### extra\_guest\_irqs
+### flask\_enabled
+### flask\_enforcing
+### font
+### gdb
+### gnttab\_max\_nr\_frames
+### guest\_loglvl
+> `= <level>[/<rate-limited level>]` where level is `none | error | warning | 
info | debug | all`
+
+> Default: `guest_loglvl=none/warning`
+
+Set the logging level for Xen guests.  Any log message with equal more more 
importance will be printed.
+
+The optional `<rate-limited level>` options instructs which severities should 
be rate limited.
+### hap\_1gb
+### hap\_2mb
+### hpetbroadcast
+### hvm\_debug
+### hvm\_port80
+### idle\_latency\_factor
+### ioapic\_ack
+### iommu
+### iommu\_inclusive\_mapping
+### irq\_ratelimit
+### irq\_vector\_map
+### lapic
+
+Force the use of use of the local APIC on a uniprocessor system, even if left 
disabled by the BIOS.  This option will accept any value at all.
+
+### lapic\_timer\_c2\_ok
+### ler
+### loglvl
+> `= <level>[/<rate-limited level>]` where level is `none | error | warning | 
info | debug | all`
+
+> Default: `loglvl=warning`
+
+Set the logging level for Xen.  Any log message with equal more more 
importance will be printed.
+
+The optional `<rate-limited level>` options instructs which severities should 
be rate limited.
+
+### max\_cstate
+### max\_gsi\_irqs
+### maxcpus
+### maxcpus
+### mce
+### mce\_fb
+### mce\_verbosity
+### mem
+> `= <size>`
+
+Specifies the maximum address of physical RAM.  Any RAM beyond this limit is 
ignored by Xen.
+
+### mmcfg
+### nmi
+> `= ignore | dom0 | fatal`
+
+> Default: `nmi=fatal`
+
+Specify what Xen should do in the event of an NMI parity or I/O error.  
`ignore` discards the error; `dom0` causes Xen to report the error to dom0, 
while 'fatal' causes Xen to print diagnostics and then hang.
+
+### noapic
+### nofxsr
+### noirqbalance
+> `= <boolean>`
+
+Disable software IRQ balancing and affinity. This can be used on systems such 
as Dell 1850/2850 that have workarounds in hardware for IRQ routing issues.
+
+### nolapic
+
+Ignore the local APIC on a uniprocessor system, even if enabled by the BIOS.  
This option will accept value.
+
+### noreboot
+> `= <boolean>`
+
+Do not automatically reboot after an error.  This is useful for catching debug 
output.  Defaults to automatically reboot after 5 seconds.
+
+### noserialnumber
+### nosmp
+> `= <boolean>`
+
+Disable SMP support.  No secondary processors will be booted.  Defaults to 
booting secondary processors.
+
+### nr\_irqs
+### numa
+### pervcpu\_vhpt
+### ple\_gap
+### ple\_window
+### reboot
+### sched
+> `= credit | credit2 | sedf | arinc653`
+
+> Default: `sched=credit`
+
+Choose the default scheduler.
+
+### sched\_credit2\_migrate\_resist
+### sched\_credit\_default\_yield
+### sched\_credit\_tslice\_ms
+### sched\_ratelimit\_us
+### sched\_smt\_power\_savings
+### serial\_tx\_buffer
+> `= <size>`
+
+Set the serial tramsit buffer size.  Defaults to 16kB.
+### smep
+### snb\_igd\_quirk
+### sync\_console
+> `= <boolean>`
+
+> Default: `false`
+
+Flag to force synchronous console output.  Useful for debugging, but not 
suitable for production environments due to incurred overhead.
+
+### tboot
+### tbuf\_size
+> `= <integer>`
+
+Specify the per-cpu trace buffer size in pages.
+
+### tdt
+### tevt\_mask
+### tickle\_one\_idle\_cpu
+### timer\_slop
+### tmem
+### tmem\_compress
+### tmem\_dedup
+### tmem\_lock
+### tmem\_shared\_auth
+### tmem\_tze
+### tsc
+### ucode
+### unrestricted\_guest
+### vcpu\_migration\_delay
+### vesa-map
+### vesa-mtrr
+### vesa-ram
+### vga
+> `= ( ask | current | text-80x<rows> | gfx-<width>x<height>x<depth> | 
mode-<mode> )[,keep]`
+
+`ask` causes Xen to display a menu of available modes and request the user to 
choose one of them.
+
+`current` causes Xen to use the graphics adapter in its current state, without 
further setup.
+
+`text-80x<rows>` instructs Xen to set up text mode.  Valid values for `<rows>` 
are `25, 28, 30, 34, 43, 50, 80`
+
+`gfx-<width>x<height>x<depth>` instructs Xen to set up graphics mode with the 
specified width, height and depth.
+
+`mode-<mode>` instructs Xen to use a specific mode, as shown with the `ask` 
option.  (N.B menu modes are displayed in hex, so `<mode>` should be a 
hexidecimal number)
+
+The optional `keep` parameter causes Xen to continue using the vga console 
even after dom0 has been started.  The default behaviour is to relinquish 
control to dom0.
+
+### vpid
+### vpmu
+### vti\_vhpt\_size
+### vti\_vtlb\_size
+### watchdog
+> `= <boolean>`
+
+Run an NMI watchdog on each processor.  Defaults to disabled.
+### x2apic
+### x2apic\_phys
+### xencons
+### xencons\_poll
+### xsave

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog