From patchwork Fri Dec 9 16:17:07 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Cedric Bosdonnat X-Patchwork-Id: 9468599 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id D1DE6607DA for ; Fri, 9 Dec 2016 16:20:02 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id B85312864E for ; Fri, 9 Dec 2016 16:20:02 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id AC2E528653; Fri, 9 Dec 2016 16:20:02 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_MED autolearn=ham version=3.3.1 Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 5408F2864E for ; Fri, 9 Dec 2016 16:19:59 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cFNrT-00080R-81; Fri, 09 Dec 2016 16:17:27 +0000 Received: from mail6.bemta6.messagelabs.com ([193.109.254.103]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cFNrR-0007wn-Bw for xen-devel@lists.xen.org; Fri, 09 Dec 2016 16:17:25 +0000 Received: from [85.158.143.35] by server-4.bemta-6.messagelabs.com id B5/C1-28568-519DA485; Fri, 09 Dec 2016 16:17:25 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFprPIsWRWlGSWpSXmKPExsVyuP0uq67ITa8 Ig5cvmC2WfFzM4sDocXT3b6YAxijWzLyk/IoE1ozZe48xFny6xFixe+lPxgbGk6sZuxi5OIQE ljBKLJh+nbWLkZODTcBeouvPUSYQW0RAWuLa58tgRcwCmxklzk+eyAKSEBbwkvi5cgsziM0io Cqx+uAlNhCbV8BC4l5HH1izhIC8xK62i2BDOQUsJS6d/cIOYgsB1SxZeJ4Vol5Q4uTMJ0AzOY AWqEusnycEEmYGam3eOpt5AiPvLCRVsxCqZiGpWsDIvIpRozi1qCy1SNfIRC+pKDM9oyQ3MTN H19DATC83tbg4MT01JzGpWC85P3cTIzCwGIBgB+PKdYGHGCU5mJREeYuZvCKE+JLyUyozEosz 4otKc1KLDzHKcHAoSfDevw6UEyxKTU+tSMvMAYY4TFqCg0dJhFcFJM1bXJCYW5yZDpE6xajLM e3Z4qdMQix5+XmpUuK810GKBECKMkrz4EbA4u0So6yUMC8j0FFCPAWpRbmZJajyrxjFORiVhH kfgEzhycwrgdv0CugIJqAj5t1wBzmiJBEhJdXAyKCv8Htu3grFpBe5500CHp5/2WQT4nY4f1q 8zabT087eOLFvv8S1vR6TP+r+kDumd3TbOjHtVzlKv4W8H199PnuHd2T0jUDV0/djln5qe8QR vir1aHeN2fmQHU7Tu7a3cMktUzFayL/r3bMnR2X4xGY+deM/F8kp2ul8JlugKOfA5hqfkK8nG pVYijMSDbWYi4oTAeKnT9OyAgAA X-Env-Sender: cbosdonnat@suse.com X-Msg-Ref: server-14.tower-21.messagelabs.com!1481300243!41740264!1 X-Originating-IP: [195.135.221.5] X-SpamReason: No, hits=0.5 required=7.0 tests=BODY_RANDOM_LONG X-StarScan-Received: X-StarScan-Version: 9.1.1; banners=-,-,- X-VirusChecked: Checked Received: (qmail 7169 invoked from network); 9 Dec 2016 16:17:23 -0000 Received: from smtp.nue.novell.com (HELO smtp.nue.novell.com) (195.135.221.5) by server-14.tower-21.messagelabs.com with DHE-RSA-AES256-GCM-SHA384 encrypted SMTP; 9 Dec 2016 16:17:23 -0000 Received: from laptop.vms (mhy71-2-88-167-63-197.fbx.proxad.net [88.167.63.197]) by smtp.nue.novell.com with ESMTP (TLS encrypted); Fri, 09 Dec 2016 17:17:21 +0100 From: =?UTF-8?q?C=C3=A9dric=20Bosdonnat?= To: xen-devel@lists.xen.org Date: Fri, 9 Dec 2016 17:17:07 +0100 Message-Id: <20161209161714.23866-5-cbosdonnat@suse.com> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20161209161714.23866-1-cbosdonnat@suse.com> References: <20161209161714.23866-1-cbosdonnat@suse.com> MIME-Version: 1.0 Cc: Andrew Cooper , Ian Jackson , Wei Liu , =?UTF-8?q?C=C3=A9dric=20Bosdonnat?= Subject: [Xen-devel] [PATCH 04/11] docs: convert xl-disk-configuration into a man page X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xen.org Sender: "Xen-devel" X-Virus-Scanned: ClamAV using ClamSMTP Convert xl-disk-configuration.txt from plain text file to a POD file to get it as a man page. The references to it in the other man pages are also updated. Signed-off-by: Cédric Bosdonnat Acked-by: Wei Liu --- docs/INDEX | 1 - docs/man/xl-disk-configuration.pod.5 | 529 +++++++++++++++++++++++++++++++++++ docs/man/xl.cfg.pod.5.in | 4 +- docs/man/xl.pod.1.in | 7 +- docs/misc/xl-disk-configuration.txt | 359 ------------------------ 5 files changed, 534 insertions(+), 366 deletions(-) create mode 100644 docs/man/xl-disk-configuration.pod.5 delete mode 100644 docs/misc/xl-disk-configuration.txt diff --git a/docs/INDEX b/docs/INDEX index 2cfeef90a9..3a8b9472d8 100644 --- a/docs/INDEX +++ b/docs/INDEX @@ -16,7 +16,6 @@ misc/tscmode TSC Mode HOWTO misc/vbd-interface Xen Guest Disk (VBD) Interface misc/xenstore Xenstore protocol specification misc/xenstore-paths Xenstore path documentation -misc/xl-disk-configuration XL Disk Configuration misc/distro_mapping Distro Directory Layouts misc/dump-core-format Xen Core Dump Format misc/vtd VT-d HOWTO diff --git a/docs/man/xl-disk-configuration.pod.5 b/docs/man/xl-disk-configuration.pod.5 new file mode 100644 index 0000000000..6510536e02 --- /dev/null +++ b/docs/man/xl-disk-configuration.pod.5 @@ -0,0 +1,529 @@ +=head1 NAME + +xl-disk-configuration - XL Disk Configuration Syntax + +=head1 SYNTAX + +This document specifies the xl config file format disk configuration +option. It has the following form: + + disk = [ 'DISKSPEC', 'DISKSPEC', ... ] + +where each C is in this form: + + [=|,]*, + [, [, [, []]]], + [=|,]* + [target=] + +For example, these strings are equivalent: + + /dev/vg/guest-volume,,hda + /dev/vg/guest-volume,raw,hda,rw + format=raw, vdev=hda, access=rw, target=/dev/vg/guest-volume + raw:/dev/vg/guest-volume,hda,w (deprecated, see below) + +As are these: + + /root/image.iso,,hdc,cdrom + /root/image.iso,,hdc,,cdrom + /root/image.iso,raw,hdc,devtype=cdrom + format=raw, vdev=hdc, access=ro, devtype=cdrom, target=/root/image.iso + raw:/root/image.iso,hdc:cdrom,ro (deprecated, see below) + +These might be specified in the domain config file like this: + + disk = [ '/dev/vg/guest-volume,,hda', '/root/image.iso,,hdc,cdrom' ] + + +More formally, the string is a series of comma-separated keyword/value +pairs, flags and positional parameters. Parameters which are not bare +keywords and which do not contain "=" symbols are assigned to the +so-far-unspecified positional parameters, in the order below. The +positional parameters may also be specified explicitly by name. + +Each parameter may be specified at most once, either as a positional +parameter or a named parameter. Default values apply if the parameter +is not specified, or if it is specified with an empty value (whether +positionally or explicitly). + +Whitespace may appear before each parameter and will be ignored. + +=head1 Positional Parameters + +=over 4 + +=item B + +=over 4 + +=item Description + +Block device or image file path. When this is used as a path, F +will be prepended if the path doesn't start with a '/'. + +=item Supported values + +N/A + +=item Deprecated values + +N/A + +=item Default value + +None. While a path is provided in most cases there is an exception: +for a cdrom device, lack of this attribute would imply an empty cdrom +drive. + +=item Special syntax + +When this parameter is specified by name, ie with the C +syntax in the configuration file, it consumes the whole rest of the +C including trailing whitespaces. Therefore in that case +it must come last. This is permissible even if an empty value for +the target was already specified as a positional parameter. This +is the only way to specify a target string containing metacharacters +such as commas and (in some cases) colons, which would otherwise be +misinterpreted. + +Future parameter and flag names will start with an ascii letter and +contain only ascii alphanumerics, hyphens and underscores, and will +not be legal as vdevs. Targets which might match that syntax +should not be specified as positional parameters. + +=back + +=item B + +=over 4 + +=item Description + +Specifies the format of image file. + +=item Supported values + +raw, qcow, qcow2, vhd, qed + +=item Deprecated values + +None + +=item Default value + +raw + +=back + +=item B + +=over 4 + +=item Description + +Virtual device as seen by the guest (also referred to as guest drive +designation in some specifications). L + +=item Supported values + +hd[x], xvd[x], sd[x] etc. Please refer to the above specification for +further details. + +=item Deprecated values + +None + +=item Default Value + +None, this parameter is mandatory. + +=back + +=item B + +=over 4 + +=item Description + +Specified access control information. Whether or not the block device is +provided to the guest in read-only or read-write mode depends on this +attribute. + +=item Supported values + +C, C (specifies read-only) + +C, C (specifies read/write) + +=item Deprecated values + +None + +=item Default value + +C unless devtype=cdrom, in which case C + +=back + +=back + +=head1 Other Parameters And Flags + +=over 4 + +=item B=I + +=over 4 + +=item Description + +Qualifies virtual device type. + +=item Supported values + +cdrom + +=item Deprecated values + +None + +=item Mandatory + +No + +=back + +=item B + +Convenience alias for "devtype=cdrom". + + +=item B=I + +=over 4 + +=item Description + +Designates a backend domain for the device + +=item Supported values + +Valid domain names + +=item Mandatory + +No + +=back + +Specifies the backend domain which this device should attach to. This +defaults to domain 0. Specifying another domain requires setting up a +driver domain which is outside the scope of this document. + + +=item B=I + +=over 4 + +=item Description + +Specifies the backend implementation to use + +=item Supported values + +phy, tap, qdisk + +=item Mandatory + +No + +=item Default value + +Automatically determine which backend to use. + +=back + +This does not affect the guest's view of the device. It controls +which software implementation of the Xen backend driver is used. + +Not all backend drivers support all combinations of other options. +For example, "phy" does not support formats other than "raw". +Normally this option should not be specified, in which case libxl will +automatically determine the most suitable backend. + + +=item B