This patch is another in the continued effort to flesh out the man pages, it adds pretty reasonable text to most of the code xen domain and host commands (device and scheduler will come in the future). Signed-off-by: Sean Dague <sean@dague.net> Diffstat output: xm.pod.1 | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++------------- 1 files changed, 150 insertions(+), 36 deletions(-) diff -r 090e44133d40 docs/man/xm.pod.1 --- a/docs/man/xm.pod.1 Mon Nov 14 18:13:38 2005 +0100 +++ b/docs/man/xm.pod.1 Mon Nov 14 16:23:36 2005 -0500 @@ -278,7 +278,7 @@ =item I<pause> <DomId> Pause a domain. When in a paused state the domain will still consume -allocated resources like memory, but will not be eligible for +allocated resources such as memory, but will not be eligible for scheduling by the Xen hypervisor. =item I<reboot> [Options] <DomId> @@ -309,46 +309,84 @@ =item I<restore> <File> -Create a domain from saved state File. +Build a domain from an B<xm save> state file. See I<save> for more info. =item I<save> <DomId> <File> -Save domain state to File. Saves domain configuration to File as well. +Saves a running domain to a state file so that it can be restored +later. Once saved, the domain will no longer be running on the +system, thus the memory allocated for the domain will be free for +other domains to use. B<xm restore> restores from this state file. + +This is roughly equivalent to doing a hibernate on a running computer, +with all the same limitations. Open network connections may be +severed upon restore, as TCP timeouts may have expired. =item I<shutdown> [Options] <DomId> -Shutdown a domain. - -=over 4 - -Additional Options: - - -a, --all Shutdown all domains. - -H, --halt Shutdown domain without reboot. - -R, --reboot Shutdown and reboot domain. - -w, --wait Wait for shutdown to complete. +Gracefully shuts down a domain. This coordinates with the domain OS +to perform graceful shutdown, so there is no guaruntee that it will +succeed, and may take a variable length of time depending on what +services must be shutdown in the domain. The command returns +immediately after signally the domain unless that I<-w> flag is used. + +The behavior of what happens to a domain when it reboots is set by the +B<on_shutdown> parameter of the xmdomain.cfg file when the domain was +created. + +B<OPTIONS> + +=over 4 + +=item I<-a> + +Shutdown B<all> domains. Often used when doing a complete shutdown of +a Xen system. + +=item I<-w> + +Wait for the domain to complete shutdown before returning. =back =item I<sysrq> <DomId> <letter> -Send a sysrq to a domain. +Send a I<Magic System Request> signal to the domain. For more +information on available magic sys req operations, see sysrq.txt in +your Linux Kernel sources. =item I<unpause> <DomId> -Unpause a paused domain. - -=item I<set-vcpus> <DomId> <VCPUs> - -Enable a specific number of VCPUs for a domain. Subcommand only enables or disables already configured VCPUs for domain. +Moves a domain out of the paused state. This will allow a previously +paused domain to now be eligible for scheduling by the Xen hypervisor. + +=item I<set-vcpus> <DomId> <VCPUCount> + +Enables the I<VCPUcount> virtual CPUs for the domain in question. +Like mem-set, this command can only allocate up to the maximum virtual +CPU count configured at boot for the domain. + +If the VCPUcount is smaller than the current number of active VCPUs, +the highest number VCPUs will be hotplug removed. This may be +important for pinning purposes. + +Attempting to set-vcpus to a number larger than the initially +configured VCPU count is an error. Trying to set-vcpus to < 1 will be +quietly ignored. =item I<vpcu-list> [DomID] -Lists VCPU information for a specific domain or all domains if DomID not given. +Lists VCPU information for a specific domain. If no domain is +specified, VCPU information for all domains will be provided. =item I<vcpu-pin> <DomId> <VCPU> <CPUs> -Sets VCPU to only run on specific CPUs. +Pins the the VCPU to only run on the specific CPUs. + +Normally VCPUs can float between available CPUs whenever Xen deems a +different run state is appropriate. Pinning can be used to restrict +this, by ensuring certain VCPUs can only run on certain physical +CPUs. =back @@ -358,37 +396,106 @@ =item I<dmesg> [OPTION] -Read or clear Xen''s message buffer. The buffer contains Xen boot, warning, and error messages. - -=over 4 - -Additional Option: - - -c, --clear Clears Xen''s message buffer. +Reads the Xen message buffer, similar to dmesg on a Linux system. The +buffer contains informational, warning, and error messages created +during Xen''s boot process. If you are having problems with Xen, this +is one of the first places to look as part of problem determination. + +B<OPTIONS> + +=over 4 + +=item I<-c, --clear> + +Clears Xen''s message buffer. =back =item I<info> -Get information about Xen host. +Print information about the Xen host in I<name : value> format. When +reporting a Xen bug, please provide this information as part of the +bug report. + +Sample xen domain info looks as follows: + + system : Linux + host : talon + release : 2.6.12.6-xen0 + version : #1 Mon Nov 14 14:26:26 EST 2005 + machine : i686 + nr_cpus : 2 + nr_nodes : 1 + sockets_per_node : 2 + cores_per_socket : 1 + threads_per_core : 1 + cpu_mhz : 696 + hw_caps : 0383fbff:00000000:00000000:00000040 + memory : 767 + free_memory : 37 + xen_major : 3 + xen_minor : 0 + xen_extra : -devel + xen_caps : xen-3.0-x86_32 + xen_params : virt_start=0xfc000000 + xen_changeset : Mon Nov 14 18:13:38 2005 +0100 7793:090e44133d40 + cc_compiler : gcc version 3.4.3 (Mandrakelinux 10.2 3.4.3-7mdk) + cc_compile_by : sdague + cc_compile_domain : (none) + cc_compile_date : Mon Nov 14 14:16:48 EST 2005 + +B<FIELDS> + +=over 4 + +Not all fields will be explained here, but some of the less obvious +ones deserve explanation: + +=item I<hw_caps> + +A vector showing what hardware capabilities are supported by your +processor. This is equivalent to, though more cryptic, the flags +field in /proc/cpuinfo on a normal Linux machine. + +=item I<free_memory> + +Available memory (in MB) not allocated to Xen, or any other Domains. + +=item I<xen_caps> + +The xen version, architecture. Architecture values can be one of: +x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64. + +=item I<xen_changeset> + +The xen mercurial changeset id. Very useful for determining exactly +what version of code your Xen system was built from. + +=back =item I<log> -Print B<xend> log. +Print out the B<xend> log. This log file can be found in +/var/log/xend.log. =item I<top> -Monitor system and domains in real-time. +Executes the xentop command, which provides real time monitoring of +domains. Xentop is a curses interface, and reasonably self +explainitory. =back =head1 SCHEDULER SUBCOMMANDS +FIXME: we really need a scheduler expert to write up this section. + =over 4 =item I<sched-bvt> <Parameters> -Set Borrowed Virtual Time (BVT) scheduler parameters. There are five parameters, which are given in order below. +Set Borrowed Virtual Time (BVT) scheduler parameters. There are five +parameters, which are given in order below. =over 4 @@ -404,11 +511,13 @@ =item I<sched-bvt-ctxallow> <Allow> -Sets the BVT scheduler''s context switch allowance. Allow is the minimum time slice allowed to run before being pre-empted. +Sets the BVT scheduler''s context switch allowance. Allow is the +minimum time slice allowed to run before being pre-empted. =item I<sched-sedf> <Parameters> -Set simple sEDF scheduler parameters. Use the following parametersin order. +Set simple sEDF scheduler parameters. Use the following parametersin +order. =over 4 @@ -426,15 +535,20 @@ =head1 VIRTUAL DEVICE COMMANDS +Most virtual devices can be added and removed while guests are +running. The effect to the guest OS is much the same as any hotplug +event. + =over 4 =item I<block-attach <DomId> <BackDev> <FrontDev> <Mode> [BackDomId] -Create a new virtual block device. +Create a new virtual block device =item I<block-detach> <DomId> <DevId> -Destroy a domain''s virtual block device. DevId may either be a device ID or the device name as mounted in the guest. +Destroy a domain''s virtual block device. DevId may either be a device +ID or the device name as mounted in the guest. =item I<block-list> <DomId> -- __________________________________________________________________ Sean Dague Mid-Hudson Valley sean at dague dot net Linux Users Group http://dague.net http://mhvlug.org There is no silver bullet. Plus, werewolves make better neighbors than zombies, and they tend to keep the vampire population down. __________________________________________________________________ _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel
Ewan Mellor
2005-Nov-15 14:26 UTC
Re: [Xen-devel] [PATCH] further xm.1 man page enhancements
On Mon, Nov 14, 2005 at 04:26:32PM -0500, Sean Dague wrote:> This patch is another in the continued effort to flesh out the man pages, it > adds pretty reasonable text to most of the code xen domain and host commands > (device and scheduler will come in the future). > > Signed-off-by: Sean Dague <sean@dague.net>Applied, thanks. Ewan. _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel