[PATCH] Add Initial Man Pages for xm and xmdomain.cfg

[PATCH] Add Initial Man Pages for xm and xmdomain.cfg

[Daniel Stekloff]

[-- Attachment #1: Type: text/plain, Size: 400 bytes --]


Here's a first stab at man pages for xm and xmdomain.cfg. Sean submitted
this patch over the summer. I've just added a xm man page to it. Both
man pages are rough and need more work. 

Sean's original post:

http://lists.xensource.com/archives/html/xen-devel/2005-08/txtOQiiLcE26t.txt

Thanks,

Dan


Signed-off-by: Sean Dague <sean@dague.net>
Signed-off-by: Daniel Stekloff <dsteklof@us.ibm.com>



[-- Attachment #2: add-initial-manpages.patch --]
[-- Type: text/x-patch, Size: 9940 bytes --]

--- xen-unstable.hg.copy/docs/Makefile	2005-10-28 18:36:33.000000000 -0700
+++ xen-unstable.hg/docs/Makefile	2005-10-28 14:58:18.000000000 -0700
@@ -1,5 +1,6 @@
 #!/usr/bin/make -f
 
+VERSION		= xen-unstable
 INSTALL		= install
 INSTALL_DIR	= $(INSTALL) -d -m0755
 
@@ -9,9 +10,15 @@
 FIG2DEV		:= fig2dev
 LATEX2HTML	:= latex2html
 DOXYGEN		:= doxygen
+POD2MAN		:= pod2man
 
 pkgdocdir	:= /usr/share/doc/xen
+mandir		:= /usr/share/man
 
+DOC_MAN5SRC	:= $(wildcard man/*.pod.5)
+DOC_MAN1SRC	:= $(wildcard man/*.pod.1)
+DOC_MAN1	:= $(patsubst man/%.pod.1,man1/%.1,$(DOC_MAN1SRC))
+DOC_MAN5	:= $(patsubst man/%.pod.5,man5/%.5,$(DOC_MAN5SRC))
 DOC_TEX		:= src/user.tex src/interface.tex
 DOC_PS		:= $(patsubst src/%.tex,ps/%.ps,$(DOC_TEX))
 DOC_PDF		:= $(patsubst src/%.tex,pdf/%.pdf,$(DOC_TEX))
@@ -22,7 +29,7 @@
 .PHONY:	all build dev-docs python-dev-docs ps pdf html clean install
 
 all: build
-build: ps pdf html
+build: ps pdf html man-pages
 	rm -f *.aux *.dvi *.bbl *.blg *.glo *.idx *.ilg *.log *.ind *.toc
 
 dev-docs: python-dev-docs
@@ -43,17 +50,36 @@
 	$(MAKE) -C api/tools/python/latex ; else                   \
         echo "Doxygen not installed; skipping python-dev-docs."; fi
 
+man-pages:
+	@if which $(POD2MAN) 1>/dev/null 2>/dev/null; then \
+	$(MAKE) $(DOC_MAN1) $(DOC_MAN5); fi
+
+man1/%.1: man/%.pod.1 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed 's/^man1.//'| \
+		sed 's/.1//'` -s 1 -c "Xen" $< $@
+
+man5/%.5: man/%.pod.5 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2MAN) --release=$(VERSION) --name=`echo $@ | sed 's/^man5.//'| \
+		sed 's/.5//'` -s 5 -c "Xen" $< $@
+
 clean:
 	rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~ 
 	rm -rf *.ilg *.log *.ind *.toc *.bak core
 	rm -rf $(GFX) ps pdf html
 	rm -rf api
+	rm -rf man5
+	rm -rf man1
 
 install: all
 	rm -rf $(DESTDIR)$(pkgdocdir)
 	$(INSTALL_DIR) $(DESTDIR)$(pkgdocdir)
 	cp -dR ps $(DESTDIR)$(pkgdocdir)
 	cp -dR pdf $(DESTDIR)$(pkgdocdir)
+	$(INSTALL_DIR) $(DESTDIR)$(mandir)
+	cp -dR man1 $(DESTDIR)$(mandir)
+	cp -dR man5 $(DESTDIR)$(mandir)
 	[ ! -d html ] || cp -dR html $(DESTDIR)$(pkgdocdir)
 
 pdf/%.pdf: ps/%.ps
diff -Nur xen-unstable.hg.copy/docs/man/xmdomain.cfg.pod.5 xen-unstable.hg/docs/man/xmdomain.cfg.pod.5
--- xen-unstable.hg.copy/docs/man/xmdomain.cfg.pod.5	1969-12-31 16:00:00.000000000 -0800
+++ xen-unstable.hg/docs/man/xmdomain.cfg.pod.5	2005-10-28 14:47:19.000000000 -0700
@@ -0,0 +1,87 @@
+=head1 NAME
+
+xmdomain.cfg - xm domain create config file format
+
+=head1 SYNOPSIS
+
+ /etc/xen/myxendomain
+ /etc/xen/myxendomain2
+ /etc/xen/auto/myxenautostarted
+
+=head1 DESCRIPTION
+
+The xm(1) program uses python executable config files to define
+domains to create from scratch.  Each of these config files needs to
+contain a number of required options, and may specify many more.
+
+Domain configuration files live in /etc/xen by default, though the
+full path to the config file must be specified in the I<xm create>
+command, so they can exist anywhere in the filesystem.
+
+/etc/xen/auto is a special case however, as domain config files in
+that directory will be started automatically at system boot if the
+xendomain init script is enabled.
+
+=head1 OPTIONS
+
+The following lists the most commonly used options for a domain config
+file.  
+
+=over 4
+
+=item I<kernel>
+
+The kernel image used in the domain.
+
+=item I<ramdisk>
+
+The initial ramdisk to be used in the domain.  Default xen domU
+kernels do not usually need a ramdisk.
+
+=item I<memory>
+
+The amount of memory, in megabytes to allocate to the domain when it
+starts.  Allocating insufficient memory for a domain may produce
+extremely bizarre behavior.
+
+=item I<name>
+
+A unique name for the domain.  You can not create 2 domains with the
+same name.
+
+=item I<root>
+
+Root stanza for the domain (required for Linux domains).
+
+=item I<disk>
+
+An array of disk stanzas 
+
+=back
+
+A bare minimal config file example might be as follows:
+
+    kernel = "/boot/vmlinuz-2.6-xenU"
+    memory = 128
+    name = "MyLinux"      
+    root = "/dev/hda1 ro"
+
+=head1 ADDITIONAL OPTIONS
+
+=over 4
+
+=item I<builder>
+
+=back
+
+=head1 SEE ALSO
+
+B<xm>(1)
+
+=head1 AUTHOR
+
+  Sean Dague <sean at dague dot net>
+
+=head1 BUGS
+
+Not all options are currently documented
diff -Nur xen-unstable.hg.copy/docs/man/xm.pod.1 xen-unstable.hg/docs/man/xm.pod.1
--- xen-unstable.hg.copy/docs/man/xm.pod.1	1969-12-31 16:00:00.000000000 -0800
+++ xen-unstable.hg/docs/man/xm.pod.1	2005-10-28 18:16:34.000000000 -0700
@@ -0,0 +1,254 @@
+=head1 NAME
+
+xm - Xen management user interface
+
+=head1 SYNOPSIS
+
+xm <subcommand> [args]
+
+=head1 DESCRIPTION
+
+The B<xm> program is the main interface for managing Xen guest domains. The program can be used to create, pause, and shutdown domains. It can also be used to list current domains, enable or pin VCPUs, and attach or detach virtual block devices. The B<xm> program relies upon B<xend>. The daemon must be running in order for the program to work.
+
+Domain name <DomName> can be substituted in the subcommands for Domain id <DomId>.
+
+=head1 DOMAIN SUBCOMMANDS
+
+=over 4
+
+=item I<console> <DomId>
+
+Attach to domain DomId's console.
+
+=item I<create> <CfgFile>
+
+Create a domain based on B<xmdomain.cfg> configuration file.
+
+=item I<destroy> <DomId>
+
+Terminate domain DomId immediately.
+
+=item I<domid> <DomName>
+
+Converts a domain name to a domain id.
+
+=item I<domname> <DomId>
+
+Converts a domain id to a domain name.
+
+=item I<help> [--long]
+
+Displays command's help message. The long option prints out the complete set of B<xm> subcommands.
+
+=item I<list> [DomId, ...]
+
+List information about domains.
+
+=item I<mem-max> <DomId> <Mem>
+
+Set domain maximum memory limit to Mem. Mem is in Megabytes. This is the upper memory mark for how much memory a domain can have.
+
+=item I<mem-set> <DomId> <Mem>
+
+Set domain's memory, in Megabytes. Mem must be less than or equal to the maximum memory for the domain.
+
+=item I<migrate> <DomId> <Host> [Options]
+
+Migrate a domain to another Host machine. B<Xend> must be running on other host machine and there must be sufficient resources as well.
+
+=over 4
+
+Additional Options:
+
+    -l, --live                    Use live migration.
+    -r, --resource <Mbit value>   Set resource level.
+
+=back
+
+=item I<pause> <DomId>
+
+Pause a domain's execution.
+
+=item I<reboot> [Options] <DomId>
+
+Reboot a domain.
+
+=over 4
+
+Additional Options:
+
+    -a, --all        reboot all domains.
+    -w, --wait       Wait for shutdown to complete.
+
+=back
+
+=item I<restore> <File>
+
+Create a domain from saved state File.
+
+=item I<save> <DomId> <File>
+
+Save domain state to File. Saves domain configuration to File as well.
+
+=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.
+
+=back
+
+=item I<sysrq> <DomId> <letter>
+
+Send a sysrq to a domain.
+
+=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.
+
+=item I<vpcu-list> [DomID]
+
+Lists VCPU information for a specific domain or all domains if DomID not given.
+
+=item I<vcpu-pin> <DomId> <VCPU> <CPUs>
+
+Sets VCPU to only run on specific CPUs.
+
+=back
+
+=head1 XEN HOST SUBCOMMANDS
+
+=over 4
+
+=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.
+
+=back
+
+=item I<info>
+
+Get information about Xen host.
+
+=item I<log>
+
+Print B<xend> log.
+
+=item I<top>
+
+Monitor system and domains in real-time.
+
+=back
+
+=head1 SCHEDULER SUBCOMMANDS
+
+=over 4
+
+=item I<sched-bvt> <Parameters>
+
+Set Borrowed Virtual Time (BVT) scheduler parameters. There are five parameters, which are given in order below.
+
+=over 4
+
+Parameters:
+
+    mcuadv - Minimum Charging Unit (MCU) advance.
+    warpback - Warp back time allowed.
+    warpvalue - Warp value.
+    warpl - Warp maximum limit.
+    warpu - Unwarped minimum limit.
+
+=back 
+
+=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.
+
+=item I<sched-sedf> <Parameters>
+
+Set simple sEDF scheduler parameters. Use the following parametersin order.
+
+=over 4
+
+Parameters:
+
+    period - in nanoseconds
+    slice - in nanoseconds
+    latency-hint - scaled period if domain is doing heavy I/O
+    extratime - flag for allowing domain to run in extra time.
+    weight - another way of setting cpu slice.
+
+=back
+
+=back
+
+=head1 VIRTUAL DEVICE COMMANDS
+
+=over 4
+
+=item I<block-attach <DomId> <BackDev> <FrontDev> <Mode> [BackDomId]
+
+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.
+
+=item I<block-list> <DomId>
+
+List virtual block devices for a domain.
+
+=item I<network-limit> <DomId> <Vif> <Credit> <Period>
+
+Limit the transmission rate of a virtual network interface.
+
+=item I<network-list> <DomId>
+
+List virtual network interfaces for a domain.
+
+=back
+
+=head1 VNET COMMANDS
+
+=over 4
+
+=item I<vnet-list> [-l|--long]
+
+List vnets.
+
+=item I<vnet-create> <config>
+
+Create a vnet from a config file.
+
+=item I<vnet-delete> <vnetid>
+
+Delete a vnet.
+
+=back
+
+=head1 SEE ALSO
+
+B<xmdomain.cfg>(5)
+
+=head1 AUTHOR
+
+  Daniel Stekloff <dsteklof at us dot ibm dot com>
+
+=head1 BUGS

[-- Attachment #3: Type: text/plain, Size: 138 bytes --]

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

Re: [PATCH] Add Initial Man Pages for xm and xmdomain.cfg

[M.A. Williamson]

It's good to see man pages appearing for other tools!

I'd still suggest considering a script for generating the command help 
though: e.g. have a "skeleton" man page but use a script (maybe just a 
shell script) to allow quick regeneration of the command descriptions (by 
just running xm help over everything and formatting the results).

We can still check a pre-generated manpage into hg and ship it readymade; 
it's just that relying on developers to update the documentation tends not 
to work ;-)

Cheers,
Mark

On Oct 29 2005, Daniel Stekloff wrote:

>
>Here's a first stab at man pages for xm and xmdomain.cfg. Sean submitted
>this patch over the summer. I've just added a xm man page to it. Both
>man pages are rough and need more work. 
>
>Sean's original post:
>
>  
> http://lists.xensource.com/archives/html/xen-devel/2005-08/txtOQiiLcE26t.txt
>
>Thanks,
>
>Dan
>
>
>Signed-off-by: Sean Dague <sean@dague.net>
>Signed-off-by: Daniel Stekloff <dsteklof@us.ibm.com>
>
>
>

Re: [PATCH] Add Initial Man Pages for xm and xmdomain.cfg

[Sean Dague]

[-- Attachment #1.1: Type: text/plain, Size: 1352 bytes --]

On Sat, Oct 29, 2005 at 05:29:43PM +0100, M.A. Williamson wrote:
> It's good to see man pages appearing for other tools!
> 
> I'd still suggest considering a script for generating the command help 
> though: e.g. have a "skeleton" man page but use a script (maybe just a 
> shell script) to allow quick regeneration of the command descriptions (by 
> just running xm help over everything and formatting the results).
> 
> We can still check a pre-generated manpage into hg and ship it readymade; 
> it's just that relying on developers to update the documentation tends not 
> to work ;-)

I still disagree. :)

If we get this man page stub into the Xen tree, I'll start working on it
again.  My lack of motivation for this has been not having it there.  This
is something easy to do in 10-20 minute bites between (or during) meetings.
;)

	-Sean

-- 
__________________________________________________________________

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.
__________________________________________________________________

[-- Attachment #1.2: Type: application/pgp-signature, Size: 189 bytes --]

[-- Attachment #2: Type: text/plain, Size: 138 bytes --]

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

Re: [PATCH] Add Initial Man Pages for xm and xmdomain.cfg

[M.A. Williamson]

>> We can still check a pre-generated manpage into hg and ship it 
>> readymade; it's just that relying on developers to update the 
>> documentation tends not to work ;-)
>
>I still disagree. :)
>
>If we get this man page stub into the Xen tree, I'll start working on it
>again.  My lack of motivation for this has been not having it there.  This
>is something easy to do in 10-20 minute bites between (or during) meetings.
>;)

OK, if someone can maintain the docs without going insane, that's also an 
acceptable solution ;-) As a general rule and for the sake of your sanity I 
think we should make "doesn't break the documentation" a patch-acceptance 
criterion :-)

Cheers,
Mark

Xen3.0 + Fedora core 4

[shino korah]

Hi,

 I'm trying to booy Xen3.0 with Fedora core 4. I treid
different things as per dev-list archive +
FedoraXenQuickstart tutorial etc.

The error message I get is 
 
  
 
   Root-NFS: No NFS server available
   VFS: Unable to mount root fs via NFS, trying floppy
   VFS: Insert root floppy and press ENTER
 
I'm using Fedora Core 4 on a Pentium III machine

My menu.lst file is 

default=0
timeout=5
splashimage=(hd0,0)/grub/splash.xpm.gz
hiddenmenu
title Xen 3.0 / XenLinux 2.6
        root(hd0,0)
        kernel /xen-3.0.gz dom0_mem=131072
        module /vmlinuz-2.6-xen0 ro
root=/dev/VolGroup00/LogVol00  console=tty0
       

title Fedora Core (2.6.11-1.1369_FC4)
        root (hd0,0)
        kernel /vmlinuz-2.6.11-1.1369_FC4 ro
root=/dev/VolGroup00/LogVol00 rhgb quiet
        initrd /initrd-2.6.11-1.1369_FC4.img

If I add initrd line
        title Xen 3.0 / XenLinux 2.6
        root(hd0,0)
        kernel /xen-3.0.gz dom0_mem=131072
        module /vmlinuz-2.6-xen0 ro
root=/dev/VolGroup00/LogVol00  console=tty0
        initrd /initrd-2.6-xen0.img

It doesn't even start booting, it says "kernel has to
be loaded before initrd"

What am I doing wrong?








	
		
__________________________________ 
Yahoo! Mail - PC Magazine Editors' Choice 2005 
http://mail.yahoo.com

Re: [PATCH] Add Initial Man Pages for xm and xmdomain.cfg

[Daniel Stekloff]

On Sat, 2005-10-29 at 20:13 +0100, M.A. Williamson wrote:
> >> We can still check a pre-generated manpage into hg and ship it 
> >> readymade; it's just that relying on developers to update the 
> >> documentation tends not to work ;-)
> >
> >I still disagree. :)
> >
> >If we get this man page stub into the Xen tree, I'll start working on it
> >again.  My lack of motivation for this has been not having it there.  This
> >is something easy to do in 10-20 minute bites between (or during) meetings.
> >;)
> 
> OK, if someone can maintain the docs without going insane, that's also an 
> acceptable solution ;-) As a general rule and for the sake of your sanity I 
> think we should make "doesn't break the documentation" a patch-acceptance 
> criterion :-)


Does the patch break the documentation build? I applied it to a clean
tree and made that tree to test it. I didn't see any errors and the docs
seemed to be made ok. I'm sorry if it broke documentation. Please let me
know if I need to fix something.

Sorry,

Dan

Re: [PATCH] Add Initial Man Pages for xm and xmdomain.cfg

[Mark Williamson]

> Does the patch break the documentation build?

No!  I wasn't criticising your patch; I think it's great to have more man 
pages in there.

I just meant that developers in general have a very strong tendancy to come 
along and break manpages (and other docs) by changing what the code actually 
does...  A "don't make the docs wrong" policy on patches would keep us 
honest ;-)

Cheers,
Mark

> I applied it to a clean 
> tree and made that tree to test it. I didn't see any errors and the docs
> seemed to be made ok. I'm sorry if it broke documentation. Please let me
> know if I need to fix something.
>
> Sorry,
>
> Dan