* [PATCH 00/11] Convert a few docs/misc pages into man pages
@ 2016-12-09 16:17 Cédric Bosdonnat
2016-12-09 16:17 ` [PATCH 01/11] docs: allow writing man pages in markdown Cédric Bosdonnat
` (11 more replies)
0 siblings, 12 replies; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, Cédric Bosdonnat
As pointed out in Ian and Andrew's emails on my recent docs improvement
attempt, getting the documents from docs/misc referenced in man pages
as man pages would would make these pages more visible for users. This
would also not break the docs html INDEX.
This series adds ability to write markdown man pages. Be aware that
markdown man pages can't link to other man pages.
I also added some pages to man 7 (Misc) section.
Cédric Bosdonnat (11):
docs: allow writing man pages in markdown
docs: add rules for man 7 section
docs: xl-network-configuration turns into a man
docs: convert xl-disk-configuration into a man page
docs: move vbd-interface from misc to man
docs: move xl-numa-placement.markdown to man7
docs: move vtpm from misc to man
docs: convert vtpmmgr into a pod man page
docs: convert misc/channel.txt into xen-pv-channel man page
docs: move pci-device-reservations from misc to man
docs: convert tscmode.txt into man page
.gitignore | 1 +
docs/INDEX | 5 -
docs/Makefile | 57 ++-
docs/{misc/tscmode.txt => man/tscmode.pod.7} | 109 +++--
.../vbd-interface.markdown.7} | 0
docs/{misc/vtpm.txt => man/vtpm.pod.7} | 364 +++++++-------
docs/{misc/vtpmmgr.txt => man/vtpmmgr.pod.7} | 351 ++++++++------
docs/man/xen-pci-device-reservations.pod.7 | 84 ++++
.../channel.txt => man/xen-pv-channel.markdown.7} | 20 +-
docs/man/xl-disk-configuration.pod.5 | 529 +++++++++++++++++++++
.../xl-network-configuration.markdown.5} | 0
.../xl-numa-placement.markdown.7} | 0
docs/man/xl.cfg.pod.5.in | 21 +-
docs/man/xl.pod.1.in | 11 +-
docs/misc/pci-device-reservations.txt | 58 ---
docs/misc/xl-disk-configuration.txt | 359 --------------
16 files changed, 1162 insertions(+), 807 deletions(-)
rename docs/{misc/tscmode.txt => man/tscmode.pod.7} (89%)
rename docs/{misc/vbd-interface.txt => man/vbd-interface.markdown.7} (100%)
rename docs/{misc/vtpm.txt => man/vtpm.pod.7} (57%)
rename docs/{misc/vtpmmgr.txt => man/vtpmmgr.pod.7} (54%)
create mode 100644 docs/man/xen-pci-device-reservations.pod.7
rename docs/{misc/channel.txt => man/xen-pv-channel.markdown.7} (92%)
create mode 100644 docs/man/xl-disk-configuration.pod.5
rename docs/{misc/xl-network-configuration.markdown => man/xl-network-configuration.markdown.5} (100%)
rename docs/{misc/xl-numa-placement.markdown => man/xl-numa-placement.markdown.7} (100%)
delete mode 100644 docs/misc/pci-device-reservations.txt
delete mode 100644 docs/misc/xl-disk-configuration.txt
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH 01/11] docs: allow writing man pages in markdown
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
@ 2016-12-09 16:17 ` Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 02/11] docs: add rules for man 7 section Cédric Bosdonnat
` (10 subsequent siblings)
11 siblings, 1 reply; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, Cédric Bosdonnat
Some of the docs/misc documents are written in markdown language.
As an effort to cleanup man pages these documents will be converted into
man pages. To avoid some more conversion, add rules to the docs/Makefile
to generate man pages out of markdown files as well as pod ones.
However, pandoc doesn't know how to convert man pages links. Thus the
man links in markdown pages won't work.
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
---
docs/Makefile | 48 ++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 42 insertions(+), 6 deletions(-)
diff --git a/docs/Makefile b/docs/Makefile
index e2537e8755..d3f5eb607c 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -3,13 +3,14 @@ include $(XEN_ROOT)/Config.mk
-include $(XEN_ROOT)/config/Docs.mk
VERSION := $(shell $(MAKE) -C $(XEN_ROOT)/xen --no-print-directory xenversion)
+DATE := $(shell date +%Y-%m-%d)
DOC_ARCHES := arm x86_32 x86_64
# Documentation sources to build
-MAN1SRC-y := $(sort $(shell find man/ -name '*.pod.1' -print))
-MAN5SRC-y := $(sort $(shell find man/ -name '*.pod.5' -print))
-MAN8SRC-y := $(sort $(shell find man/ -name '*.pod.8' -print))
+MAN1SRC-y := $(sort $(shell find man/ -regex '.*\.\(pod\|markdown\)\.1' -print))
+MAN5SRC-y := $(sort $(shell find man/ -regex '.*\.\(pod\|markdown\)\.5' -print))
+MAN8SRC-y := $(sort $(shell find man/ -regex '.*\.\(pod\|markdown\)\.8' -print))
MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
@@ -18,11 +19,17 @@ TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print))
PANDOCSRC-y := $(sort $(shell find features/ misc/ specs/ -name '*.pandoc' -print))
# Documentation targets
-DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y))
-DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(MAN5SRC-y))
-DOC_MAN8 := $(patsubst man/%.pod.8,man8/%.8,$(MAN8SRC-y))
+DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y)) \
+ $(patsubst man/%.markdown.1,man1/%.1,$(MAN1SRC-y))
+DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(MAN5SRC-y)) \
+ $(patsubst man/%.markdown.5,man5/%.5,$(MAN5SRC-y))
+DOC_MAN8 := $(patsubst man/%.pod.8,man8/%.8,$(MAN8SRC-y)) \
+ $(patsubst man/%.markdown.8,man8/%.8,$(MAN8SRC-y))
DOC_HTML := $(patsubst %.markdown,html/%.html,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,html/%.html,$(PANDOCSRC-y)) \
+ $(patsubst man/%.markdown.1,html/man/%.1.html,$(MAN1SRC-y)) \
+ $(patsubst man/%.markdown.5,html/man/%.5.html,$(MAN5SRC-y)) \
+ $(patsubst man/%.markdown.8,html/man/%.8.html,$(MAN8SRC-y)) \
$(patsubst man/%.pod.1,html/man/%.1.html,$(MAN1SRC-y)) \
$(patsubst man/%.pod.5,html/man/%.5.html,$(MAN5SRC-y)) \
$(patsubst man/%.pod.8,html/man/%.8.html,$(MAN8SRC-y)) \
@@ -31,6 +38,9 @@ DOC_HTML := $(patsubst %.markdown,html/%.html,$(MARKDOWNSRC-y)) \
DOC_TXT := $(patsubst %.txt,txt/%.txt,$(TXTSRC-y)) \
$(patsubst %.markdown,txt/%.txt,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,txt/%.txt,$(PANDOCSRC-y)) \
+ $(patsubst man/%.markdown.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
+ $(patsubst man/%.markdown.5,txt/man/%.5.txt,$(MAN5SRC-y)) \
+ $(patsubst man/%.markdown.8,txt/man/%.8.txt,$(MAN8SRC-y)) \
$(patsubst man/%.pod.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
$(patsubst man/%.pod.5,txt/man/%.5.txt,$(MAN5SRC-y)) \
$(patsubst man/%.pod.8,txt/man/%.8.txt,$(MAN8SRC-y))
@@ -89,6 +99,16 @@ else
@echo "pod2man not installed; skipping $$@"
endif
+man$(1)/%.$(1): man/%.markdown.$(1) Makefile
+ifneq ($(PANDOC),)
+ @$(INSTALL_DIR) $$(@D)
+ $(PANDOC) --standalone -V title=$$* -V section=$(1) \
+ -V date="$(DATE)" -V footer="$(VERSION)" \
+ -V header=Xen $$< -t man --output $$@
+else
+ @echo "pandoc not installed; skipping $$@"
+endif
+
# HTML manpages
html/man/%.$(1).html: man/%.pod.$(1) Makefile
ifneq ($(POD2HTML),)
@@ -98,6 +118,14 @@ else
@echo "pod2html not installed; skipping $$@"
endif
+html/man/%.$(1).html: man/%.markdown.$(1) Makefile
+ifneq ($(PANDOC),)
+ @$(INSTALL_DIR) $$(@D)
+ $(PANDOC) --standalone $$< -t html --toc --output $$@
+else
+ @echo "pandoc not installed; skipping $$@"
+endif
+
# Text manpages
txt/man/%.$(1).txt: man/%.pod.$(1) Makefile
ifneq ($(POD2TEXT),)
@@ -107,6 +135,14 @@ else
@echo "pod2text not installed; skipping $$@"
endif
+txt/man/%.$(1).txt: man/%.markdown.$(1) Makefile
+ifneq ($(PANDOC),)
+ @$(INSTALL_DIR) $$(@D)
+ $(PANDOC) --standalone $$< -t plain --output $$@
+else
+ @echo "pandoc not installed; skipping $$@"
+endif
+
# Build
.PHONY: man$(1)-pages
man$(1)-pages: $$(DOC_MAN$(1))
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [PATCH 02/11] docs: add rules for man 7 section
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
2016-12-09 16:17 ` [PATCH 01/11] docs: allow writing man pages in markdown Cédric Bosdonnat
@ 2016-12-09 16:17 ` Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2017-01-05 12:00 ` Wei Liu
2016-12-09 16:17 ` [PATCH 03/11] docs: xl-network-configuration turns into a man Cédric Bosdonnat
` (9 subsequent siblings)
11 siblings, 2 replies; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, Cédric Bosdonnat
Some of the docs/misc documents will need to go in man 7 section,
prepare docs/Makefile for it.
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
---
.gitignore | 1 +
docs/Makefile | 9 ++++++++-
2 files changed, 9 insertions(+), 1 deletion(-)
diff --git a/.gitignore b/.gitignore
index a2f34a14cb..7584956383 100644
--- a/.gitignore
+++ b/.gitignore
@@ -45,6 +45,7 @@ docs/man/xl.cfg.pod.5
docs/man/xl.pod.1
docs/man1/
docs/man5/
+docs/man7/
docs/man8/
docs/pdf/
docs/txt/
diff --git a/docs/Makefile b/docs/Makefile
index d3f5eb607c..e064de0b77 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -10,6 +10,7 @@ DOC_ARCHES := arm x86_32 x86_64
# Documentation sources to build
MAN1SRC-y := $(sort $(shell find man/ -regex '.*\.\(pod\|markdown\)\.1' -print))
MAN5SRC-y := $(sort $(shell find man/ -regex '.*\.\(pod\|markdown\)\.5' -print))
+MAN7SRC-y := $(sort $(shell find man/ -regex '.*\.\(pod\|markdown\)\.7' -print))
MAN8SRC-y := $(sort $(shell find man/ -regex '.*\.\(pod\|markdown\)\.8' -print))
MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
@@ -23,15 +24,19 @@ DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y)) \
$(patsubst man/%.markdown.1,man1/%.1,$(MAN1SRC-y))
DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(MAN5SRC-y)) \
$(patsubst man/%.markdown.5,man5/%.5,$(MAN5SRC-y))
+DOC_MAN7 := $(patsubst man/%.pod.7,man7/%.7,$(MAN7SRC-y)) \
+ $(patsubst man/%.markdown.7,man7/%.7,$(MAN7SRC-y))
DOC_MAN8 := $(patsubst man/%.pod.8,man8/%.8,$(MAN8SRC-y)) \
$(patsubst man/%.markdown.8,man8/%.8,$(MAN8SRC-y))
DOC_HTML := $(patsubst %.markdown,html/%.html,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,html/%.html,$(PANDOCSRC-y)) \
$(patsubst man/%.markdown.1,html/man/%.1.html,$(MAN1SRC-y)) \
$(patsubst man/%.markdown.5,html/man/%.5.html,$(MAN5SRC-y)) \
+ $(patsubst man/%.markdown.7,html/man/%.7.html,$(MAN7SRC-y)) \
$(patsubst man/%.markdown.8,html/man/%.8.html,$(MAN8SRC-y)) \
$(patsubst man/%.pod.1,html/man/%.1.html,$(MAN1SRC-y)) \
$(patsubst man/%.pod.5,html/man/%.5.html,$(MAN5SRC-y)) \
+ $(patsubst man/%.pod.7,html/man/%.7.html,$(MAN7SRC-y)) \
$(patsubst man/%.pod.8,html/man/%.8.html,$(MAN8SRC-y)) \
$(patsubst %.txt,html/%.txt,$(TXTSRC-y)) \
$(patsubst %,html/hypercall/%/index.html,$(DOC_ARCHES))
@@ -40,9 +45,11 @@ DOC_TXT := $(patsubst %.txt,txt/%.txt,$(TXTSRC-y)) \
$(patsubst %.pandoc,txt/%.txt,$(PANDOCSRC-y)) \
$(patsubst man/%.markdown.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
$(patsubst man/%.markdown.5,txt/man/%.5.txt,$(MAN5SRC-y)) \
+ $(patsubst man/%.markdown.7,txt/man/%.7.txt,$(MAN7SRC-y)) \
$(patsubst man/%.markdown.8,txt/man/%.8.txt,$(MAN8SRC-y)) \
$(patsubst man/%.pod.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
$(patsubst man/%.pod.5,txt/man/%.5.txt,$(MAN5SRC-y)) \
+ $(patsubst man/%.pod.7,txt/man/%.7.txt,$(MAN7SRC-y)) \
$(patsubst man/%.pod.8,txt/man/%.8.txt,$(MAN8SRC-y))
DOC_PDF := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,pdf/%.pdf,$(PANDOCSRC-y))
@@ -166,7 +173,7 @@ clean-man-pages: clean-man$(1)-pages
endef
# Generate manpage rules for each section
-$(foreach i,1 5 8,$(eval $(call GENERATE_MANPAGE_RULES,$(i))))
+$(foreach i,1 5 7 8,$(eval $(call GENERATE_MANPAGE_RULES,$(i))))
.PHONY: install-html
install-html: html txt figs
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [PATCH 03/11] docs: xl-network-configuration turns into a man
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
2016-12-09 16:17 ` [PATCH 01/11] docs: allow writing man pages in markdown Cédric Bosdonnat
2016-12-09 16:17 ` [PATCH 02/11] docs: add rules for man 7 section Cédric Bosdonnat
@ 2016-12-09 16:17 ` Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 04/11] docs: convert xl-disk-configuration into a man page Cédric Bosdonnat
` (8 subsequent siblings)
11 siblings, 1 reply; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, Cédric Bosdonnat
Move docs/misc/xl-network-configuration.markdown to docs/man and
update the references to it in the other man pages.
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
---
docs/INDEX | 1 -
.../xl-network-configuration.markdown.5} | 0
docs/man/xl.cfg.pod.5.in | 4 ++--
docs/man/xl.pod.1.in | 4 ++--
4 files changed, 4 insertions(+), 5 deletions(-)
rename docs/{misc/xl-network-configuration.markdown => man/xl-network-configuration.markdown.5} (100%)
diff --git a/docs/INDEX b/docs/INDEX
index 7d26cf85d4..2cfeef90a9 100644
--- a/docs/INDEX
+++ b/docs/INDEX
@@ -17,7 +17,6 @@ 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/xl-network-configuration XL Network Configuration
misc/distro_mapping Distro Directory Layouts
misc/dump-core-format Xen Core Dump Format
misc/vtd VT-d HOWTO
diff --git a/docs/misc/xl-network-configuration.markdown b/docs/man/xl-network-configuration.markdown.5
similarity index 100%
rename from docs/misc/xl-network-configuration.markdown
rename to docs/man/xl-network-configuration.markdown.5
diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in
index 21b58bc21e..517c7f9910 100644
--- a/docs/man/xl.cfg.pod.5.in
+++ b/docs/man/xl.cfg.pod.5.in
@@ -486,7 +486,7 @@ the host they should map to. See F<docs/misc/xl-disk-configuration.txt>.
Specifies the networking provision (both emulated network adapters,
and Xen virtual interfaces) to provided to the guest. See
-F<docs/misc/xl-network-configuration.markdown>.
+L<xl-network-configuration(5)>.
=item B<vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]>
@@ -2032,7 +2032,7 @@ natively or via hardware backwards compatibility support.
=item F<xl-disk-configuration>
-=item F<xl-network-configuration>
+=item L<xl-network-configuration(5)>
=item F<docs/misc/tscmode.txt>
diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
index 8e2aa5b5af..2937f33003 100644
--- a/docs/man/xl.pod.1.in
+++ b/docs/man/xl.pod.1.in
@@ -1383,7 +1383,7 @@ How the device should be presented to the guest domain; for example "hdc".
Creates a new network device in the domain specified by I<domain-id>.
I<network-device> describes the device to attach, using the same format as the
B<vif> string in the domain config file. See L<xl.cfg> and
-L<http://xenbits.xen.org/docs/unstable/misc/xl-network-configuration.html>
+L<xl-network-configuration(5)>
for more informations.
Note that only attaching PV network interface is supported.
@@ -1797,10 +1797,10 @@ Transcendent Memory.
The following man pages:
L<xl.cfg>(5), L<xlcpupool.cfg>(5), B<xentop>(1)
+L<xl-network-configuration(5)>
And the following documents on the xen.org website:
-L<http://xenbits.xen.org/docs/unstable/misc/xl-network-configuration.html>
L<http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt>
L<http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [PATCH 04/11] docs: convert xl-disk-configuration into a man page
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
` (2 preceding siblings ...)
2016-12-09 16:17 ` [PATCH 03/11] docs: xl-network-configuration turns into a man Cédric Bosdonnat
@ 2016-12-09 16:17 ` Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 05/11] docs: move vbd-interface from misc to man Cédric Bosdonnat
` (7 subsequent siblings)
11 siblings, 1 reply; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, Cédric Bosdonnat
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 <cbosdonnat@suse.com>
---
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<DISKSPEC> is in this form:
+
+ [<key>=<value>|<flag>,]*,
+ [<target>, [<format>, [<vdev>, [<access>]]]],
+ [<key>=<value>|<flag>,]*
+ [target=<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<target>
+
+=over 4
+
+=item Description
+
+Block device or image file path. When this is used as a path, F</dev>
+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<target=>
+syntax in the configuration file, it consumes the whole rest of the
+C<DISKSPEC> 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<format>
+
+=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<vdev>
+
+=over 4
+
+=item Description
+
+Virtual device as seen by the guest (also referred to as guest drive
+designation in some specifications). L<vbd-interface(7)>
+
+=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<access>
+
+=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<ro>, C<r> (specifies read-only)
+
+C<rw>, C<w> (specifies read/write)
+
+=item Deprecated values
+
+None
+
+=item Default value
+
+C<rw> unless devtype=cdrom, in which case C<r>
+
+=back
+
+=back
+
+=head1 Other Parameters And Flags
+
+=over 4
+
+=item B<devtype>=I<DEVTYPE>
+
+=over 4
+
+=item Description
+
+Qualifies virtual device type.
+
+=item Supported values
+
+cdrom
+
+=item Deprecated values
+
+None
+
+=item Mandatory
+
+No
+
+=back
+
+=item B<cdrom>
+
+Convenience alias for "devtype=cdrom".
+
+
+=item B<backend>=I<DOMAIN-NAME>
+
+=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<backendtype>=I<TYPE>
+
+=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<script>=I<SCRIPT>
+
+Specifies that B<target> is not a normal host path, but rather
+information to be interpreted by the executable program I<SCRIPT>,
+(looked for in F</etc/xen/scripts>, if it doesn't contain a slash).
+
+These scripts are normally called "block-I<SCRIPT>".
+
+
+=item B<direct-io-safe>
+
+=over 4
+
+=item Description
+
+Disables non-O_DIRECT workaround
+
+=item Supported values
+
+absent, present
+
+=item Mandatory
+
+No
+
+=item Default value
+
+absent (workaround may be enabled)
+
+=back
+
+There is a memory lifetime bug in some driver domain (dom0) kernels
+which can cause crashes when using O_DIRECT. The bug occurs due to a
+mismatch between the backend-visible lifetime of pages used for the
+Xen PV network protocol and that expected by the backend kernel's
+networking subsystem. This can cause crashes when using certain
+backends with certain underlying storage.
+
+See:
+ L<http://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html>
+
+For this reason, (this version of) the Xen libxl toolstack disables
+O_DIRECT when using the qemu-based Xen PV backend (C<qdisk>).
+
+However, this workaround has performance and scaling implications, and
+it is only necessary if the underlying device is a network filesystem.
+If the underlying device is not, then it is good to disable it; that
+is what this option is for.
+
+This option simply requests that the workaround be disabled. (However,
+not all backends versions which use the workaround understand this
+option, so this is on a best effort basis.)
+
+It's important to note that if you are storing the VM disk on a
+network filesystem or a network block device (NFS or ISCSI) it might
+not be safe to use this option. Otherwise specifying it is safe and
+can give better performances.
+
+If in the future the bug is fixed properly this option will then be
+silently ignored.
+
+
+=item B<discard> / B<no-discard>
+
+=over 4
+
+=item Description
+
+Request that backend advertise discard support to frontend
+
+=item Supported values
+
+discard, no-discard
+
+=item Mandatory
+
+No
+
+=item Default value
+
+discard
+
+=back
+
+An advisory setting for the backend driver, specifying whether to
+advertise discard support (TRIM, UNMAP) to the frontend. The real
+benefit of this option is to be able to force it off rather than on. It
+can be used to disable "hole punching" for file based backends which
+were intentionally created non-sparse to avoid fragmentation of the
+file.
+
+=back
+
+
+=head1 COLO Parameters
+
+=over 4
+
+=item B<colo>
+
+Enable COLO HA for disk. For better understanding block replication on
+QEMU, please refer to: L<http://wiki.qemu.org/Features/BlockReplication>
+Note that the COLO configuration settings should be considered unstable.
+They may change incompatibly in future versions of Xen.
+
+
+=item B<colo-host>
+
+=over 4
+
+=item Description
+
+Secondary host's address
+
+=item Mandatory
+
+Yes when COLO enabled
+
+=back
+
+=item B<colo-port>
+
+=over 4
+
+=item Description
+
+Secondary port. We will run a nbd server on secondary host,
+and the nbd server will listen this port.
+
+=item Mandatory
+
+Yes when COLO enabled
+
+=back
+
+=item B<colo-export>
+
+=over 4
+
+=item Description
+
+We will run a nbd server on secondary host, exportname is
+the nbd server's disk export name.
+
+=item Mandatory
+
+Yes when COLO enabled
+
+=back
+
+=item B<active-disk>
+
+=over 4
+
+=item Description
+
+This is used by secondary. Secondary guest's write will be buffered in this
+disk.
+
+=item Mandatory
+
+Yes when COLO enabled
+
+=back
+
+=item B<hidden-disk>
+
+=over 4
+
+=item Description
+
+This is used by secondary. It buffers the original content that is modified
+by the primary VM.
+
+=item Mandatory
+
+Yes when COLO enabled
+
+=back
+
+=back
+
+
+=head1 Deprecated Parameters, Prefixes And Syntaxes
+
+Deprecated forms are acceptable and are intended work compatibly with
+xend and xl from xen 4.1. In future they may print a warning.
+Support for deprecated parameters and syntaxes are likely to be
+dropped in future versions of xl.
+
+There is support for a deprecated old syntax for C<DISKSPEC>:
+
+ [<format>:][<target>],<vdev>[:<devtype>],<access> (deprecated)
+
+This syntax also supports deprecated prefixes, described below. These
+are found prepended to the format parameter - eg C<tap:aio:qcow:>.
+
+=over 4
+
+=item B<format>
+
+=over 4
+
+=item Description
+
+Specifies the format (deprecated)
+
+=item Supported values
+
+raw: qcow2: vhd: qed:
+
+=back
+
+In xend and old versions of libxl it was necessary to specify the
+format with a prefix. For compatibility, these three prefixes are
+recognised as specifying the corresponding format. They are
+equivalent to C<format=FORMAT> or the specification of B<format>
+(without a colon) as a positional parameter.
+
+
+=item B<script>
+
+=over 4
+
+=item Description
+
+Specifies the script (deprecated)
+
+=item Supported values
+
+iscsi: nbd: enbd: drbd:
+
+=back
+
+In xend and old versions of libxl it was necessary to specify the
+"script" (see above) with a prefix. For compatibility, these four
+prefixes are recognised as specifying the corresponding script. They
+are equivalent to C<script=block-SCRIPT>.
+
+
+=item B<deprecated-prefix>
+
+=over 4
+
+=item Description
+
+Deprecated prefix, ignored
+
+=item Supported values
+
+tapdisk: tap2: aio: ioemu: file: phy:
+
+=back
+
+Various prefixes were required by xend and older versions of libxl to
+make the block devices work. In some cases these options would
+override the backend type, but in other cases they would be ignored in
+favour of "making it work"; in yet other cases it would be necessary
+to specify several of these, for example:
+
+ tap:aio:/some/path...
+
+All of these prefixes are now stripped and ignored.
+
+=back
+
+=head2 Missing format and empty target
+
+The following syntax is also supported:
+
+ ,<vdev>:<devtype>,<access> (deprecated)
+
+This is solely for compatibility with xend's syntax for empty cdroms,
+which is (for example) C<,hdc:cdrom,r>.
diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in
index 517c7f9910..7fc8f55970 100644
--- a/docs/man/xl.cfg.pod.5.in
+++ b/docs/man/xl.cfg.pod.5.in
@@ -480,7 +480,7 @@ devices which the guest will contain.
Specifies the disks (both emulated disks and Xen virtual block
devices) which are to be provided to the guest, and what objects on
-the host they should map to. See F<docs/misc/xl-disk-configuration.txt>.
+the host they should map to. See L<xl-disk-configuration(5)>.
=item B<vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]>
@@ -2030,7 +2030,7 @@ natively or via hardware backwards compatibility support.
=item L<xlcpupool.cfg(5)>
-=item F<xl-disk-configuration>
+=item L<xl-disk-configuration(5)>
=item L<xl-network-configuration(5)>
diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.pod.1.in
index 2937f33003..09c1faae13 100644
--- a/docs/man/xl.pod.1.in
+++ b/docs/man/xl.pod.1.in
@@ -1315,7 +1315,7 @@ The domain id of the guest domain that the device will be attached to.
A disc specification in the same format used for the B<disk> variable in
the domain config file. See
-L<http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt>.
+L<xl-disk-configuration(5)>.
=back
@@ -1354,7 +1354,7 @@ How the device should be presented to the guest domain; for example "hdc".
the target path in the backend domain (usually domain 0) to be
exported; Can be a block device or a file etc. See B<target> in
-F<docs/misc/xl-disk-configuration.txt>.
+L<xl-disk-configuration(5)>.
=back
@@ -1796,12 +1796,11 @@ Transcendent Memory.
The following man pages:
-L<xl.cfg>(5), L<xlcpupool.cfg>(5), B<xentop>(1)
+L<xl.cfg>(5), L<xlcpupool.cfg>(5), L<xentop>(1), L<xl-disk-configuration(5)>
L<xl-network-configuration(5)>
And the following documents on the xen.org website:
-L<http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt>
L<http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>
diff --git a/docs/misc/xl-disk-configuration.txt b/docs/misc/xl-disk-configuration.txt
deleted file mode 100644
index 310d2586c0..0000000000
--- a/docs/misc/xl-disk-configuration.txt
+++ /dev/null
@@ -1,359 +0,0 @@
- ---------------------
- XL DISK CONFIGURATION
- ---------------------
-
-This document specifies the xl config file format disk configuration
-option. It has the following form:
-
- disk = [ '<diskspec>', '<diskspec>', ... ]
-
-where each diskspec is in this form:
-
- [<key>=<value>|<flag>,]*,
- [<target>, [<format>, [<vdev>, [<access>]]]],
- [<key>=<value>|<flag>,]*
- [target=<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.
-
-
-=====================
-POSITIONAL PARAMETERS
-=====================
-
-target
-------
-
-Description: Block device or image file path. When this is
- used as a path, /dev will be prepended
- if the path doesn't start with a '/'.
-Supported values: N/A
-Deprecated values: N/A
-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.
-
-Special syntax:
-
- When this parameter is specified by name, ie with the "target="
- syntax in the configuration file, it consumes the whole rest of the
- <diskspec> 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.
-
-
-format
-------
-
-Description: Specifies the format of image file.
-Supported values: raw, qcow, qcow2, vhd, qed
-Deprecated values: None
-Default value: raw
-
-
-vdev
-----
-
-Description: Virtual device as seen by the guest (also
- referred to as guest drive designation in some
- specifications). See docs/misc/vbd-interface.txt.
-Supported values: hd[x], xvd[x], sd[x] etc. Please refer to the
- above specification for further details.
-Deprecated values: None
-Default Value: None, this parameter is mandatory.
-
-
-access
--------
-
-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.
-Supported values: ro, r (specifies read-only)
- rw, w (specifies read/write)
-Deprecated values: None
-Default value: rw
- unless devtype=cdrom, in which case r
-
-
-
-==========================
-OTHER PARAMETERS AND FLAGS
-==========================
-
-
-devtype=<devtype>
------------------
-
-Description: Qualifies virtual device type.
-Supported values: cdrom
-Deprecated values: None
-Mandatory: No
-
-
-cdrom
------
-
-Convenience alias for "devtype=cdrom".
-
-
-backend=<domain-name>
----------------------
-
-Description: Designates a backend domain for the device
-Supported values: Valid domain names
-Mandatory: No
-
-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.
-
-
-backendtype=<backend-type>
---------------------------
-
-Description: Specifies the backend implementation to use
-Supported values: phy, tap, qdisk
-Mandatory: No
-Default value: Automatically determine which backend to use.
-
-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.
-
-
-script=<script>
----------------
-
-Specifies that <target> is not a normal host path, but rather
-information to be interpreted by the executable program <script>,
-(looked for in /etc/xen/scripts, if it doesn't contain a slash).
-
-These scripts are normally called "block-<script>".
-
-
-direct-io-safe
---------------
-
-Description: Disables non-O_DIRECT workaround
-Supported values: absent, present
-Mandatory: No
-Default value: absent (workaround may be enabled)
-
-There is a memory lifetime bug in some driver domain (dom0) kernels
-which can cause crashes when using O_DIRECT. The bug occurs due to a
-mismatch between the backend-visible lifetime of pages used for the
-Xen PV network protocol and that expected by the backend kernel's
-networking subsystem. This can cause crashes when using certain
-backends with certain underlying storage.
-
-See:
- http://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html
-
-For this reason, (this version of) the Xen libxl toolstack disables
-O_DIRECT when using the qemu-based Xen PV backend ("qdisk").
-
-However, this workaround has performance and scaling implications, and
-it is only necessary if the underlying device is a network filesystem.
-If the underlying device is not, then it is good to disable it; that
-is what this option is for.
-
-This option simply requests that the workaround be disabled. (However,
-not all backends versions which use the workaround understand this
-option, so this is on a best effort basis.)
-
-It's important to note that if you are storing the VM disk on a
-network filesystem or a network block device (NFS or ISCSI) it might
-not be safe to use this option. Otherwise specifying it is safe and
-can give better performances.
-
-If in the future the bug is fixed properly this option will then be
-silently ignored.
-
-
-discard / no-discard
----------------
-
-Description: Request that backend advertise discard support to frontend
-Supported values: discard
- no-discard
-Mandatory: No
-Default value: discard
-
-An advisory setting for the backend driver, specifying whether to
-advertise discard support (TRIM, UNMAP) to the frontend. The real
-benefit of this option is to be able to force it off rather than on. It
-can be used to disable "hole punching" for file based backends which
-were intentionally created non-sparse to avoid fragmentation of the
-file.
-
-
-===============
-COLO PARAMETERS
-===============
-
-
-colo
-----
-
-Enable COLO HA for disk. For better understanding block replication on
-QEMU, please refer to:
-http://wiki.qemu.org/Features/BlockReplication
-Note that the COLO configuration settings should be considered unstable.
-They may change incompatibly in future versions of Xen.
-
-
-colo-host
----------
-
-Description: Secondary host's address
-Mandatory: Yes when COLO enabled
-
-
-colo-port
----------
-
-Description: Secondary port
- We will run a nbd server on secondary host,
- and the nbd server will listen this port.
-Mandatory: Yes when COLO enabled
-
-
-colo-export
------------
-
-Description: We will run a nbd server on secondary host,
- exportname is the nbd server's disk export name.
-Mandatory: Yes when COLO enabled
-
-
-active-disk
------------
-
-Description: This is used by secondary. Secondary guest's write
- will be buffered in this disk.
-Mandatory: Yes when COLO enabled
-
-
-hidden-disk
------------
-
-Description: This is used by secondary. It buffers the original
- content that is modified by the primary VM.
-Mandatory: Yes when COLO enabled
-
-
-============================================
-DEPRECATED PARAMETERS, PREFIXES AND SYNTAXES
-============================================
-
-Deprecated forms are acceptable and are intended work compatibly with
-xend and xl from xen 4.1. In future they may print a warning.
-Support for deprecated parameters and syntaxes are likely to be
-dropped in future versions of xl.
-
-
-There is support for a deprecated old syntax for <diskspec>:
-
- [<format>:][<target>],<vdev>[:<devtype>],<access> (deprecated)
-
-This syntax also supports deprecated prefixes, described below. These
-are found prepended to the format parameter - eg "tap:aio:qcow:".
-
-
-<format>:
----------
-
-Description: Specifies the format (deprecated)
-Supported values: raw: qcow2: vhd: qed:
-
-In xend and old versions of libxl it was necessary to specify the
-format with a prefix. For compatibility, these three prefixes are
-recognised as specifying the corresponding format. They are
-equivalent to "format=<format>" or the specification of <format>
-(without a colon) as a positional parameter.
-
-
-<script>:
----------
-
-Description: Specifies the script (deprecated)
-Supported values: iscsi: nbd: enbd: drbd:
-
-In xend and old versions of libxl it was necessary to specify the
-"script" (see above) with a prefix. For compatibility, these four
-prefixes are recognised as specifying the corresponding script. They
-are equivalent to "script=block-<script>".
-
-
-<deprecated-prefix>:
---------------------
-
-Description; Deprecated prefix, ignored
-Supported values: tapdisk: tap2: aio: ioemu: file: phy:
-
-Various prefixes were required by xend and older versions of libxl to
-make the block devices work. In some cases these options would
-override the backend type, but in other cases they would be ignored in
-favour of "making it work"; in yet other cases it would be necessary
-to specify several of these, for example:
- "tap:aio:/some/path..."
-
-All of these prefixes are now stripped and ignored.
-
-
-Missing format and empty target
--------------------------------
-
-The following syntax is also supported:
-
- ,<vdev>:<devtype>,<access> (deprecated)
-
-This is soley for compatibility with xend's syntax for empty cdroms,
-which is (for example) ",hdc:cdrom,r".
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [PATCH 05/11] docs: move vbd-interface from misc to man
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
` (3 preceding siblings ...)
2016-12-09 16:17 ` [PATCH 04/11] docs: convert xl-disk-configuration into a man page Cédric Bosdonnat
@ 2016-12-09 16:17 ` Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 06/11] docs: move xl-numa-placement.markdown to man7 Cédric Bosdonnat
` (6 subsequent siblings)
11 siblings, 1 reply; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel
Cc: Stefano Stabellini, Wei Liu, George Dunlap, Andrew Cooper,
Ian Jackson, Tim Deegan, Cédric Bosdonnat, Jan Beulich
Make vbd-interface a man page, section7, as this document is
referenced in other man pages (xl-disk-configuration)
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
---
docs/INDEX | 1 -
docs/{misc/vbd-interface.txt => man/vbd-interface.markdown.7} | 0
2 files changed, 1 deletion(-)
rename docs/{misc/vbd-interface.txt => man/vbd-interface.markdown.7} (100%)
diff --git a/docs/INDEX b/docs/INDEX
index 3a8b9472d8..101d43c7aa 100644
--- a/docs/INDEX
+++ b/docs/INDEX
@@ -13,7 +13,6 @@ misc/crashdb Xen crash debugger notes
misc/grant-tables A Rough Introduction to Using Grant Tables
misc/kexec_and_kdump Kexec and Kdump for Xen
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/distro_mapping Distro Directory Layouts
diff --git a/docs/misc/vbd-interface.txt b/docs/man/vbd-interface.markdown.7
similarity index 100%
rename from docs/misc/vbd-interface.txt
rename to docs/man/vbd-interface.markdown.7
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [PATCH 06/11] docs: move xl-numa-placement.markdown to man7
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
` (4 preceding siblings ...)
2016-12-09 16:17 ` [PATCH 05/11] docs: move vbd-interface from misc to man Cédric Bosdonnat
@ 2016-12-09 16:17 ` Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 07/11] docs: move vtpm from misc to man Cédric Bosdonnat
` (5 subsequent siblings)
11 siblings, 1 reply; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, Cédric Bosdonnat
docs/misc/xl-numa-placement.markdown is referenced by xl.cfg.5 man page,
move it to a man page, section 7.
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
---
.../xl-numa-placement.markdown => man/xl-numa-placement.markdown.7} | 0
docs/man/xl.cfg.pod.5.in | 2 +-
2 files changed, 1 insertion(+), 1 deletion(-)
rename docs/{misc/xl-numa-placement.markdown => man/xl-numa-placement.markdown.7} (100%)
diff --git a/docs/misc/xl-numa-placement.markdown b/docs/man/xl-numa-placement.markdown.7
similarity index 100%
rename from docs/misc/xl-numa-placement.markdown
rename to docs/man/xl-numa-placement.markdown.7
diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in
index 7fc8f55970..fc2faac12b 100644
--- a/docs/man/xl.cfg.pod.5.in
+++ b/docs/man/xl.cfg.pod.5.in
@@ -185,7 +185,7 @@ host cpus and memory. In that case, the soft affinity of all the vcpus
of the domain will be set to the pcpus belonging to the NUMA nodes
chosen during placement.
-For more details, see F<docs/misc/xl-numa-placement.markdown>.
+For more details, see L<xl-numa-placement(7)>.
=back
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [PATCH 07/11] docs: move vtpm from misc to man
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
` (5 preceding siblings ...)
2016-12-09 16:17 ` [PATCH 06/11] docs: move xl-numa-placement.markdown to man7 Cédric Bosdonnat
@ 2016-12-09 16:17 ` Cédric Bosdonnat
2016-12-14 21:08 ` Daniel De Graaf
2016-12-09 16:17 ` [PATCH 08/11] docs: convert vtpmmgr into a pod man page Cédric Bosdonnat
` (4 subsequent siblings)
11 siblings, 1 reply; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel
Cc: Quan Xu, Wei Liu, Andrew Cooper, Ian Jackson,
Cédric Bosdonnat, Daniel De Graaf
vtpm.txt is referenced in xl.cfg man page. Convert it to pod,
move it to the man folder and update the reference.
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
---
docs/INDEX | 1 -
docs/{misc/vtpm.txt => man/vtpm.pod.7} | 364 +++++++++++++++++----------------
docs/man/xl.cfg.pod.5.in | 3 +-
3 files changed, 194 insertions(+), 174 deletions(-)
rename docs/{misc/vtpm.txt => man/vtpm.pod.7} (57%)
diff --git a/docs/INDEX b/docs/INDEX
index 101d43c7aa..66cc82b78c 100644
--- a/docs/INDEX
+++ b/docs/INDEX
@@ -18,7 +18,6 @@ misc/xenstore-paths Xenstore path documentation
misc/distro_mapping Distro Directory Layouts
misc/dump-core-format Xen Core Dump Format
misc/vtd VT-d HOWTO
-misc/vtpm Virtual TPM
misc/xen-error-handling Xen Error Handling
misc/xenpaging Xen Paging
misc/xsm-flask XSM/FLASK Configuration
diff --git a/docs/misc/vtpm.txt b/docs/man/vtpm.pod.7
similarity index 57%
rename from docs/misc/vtpm.txt
rename to docs/man/vtpm.pod.7
index 1887d40d25..03bde1d4eb 100644
--- a/docs/misc/vtpm.txt
+++ b/docs/man/vtpm.pod.7
@@ -7,9 +7,8 @@ This document describes the virtual Trusted Platform Module (vTPM) subsystem
for Xen. The reader is assumed to have familiarity with building and installing
Xen, Linux, and a basic understanding of the TPM and vTPM concepts.
-------------------------------
-INTRODUCTION
-------------------------------
+=head1 INTRODUCTION
+
The goal of this work is to provide a TPM functionality to a virtual guest
operating system (a DomU). This allows programs to interact with a TPM in a
virtual system the same way they interact with a TPM on the physical system.
@@ -25,99 +24,114 @@ mini-os to reduce memory and processor overhead.
This mini-os vTPM subsystem was built on top of the previous vTPM work done by
IBM and Intel corporation.
-------------------------------
-DESIGN OVERVIEW
-------------------------------
+=head1 DESIGN OVERVIEW
The architecture of vTPM is described below:
-+------------------+
-| Linux DomU | ...
-| | ^ |
-| v | |
-| xen-tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpm-stubdom | ...
-| | ^ |
-| v | |
-| mini-os/tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpmmgr-stubdom |
-| | ^ |
-| v | |
-| mini-os/tpm_tis |
-+------------------+
- | ^
- v |
-+------------------+
-| Hardware TPM |
-+------------------+
- * Linux DomU: The Linux based guest that wants to use a vTPM. There many be
- more than one of these.
-
- * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver
- provides vTPM access to a para-virtualized Linux based DomU.
-
- * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver
- connects to this backend driver to facilitate
- communications between the Linux DomU and its vTPM. This
- driver is also used by vtpmmgr-stubdom to communicate with
- vtpm-stubdom.
-
- * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a
- one to one mapping between running vtpm-stubdom instances and
- logical vtpms on the system. The vTPM Platform Configuration
- Registers (PCRs) are all initialized to zero.
-
- * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain
- vtpm-stubdom uses this driver to communicate with
- vtpmmgr-stubdom. This driver could also be used separately to
- implement a mini-os domain that wishes to use a vTPM of
- its own.
-
- * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager.
- There is only one vTPM manager and it should be running during
- the entire lifetime of the machine. This domain regulates
- access to the physical TPM on the system and secures the
- persistent state of each vTPM.
-
- * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS)
- driver. This driver used by vtpmmgr-stubdom to talk directly to
- the hardware TPM. Communication is facilitated by mapping
- hardware memory pages into vtpmmgr-stubdom.
-
- * Hardware TPM: The physical TPM that is soldered onto the motherboard.
-
-------------------------------
-INSTALLATION
-------------------------------
-
-Prerequisites:
---------------
+ +------------------+
+ | Linux DomU | ...
+ | | ^ |
+ | v | |
+ | xen-tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpm-stubdom | ...
+ | | ^ |
+ | v | |
+ | mini-os/tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpmmgr-stubdom |
+ | | ^ |
+ | v | |
+ | mini-os/tpm_tis |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | Hardware TPM |
+ +------------------+
+
+=over 4
+
+=item Linux DomU
+
+The Linux based guest that wants to use a vTPM. There many be
+more than one of these.
+
+=item xen-tpmfront.ko
+
+Linux kernel virtual TPM frontend driver. This driver
+provides vTPM access to a para-virtualized Linux based DomU.
+
+=item mini-os/tpmback
+
+Mini-os TPM backend driver. The Linux frontend driver
+connects to this backend driver to facilitate
+communications between the Linux DomU and its vTPM. This
+driver is also used by vtpmmgr-stubdom to communicate with
+vtpm-stubdom.
+
+=item vtpm-stubdom
+
+A mini-os stub domain that implements a vTPM. There is a
+one to one mapping between running vtpm-stubdom instances and
+logical vtpms on the system. The vTPM Platform Configuration
+Registers (PCRs) are all initialized to zero.
+
+=item mini-os/tpmfront
+
+Mini-os TPM frontend driver. The vTPM mini-os domain
+vtpm-stubdom uses this driver to communicate with
+vtpmmgr-stubdom. This driver could also be used separately to
+implement a mini-os domain that wishes to use a vTPM of
+its own.
+
+=item vtpmmgr-stubdom
+
+A mini-os domain that implements the vTPM manager.
+There is only one vTPM manager and it should be running during
+the entire lifetime of the machine. This domain regulates
+access to the physical TPM on the system and secures the
+persistent state of each vTPM.
+
+=item mini-os/tpm_tis
+
+Mini-os TPM version 1.2 TPM Interface Specification (TIS)
+driver. This driver used by vtpmmgr-stubdom to talk directly to
+the hardware TPM. Communication is facilitated by mapping
+hardware memory pages into vtpmmgr-stubdom.
+
+=item Hardware TPM
+
+The physical TPM that is soldered onto the motherboard.
+
+=back
+
+=head1 INSTALLATION
+
+=head2 Prerequisites:
+
You must have an x86 machine with a TPM on the motherboard. The only extra
software requirement for compiling vTPM is cmake. You must use libxl to manage
domains with vTPMs; 'xm' is deprecated and does not support vTPMs.
-Compiling the Xen tree:
------------------------
+=head2 Compiling the Xen tree:
Compile and install the Xen tree as usual; be sure that the vTPM domains are
enabled when you run configure.
-Compiling the LINUX dom0 kernel:
---------------------------------
+=head2 Compiling the LINUX dom0 kernel:
Because the TPM manager uses direct access to the physical TPM, it may interfere
with access to the TPM by dom0. The simplest solution for this is to prevent
@@ -137,30 +151,25 @@ a later time. If a vTPM gets an error when loading its key, it will currently
generate a fresh vTPM image (with a new EK, SRK, and blank NVRAM).
-Compiling the LINUX domU kernel:
---------------------------------
+=head2 Compiling the LINUX domU kernel:
The domU kernel used by domains with vtpms must include the xen-tpmfront.ko
driver. It can be built directly into the kernel or as a module; however, some
features such as IMA require the TPM to be built in to the kernel.
-CONFIG_TCG_TPM=y
-CONFIG_TCG_XEN=y
+ CONFIG_TCG_TPM=y
+ CONFIG_TCG_XEN=y
-------------------------------
-VTPM MANAGER SETUP
-------------------------------
+=head1 VTPM MANAGER SETUP
-Manager disk image setup:
--------------------------
+=head2 Manager disk image setup:
The vTPM Manager requires a disk image to store its encrypted data. The image
does not require a filesystem and can live anywhere on the host disk. The image
is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image
but can support more than 20,000 vTPMs.
-Manager config file:
---------------------
+=head2 Manager config file:
The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen
virtual machine and requires a config file. The manager requires a disk image
@@ -172,8 +181,7 @@ uses locality 0 (so only the page at 0xfed40 is needed); this can be changed on
the domain's command line. For full functionality in deep quotes, using
locality 2 is required to manipulate PCR 20-22.
-Starting and stopping the manager:
-----------------------------------
+=head2 Starting and stopping the manager:
The vTPM manager should be started at boot; you may wish to create an init
script to do this. If a domain builder is used, the TPM Manager should be
@@ -181,43 +189,39 @@ started by the domain builder to minimize the trusted computing base for the
vTPM manager's secrets.
Once initialization is complete you should see the following:
-INFO[VTPM]: Waiting for commands from vTPM's:
+
+ INFO[VTPM]: Waiting for commands from vTPM's:
The TPM Manager does not respond to shutdown requests; use the destroy command
to shut it down.
-------------------------------
-VTPM AND LINUX PVM SETUP
-------------------------------
+=head1 VTPM AND LINUX PVM SETUP
-vTPM disk image setup:
-----------------------
+=head2 vTPM disk image setup:
The vTPM requires a disk image to store its persistent data (RSA keys, NVRAM,
etc). The image does not require a filesystem. The image does not need to be
large; 2 Mb should be sufficient.
-vTPM config file:
------------------
+=head2 vTPM config file:
The vTPM domain requires a configuration file like any other domain. The vTPM
requires a disk image for storage and a TPM frontend driver to communicate with
the manager. You are required to generate a uuid for this vtpm, which is
-specified on the "vtpm=" line that describes its connection to the vTPM Manager.
+specified on the C<vtpm=> line that describes its connection to the vTPM Manager.
The uuidgen application may be used to generate a uuid, or one from the output
-of the "manage-vtpmmgr.pl vtpm-add" command may be used to create a vTPM
+of the C<manage-vtpmmgr.pl vtpm-add> command may be used to create a vTPM
belonging to a specific group.
If you wish to clear the vTPM data you can either recreate the disk image or
change the uuid.
-Linux Guest config file:
-------------------------
+=head2 Linux Guest config file:
The Linux guest config file needs to be modified to include the Linux tpmfront
driver. Add the following line:
-vtpm=["backend=domu-vtpm"]
+ vtpm=["backend=domu-vtpm"]
Currently only Linux guests are supported (PV or HVM with PV drivers).
@@ -229,34 +233,34 @@ configuration. Attaching a vTPM to a running domain should only be used for
trusted domains or when measurements have already been sent to the vTPM from
another source.
-Using the vTPM in the guest:
-----------------------------
+=head2 Using the vTPM in the guest:
If xen-tpmfront was compiled as a module, it must be loaded it in the guest.
-# modprobe xen-tpmfront
+ # modprobe xen-tpmfront
After the Linux domain boots and the xen-tpmfront driver is loaded, you should
see the following on the vtpm console:
-Info: VTPM attached to Frontend X/Y
+ Info: VTPM attached to Frontend X/Y
You can quickly test the vTPM by using the sysfs interface:
-# cat /sys/devices/vtpm-0/pubek
-# cat /sys/devices/vtpm-0/pcrs
+ # cat /sys/devices/vtpm-0/pubek
+ # cat /sys/devices/vtpm-0/pcrs
If you have trousers and tpm_tools installed on the guest, the tpm_version
command should return the following:
The version command should return the following:
- TPM 1.2 Version Info:
- Chip Version: 1.2.0.7
- Spec Level: 2
- Errata Revision: 1
- TPM Vendor ID: ETHZ
- TPM Version: 01010000
- Manufacturer Info: 4554485a
+
+ TPM 1.2 Version Info:
+ Chip Version: 1.2.0.7
+ Spec Level: 2
+ Errata Revision: 1
+ TPM Vendor ID: ETHZ
+ TPM Version: 01010000
+ Manufacturer Info: 4554485a
You should also see the command being sent to the vtpm console as well as the
vtpm saving its state. You should see the vtpm key being encrypted and stored on
@@ -265,9 +269,7 @@ the vtpmmgr console.
You may wish to write a script to start your vtpm and guest together and to
destroy the vtpm when the guest shuts down.
-------------------------------
-INTEGRATION WITH PV-GRUB
-------------------------------
+=head1 INTEGRATION WITH PV-GRUB
The vTPM currently starts up with all PCRs set to their default values (all
zeros for the lower 16). This means that any decisions about the
@@ -283,16 +285,12 @@ extend the hash of the kernel that it boots into PCR #4, and will extend the
command line and initrd into PCR #5 before booting so that a domU booted in this
way can attest to its early boot state.
-------------------------------
-MORE INFORMATION
-------------------------------
+=head1 MORE INFORMATION
-See vtpmmgr.txt for more details about how the manager domain works, how to use
+See <vtpmmgr(7)> for more details about how the manager domain works, how to use
it, and its command line parameters.
-------------------------------
-VTPM DOMAIN OPERATION
-------------------------------
+=head1 VTPM DOMAIN OPERATION
The vtpm-stubdom is a mini-OS domain that emulates a TPM for the guest OS to
use. It is a small wrapper around the Berlios TPM emulator version 0.7.4.
@@ -302,54 +300,78 @@ machine. The key used to encrypt the data along with a hash of the vTPM's data
is sent to the vTPM manager for secure storage and later retrieval. The vTPM
domain communicates with the manager using a mini-os tpm front/back device pair.
-------------------------------------
-VTPM DOMAIN COMMAND LINE ARGUMENTS
-------------------------------------
+=head1 VTPM DOMAIN COMMAND LINE ARGUMENTS
Command line arguments are passed to the domain via the 'extra' parameter in the
VM config file. Each parameter is separated by white space. For example:
-extra="foo=bar baz"
+ extra="foo=bar baz"
+
+=head2 List of Arguments:
+
+=over 4
+
+=item B<loglevel>=<LOG>
+
+Controls the amount of logging printed to the console.
+The possible values for <LOG> are:
+
+=over 4
+
+=item * error
+
+=item * info (default)
+
+=item * debug
+
+=back
+
+=item B<clear>
+
+Start the Berlios emulator in "clear" mode. (default)
+
+=item B<save>
+
+Start the Berlios emulator in "save" mode.
+
+=item B<deactivated>
+
+Start the Berlios emulator in "deactivated" mode.
+See the Berlios TPM emulator documentation for details
+about the startup mode. For all normal use, always use clear
+which is the default. You should not need to specify any of these.
+
+=item B<maintcmds>=<1|0>
+
+Enable to disable the TPM maintenance commands.
+These commands are used by tpm manufacturers and thus
+open a security hole. They are disabled by default.
+
+=item B<hwinitpcr>=<PCRSPEC>
+
+Initialize the virtual Platform Configuration Registers
+(PCRs) with PCR values from the hardware TPM. Each pcr specified by
+<PCRSPEC> will be initialized with the value of that same PCR in TPM
+once at startup. By default all PCRs are zero initialized.
+Possible values of <PCRSPEC> are:
-List of Arguments:
-------------------
+=over
-loglevel=<LOG>: Controls the amount of logging printed to the console.
- The possible values for <LOG> are:
- error
- info (default)
- debug
+=item * all: copy all pcrs
-clear: Start the Berlios emulator in "clear" mode. (default)
+=item * none: copy no pcrs (default)
-save: Start the Berlios emulator in "save" mode.
+=item * <N>: copy pcr n
-deactivated: Start the Berlios emulator in "deactivated" mode.
- See the Berlios TPM emulator documentation for details
- about the startup mode. For all normal use, always use clear
- which is the default. You should not need to specify any of these.
+=item * <X-Y>: copy pcrs x to y (inclusive)
-maintcmds=<1|0>: Enable to disable the TPM maintenance commands.
- These commands are used by tpm manufacturers and thus
- open a security hole. They are disabled by default.
+=back
-hwinitpcr=<PCRSPEC>: Initialize the virtual Platform Configuration Registers
- (PCRs) with PCR values from the hardware TPM. Each pcr specified by
- <PCRSPEC> will be initialized with the value of that same PCR in TPM
- once at startup. By default all PCRs are zero initialized.
- Value values of <PCRSPEC> are:
- all: copy all pcrs
- none: copy no pcrs (default)
- <N>: copy pcr n
- <X-Y>: copy pcrs x to y (inclusive)
+These can also be combined by comma separation, for example:
+C<hwinitpcrs=5,12-16> will copy pcrs 5, 12, 13, 14, 15, and 16.
- These can also be combined by comma separation, for example:
- hwinitpcrs=5,12-16
- will copy pcrs 5, 12, 13, 14, 15, and 16.
+=back
-------------------------------
-REFERENCES
-------------------------------
+=head1 REFERENCES
-Berlios TPM Emulator:
-http://tpm-emulator.berlios.de/
+Berlios TPM Emulator: L<http://tpm-emulator.berlios.de/>
diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in
index fc2faac12b..33fae038f7 100644
--- a/docs/man/xl.cfg.pod.5.in
+++ b/docs/man/xl.cfg.pod.5.in
@@ -491,8 +491,7 @@ L<xl-network-configuration(5)>.
=item B<vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]>
Specifies the virtual trusted platform module to be
-provided to the guest. Please see F<docs/misc/vtpm.txt>
-for more details.
+provided to the guest. Please see L<vtpm(7)> for more details.
Each B<VTPM_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
settings, from the following list:
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [PATCH 08/11] docs: convert vtpmmgr into a pod man page
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
` (6 preceding siblings ...)
2016-12-09 16:17 ` [PATCH 07/11] docs: move vtpm from misc to man Cédric Bosdonnat
@ 2016-12-09 16:17 ` Cédric Bosdonnat
2016-12-09 16:17 ` [PATCH 09/11] docs: convert misc/channel.txt into xen-pv-channel " Cédric Bosdonnat
` (3 subsequent siblings)
11 siblings, 0 replies; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, Cédric Bosdonnat
vtpmmgr.txt is referenced in a man page, convert it to a man page.
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
---
docs/{misc/vtpmmgr.txt => man/vtpmmgr.pod.7} | 351 ++++++++++++++++-----------
1 file changed, 206 insertions(+), 145 deletions(-)
rename docs/{misc/vtpmmgr.txt => man/vtpmmgr.pod.7} (54%)
diff --git a/docs/misc/vtpmmgr.txt b/docs/man/vtpmmgr.pod.7
similarity index 54%
rename from docs/misc/vtpmmgr.txt
rename to docs/man/vtpmmgr.pod.7
index d4f756c9d1..f2b2ca038e 100644
--- a/docs/misc/vtpmmgr.txt
+++ b/docs/man/vtpmmgr.pod.7
@@ -1,22 +1,30 @@
-================================================================================
-Authors:
- Daniel De Graaf <dgdegra@tycho.nsa.gov>
- Quan Xu <quan.xu@intel.com>
-================================================================================
+=head1 Authors
+
+=over 4
+
+=item Daniel De Graaf <dgdegra@tycho.nsa.gov>
+
+=item Quan Xu <quan.xu@intel.com>
+
+=back
This document describes the operation and command line interface of
-vtpmmgr-stubdom. See docs/misc/vtpm.txt for details on the vTPM subsystem as a
+vtpmmgr-stubdom. See L<vtpm(7)> for details on the vTPM subsystem as a
whole.
-================================================================================
-Overview
-================================================================================
+=head1 Overview
The TPM Manager has three primary functions:
-1. Securely store the encryption keys for vTPMs
-2. Provide a single controlled path of access to the physical TPM
-3. Provide evidence (via TPM Quotes) of the current configuration
+=over 4
+
+=item 1. Securely store the encryption keys for vTPMs
+
+=item 2. Provide a single controlled path of access to the physical TPM
+
+=item 3. Provide evidence (via TPM Quotes) of the current configuration
+
+=back
When combined with a platform that provides a trusted method for creating
domains, the TPM Manager provides assurance that the private keys in a vTPM are
@@ -26,9 +34,7 @@ The manager accepts commands from the vtpm-stubdom domains via the mini-os TPM
backend driver. The vTPM manager communicates directly with hardware TPM using
the mini-os tpm_tis driver.
-================================================================================
-Boot Configurations and TPM Groups
-================================================================================
+=head1 Boot Configurations and TPM Groups
The TPM Manager's data is secured by using the physical TPM's seal operation,
which allows data to be bound to specific PCRs. These PCRs are populated in the
@@ -52,9 +58,7 @@ has its own AIK in the physical TPM for quotes of the hardware TPM state; when
used with a conforming Privacy CA, this allows each group on the system to form
the basis of a distinct identity.
-================================================================================
-Initial Provisioning
-================================================================================
+=head1 Initial Provisioning
When the TPM Manager first boots up, it will create a stub vTPM group along with
entries for any vTPMs that communicate with it. This stub group must be
@@ -73,51 +77,87 @@ group is created, a signed list of boot measurements can be installed. The
initial group controls the ability to boot the system as a whole, and cannot be
deleted once provisioned.
-================================================================================
-Command Line Arguments
-================================================================================
+=head1 Command Line Arguments
Command line arguments are passed to the domain via the 'extra' parameter in the
VM config file. Each parameter is separated by white space. For example:
-extra="foo=bar baz"
+ extra="foo=bar baz"
Valid arguments:
-owner_auth=<AUTHSPEC>
-srk_auth=<AUTHSPEC>
- Set the owner and SRK authdata for the TPM. If not specified, the
- default is 160 zero bits (the well-known auth value). Valid values of
- <AUTHSPEC> are:
- well-known Use the well known auth (default)
- hash:<HASH> Use the given 40-character ASCII hex string
- text:<STR> Use sha1 hash of <STR>.
-
-tpmdriver=<DRIVER>
- Choose the driver used for communication with the hardware TPM. Values
- other than tpm_tis should only be used for testing.
-
- The possible values of <DRIVER> are:
- tpm_tis Direct communication with a hardware TPM 1.2. The
- domain must have access to TPM IO memory. (default)
- tpmfront Use the Xen tpmfront interface to talk to another
- domain which provides access to the TPM.
+=over 4
+
+=item owner_auth=<AUTHSPEC>
+
+=item srk_auth=<AUTHSPEC>
+
+Set the owner and SRK authdata for the TPM. If not specified, the
+default is 160 zero bits (the well-known auth value). Valid values of
+<AUTHSPEC> are:
+
+=over 4
+
+=item well-known
+
+Use the well known auth (default)
+
+=item hash:<HASH>
+
+Use the given 40-character ASCII hex string
+
+=item text:<STR>
+
+Use sha1 hash of <STR>.
+
+=back
+
+=item tpmdriver=<DRIVER>
+
+Choose the driver used for communication with the hardware TPM. Values
+other than tpm_tis should only be used for testing.
+
+The possible values of <DRIVER> are:
+
+=over 4
+
+=item tpm_tis
+
+Direct communication with a hardware TPM 1.2. The
+domain must have access to TPM IO memory. (default)
+
+=item tpmfront
+
+Use the Xen tpmfront interface to talk to another
+domain which provides access to the TPM.
+
+=back
+
+=back
The following options only apply to the tpm_tis driver:
-tpmiomem=<ADDR>: The base address of the hardware memory pages of the TPM.
- The default is 0xfed40000, as defined by the TCG's PC Client spec.
+=over 4
+
+=item tpmiomem=<ADDR>
-tpmirq=<IRQ>: The irq of the hardware TPM if using interrupts. A value of
- "probe" can be set to probe for the irq. A value of 0 disables
- interrupts and uses polling (default 0).
+The base address of the hardware memory pages of the TPM.
+The default is 0xfed40000, as defined by the TCG's PC Client spec.
-tpmlocality=<LOC>: Attempt to use locality <LOC> of the hardware TPM.
- For full functionality of the TPM Manager, this should be set to "2".
+=item tpmirq=<IRQ>
-================================================================================
-Platform Security Assumptions
-================================================================================
+The irq of the hardware TPM if using interrupts. A value of
+"probe" can be set to probe for the irq. A value of 0 disables
+interrupts and uses polling (default 0).
+
+=item tpmlocality=<LOC>
+
+Attempt to use locality <LOC> of the hardware TPM.
+For full functionality of the TPM Manager, this should be set to "2".
+
+=back
+
+=head1 Platform Security Assumptions
While the TPM Manager has the ability to check the hash of the vTPM requesting a
key, there is currently no trusted method to inform the TPM Manager of the hash
@@ -143,9 +183,7 @@ unexpected busy errors from the TPM driver. The ability to access locality 2 of
the TPM should be enforced using IO memory labeling in the XSM policy; the
physical address 0xFED42xxx is always locality 2 for TPMs using the TIS driver.
-================================================================================
-Appendix: unsecured migration process for vtpmmgr domain upgrade
-================================================================================
+=head1 Appendix: unsecured migration process for vtpmmgr domain upgrade
There is no direct upgrade supported from previous versions of the vtpmmgr
domain due to changes in the on-disk format and the method used to seal data.
@@ -156,34 +194,40 @@ If adding migration support to the vTPM is not desired, a simpler migration
domain usable only for local migration can be constructed. The migration process
would look like the following:
-1. Start the old vtpmmgr
-2. Start the vTPM migration domain
-3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr
-4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0
-5. Start the new vtpmmgr, possibly shutting down the old one first
-6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr
-7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1
+=over 4
+
+=item 1. Start the old vtpmmgr
+
+=item 2. Start the vTPM migration domain
+
+=item 3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr
+
+=item 4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0
+
+=item 5. Start the new vtpmmgr, possibly shutting down the old one first
+
+=item 6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr
+
+=item 7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1
+
+=back
This requires the migration domain to be added to the list of valid vTPM kernel
hashes. In the current version of the vtpmmgr domain, this is the hash of the
XSM label, not the kernel.
-================================================================================
-Appendix B: vtpmmgr on TPM 2.0
-================================================================================
+=head1 Appendix B: vtpmmgr on TPM 2.0
-Manager disk image setup:
--------------------------
+=head2 Manager disk image setup:
The vTPM Manager requires a disk image to store its encrypted data. The image
does not require a filesystem and can live anywhere on the host disk. The image
is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image
but can support more than 20,000 vTPMs.
- dd if=/dev/zero of=/home/vtpm2/vmgr bs=16M count=1
+ dd if=/dev/zero of=/home/vtpm2/vmgr bs=16M count=1
-Manager config file:
---------------------
+=head2 Manager config file:
The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen
virtual machine and requires a config file. The manager requires a disk image
@@ -194,9 +238,9 @@ locality) that start at physical address 0xfed40000. By default, the TPM manager
uses locality 0 (so only the page at 0xfed40 is needed).
Add:
-..
+
extra="tpm2=1"
-..
+
extra option to launch vtpmmgr-stubdom domain on TPM 2.0, and ignore it on TPM
1.x. for example:
@@ -208,8 +252,7 @@ extra option to launch vtpmmgr-stubdom domain on TPM 2.0, and ignore it on TPM
extra="tpm2=1"
-Key Hierarchy
-------------------------------
+=head2 Key Hierarchy
+------------------+
| vTPM's secrets | ...
@@ -238,81 +281,99 @@ that users of the vtpmmgr rely on. I will replace TPM2_Bind/TPM2_Unbind with
TPM2_Seal/TPM2_Unseal to provide as much security as it did for TPM 1.2 in later
series of patch.
-DESIGN OVERVIEW
-------------------------------
+=head2 Design Overview
The architecture of vTPM subsystem on TPM 2.0 is described below:
-+------------------+
-| Linux DomU | ...
-| | ^ |
-| v | |
-| xen-tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpm-stubdom | ...
-| | ^ |
-| v | |
-| mini-os/tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpmmgr-stubdom |
-| | ^ |
-| v | |
-| mini-os/tpm2_tis |
-+------------------+
- | ^
- v |
-+------------------+
-| Hardware TPM 2.0 |
-+------------------+
-
- * Linux DomU: The Linux based guest that wants to use a vTPM. There many be
- more than one of these.
-
- * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver
- provides vTPM access to a para-virtualized Linux based DomU.
-
- * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver
- connects to this backend driver to facilitate
- communications between the Linux DomU and its vTPM. This
- driver is also used by vtpmmgr-stubdom to communicate with
- vtpm-stubdom.
-
- * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a
- one to one mapping between running vtpm-stubdom instances and
- logical vtpms on the system. The vTPM Platform Configuration
- Registers (PCRs) are all initialized to zero.
-
- * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain
- vtpm-stubdom uses this driver to communicate with
- vtpmmgr-stubdom. This driver could also be used separately to
- implement a mini-os domain that wishes to use a vTPM of
- its own.
-
- * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager.
- There is only one vTPM manager and it should be running during
- the entire lifetime of the machine. This domain regulates
- access to the physical TPM on the system and secures the
- persistent state of each vTPM.
-
- * mini-os/tpm2_tis: Mini-os TPM version 2.0 TPM Interface Specification (TIS)
- driver. This driver used by vtpmmgr-stubdom to talk directly
- to the hardware TPM 2.0. Communication is facilitated by mapping
- hardware memory pages into vtpmmgr-stubdom.
-
- * Hardware TPM 2.0: The physical TPM 2.0 that is soldered onto the motherboard.
-
----------------------
+ +------------------+
+ | Linux DomU | ...
+ | | ^ |
+ | v | |
+ | xen-tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpm-stubdom | ...
+ | | ^ |
+ | v | |
+ | mini-os/tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpmmgr-stubdom |
+ | | ^ |
+ | v | |
+ | mini-os/tpm2_tis |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | Hardware TPM 2.0 |
+ +------------------+
+
+=over 4
+
+=item Linux DomU
+
+The Linux based guest that wants to use a vTPM. There many be
+more than one of these.
+
+=item xen-tpmfront.ko
+
+Linux kernel virtual TPM frontend driver. This driver
+provides vTPM access to a para-virtualized Linux based DomU.
+
+=item mini-os/tpmback
+
+Mini-os TPM backend driver. The Linux frontend driver
+connects to this backend driver to facilitate
+communications between the Linux DomU and its vTPM. This
+driver is also used by vtpmmgr-stubdom to communicate with
+vtpm-stubdom.
+
+=item vtpm-stubdom
+
+A mini-os stub domain that implements a vTPM. There is a
+one to one mapping between running vtpm-stubdom instances and
+logical vtpms on the system. The vTPM Platform Configuration
+Registers (PCRs) are all initialized to zero.
+
+=item mini-os/tpmfront
+
+Mini-os TPM frontend driver. The vTPM mini-os domain
+vtpm-stubdom uses this driver to communicate with
+vtpmmgr-stubdom. This driver could also be used separately to
+implement a mini-os domain that wishes to use a vTPM of
+its own.
+
+=item vtpmmgr-stubdom
+
+A mini-os domain that implements the vTPM manager.
+There is only one vTPM manager and it should be running during
+the entire lifetime of the machine. This domain regulates
+access to the physical TPM on the system and secures the
+persistent state of each vTPM.
+
+=item mini-os/tpm2_tis
+
+Mini-os TPM version 2.0 TPM Interface Specification (TIS)
+driver. This driver used by vtpmmgr-stubdom to talk directly
+to the hardware TPM 2.0. Communication is facilitated by mapping
+hardware memory pages into vtpmmgr-stubdom.
+
+=item Hardware TPM 2.0
+
+The physical TPM 2.0 that is soldered onto the motherboard.
+
+=back
+
Noted:
functionality for a virtual guest operating system (a DomU) is still TPM 1.2.
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [PATCH 09/11] docs: convert misc/channel.txt into xen-pv-channel man page
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
` (7 preceding siblings ...)
2016-12-09 16:17 ` [PATCH 08/11] docs: convert vtpmmgr into a pod man page Cédric Bosdonnat
@ 2016-12-09 16:17 ` Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 10/11] docs: move pci-device-reservations from misc to man Cédric Bosdonnat
` (2 subsequent siblings)
11 siblings, 1 reply; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, Cédric Bosdonnat
channel.txt is referenced in xl.cfg(5). Move it to man pages, section 7
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
---
.../channel.txt => man/xen-pv-channel.markdown.7} | 20 ++++++++++----------
docs/man/xl.cfg.pod.5.in | 2 +-
2 files changed, 11 insertions(+), 11 deletions(-)
rename docs/{misc/channel.txt => man/xen-pv-channel.markdown.7} (92%)
diff --git a/docs/misc/channel.txt b/docs/man/xen-pv-channel.markdown.7
similarity index 92%
rename from docs/misc/channel.txt
rename to docs/man/xen-pv-channel.markdown.7
index 9fc701a64a..1c6149dae0 100644
--- a/docs/misc/channel.txt
+++ b/docs/man/xen-pv-channel.markdown.7
@@ -94,13 +94,13 @@ Channel name registry
It is important that channel names are globally unique. To help ensure
that no-one's name clashes with yours, please add yours to this list.
-Key:
-N: Name
-C: Contact
-D: Short description of use, possibly including a URL to your software
- or API
-
-N: org.xenproject.guest.clipboard.0.1
-C: David Scott <dave.scott@citrix.com>
-D: Share clipboard data via an in-guest agent. See:
- http://wiki.xenproject.org/wiki/Clipboard_sharing_protocol
+ Key:
+ N: Name
+ C: Contact
+ D: Short description of use, possibly including a URL to your software
+ or API
+
+ N: org.xenproject.guest.clipboard.0.1
+ C: David Scott <dave.scott@citrix.com>
+ D: Share clipboard data via an in-guest agent. See:
+ http://wiki.xenproject.org/wiki/Clipboard_sharing_protocol
diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in
index 33fae038f7..94eada381f 100644
--- a/docs/man/xl.cfg.pod.5.in
+++ b/docs/man/xl.cfg.pod.5.in
@@ -603,7 +603,7 @@ Specifies the virtual channels to be provided to the guest. A
channel is a low-bandwidth, bidirectional byte stream, which resembles
a serial link. Typical uses for channels include transmitting VM
configuration after boot and signalling to in-guest agents. Please see
-F<docs/misc/channels.txt> for more details.
+L<xen-pv-channel(7)> for more details.
Each B<CHANNEL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
settings. Leading and trailing whitespace is ignored in both KEY and
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [PATCH 10/11] docs: move pci-device-reservations from misc to man
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
` (8 preceding siblings ...)
2016-12-09 16:17 ` [PATCH 09/11] docs: convert misc/channel.txt into xen-pv-channel " Cédric Bosdonnat
@ 2016-12-09 16:17 ` Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 11/11] docs: convert tscmode.txt into man page Cédric Bosdonnat
2017-01-04 15:07 ` [PATCH 00/11] Convert a few docs/misc pages into man pages Wei Liu
11 siblings, 1 reply; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, Cédric Bosdonnat
pci-device-reservations is references in xl.cfg(5), convert it as a man
page in pod format. The name is now prefixed with 'xen-' to avoid
possible name conflicts.
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
---
docs/man/xen-pci-device-reservations.pod.7 | 84 ++++++++++++++++++++++++++++++
docs/man/xl.cfg.pod.5.in | 2 +-
docs/misc/pci-device-reservations.txt | 58 ---------------------
3 files changed, 85 insertions(+), 59 deletions(-)
create mode 100644 docs/man/xen-pci-device-reservations.pod.7
delete mode 100644 docs/misc/pci-device-reservations.txt
diff --git a/docs/man/xen-pci-device-reservations.pod.7 b/docs/man/xen-pci-device-reservations.pod.7
new file mode 100644
index 0000000000..dac92764fc
--- /dev/null
+++ b/docs/man/xen-pci-device-reservations.pod.7
@@ -0,0 +1,84 @@
+=head1 Description
+
+PCI vendor ID 0x5853 has been reserved for use by Xen systems in order to
+advertise certain virtual hardware to guest virtual machines. The primary
+use of this is with device ID 0x0001 to advertise the Xen Platform PCI
+device - the presence of this virtual device enables a guest Operating
+System (subject to the availability of suitable drivers) to make use of
+paravirtualisation features such as disk and network devices etc.
+
+Some Xen vendors wish to provide alternative and/or additional guest drivers
+that can bind to virtual devices[1]. This may be done using the Xen PCI
+vendor ID of 0x5853 and Xen-vendor/device specific PCI device IDs. This file
+records reservations made within the device ID range in order to avoid
+multiple Xen vendors using conflicting IDs.
+
+=head1 Guidelines
+
+=over 4
+
+=item 1. A vendor may request a range of device IDs by submitting a patch to
+ this file.
+
+=item 2. Vendor allocations should be in the range 0xc000-0xfffe to reduce the
+ possibility of clashes with community IDs assigned from the bottom up.
+
+=item 3. The vendor is responsible for allocations within the range and should
+ try to record specific device IDs in PCI ID databases such as
+ http://pciids.sourceforge.net and http//www.pcidatabase.com
+
+=back
+
+=head1 Reservations
+
+ range | vendor/product
+ --------------+--------------------------------------------------------------
+ 0x0001 | (Xen Platform PCI device)
+ 0x0002 | Citrix XenServer (grandfathered allocation for XenServer 6.1)
+ 0xc000-0xc0ff | Citrix XenServer
+ 0xc100-0xc1ff | Citrix XenClient
+
+=head1 Notes
+
+=over 4
+
+=item 1.
+
+Upstream QEMU provides a parameterized device called xen-pvdevice that
+can be used to host guest drivers. Execute:
+
+ qemu-system-i386 -device xen-pvdevice,help
+
+for a list of all parameters. The following parameters are relevant to
+driver binding:
+
+=over 4
+
+=item vendor-id (default 0x5853)
+
+The PCI vendor ID and subsystem vendor ID of the device.
+
+=item device-id (must be specified)
+
+The PCI device ID and subsystem device ID of the device.
+
+=item revision (default 0x01)
+
+The PCI revision of the device
+
+=back
+
+Also the size parameter (default 0x400000) can be used to specify the
+size of the single MMIO BAR that the device exposes. This area may be
+used by drivers for mapping grant tables, etc.
+
+Note that the presence of the Xen Platform PCI device is generally a
+pre-requisite for an additional xen-pvdevice as it is the platform
+device that provides that IO ports necessary for unplugging emulated
+devices. See hvm-emulated-unplug.markdown for details of the IO ports
+and unplug protocol.
+
+libxl provides support for creation of a single additional xen-pvdevice.
+See the vendor_device parameter in xl.cfg(5).
+
+=back
diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in
index 94eada381f..0dac6f1d9a 100644
--- a/docs/man/xl.cfg.pod.5.in
+++ b/docs/man/xl.cfg.pod.5.in
@@ -1894,7 +1894,7 @@ specified, enabling the use of XenServer PV drivers in the guest.
=back
This parameter only takes effect when device_model_version=qemu-xen.
-See F<docs/misc/pci-device-reservations.txt> for more information.
+See L<xen-pci-device-reservations(7)> for more information.
=back
diff --git a/docs/misc/pci-device-reservations.txt b/docs/misc/pci-device-reservations.txt
deleted file mode 100644
index 9d6d780ace..0000000000
--- a/docs/misc/pci-device-reservations.txt
+++ /dev/null
@@ -1,58 +0,0 @@
-PCI vendor ID 0x5853 has been reserved for use by Xen systems in order to
-advertise certain virtual hardware to guest virtual machines. The primary
-use of this is with device ID 0x0001 to advertise the Xen Platform PCI
-device - the presence of this virtual device enables a guest Operating
-System (subject to the availability of suitable drivers) to make use of
-paravirtualisation features such as disk and network devices etc.
-
-Some Xen vendors wish to provide alternative and/or additional guest drivers
-that can bind to virtual devices[1]. This may be done using the Xen PCI
-vendor ID of 0x5853 and Xen-vendor/device specific PCI device IDs. This file
-records reservations made within the device ID range in order to avoid
-multiple Xen vendors using conflicting IDs.
-
-Guidelines
- 1. A vendor may request a range of device IDs by submitting a patch to
- this file.
- 2. Vendor allocations should be in the range 0xc000-0xfffe to reduce the
- possibility of clashes with community IDs assigned from the bottom up.
- 3. The vendor is responsible for allocations within the range and should
- try to record specific device IDs in PCI ID databases such as
- http://pciids.sourceforge.net and http//www.pcidatabase.com
-
-Reservations
-============
-
- range | vendor/product
---------------+--------------------------------------------------------------
-0x0001 | (Xen Platform PCI device)
-0x0002 | Citrix XenServer (grandfathered allocation for XenServer 6.1)
-0xc000-0xc0ff | Citrix XenServer
-0xc100-0xc1ff | Citrix XenClient
-
-[1] Upstream QEMU provides a parameterized device called xen-pvdevice that
- can be used to host guest drivers. Execute:
-
- qemu-system-i386 -device xen-pvdevice,help
-
- for a list of all parameters. The following parameters are relevant to
- driver binding:
-
- vendor-id (default 0x5853): The PCI vendor ID and subsystem vendor
- ID of the device.
- device-id (must be specified): The PCI device ID and subsystem device
- ID of the device.
- revision (default 0x01): The PCI revision of the device
-
- Also the size parameter (default 0x400000) can be used to specify the
- size of the single MMIO BAR that the device exposes. This area may be
- used by drivers for mapping grant tables, etc.
-
- Note that the presence of the Xen Platform PCI device is generally a
- pre-requisite for an additional xen-pvdevice as it is the platform
- device that provides that IO ports necessary for unplugging emulated
- devices. See hvm-emulated-unplug.markdown for details of the IO ports
- and unplug protocol.
-
- libxl provides support for creation of a single additional xen-pvdevice.
- See the vendor_device parameter in xl.cfg(5).
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply related [flat|nested] 31+ messages in thread
* [PATCH 11/11] docs: convert tscmode.txt into man page
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
` (9 preceding siblings ...)
2016-12-09 16:17 ` [PATCH 10/11] docs: move pci-device-reservations from misc to man Cédric Bosdonnat
@ 2016-12-09 16:17 ` Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2017-01-04 15:07 ` [PATCH 00/11] Convert a few docs/misc pages into man pages Wei Liu
11 siblings, 1 reply; 31+ messages in thread
From: Cédric Bosdonnat @ 2016-12-09 16:17 UTC (permalink / raw)
To: xen-devel; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, Cédric Bosdonnat
tscmode.txt is referenced in xl.cfg(5). Convert it into a pod
formatted man page.
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
---
docs/INDEX | 1 -
docs/{misc/tscmode.txt => man/tscmode.pod.7} | 109 ++++++++++++++++++---------
docs/man/xl.cfg.pod.5.in | 4 +-
3 files changed, 76 insertions(+), 38 deletions(-)
rename docs/{misc/tscmode.txt => man/tscmode.pod.7} (89%)
diff --git a/docs/INDEX b/docs/INDEX
index 66cc82b78c..868ab1fc1d 100644
--- a/docs/INDEX
+++ b/docs/INDEX
@@ -12,7 +12,6 @@ misc/xen-command-line Xen Hypervisor Command Line Options
misc/crashdb Xen crash debugger notes
misc/grant-tables A Rough Introduction to Using Grant Tables
misc/kexec_and_kdump Kexec and Kdump for Xen
-misc/tscmode TSC Mode HOWTO
misc/xenstore Xenstore protocol specification
misc/xenstore-paths Xenstore path documentation
misc/distro_mapping Distro Directory Layouts
diff --git a/docs/misc/tscmode.txt b/docs/man/tscmode.pod.7
similarity index 89%
rename from docs/misc/tscmode.txt
rename to docs/man/tscmode.pod.7
index 01ee060598..0da57e5327 100644
--- a/docs/misc/tscmode.txt
+++ b/docs/man/tscmode.pod.7
@@ -1,7 +1,4 @@
-TSC_MODE HOW-TO
-by: Dan Magenheimer <dan.magenheimer@oracle.com>
-
-OVERVIEW
+=head1 OVERVIEW
As of Xen 4.0, a new config option called tsc_mode may be specified
for each domain. The default for tsc_mode handles the vast majority
@@ -16,16 +13,29 @@ equally to both the OS and ALL apps that are running on this
domain, now or in the future.
Key questions to be answered for the OS and/or each application are:
-- Does the OS/app use the rdtsc instruction at all? (We will explain below
- how to determine this.)
-- At what frequency is the rdtsc instruction executed by either the OS
- or any running apps? If the sum exceeds about 10,000 rdtsc instructions
- per second per processor, we call this a "high-TSC-frequency"
- OS/app/environment. (This is relatively rare, and developers of OS's
- and apps that are high-TSC-frequency are usually aware of it.)
-- If the OS/app does use rdtsc, will it behave incorrectly if "time goes
- backwards" or if the frequency of the TSC suddenly changes? If so,
- we call this a "TSC-sensitive" app or OS; otherwise it is "TSC-resilient".
+
+=over 4
+
+=item *
+
+Does the OS/app use the rdtsc instruction at all?
+(We will explain below how to determine this.)
+
+=item *
+
+At what frequency is the rdtsc instruction executed by either the OS
+or any running apps? If the sum exceeds about 10,000 rdtsc instructions
+per second per processor, we call this a "high-TSC-frequency"
+OS/app/environment. (This is relatively rare, and developers of OS's
+and apps that are high-TSC-frequency are usually aware of it.)
+
+=item *
+
+If the OS/app does use rdtsc, will it behave incorrectly if "time goes
+backwards" or if the frequency of the TSC suddenly changes? If so,
+we call this a "TSC-sensitive" app or OS; otherwise it is "TSC-resilient".
+
+=back
This last is the US$64,000 question as it may be very difficult
(or, for legacy apps, even impossible) to predict all possible
@@ -46,38 +56,63 @@ an intelligent default but allows system administrator's to adjust
how rdtsc instructions are executed differently for different domains.
The non-default choices for tsc_mode are:
-- tsc_mode=1 (always emulate). All rdtsc instructions are emulated;
- this is the best choice when TSC-sensitive apps are running and
- it is necessary to understand worst-case performance degradation
- for a specific hardware environment.
-- tsc_mode=2 (never emulate). This is the same as prior to Xen 4.0
- and is the best choice if it is certain that all apps running in
- this VM are TSC-resilient and highest performance is required.
-- tsc_mode=3 (PVRDTSCP). High-TSC-frequency apps may be paravirtualized
- (modified) to obtain both correctness and highest performance; any
- unmodified apps must be TSC-resilient.
-
-If tsc_mode is left unspecified (or set to tsc_mode=0), a hybrid
+
+=over 4
+
+=item * B<tsc_mode=1> (always emulate).
+
+All rdtsc instructions are emulated; this is the best choice when
+TSC-sensitive apps are running and it is necessary to understand
+worst-case performance degradation for a specific hardware environment.
+
+=item * B<tsc_mode=2> (never emulate).
+
+This is the same as prior to Xen 4.0 and is the best choice if it
+is certain that all apps running in this VM are TSC-resilient and
+highest performance is required.
+
+=item * B<tsc_mode=3> (PVRDTSCP).
+
+High-TSC-frequency apps may be paravirtualized (modified) to
+obtain both correctness and highest performance; any unmodified
+apps must be TSC-resilient.
+
+=back
+
+If tsc_mode is left unspecified (or set to B<tsc_mode=0>), a hybrid
algorithm is utilized to ensure correctness while providing the
best performance possible given:
-- the requirement of correctness,
-- the underlying hardware, and
-- whether or not the VM has been saved/restored/migrated
+
+=over 4
+
+=item *
+
+the requirement of correctness,
+
+=item *
+
+the underlying hardware, and
+
+=item *
+
+whether or not the VM has been saved/restored/migrated
To understand this in more detail, the rest of this document must
be read.
-DETERMINING RDTSC FREQUENCY
+=back
+
+=head1 DETERMINING RDTSC FREQUENCY
To determine the frequency of rdtsc instructions that are emulated,
an "xm" command can be used by a privileged user of domain0. The
command:
-# xm debug-key s; xm dmesg | tail
+ # xm debug-key s; xm dmesg | tail
provides information about TSC usage in each domain where TSC
emulation is currently enabled.
-TSC HISTORY
+=head1 TSC HISTORY
To understand tsc_mode completely, some background on TSC is required:
@@ -214,7 +249,7 @@ then restored 30 seconds later, TSC is only guaranteed to be greater
than or equal to 1001, not precisely 1030. This has some OS implications
as will be seen in the next section.
-TSC INVARIANT BIT and NO_MIGRATE
+=head1 TSC INVARIANT BIT and NO_MIGRATE
Related to TSC emulation, the "TSC Invariant" bit is architecturally defined
in a cpuid bit on the most recent x86 processors. If set, TSC invariance
@@ -251,7 +286,7 @@ decisions based on that bit. This is still an unsolved problem, though
a workaround exists as part of the PVRDTSCP tsc_mode for apps that
can be modified.
-MORE ON PVRDTSCP
+=head1 MORE ON PVRDTSCP
Paravirtualized OS's use the "pvclock" algorithm to manage the passing
of time. This sophisticated algorithm obtains information from a memory
@@ -298,7 +333,7 @@ While pvrtscp is too complex for most apps, certain enterprise
TSC-sensitive high-TSC-frequency apps may find it useful to
obtain a significant performance gain.
-Hardware TSC Scaling
+=head1 HARDWARE TSC SCALING
Intel VMX TSC scaling and AMD SVM TSC ratio allow the guest TSC read
by guest rdtsc/p increasing in a different frequency than the host
@@ -318,3 +353,7 @@ executed natively before and after migration.
For above HVM container in PVRDTSCP mode (tsc_mode=3), if the
destination host does not support rdtscp, the guest rdtscp instruction
will be emulated with the guest TSC frequency.
+
+=head1 AUTHORS
+
+Dan Magenheimer <dan.magenheimer@oracle.com>
diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in
index 0dac6f1d9a..de6c5edb99 100644
--- a/docs/man/xl.cfg.pod.5.in
+++ b/docs/man/xl.cfg.pod.5.in
@@ -1463,7 +1463,7 @@ determined in the similar way to that of B<default> TSC mode.
=back
-Please see F<docs/misc/tscmode.txt> for more information on this option.
+Please see L<tscmode(7)> for more information on this option.
=item B<localtime=BOOLEAN>
@@ -2033,7 +2033,7 @@ natively or via hardware backwards compatibility support.
=item L<xl-network-configuration(5)>
-=item F<docs/misc/tscmode.txt>
+=item L<tscmode(7)>
=back
--
2.11.0
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply related [flat|nested] 31+ messages in thread
* Re: [PATCH 07/11] docs: move vtpm from misc to man
2016-12-09 16:17 ` [PATCH 07/11] docs: move vtpm from misc to man Cédric Bosdonnat
@ 2016-12-14 21:08 ` Daniel De Graaf
2016-12-19 10:45 ` Cedric Bosdonnat
0 siblings, 1 reply; 31+ messages in thread
From: Daniel De Graaf @ 2016-12-14 21:08 UTC (permalink / raw)
To: Cédric Bosdonnat, xen-devel
Cc: Andrew Cooper, Quan Xu, Ian Jackson, Wei Liu
On 12/09/2016 11:17 AM, Cédric Bosdonnat wrote:
> vtpm.txt is referenced in xl.cfg man page. Convert it to pod,
> move it to the man folder and update the reference.
>
> Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Since this manpage only describes Xen's vTPM implementation, and
Xen is not the only vTPM that exists in Linux (there's a Linux
kernel "vtpm_proxy" interface and another ibmvtpm module), I think
it needs be named something like "xen-vtpm". The same applies to
patch 8 (vtpmmgr) as that manpage (and software) is Xen-specific.
The POD sources look correct, though I have not compiled & looked
at the resulting manpages.
--
Daniel De Graaf
National Security Agency
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 07/11] docs: move vtpm from misc to man
2016-12-14 21:08 ` Daniel De Graaf
@ 2016-12-19 10:45 ` Cedric Bosdonnat
0 siblings, 0 replies; 31+ messages in thread
From: Cedric Bosdonnat @ 2016-12-19 10:45 UTC (permalink / raw)
To: Daniel De Graaf, xen-devel; +Cc: Andrew Cooper, Quan Xu, Ian Jackson, Wei Liu
On Wed, 2016-12-14 at 16:08 -0500, Daniel De Graaf wrote:
> On 12/09/2016 11:17 AM, Cédric Bosdonnat wrote:
> > vtpm.txt is referenced in xl.cfg man page. Convert it to pod,
> > move it to the man folder and update the reference.
> >
> > Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
>
> Since this manpage only describes Xen's vTPM implementation, and
> Xen is not the only vTPM that exists in Linux (there's a Linux
> kernel "vtpm_proxy" interface and another ibmvtpm module), I think
> it needs be named something like "xen-vtpm". The same applies to
> patch 8 (vtpmmgr) as that manpage (and software) is Xen-specific.
I just changed the names locally. I'll resubmit after having gathered
a few more comments.
Thanks for your review.
--
Cedric
> The POD sources look correct, though I have not compiled & looked
> at the resulting manpages.
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 00/11] Convert a few docs/misc pages into man pages
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
` (10 preceding siblings ...)
2016-12-09 16:17 ` [PATCH 11/11] docs: convert tscmode.txt into man page Cédric Bosdonnat
@ 2017-01-04 15:07 ` Wei Liu
2017-01-04 15:49 ` Cedric Bosdonnat
11 siblings, 1 reply; 31+ messages in thread
From: Wei Liu @ 2017-01-04 15:07 UTC (permalink / raw)
To: Cédric Bosdonnat; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, xen-devel
On Fri, Dec 09, 2016 at 05:17:03PM +0100, Cédric Bosdonnat wrote:
> As pointed out in Ian and Andrew's emails on my recent docs improvement
> attempt, getting the documents from docs/misc referenced in man pages
> as man pages would would make these pages more visible for users. This
> would also not break the docs html INDEX.
>
> This series adds ability to write markdown man pages. Be aware that
> markdown man pages can't link to other man pages.
>
> I also added some pages to man 7 (Misc) section.
>
Do you have a git branch that I can pull from?
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 00/11] Convert a few docs/misc pages into man pages
2017-01-04 15:07 ` [PATCH 00/11] Convert a few docs/misc pages into man pages Wei Liu
@ 2017-01-04 15:49 ` Cedric Bosdonnat
2017-01-05 15:01 ` Wei Liu
0 siblings, 1 reply; 31+ messages in thread
From: Cedric Bosdonnat @ 2017-01-04 15:49 UTC (permalink / raw)
To: Wei Liu; +Cc: Andrew Cooper, Ian Jackson, xen-devel
On Wed, 2017-01-04 at 15:07 +0000, Wei Liu wrote:
> On Fri, Dec 09, 2016 at 05:17:03PM +0100, Cédric Bosdonnat wrote:
> > As pointed out in Ian and Andrew's emails on my recent docs improvement
> > attempt, getting the documents from docs/misc referenced in man pages
> > as man pages would would make these pages more visible for users. This
> > would also not break the docs html INDEX.
> >
> > This series adds ability to write markdown man pages. Be aware that
> > markdown man pages can't link to other man pages.
> >
> > I also added some pages to man 7 (Misc) section.
> >
>
> Do you have a git branch that I can pull from?
The docs branch on https://github.com/cbosdo/xen
--
Cedric
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 01/11] docs: allow writing man pages in markdown
2016-12-09 16:17 ` [PATCH 01/11] docs: allow writing man pages in markdown Cédric Bosdonnat
@ 2017-01-04 17:55 ` Wei Liu
0 siblings, 0 replies; 31+ messages in thread
From: Wei Liu @ 2017-01-04 17:55 UTC (permalink / raw)
To: Cédric Bosdonnat; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, xen-devel
On Fri, Dec 09, 2016 at 05:17:04PM +0100, Cédric Bosdonnat wrote:
> Some of the docs/misc documents are written in markdown language.
> As an effort to cleanup man pages these documents will be converted into
> man pages. To avoid some more conversion, add rules to the docs/Makefile
> to generate man pages out of markdown files as well as pod ones.
>
> However, pandoc doesn't know how to convert man pages links. Thus the
> man links in markdown pages won't work.
>
> Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 02/11] docs: add rules for man 7 section
2016-12-09 16:17 ` [PATCH 02/11] docs: add rules for man 7 section Cédric Bosdonnat
@ 2017-01-04 17:55 ` Wei Liu
2017-01-05 12:00 ` Wei Liu
1 sibling, 0 replies; 31+ messages in thread
From: Wei Liu @ 2017-01-04 17:55 UTC (permalink / raw)
To: Cédric Bosdonnat; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, xen-devel
On Fri, Dec 09, 2016 at 05:17:05PM +0100, Cédric Bosdonnat wrote:
> Some of the docs/misc documents will need to go in man 7 section,
> prepare docs/Makefile for it.
>
> Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 03/11] docs: xl-network-configuration turns into a man
2016-12-09 16:17 ` [PATCH 03/11] docs: xl-network-configuration turns into a man Cédric Bosdonnat
@ 2017-01-04 17:55 ` Wei Liu
0 siblings, 0 replies; 31+ messages in thread
From: Wei Liu @ 2017-01-04 17:55 UTC (permalink / raw)
To: Cédric Bosdonnat; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, xen-devel
On Fri, Dec 09, 2016 at 05:17:06PM +0100, Cédric Bosdonnat wrote:
> Move docs/misc/xl-network-configuration.markdown to docs/man and
> update the references to it in the other man pages.
>
> Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 04/11] docs: convert xl-disk-configuration into a man page
2016-12-09 16:17 ` [PATCH 04/11] docs: convert xl-disk-configuration into a man page Cédric Bosdonnat
@ 2017-01-04 17:55 ` Wei Liu
0 siblings, 0 replies; 31+ messages in thread
From: Wei Liu @ 2017-01-04 17:55 UTC (permalink / raw)
To: Cédric Bosdonnat; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, xen-devel
On Fri, Dec 09, 2016 at 05:17:07PM +0100, Cédric Bosdonnat wrote:
> 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 <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 05/11] docs: move vbd-interface from misc to man
2016-12-09 16:17 ` [PATCH 05/11] docs: move vbd-interface from misc to man Cédric Bosdonnat
@ 2017-01-04 17:55 ` Wei Liu
0 siblings, 0 replies; 31+ messages in thread
From: Wei Liu @ 2017-01-04 17:55 UTC (permalink / raw)
To: Cédric Bosdonnat
Cc: Tim Deegan, Stefano Stabellini, Wei Liu, George Dunlap,
Andrew Cooper, Ian Jackson, xen-devel, Jan Beulich
On Fri, Dec 09, 2016 at 05:17:08PM +0100, Cédric Bosdonnat wrote:
> Make vbd-interface a man page, section7, as this document is
> referenced in other man pages (xl-disk-configuration)
>
> Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 06/11] docs: move xl-numa-placement.markdown to man7
2016-12-09 16:17 ` [PATCH 06/11] docs: move xl-numa-placement.markdown to man7 Cédric Bosdonnat
@ 2017-01-04 17:55 ` Wei Liu
0 siblings, 0 replies; 31+ messages in thread
From: Wei Liu @ 2017-01-04 17:55 UTC (permalink / raw)
To: Cédric Bosdonnat; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, xen-devel
On Fri, Dec 09, 2016 at 05:17:09PM +0100, Cédric Bosdonnat wrote:
> docs/misc/xl-numa-placement.markdown is referenced by xl.cfg.5 man page,
> move it to a man page, section 7.
>
> Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 09/11] docs: convert misc/channel.txt into xen-pv-channel man page
2016-12-09 16:17 ` [PATCH 09/11] docs: convert misc/channel.txt into xen-pv-channel " Cédric Bosdonnat
@ 2017-01-04 17:55 ` Wei Liu
0 siblings, 0 replies; 31+ messages in thread
From: Wei Liu @ 2017-01-04 17:55 UTC (permalink / raw)
To: Cédric Bosdonnat; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, xen-devel
On Fri, Dec 09, 2016 at 05:17:12PM +0100, Cédric Bosdonnat wrote:
> channel.txt is referenced in xl.cfg(5). Move it to man pages, section 7
>
> Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 10/11] docs: move pci-device-reservations from misc to man
2016-12-09 16:17 ` [PATCH 10/11] docs: move pci-device-reservations from misc to man Cédric Bosdonnat
@ 2017-01-04 17:55 ` Wei Liu
0 siblings, 0 replies; 31+ messages in thread
From: Wei Liu @ 2017-01-04 17:55 UTC (permalink / raw)
To: Cédric Bosdonnat; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, xen-devel
On Fri, Dec 09, 2016 at 05:17:13PM +0100, Cédric Bosdonnat wrote:
> pci-device-reservations is references in xl.cfg(5), convert it as a man
> page in pod format. The name is now prefixed with 'xen-' to avoid
> possible name conflicts.
>
> Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 11/11] docs: convert tscmode.txt into man page
2016-12-09 16:17 ` [PATCH 11/11] docs: convert tscmode.txt into man page Cédric Bosdonnat
@ 2017-01-04 17:55 ` Wei Liu
0 siblings, 0 replies; 31+ messages in thread
From: Wei Liu @ 2017-01-04 17:55 UTC (permalink / raw)
To: Cédric Bosdonnat; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, xen-devel
On Fri, Dec 09, 2016 at 05:17:14PM +0100, Cédric Bosdonnat wrote:
> tscmode.txt is referenced in xl.cfg(5). Convert it into a pod
> formatted man page.
>
> Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 02/11] docs: add rules for man 7 section
2016-12-09 16:17 ` [PATCH 02/11] docs: add rules for man 7 section Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
@ 2017-01-05 12:00 ` Wei Liu
1 sibling, 0 replies; 31+ messages in thread
From: Wei Liu @ 2017-01-05 12:00 UTC (permalink / raw)
To: Cédric Bosdonnat; +Cc: Andrew Cooper, Ian Jackson, Wei Liu, xen-devel
On Fri, Dec 09, 2016 at 05:17:05PM +0100, Cédric Bosdonnat wrote:
> Some of the docs/misc documents will need to go in man 7 section,
> prepare docs/Makefile for it.
>
> Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 00/11] Convert a few docs/misc pages into man pages
2017-01-04 15:49 ` Cedric Bosdonnat
@ 2017-01-05 15:01 ` Wei Liu
2017-01-05 15:12 ` Cedric Bosdonnat
0 siblings, 1 reply; 31+ messages in thread
From: Wei Liu @ 2017-01-05 15:01 UTC (permalink / raw)
To: Cedric Bosdonnat; +Cc: Andrew Cooper, Wei Liu, Ian Jackson, xen-devel
On Wed, Jan 04, 2017 at 04:49:25PM +0100, Cedric Bosdonnat wrote:
> On Wed, 2017-01-04 at 15:07 +0000, Wei Liu wrote:
> > On Fri, Dec 09, 2016 at 05:17:03PM +0100, Cédric Bosdonnat wrote:
> > > As pointed out in Ian and Andrew's emails on my recent docs improvement
> > > attempt, getting the documents from docs/misc referenced in man pages
> > > as man pages would would make these pages more visible for users. This
> > > would also not break the docs html INDEX.
> > >
> > > This series adds ability to write markdown man pages. Be aware that
> > > markdown man pages can't link to other man pages.
> > >
> > > I also added some pages to man 7 (Misc) section.
> > >
> >
> > Do you have a git branch that I can pull from?
>
> The docs branch on https://github.com/cbosdo/xen
I think I've gone through all of the patches. Please address Daniel's
comments and resend this series.
Wei.
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 00/11] Convert a few docs/misc pages into man pages
2017-01-05 15:01 ` Wei Liu
@ 2017-01-05 15:12 ` Cedric Bosdonnat
2017-01-05 15:19 ` Wei Liu
0 siblings, 1 reply; 31+ messages in thread
From: Cedric Bosdonnat @ 2017-01-05 15:12 UTC (permalink / raw)
To: Wei Liu; +Cc: Andrew Cooper, Ian Jackson, xen-devel
On Thu, 2017-01-05 at 15:01 +0000, Wei Liu wrote:
> On Wed, Jan 04, 2017 at 04:49:25PM +0100, Cedric Bosdonnat wrote:
> > On Wed, 2017-01-04 at 15:07 +0000, Wei Liu wrote:
> > > On Fri, Dec 09, 2016 at 05:17:03PM +0100, Cédric Bosdonnat wrote:
> > > > As pointed out in Ian and Andrew's emails on my recent docs improvement
> > > > attempt, getting the documents from docs/misc referenced in man pages
> > > > as man pages would would make these pages more visible for users. This
> > > > would also not break the docs html INDEX.
> > > >
> > > > This series adds ability to write markdown man pages. Be aware that
> > > > markdown man pages can't link to other man pages.
> > > >
> > > > I also added some pages to man 7 (Misc) section.
> > > >
> > >
> > > Do you have a git branch that I can pull from?
> >
> > The docs branch on https://github.com/cbosdo/xen
>
> I think I've gone through all of the patches. Please address Daniel's
> comments and resend this series.
They were already addressed in the repo I pointed you to.
--
Cedric
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 00/11] Convert a few docs/misc pages into man pages
2017-01-05 15:12 ` Cedric Bosdonnat
@ 2017-01-05 15:19 ` Wei Liu
2017-01-09 10:39 ` Cedric Bosdonnat
0 siblings, 1 reply; 31+ messages in thread
From: Wei Liu @ 2017-01-05 15:19 UTC (permalink / raw)
To: Cedric Bosdonnat; +Cc: Andrew Cooper, Wei Liu, Ian Jackson, xen-devel
On Thu, Jan 05, 2017 at 04:12:46PM +0100, Cedric Bosdonnat wrote:
> On Thu, 2017-01-05 at 15:01 +0000, Wei Liu wrote:
> > On Wed, Jan 04, 2017 at 04:49:25PM +0100, Cedric Bosdonnat wrote:
> > > On Wed, 2017-01-04 at 15:07 +0000, Wei Liu wrote:
> > > > On Fri, Dec 09, 2016 at 05:17:03PM +0100, Cédric Bosdonnat wrote:
> > > > > As pointed out in Ian and Andrew's emails on my recent docs improvement
> > > > > attempt, getting the documents from docs/misc referenced in man pages
> > > > > as man pages would would make these pages more visible for users. This
> > > > > would also not break the docs html INDEX.
> > > > >
> > > > > This series adds ability to write markdown man pages. Be aware that
> > > > > markdown man pages can't link to other man pages.
> > > > >
> > > > > I also added some pages to man 7 (Misc) section.
> > > > >
> > > >
> > > > Do you have a git branch that I can pull from?
> > >
> > > The docs branch on https://github.com/cbosdo/xen
> >
> > I think I've gone through all of the patches. Please address Daniel's
> > comments and resend this series.
>
> They were already addressed in the repo I pointed you to.
>
Right. I missed that, sorry.
I think you need some more renaming. tscmode.7 and vbd-interface.7
should have xen- prefix, too.
Wei.
> --
> Cedric
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 00/11] Convert a few docs/misc pages into man pages
2017-01-05 15:19 ` Wei Liu
@ 2017-01-09 10:39 ` Cedric Bosdonnat
2017-01-09 11:07 ` Wei Liu
0 siblings, 1 reply; 31+ messages in thread
From: Cedric Bosdonnat @ 2017-01-09 10:39 UTC (permalink / raw)
To: Wei Liu; +Cc: Andrew Cooper, Ian Jackson, xen-devel
On Thu, 2017-01-05 at 15:19 +0000, Wei Liu wrote:
> On Thu, Jan 05, 2017 at 04:12:46PM +0100, Cedric Bosdonnat wrote:
> > On Thu, 2017-01-05 at 15:01 +0000, Wei Liu wrote:
> > > On Wed, Jan 04, 2017 at 04:49:25PM +0100, Cedric Bosdonnat wrote:
> > > > On Wed, 2017-01-04 at 15:07 +0000, Wei Liu wrote:
> > > > > On Fri, Dec 09, 2016 at 05:17:03PM +0100, Cédric Bosdonnat wrote:
> > > > > > As pointed out in Ian and Andrew's emails on my recent docs improvement
> > > > > > attempt, getting the documents from docs/misc referenced in man pages
> > > > > > as man pages would would make these pages more visible for users. This
> > > > > > would also not break the docs html INDEX.
> > > > > >
> > > > > > This series adds ability to write markdown man pages. Be aware that
> > > > > > markdown man pages can't link to other man pages.
> > > > > >
> > > > > > I also added some pages to man 7 (Misc) section.
> > > > > >
> > > > >
> > > > > Do you have a git branch that I can pull from?
> > > >
> > > > The docs branch on https://github.com/cbosdo/xen
> > >
> > > I think I've gone through all of the patches. Please address Daniel's
> > > comments and resend this series.
> >
> > They were already addressed in the repo I pointed you to.
> >
>
> Right. I missed that, sorry.
>
> I think you need some more renaming. tscmode.7 and vbd-interface.7
> should have xen- prefix, too.
I just updated my github branch with those changes.
--
Cedric
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH 00/11] Convert a few docs/misc pages into man pages
2017-01-09 10:39 ` Cedric Bosdonnat
@ 2017-01-09 11:07 ` Wei Liu
0 siblings, 0 replies; 31+ messages in thread
From: Wei Liu @ 2017-01-09 11:07 UTC (permalink / raw)
To: Cedric Bosdonnat; +Cc: Andrew Cooper, Wei Liu, Ian Jackson, xen-devel
On Mon, Jan 09, 2017 at 11:39:06AM +0100, Cedric Bosdonnat wrote:
> On Thu, 2017-01-05 at 15:19 +0000, Wei Liu wrote:
> > On Thu, Jan 05, 2017 at 04:12:46PM +0100, Cedric Bosdonnat wrote:
> > > On Thu, 2017-01-05 at 15:01 +0000, Wei Liu wrote:
> > > > On Wed, Jan 04, 2017 at 04:49:25PM +0100, Cedric Bosdonnat wrote:
> > > > > On Wed, 2017-01-04 at 15:07 +0000, Wei Liu wrote:
> > > > > > On Fri, Dec 09, 2016 at 05:17:03PM +0100, Cédric Bosdonnat wrote:
> > > > > > > As pointed out in Ian and Andrew's emails on my recent docs improvement
> > > > > > > attempt, getting the documents from docs/misc referenced in man pages
> > > > > > > as man pages would would make these pages more visible for users. This
> > > > > > > would also not break the docs html INDEX.
> > > > > > >
> > > > > > > This series adds ability to write markdown man pages. Be aware that
> > > > > > > markdown man pages can't link to other man pages.
> > > > > > >
> > > > > > > I also added some pages to man 7 (Misc) section.
> > > > > > >
> > > > > >
> > > > > > Do you have a git branch that I can pull from?
> > > > >
> > > > > The docs branch on https://github.com/cbosdo/xen
> > > >
> > > > I think I've gone through all of the patches. Please address Daniel's
> > > > comments and resend this series.
> > >
> > > They were already addressed in the repo I pointed you to.
> > >
> >
> > Right. I missed that, sorry.
> >
> > I think you need some more renaming. tscmode.7 and vbd-interface.7
> > should have xen- prefix, too.
>
> I just updated my github branch with those changes.
>
Hmm... your branch is missing all your SoBs.
Anyway, I've added that for you and will push this series soon.
Wei.
> --
> Cedric
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel
^ permalink raw reply [flat|nested] 31+ messages in thread
end of thread, other threads:[~2017-01-09 11:07 UTC | newest]
Thread overview: 31+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-12-09 16:17 [PATCH 00/11] Convert a few docs/misc pages into man pages Cédric Bosdonnat
2016-12-09 16:17 ` [PATCH 01/11] docs: allow writing man pages in markdown Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 02/11] docs: add rules for man 7 section Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2017-01-05 12:00 ` Wei Liu
2016-12-09 16:17 ` [PATCH 03/11] docs: xl-network-configuration turns into a man Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 04/11] docs: convert xl-disk-configuration into a man page Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 05/11] docs: move vbd-interface from misc to man Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 06/11] docs: move xl-numa-placement.markdown to man7 Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 07/11] docs: move vtpm from misc to man Cédric Bosdonnat
2016-12-14 21:08 ` Daniel De Graaf
2016-12-19 10:45 ` Cedric Bosdonnat
2016-12-09 16:17 ` [PATCH 08/11] docs: convert vtpmmgr into a pod man page Cédric Bosdonnat
2016-12-09 16:17 ` [PATCH 09/11] docs: convert misc/channel.txt into xen-pv-channel " Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 10/11] docs: move pci-device-reservations from misc to man Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2016-12-09 16:17 ` [PATCH 11/11] docs: convert tscmode.txt into man page Cédric Bosdonnat
2017-01-04 17:55 ` Wei Liu
2017-01-04 15:07 ` [PATCH 00/11] Convert a few docs/misc pages into man pages Wei Liu
2017-01-04 15:49 ` Cedric Bosdonnat
2017-01-05 15:01 ` Wei Liu
2017-01-05 15:12 ` Cedric Bosdonnat
2017-01-05 15:19 ` Wei Liu
2017-01-09 10:39 ` Cedric Bosdonnat
2017-01-09 11:07 ` Wei Liu
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).