Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

[Stefano Stabellini <stefano.stabellini@xxxxxxxxxxxxx>]

On Mon, 7 Nov 2011, Ian Campbell wrote:
> # HG changeset patch
> # User Ian Campbell <ian.campbell@xxxxxxxxxx>
> # Date 1320678758 0
> # Node ID 291f6cb0d03e56e4edbe53c640c96dff85d9bf08
> # Parent  705b2e659ff885379fb8b1c4aefbecfb3b8cc1eb
> docs: add a document describing the xl cfg file syntax
> 
> Based on an initial version by Ian Jackson.
> 
> I believe that all keys are now present in the document although there are are
> various omissions in the actual documentation of them. Hopefully however this
> covers the majority of the most interesting keys.

I think it would be very useful as a manpage.
If we really want to keep it in markdown rather than pod, we could still
find a way to convert it into a manpage (using ronn, pandoc, etc.).


> Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
> 
> diff -r 705b2e659ff8 -r 291f6cb0d03e docs/Makefile
> --- a/docs/Makefile     Mon Nov 07 15:12:08 2011 +0000
> +++ b/docs/Makefile     Mon Nov 07 15:12:38 2011 +0000
> @@ -11,7 +11,7 @@ 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_MARKDOWN   := $(wildcard misc/*.markdown)
> +DOC_MARKDOWN   := $(wildcard misc/*.markdown) $(wildcard user/*.markdown)
>  DOC_PS         := $(patsubst src/%.tex,ps/%.ps,$(DOC_TEX))
>  DOC_PDF                := $(patsubst src/%.tex,pdf/%.pdf,$(DOC_TEX))
>  DOC_HTML       := $(patsubst src/%.tex,html/%/index.html,$(DOC_TEX)) \
> diff -r 705b2e659ff8 -r 291f6cb0d03e docs/user/xl-domain-config.markdown
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/docs/user/xl-domain-config.markdown       Mon Nov 07 15:12:38 2011 +0000
> @@ -0,0 +1,554 @@
> + # xl Domain Configuration
> +
> +To create a VM (a domain in Xen terminology, sometimes called a guest)
> +with xl requires the provision of a domain config file.  Typically
> +these live in `/etc/xen/DOMAIN.cfg` where DOMAIN is the name of the
> +domain.
> +
> +## Work In Progress
> +
> +This document is a work in progress and contains items which require
> +further documentation and which are generally incomplete (marked with
> +XXX).  However all options are included here whether or not they are
> +fully documented.
> +
> +Patches to improve incomplete items (or any other item) would be
> +greatfully received on the [xen-devel][] mailing list. Please see
> +[SubmittingXenPatches][] wiki page for information on how to submit a
> +patch to Xen.
> +
> +[xen-devel]: mailto:xen-devel@xxxxxxxxxxxxxxxxxxx
> +[SubmittingXenPatches]: http://wiki.xen.org/xenwiki/SubmittingXenPatches
> +
> +----------------------------------------
> +
> +## Syntax
> +
> +A domain config file consists of a series of `KEY=VALUE` pairs.
> +
> +Some `KEY`s are mandatory, others are global options which apply to
> +any guest type while others relate only to specific guest types
> +(e.g. PV or HVM guests).
> +
> +A value `VALUE` is one of:
> +
> + * `"STRING"`: A string, surrounded by either single or double quotes.
> + * `NUMBER`: A number, in either decimal, octal (using a `0 prefix`)
> +   or hexadecimal (using an `0x` prefix`).
> + * `BOOLEAN`: A `NUMBER` interpreted as `False` (`0`) or `True` (any
> +   other value).
> + * `[ VALUE, VALUE, ... ]`: A list of `VALUES` of the above
> +   types. Lists are homogeneous and are not nested.
> +
> +The semantics of each `KEY` defines which form of `VALUE` is required.
> +
> +----------------------------------------
> +
> +## Mandatory Configuration Items
> +
> +The following key is mandatory for any guest type:
> +
> + * `name="NAME"`: Specifies the name of the domain.  Names of domains
> +   existing on a single host must be unique.
> +
> +## Selecting Guest Type
> +
> + * `builder=hvm`: Specifies that this is to be an HVM domain.  That
> +   is, a fully virtualised computer with emulated BIOS, disk and
> +   network peripherals, etc.  The default is a PV domain, suitable for
> +   hosting Xen-aware guest operating systems.

I think builder=[hvm|pv] would make it clearer what the options are. I
know that the idea is that a pv guest doesn't need this key pair but I
think that as it is can be confusing.

[...]

> +
> +## Devices
> +
> +The following options define the paravirtual, emulated and physical
> +devices which the guest will contain.
> +
> + * `disk=[ "DISK_SPEC_STRING", "DISK_SPEC_STRING", ...]`: Specifies
> +   the disks (both emulated disks and Xen virtual block devices) which
> +   are to be provided to the guest, and what objects on the they
> +   should map to.  See `docs/misc/xl-disk-configuration.txt`.
> +
> + * `vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]`: Specifies the
> +   networking provision (both emulated network adapters, and Xen
> +   virtual interfaces) to provided to the guest.  See
> +   `docs/misc/xl-network-configuration.markdown`.
> +
> + * `vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]`: Specifies the
> +   paravirtual framebuffer devices which should be supplied to the domain.
> +
> +   This options does not control the emulated graphics card presented
> +   to an HVM guest. See "Emulated VGA Graphics Device" below for how
> +   to configure the emulated device.

and it is only relevant for PV guests.

[...]

> + * `tsc_mode=VALUE`: Specifies how the TSC (Time Stamp Counter) should
> +   be provided to the guest.  XXX ???

see docs/misc/tscmode.txt


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