* [PATCH 0/4] docs: Multiple fixes to docs
@ 2019-01-02 11:43 Andrew Cooper
2019-01-02 11:43 ` [PATCH 1/4] docs/pandoc: Don't escape underscores in the middle of text Andrew Cooper
` (3 more replies)
0 siblings, 4 replies; 12+ messages in thread
From: Andrew Cooper @ 2019-01-02 11:43 UTC (permalink / raw)
To: Xen-devel
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk,
George Dunlap, Andrew Cooper, Tim Deegan, Julien Grall,
Jan Beulich, Ian Jackson, Doug Goldstein
This work started to fix a regression introduced by c/s a3a99df44
"docs/cmdline: Rewrite the cpuid_mask_* section" which has broken the
formatting of xen-command-line.html on xenbits.xen.org/docs.
It developed into several swamps of work...
Andrew Cooper (4):
docs/pandoc: Don't escape underscores in the middle of text
docs/markdown: Switch to using pandoc, and fix underscore escaping
docs/man: Fix/simplify generation of manpages
docs: Remove Markdown from configure.ac and the build instructions
.gitignore | 4 +-
.travis.yml | 1 -
README | 3 +-
automation/build/centos/7.2.dockerfile | 3 +-
automation/build/centos/7.dockerfile | 3 +-
automation/build/debian/jessie-i386.dockerfile | 1 -
automation/build/debian/jessie.dockerfile | 1 -
automation/build/debian/stretch-i386.dockerfile | 1 -
automation/build/debian/stretch.dockerfile | 1 -
.../build/debian/unstable-arm64v8.dockerfile | 1 -
automation/build/debian/unstable-i386.dockerfile | 1 -
automation/build/debian/unstable.dockerfile | 1 -
automation/build/ubuntu/bionic.dockerfile | 1 -
automation/build/ubuntu/trusty.dockerfile | 1 -
automation/build/ubuntu/xenial.dockerfile | 1 -
config/Docs.mk.in | 1 -
docs/Makefile | 76 +++------
docs/configure | 63 +------
docs/configure.ac | 5 +-
docs/designs/{dmop.markdown => dmop.pandoc} | 0
.../{dom0less.markdown => dom0less.pandoc} | 0
docs/features/feature-levelling.pandoc | 16 +-
docs/features/migration.pandoc | 2 +-
docs/features/sched_credit2.pandoc | 6 +-
docs/features/sched_rtds.pandoc | 8 +-
...ons.pod.7 => xen-pci-device-reservations.7.pod} | 0
.../{xen-pv-channel.pod.7 => xen-pv-channel.7.pod} | 0
docs/man/{xen-tscmode.pod.7 => xen-tscmode.7.pod} | 0
...rface.markdown.7 => xen-vbd-interface.7.pandoc} | 0
docs/man/{xen-vtpm.pod.7 => xen-vtpm.7.pod} | 0
docs/man/{xen-vtpmmgr.pod.7 => xen-vtpmmgr.7.pod} | 0
.../{xenstore-chmod.pod.1 => xenstore-chmod.1.pod} | 0
docs/man/{xenstore-ls.pod.1 => xenstore-ls.1.pod} | 0
.../{xenstore-read.pod.1 => xenstore-read.1.pod} | 0
.../{xenstore-write.pod.1 => xenstore-write.1.pod} | 0
docs/man/{xenstore.pod.1 => xenstore.1.pod} | 0
docs/man/{xentop.pod.1 => xentop.1.pod} | 0
docs/man/{xentrace.pod.8 => xentrace.8.pod} | 0
...xentrace_format.pod.1 => xentrace_format.1.pod} | 0
...iguration.pod.5 => xl-disk-configuration.5.pod} | 0
...ration.pod.5 => xl-network-configuration.5.pod} | 0
...uma-placement.pod.7 => xl-numa-placement.7.pod} | 0
docs/man/{xl.pod.1.in => xl.1.pod.in} | 0
docs/man/{xl.cfg.pod.5.in => xl.cfg.5.pod.in} | 0
docs/man/{xl.conf.pod.5 => xl.conf.5.pod} | 0
.../{xlcpupool.cfg.pod.5 => xlcpupool.cfg.5.pod} | 0
docs/misc/{9pfs.markdown => 9pfs.pandoc} | 42 ++---
docs/misc/{coverage.markdown => coverage.pandoc} | 0
docs/misc/{efi.markdown => efi.pandoc} | 2 +-
...-unplug.markdown => hvm-emulated-unplug.pandoc} | 0
docs/misc/{livepatch.markdown => livepatch.pandoc} | 108 ++++++------
...ecycle.markdown => pv-drivers-lifecycle.pandoc} | 0
docs/misc/{pvcalls.markdown => pvcalls.pandoc} | 18 +-
docs/misc/{pvh.markdown => pvh.pandoc} | 10 +-
...loader.markdown => x86-xenpv-bootloader.pandoc} | 8 +-
...mmand-line.markdown => xen-command-line.pandoc} | 188 ++++++++++-----------
...nstore-paths.markdown => xenstore-paths.pandoc} | 6 +-
docs/misc/{xl-psr.markdown => xl-psr.pandoc} | 0
docs/specs/libxc-migration-stream.pandoc | 60 +++----
docs/specs/libxl-migration-stream.pandoc | 34 ++--
60 files changed, 286 insertions(+), 391 deletions(-)
rename docs/designs/{dmop.markdown => dmop.pandoc} (100%)
rename docs/features/{dom0less.markdown => dom0less.pandoc} (100%)
rename docs/man/{xen-pci-device-reservations.pod.7 => xen-pci-device-reservations.7.pod} (100%)
rename docs/man/{xen-pv-channel.pod.7 => xen-pv-channel.7.pod} (100%)
rename docs/man/{xen-tscmode.pod.7 => xen-tscmode.7.pod} (100%)
rename docs/man/{xen-vbd-interface.markdown.7 => xen-vbd-interface.7.pandoc} (100%)
rename docs/man/{xen-vtpm.pod.7 => xen-vtpm.7.pod} (100%)
rename docs/man/{xen-vtpmmgr.pod.7 => xen-vtpmmgr.7.pod} (100%)
rename docs/man/{xenstore-chmod.pod.1 => xenstore-chmod.1.pod} (100%)
rename docs/man/{xenstore-ls.pod.1 => xenstore-ls.1.pod} (100%)
rename docs/man/{xenstore-read.pod.1 => xenstore-read.1.pod} (100%)
rename docs/man/{xenstore-write.pod.1 => xenstore-write.1.pod} (100%)
rename docs/man/{xenstore.pod.1 => xenstore.1.pod} (100%)
rename docs/man/{xentop.pod.1 => xentop.1.pod} (100%)
rename docs/man/{xentrace.pod.8 => xentrace.8.pod} (100%)
rename docs/man/{xentrace_format.pod.1 => xentrace_format.1.pod} (100%)
rename docs/man/{xl-disk-configuration.pod.5 => xl-disk-configuration.5.pod} (100%)
rename docs/man/{xl-network-configuration.pod.5 => xl-network-configuration.5.pod} (100%)
rename docs/man/{xl-numa-placement.pod.7 => xl-numa-placement.7.pod} (100%)
rename docs/man/{xl.pod.1.in => xl.1.pod.in} (100%)
rename docs/man/{xl.cfg.pod.5.in => xl.cfg.5.pod.in} (100%)
rename docs/man/{xl.conf.pod.5 => xl.conf.5.pod} (100%)
rename docs/man/{xlcpupool.cfg.pod.5 => xlcpupool.cfg.5.pod} (100%)
rename docs/misc/{9pfs.markdown => 9pfs.pandoc} (98%)
rename docs/misc/{coverage.markdown => coverage.pandoc} (100%)
rename docs/misc/{efi.markdown => efi.pandoc} (99%)
rename docs/misc/{hvm-emulated-unplug.markdown => hvm-emulated-unplug.pandoc} (100%)
rename docs/misc/{livepatch.markdown => livepatch.pandoc} (92%)
rename docs/misc/{pv-drivers-lifecycle.markdown => pv-drivers-lifecycle.pandoc} (100%)
rename docs/misc/{pvcalls.markdown => pvcalls.pandoc} (99%)
rename docs/misc/{pvh.markdown => pvh.pandoc} (93%)
rename docs/misc/{x86-xenpv-bootloader.markdown => x86-xenpv-bootloader.pandoc} (89%)
rename docs/misc/{xen-command-line.markdown => xen-command-line.pandoc} (95%)
rename docs/misc/{xenstore-paths.markdown => xenstore-paths.pandoc} (99%)
rename docs/misc/{xl-psr.markdown => xl-psr.pandoc} (100%)
--
2.1.4
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH 1/4] docs/pandoc: Don't escape underscores in the middle of text
2019-01-02 11:43 [PATCH 0/4] docs: Multiple fixes to docs Andrew Cooper
@ 2019-01-02 11:43 ` Andrew Cooper
2019-01-02 12:28 ` Ian Jackson
2019-01-02 11:43 ` [PATCH 2/4] docs/markdown: Switch to using pandoc, and fix underscore escaping Andrew Cooper
` (2 subsequent siblings)
3 siblings, 1 reply; 12+ messages in thread
From: Andrew Cooper @ 2019-01-02 11:43 UTC (permalink / raw)
To: Xen-devel
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk,
George Dunlap, Andrew Cooper, Tim Deegan, Julien Grall,
Jan Beulich, Ian Jackson
Pandoc deliberately (and contrary to markdown) doesn't treat underscores in
the middle of normal text as emphasis markers, as this is almost always the
unhelpful interpretation.
For text which is emphasised using _, an underscore in the middle is
interpreted, but the emphasis marker can be switched to * instead.
One problem case is where we use {} globbing with identifier names, as it
counts as a word break. Therefore, we do need to retain the escaped
underscore immediately following a closing brace.
No change in content - only formatting. This results in the text being easier
to read and grep.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: George Dunlap <George.Dunlap@eu.citrix.com>
CC: Ian Jackson <ian.jackson@citrix.com>
CC: Jan Beulich <JBeulich@suse.com>
CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Tim Deegan <tim@xen.org>
CC: Wei Liu <wei.liu2@citrix.com>
CC: Julien Grall <julien.grall@arm.com>
---
docs/features/feature-levelling.pandoc | 16 ++++-----
docs/features/migration.pandoc | 2 +-
docs/features/sched_credit2.pandoc | 6 ++--
docs/features/sched_rtds.pandoc | 8 ++---
docs/specs/libxc-migration-stream.pandoc | 60 ++++++++++++++++----------------
docs/specs/libxl-migration-stream.pandoc | 34 +++++++++---------
6 files changed, 63 insertions(+), 63 deletions(-)
diff --git a/docs/features/feature-levelling.pandoc b/docs/features/feature-levelling.pandoc
index ef77eb8..171a42c 100644
--- a/docs/features/feature-levelling.pandoc
+++ b/docs/features/feature-levelling.pandoc
@@ -127,19 +127,19 @@ time.
## Host boot
As Xen boots, it will enumerate the features it can see. This is stored as
-the _raw\_featureset_.
+the *raw_featureset*.
Errata checks and command line arguments are then taken into account to reduce
-the _raw\_featureset_ into the _host\_featureset_, which is the set of
+the *raw_featureset* into the *host_featureset*, which is the set of
features Xen uses. On hardware with masking/override MSRs, the default MSR
-values are picked from the _host\_featureset_.
+values are picked from the *host_featureset*.
-The _host\_featureset_ is then used to calculate the _pv\_featureset_ and
-_hvm\_featureset_, which are the maximum featuresets Xen is willing to offer
+The *host_featureset* is then used to calculate the *pv_featureset* and
+*hvm_featureset*, which are the maximum featuresets Xen is willing to offer
to PV and HVM guests respectively.
In addition, Xen will calculate how much control it has over non-cooperative
-PV `CPUID` instructions, storing this information as _levelling\_caps_.
+PV `CPUID` instructions, storing this information as *levelling_caps*.
## Domain creation
@@ -163,7 +163,7 @@ features will be able to find some of them. e.g. There is no way of forcibly
preventing a guest from using 1GB superpages if the hardware supports it.
Some information simply cannot be hidden from guests. There is no way to
-control certain behaviour such as the hardware MXCSR\_MASK or x87 FPU exception
+control certain behaviour such as the hardware MXCSR_MASK or x87 FPU exception
behaviour.
@@ -196,7 +196,7 @@ be at the head of the migration stream.
MSRs are another source of features for guests. There is no general provision
for controlling the available MSRs. E.g. 64bit versions of Windows notice
-changes in IA32\_MISC\_ENABLE, and suffer a BSOD 0x109 (Critical Structure
+changes in IA32_MISC_ENABLE, and suffer a BSOD 0x109 (Critical Structure
Corruption)
diff --git a/docs/features/migration.pandoc b/docs/features/migration.pandoc
index 151c50d..7199258 100644
--- a/docs/features/migration.pandoc
+++ b/docs/features/migration.pandoc
@@ -65,7 +65,7 @@ legacy stream into a migration v2 stream.
## libxl
-With migration v2 support, LIBXL\_HAVE\_SRM\_V2 and LIBXL\_HAVE\_SRM\_V1
+With migration v2 support, LIBXL_HAVE_SRM_V2 and LIBXL_HAVE_SRM_V1
are introduced to indicate support. `domain_restore_params` gains a new
parameter, `stream_version`, which is used to distinguish between legacy and
v2 migration streams, and hence whether legacy conversion is required.
diff --git a/docs/features/sched_credit2.pandoc b/docs/features/sched_credit2.pandoc
index 6dbfdf9..bce843e 100644
--- a/docs/features/sched_credit2.pandoc
+++ b/docs/features/sched_credit2.pandoc
@@ -57,7 +57,7 @@ is all contained in `xen/common/sched_credit2.c`.
Global scheduling parameters, such as context switching rate
limiting, is only available from Xen 4.8 onward. In libxl, the
-`LIBXL\_HAVE\_SCHED\_CREDIT2\_PARAMS` symbol is introduced to
+LIBXL_HAVE_SCHED_CREDIT2_PARAMS symbol is introduced to
indicate their availability.
# Testing
@@ -82,8 +82,8 @@ following:
* vCPUs' reservations (similar to caps, but providing a vCPU with guarantees
about some pCPU time it will always be able to execute for);
* benchmarking for assessing the best combination of values for the various
- parameters (`sched\_credit2\_migrate\_resist`, `credit2\_balance\_over`,
- `credit2\_balance\_under`)
+ parameters (`sched_credit2_migrate_resist`, `credit2_balance_over`,
+ `credit2_balance_under`)
# Known issues
diff --git a/docs/features/sched_rtds.pandoc b/docs/features/sched_rtds.pandoc
index d51b499..4ccf704 100644
--- a/docs/features/sched_rtds.pandoc
+++ b/docs/features/sched_rtds.pandoc
@@ -49,12 +49,12 @@ hook based, architecture for schedulers. Thanks to this, RTDS code
is all contained in `xen/common/sched_rtds.c`.
In libxl, the availability of the RTDS scheduler is advertised by
-the presence of the LIBXL\_HAVE\_SCHED\_RTDS symbol. The ability of
+the presence of the LIBXL_HAVE_SCHED_RTDS symbol. The ability of
specifying different scheduling parameters for each vcpu has been
introduced later, and is available if the following symbols are defined:
- * `LIBXL\_HAVE\_VCPU\_SCHED\_PARAMS`,
- * `LIBXL\_HAVE\_SCHED\_RTDS\_VCPU\_PARAMS`,
- * `LIBXL\_HAVE\_SCHED\_RTDS\_VCPU\_EXTRA`.
+ * LIBXL_HAVE_VCPU_SCHED_PARAMS,
+ * LIBXL_HAVE_SCHED_RTDS_VCPU_PARAMS,
+ * LIBXL_HAVE_SCHED_RTDS_VCPU_EXTRA.
# Limitations
diff --git a/docs/specs/libxc-migration-stream.pandoc b/docs/specs/libxc-migration-stream.pandoc
index 73421ff..97dacb6 100644
--- a/docs/specs/libxc-migration-stream.pandoc
+++ b/docs/specs/libxc-migration-stream.pandoc
@@ -298,14 +298,14 @@ count Number of pages described in this record.
pfn An array of count PFNs and their types.
- Bit 63-60: XEN\_DOMCTL\_PFINFO\_* type (from
+ Bit 63-60: XEN_DOMCTL_PFINFO_* type (from
`public/domctl.h` but shifted by 32 bits)
Bit 59-52: Reserved.
Bit 51-0: PFN.
-page\_data page\_size octets of uncompressed page contents for each
+page_data page_size octets of uncompressed page contents for each
page set as present in the pfn array.
--------------------------------------------------------------------
@@ -342,7 +342,7 @@ XALLOC 0xE Allocate only.
XTAB 0xF Invalid page.
--------------------------------------------------------------------
-Table: XEN\_DOMCTL\_PFINFO\_* Page Types.
+Table: XEN_DOMCTL_PFINFO_* Page Types.
PFNs with type `BROKEN`, `XALLOC`, or `XTAB` do not have any
corresponding `page_data`.
@@ -429,13 +429,13 @@ context Binary data for this VCPU.
---------------------------------------------------------------------
Record type Accessor hypercalls
----------------------- ----------------------------------------
-X86\_PV\_VCPU\_BASIC XEN\_DOMCTL\_{get,set}vcpucontext
+X86_PV_VCPU_BASIC XEN_DOMCTL_{get,set}vcpucontext
-X86\_PV\_VCPU\_EXTENDED XEN\_DOMCTL\_{get,set}\_ext\_vcpucontext
+X86_PV_VCPU_EXTENDED XEN_DOMCTL_{get,set}\_ext_vcpucontext
-X86\_PV\_VCPU\_XSAVE XEN\_DOMCTL\_{get,set}vcpuextstate
+X86_PV_VCPU_XSAVE XEN_DOMCTL_{get,set}vcpuextstate
-X86\_PV\_VCPU\_MSRS XEN\_DOMCTL\_{get,set}\_vcpu\_msrs
+X86_PV_VCPU_MSRS XEN_DOMCTL_{get,set}\_vcpu_msrs
---------------------------------------------------------------------
\clearpage
@@ -464,7 +464,7 @@ TSC_INFO
--------
Domain TSC information, as accessed by the
-XEN\_DOMCTL\_{get,set}tscinfo hypercall sub-ops.
+XEN_DOMCTL_{get,set}tscinfo hypercall sub-ops.
0 1 2 3 4 5 6 7 octet
+------------------------+------------------------+
@@ -478,7 +478,7 @@ XEN\_DOMCTL\_{get,set}tscinfo hypercall sub-ops.
--------------------------------------------------------------------
Field Description
----------- ---------------------------------------------------
-mode TSC mode, TSC\_MODE\_* constant.
+mode TSC mode, TSC_MODE_* constant.
khz TSC frequency, in kHz.
@@ -493,7 +493,7 @@ HVM_CONTEXT
-----------
HVM Domain context, as accessed by the
-XEN\_DOMCTL\_{get,set}hvmcontext hypercall sub-ops.
+XEN_DOMCTL_{get,set}hvmcontext hypercall sub-ops.
0 1 2 3 4 5 6 7 octet
+-------------------------------------------------+
@@ -513,7 +513,7 @@ HVM_PARAMS
----------
HVM Domain parameters, as accessed by the
-HVMOP\_{get,set}\_param hypercall sub-ops.
+HVMOP_{get,set}\_param hypercall sub-ops.
0 1 2 3 4 5 6 7 octet
+------------------------+------------------------+
@@ -643,25 +643,25 @@ A typical save record for an x86 PV guest image would look like:
1. Image header
2. Domain header
-3. X86\_PV\_INFO record
-4. X86\_PV\_P2M\_FRAMES record
-5. Many PAGE\_DATA records
-6. TSC\_INFO
-7. SHARED\_INFO record
+3. X86_PV_INFO record
+4. X86_PV_P2M_FRAMES record
+5. Many PAGE_DATA records
+6. TSC_INFO
+7. SHARED_INFO record
8. VCPU context records for each online VCPU
- a. X86\_PV\_VCPU\_BASIC record
- b. X86\_PV\_VCPU\_EXTENDED record
- c. X86\_PV\_VCPU\_XSAVE record
- d. X86\_PV\_VCPU\_MSRS record
+ a. X86_PV_VCPU_BASIC record
+ b. X86_PV_VCPU_EXTENDED record
+ c. X86_PV_VCPU_XSAVE record
+ d. X86_PV_VCPU_MSRS record
9. END record
There are some strict ordering requirements. The following records must
be present in the following order as each of them depends on information
present in the preceding ones.
-1. X86\_PV\_INFO record
-2. X86\_PV\_P2M\_FRAMES record
-3. PAGE\_DATA records
+1. X86_PV_INFO record
+2. X86_PV_P2M_FRAMES record
+3. PAGE_DATA records
4. VCPU records
x86 HVM Guest
@@ -671,12 +671,12 @@ A typical save record for an x86 HVM guest image would look like:
1. Image header
2. Domain header
-3. Many PAGE\_DATA records
-4. TSC\_INFO
-5. HVM\_PARAMS
-6. HVM\_CONTEXT
+3. Many PAGE_DATA records
+4. TSC_INFO
+5. HVM_PARAMS
+6. HVM_CONTEXT
-HVM\_PARAMS must precede HVM\_CONTEXT, as certain parameters can affect
+HVM_PARAMS must precede HVM_CONTEXT, as certain parameters can affect
the validity of architectural state in the context.
@@ -731,5 +731,5 @@ Errata
1. For compatibility with older code, the receving side of a stream should
tolerate and ignore variable sized records with zero content. Xen releases
- between 4.6 and 4.8 could end up generating valid HVM\_PARAMS or
- X86\_PV\_VCPU\_{EXTENDED,XSAVE,MSRS} records with zero-length content.
+ between 4.6 and 4.8 could end up generating valid HVM_PARAMS or
+ X86_PV_VCPU_{EXTENDED,XSAVE,MSRS} records with zero-length content.
diff --git a/docs/specs/libxl-migration-stream.pandoc b/docs/specs/libxl-migration-stream.pandoc
index a1ba1ac..3766f37 100644
--- a/docs/specs/libxl-migration-stream.pandoc
+++ b/docs/specs/libxl-migration-stream.pandoc
@@ -182,8 +182,8 @@ in the stream.
The end record contains no fields; its body_length is 0.
-LIBXC\_CONTEXT
---------------
+LIBXC_CONTEXT
+-------------
A libxc context record is a marker, indicating that the stream should be
handed to `xc_domain_restore()`. `libxc` shall be responsible for reading its
@@ -199,8 +199,8 @@ The libxc context record contains no fields; its body_length is 0[^1].
might write into the stream, especially for live migration where the quantity
of data is partially proportional to the elapsed time.
-EMULATOR\_XENSTORE\_DATA
-------------------------
+EMULATOR_XENSTORE_DATA
+----------------------
A set of xenstore key/value pairs for a specific emulator associated with the
domain.
@@ -226,7 +226,7 @@ domain. At the time of writing, keys are relative to the path
although this path is free to change moving forward, thus should not be
assumed.
-EMULATOR\_CONTEXT
+EMULATOR_CONTEXT
----------------
A context blob for a specific emulator associated with the domain.
@@ -242,8 +242,8 @@ A context blob for a specific emulator associated with the domain.
The *emulator_ctx* is a binary blob interpreted by the emulator identified by
*emulator_id*. Its format is unspecified.
-CHECKPOINT\_END
----------------
+CHECKPOINT_END
+--------------
A checkpoint end record marks the end of a checkpoint in the image.
@@ -253,8 +253,8 @@ A checkpoint end record marks the end of a checkpoint in the image.
The end record contains no fields; its body_length is 0.
-CHECKPOINT\_STATE
---------------
+CHECKPOINT_STATE
+----------------
A checkpoint state record contains the control information for checkpoint. It
is only used by COLO, more detail please reference README.colo.
@@ -282,26 +282,26 @@ In COLO, Primary is running in below loop:
1. Suspend primary vm
a. Suspend primary vm
- b. Read _CHECKPOINT\_SVM\_SUSPENDED_ sent by secondary
+ b. Read *CHECKPOINT_SVM_SUSPENDED* sent by secondary
2. Checkpoint
3. Resume primary vm
- a. Read _CHECKPOINT\_SVM\_READY_ from secondary
+ a. Read *CHECKPOINT_SVM_READY* from secondary
b. Resume primary vm
- c. Read _CHECKPOINT\_SVM\_RESUMED_ from secondary
+ c. Read *CHECKPOINT_SVM_RESUMED* from secondary
4. Wait a new checkpoint
- a. Send _CHECKPOINT\_NEW_ to secondary
+ a. Send *CHECKPOINT_NEW* to secondary
While Secondary is running in below loop:
1. Resume secondary vm
- a. Send _CHECKPOINT\_SVM\_READY_ to primary
+ a. Send *CHECKPOINT_SVM_READY* to primary
b. Resume secondary vm
- c. Send _CHECKPOINT\_SVM\_RESUMED_ to primary
+ c. Send *CHECKPOINT_SVM_RESUMED* to primary
2. Wait a new checkpoint
- a. Read _CHECKPOINT\_NEW_ from primary
+ a. Read *CHECKPOINT_NEW* from primary
3. Suspend secondary vm
a. Suspend secondary vm
- b. Send _CHECKPOINT\_SVM\_SUSPENDED_ to primary
+ b. Send *CHECKPOINT_SVM_SUSPENDED* to primary
4. Checkpoint
Future Extensions
--
2.1.4
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH 2/4] docs/markdown: Switch to using pandoc, and fix underscore escaping
2019-01-02 11:43 [PATCH 0/4] docs: Multiple fixes to docs Andrew Cooper
2019-01-02 11:43 ` [PATCH 1/4] docs/pandoc: Don't escape underscores in the middle of text Andrew Cooper
@ 2019-01-02 11:43 ` Andrew Cooper
2019-01-02 12:28 ` Ian Jackson
2019-01-02 11:43 ` [PATCH 3/4] docs/man: Fix/simplify generation of manpages Andrew Cooper
2019-01-02 11:43 ` [PATCH 4/4] docs: Remove Markdown from configure.ac and the build instructions Andrew Cooper
3 siblings, 1 reply; 12+ messages in thread
From: Andrew Cooper @ 2019-01-02 11:43 UTC (permalink / raw)
To: Xen-devel
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk,
George Dunlap, Andrew Cooper, Tim Deegan, Julien Grall,
Jan Beulich, Ian Jackson
c/s a3a99df44 "docs/cmdline: Rewrite the cpuid_mask_* section" completely
forgot about how markdown gets rendered to HTML (as opposed to PDF), because
we use different translators depending on the destination format.
markdown and pandoc are very similar markup languages, but a couple of details
about pandoc cause it to have far more user-friendly inline markup.
Switch all markdown documents to be pandoc (so we are using a single
translator, and therefore a single flavour of markdown), which fixes the
rendered docs on xenbits.xen.org/docs.
While changing the format, fix the remainder of the escaped underscores in the
same mannor as the previous patch. The two problem cases here are __LINE__
and __FILE__ where the first underscore still needs escaping.
In addition, dmop.markdown and dom0less.markdown didn't used to get processed,
as only .markdown files in the misc/ directory got considered.
dom0less.pandoc gets picked up automatically now, due to being in the
features/ directory, but designs/ needs adding to the pandoc directory list
for dmop.pandoc to get processed.
While edting in appropriate areas, take the opportunity to fix some markup to
the surrounding style, and drop trailing whitespace.
No change in content - only formatting. This results in the text being easier
to read and grep.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: George Dunlap <George.Dunlap@eu.citrix.com>
CC: Ian Jackson <ian.jackson@citrix.com>
CC: Jan Beulich <JBeulich@suse.com>
CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Tim Deegan <tim@xen.org>
CC: Wei Liu <wei.liu2@citrix.com>
CC: Julien Grall <julien.grall@arm.com>
---
docs/Makefile | 2 +-
docs/designs/{dmop.markdown => dmop.pandoc} | 0
.../{dom0less.markdown => dom0less.pandoc} | 0
docs/misc/{9pfs.markdown => 9pfs.pandoc} | 42 ++---
docs/misc/{coverage.markdown => coverage.pandoc} | 0
docs/misc/{efi.markdown => efi.pandoc} | 2 +-
...-unplug.markdown => hvm-emulated-unplug.pandoc} | 0
docs/misc/{livepatch.markdown => livepatch.pandoc} | 108 ++++++------
...ecycle.markdown => pv-drivers-lifecycle.pandoc} | 0
docs/misc/{pvcalls.markdown => pvcalls.pandoc} | 18 +-
docs/misc/{pvh.markdown => pvh.pandoc} | 10 +-
...loader.markdown => x86-xenpv-bootloader.pandoc} | 8 +-
...mmand-line.markdown => xen-command-line.pandoc} | 188 ++++++++++-----------
...nstore-paths.markdown => xenstore-paths.pandoc} | 6 +-
docs/misc/{xl-psr.markdown => xl-psr.pandoc} | 0
15 files changed, 192 insertions(+), 192 deletions(-)
rename docs/designs/{dmop.markdown => dmop.pandoc} (100%)
rename docs/features/{dom0less.markdown => dom0less.pandoc} (100%)
rename docs/misc/{9pfs.markdown => 9pfs.pandoc} (98%)
rename docs/misc/{coverage.markdown => coverage.pandoc} (100%)
rename docs/misc/{efi.markdown => efi.pandoc} (99%)
rename docs/misc/{hvm-emulated-unplug.markdown => hvm-emulated-unplug.pandoc} (100%)
rename docs/misc/{livepatch.markdown => livepatch.pandoc} (92%)
rename docs/misc/{pv-drivers-lifecycle.markdown => pv-drivers-lifecycle.pandoc} (100%)
rename docs/misc/{pvcalls.markdown => pvcalls.pandoc} (99%)
rename docs/misc/{pvh.markdown => pvh.pandoc} (93%)
rename docs/misc/{x86-xenpv-bootloader.markdown => x86-xenpv-bootloader.pandoc} (89%)
rename docs/misc/{xen-command-line.markdown => xen-command-line.pandoc} (95%)
rename docs/misc/{xenstore-paths.markdown => xenstore-paths.pandoc} (99%)
rename docs/misc/{xl-psr.markdown => xl-psr.pandoc} (100%)
diff --git a/docs/Makefile b/docs/Makefile
index fba6673..8f933cf 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -17,7 +17,7 @@ MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print))
-PANDOCSRC-y := $(sort $(shell find process/ features/ misc/ specs/ -name '*.pandoc' -print))
+PANDOCSRC-y := $(sort $(shell find designs/ features/ misc/ process/ specs/ -name '*.pandoc' -print))
# Documentation targets
DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y)) \
diff --git a/docs/designs/dmop.markdown b/docs/designs/dmop.pandoc
similarity index 100%
rename from docs/designs/dmop.markdown
rename to docs/designs/dmop.pandoc
diff --git a/docs/features/dom0less.markdown b/docs/features/dom0less.pandoc
similarity index 100%
rename from docs/features/dom0less.markdown
rename to docs/features/dom0less.pandoc
diff --git a/docs/misc/9pfs.markdown b/docs/misc/9pfs.pandoc
similarity index 98%
rename from docs/misc/9pfs.markdown
rename to docs/misc/9pfs.pandoc
index 7f13831..a4dc86f 100644
--- a/docs/misc/9pfs.markdown
+++ b/docs/misc/9pfs.pandoc
@@ -1,4 +1,4 @@
-# Xen transport for 9pfs version 1
+# Xen transport for 9pfs version 1
## Background
@@ -74,7 +74,7 @@ frontend:
versions
Values: <string>
-
+
List of comma separated protocol versions supported by the backend.
For example "1,2,3". Currently the value is just "1", as there is
only one version. N.B.: this is the version of the Xen trasport
@@ -82,12 +82,12 @@ frontend:
max-rings
Values: <uint32_t>
-
+
The maximum supported number of rings per frontend.
-
+
max-ring-page-order
Values: <uint32_t>
-
+
The maximum supported size of a memory allocation in units of
log2n(machine pages), e.g. 1 = 2 pages, 2 == 4 pages, etc. It
must be at least 1.
@@ -97,18 +97,18 @@ backend:
path
Values: <string>
-
+
Host filesystem path to share.
-
+
tag
Values: <string>
-
+
Alphanumeric tag that identifies the 9pfs share. The client needs
to know the tag to be able to mount it.
-
+
security-model
Values: "none"
-
+
*none*: files are stored using the same credentials as they are
created on the guest (no user ownership squash or remap)
Only "none" is supported in this version of the protocol.
@@ -117,25 +117,25 @@ backend:
version
Values: <string>
-
+
Protocol version, chosen among the ones supported by the backend
(see **versions** under [Backend XenBus Nodes]). Currently the
value must be "1".
num-rings
Values: <uint32_t>
-
+
Number of rings. It needs to be lower or equal to max-rings.
-
+
event-channel-<num> (event-channel-0, event-channel-1, etc)
Values: <uint32_t>
-
+
The identifier of the Xen event channel used to signal activity
in the ring buffer. One for each ring.
-
+
ring-ref<num> (ring-ref0, ring-ref1, etc)
Values: <uint32_t>
-
+
The Xen grant reference granting permission for the backend to
map a page with information to setup a share ring. One for each
ring.
@@ -263,7 +263,7 @@ The shared page has the following layout:
The binary layout of `struct xen_9pfs_intf` follows:
- 0 4 8 64 68 72 76
+ 0 4 8 64 68 72 76
+---------+---------+-----//-----+---------+---------+---------+
| in_cons | in_prod | padding |out_cons |out_prod |ring_orde|
+---------+---------+-----//-----+---------+---------+---------+
@@ -315,7 +315,7 @@ what [ring.h] does.
## Ring Usage
The **in** and **out** arrays are used as circular buffers:
-
+
0 sizeof(array) == ((1<<ring_order)<<PAGE_SHIFT)/2
+-----------------------------------+
|to consume| free |to consume |
@@ -349,7 +349,7 @@ The following functions are provided to read and write to an array:
}
*masked_cons = _MASK_XEN_9PFS_IDX(*masked_cons + len);
}
-
+
static inline void xen_9pfs_write(char *buf,
XEN_9PFS_RING_IDX *masked_prod, XEN_9PFS_RING_IDX *masked_cons,
uint8_t *opaque, size_t len) {
@@ -358,9 +358,9 @@ The following functions are provided to read and write to an array:
} else {
if (len > XEN_9PFS_RING_SIZE - *masked_prod) {
memcpy(buf + *masked_prod, opaque, XEN_9PFS_RING_SIZE - *masked_prod);
- memcpy(buf, opaque + (XEN_9PFS_RING_SIZE - *masked_prod), len - (XEN_9PFS_RING_SIZE - *masked_prod));
+ memcpy(buf, opaque + (XEN_9PFS_RING_SIZE - *masked_prod), len - (XEN_9PFS_RING_SIZE - *masked_prod));
} else {
- memcpy(buf + *masked_prod, opaque, len);
+ memcpy(buf + *masked_prod, opaque, len);
}
}
*masked_prod = _MASK_XEN_9PFS_IDX(*masked_prod + len);
diff --git a/docs/misc/coverage.markdown b/docs/misc/coverage.pandoc
similarity index 100%
rename from docs/misc/coverage.markdown
rename to docs/misc/coverage.pandoc
diff --git a/docs/misc/efi.markdown b/docs/misc/efi.pandoc
similarity index 99%
rename from docs/misc/efi.markdown
rename to docs/misc/efi.pandoc
index 5b54314..23c1a27 100644
--- a/docs/misc/efi.markdown
+++ b/docs/misc/efi.pandoc
@@ -47,7 +47,7 @@ thus look like this (`#` serving as comment character):
[global]
default=sle11sp2
-
+
[sle11sp2]
options=console=vga,com1 com1=57600 loglvl=all noreboot
kernel=vmlinuz-3.0.31-0.4-xen [domain 0 command line options]
diff --git a/docs/misc/hvm-emulated-unplug.markdown b/docs/misc/hvm-emulated-unplug.pandoc
similarity index 100%
rename from docs/misc/hvm-emulated-unplug.markdown
rename to docs/misc/hvm-emulated-unplug.pandoc
diff --git a/docs/misc/livepatch.markdown b/docs/misc/livepatch.pandoc
similarity index 92%
rename from docs/misc/livepatch.markdown
rename to docs/misc/livepatch.pandoc
index 2bdf871..6d9f72f 100644
--- a/docs/misc/livepatch.markdown
+++ b/docs/misc/livepatch.pandoc
@@ -100,13 +100,13 @@ while the new patched hypervisor would be:
48 89 e0 mov %rsp,%rax
48 25 00 80 ff ff and $0xffffffffffff8000,%rax
-This is inside the arch\_do\_domctl. This new change adds 21 extra
+This is inside the `arch_do_domctl`. This new change adds 21 extra
bytes of code which alters all the offsets inside the function. To alter
these offsets and add the extra 21 bytes of code we might not have enough
space in .text to squeeze this in.
As such we could simplify this problem by only patching the site
-which calls arch\_do\_domctl:
+which calls `arch_do_domctl`:
do_domctl:
e8 4b b1 05 00 callq ffff82d08015fbb9 <arch_do_domctl>
@@ -154,7 +154,7 @@ CPU branching logic (I-cache, but it is just one unconditional jump).
For this example we will assume that the hypervisor has not been compiled with
XSA-125 (see
-[pre-fill structures for certain HYPERVISOR\_xen\_version sub-ops](http://xenbits.xen.org/gitweb/?p=xen.git;a=commitdiff;h=fe2e079f642effb3d24a6e1a7096ef26e691d93e))
+[pre-fill structures for certain HYPERVISOR_xen_version sub-ops](http://xenbits.xen.org/gitweb/?p=xen.git;a=commitdiff;h=fe2e079f642effb3d24a6e1a7096ef26e691d93e))
which mem-sets an structure in `xen_version` hypercall. This function is not
called **anywhere** in the hypervisor (it is called by the guest) but
referenced in the `compat_hypercall_table` and `hypercall_table` (and
@@ -192,7 +192,7 @@ new replacement function which required:
* Inserting trampoline with new offset in the old function to point to the
new function.
* Optionally we can insert in the old function a trampoline jump to an function
- providing an BUG\_ON to catch errant code.
+ providing an BUG_ON to catch errant code.
The disadvantage of this are that the unconditional jump will consume a small
I-cache penalty. However the simplicity of the patching and higher chance
@@ -244,7 +244,7 @@ Note that every structure has padding. This is added so that the hypervisor
can re-use those fields as it sees fit.
Earlier design attempted to ineptly explain the relations of the ELF sections
-to each other without using proper ELF mechanism (sh\_info, sh\_link, data
+to each other without using proper ELF mechanism (sh_info, sh_link, data
structures using Elf types, etc). This design will explain the structures
and how they are used together and not dig in the ELF format - except mention
that the section names should match the structure names.
@@ -269,14 +269,14 @@ like what the Linux kernel module loader does.
The payload contains at least three sections:
- * `.livepatch.funcs` - which is an array of livepatch\_func structures.
+ * `.livepatch.funcs` - which is an array of livepatch_func structures.
* `.livepatch.depends` - which is an ELF Note that describes what the payload
depends on. **MUST** have one.
* `.note.gnu.build-id` - the build-id of this payload. **MUST** have one.
### .livepatch.funcs
-The `.livepatch.funcs` contains an array of livepatch\_func structures
+The `.livepatch.funcs` contains an array of livepatch_func structures
which describe the functions to be patched:
struct livepatch_func {
@@ -395,7 +395,7 @@ which follows the format of an ELF Note. The contents of this
build the hypevisor and payload.
If GNU linker is used then the name is `GNU` and the description
-is a NT\_GNU\_BUILD\_ID type ID. The description can be an SHA1
+is a NT_GNU_BUILD_ID type ID. The description can be an SHA1
checksum, MD5 checksum or any unique value.
The size of these structures varies with the `--build-id` linker option.
@@ -426,7 +426,7 @@ Furthermore it is possible to have multiple different payloads for the same
function. As such an unique name per payload has to be visible to allow proper manipulation.
The hypercall is part of the `xen_sysctl`. The top level structure contains
-one uint32\_t to determine the sub-operations and one padding field which
+one uint32_t to determine the sub-operations and one padding field which
*MUST* always be zero.
struct xen_sysctl_livepatch_op {
@@ -439,7 +439,7 @@ one uint32\_t to determine the sub-operations and one padding field which
while the rest of hypercall specific structures are part of the this structure.
-### Basic type: struct xen\_livepatch\_name
+### Basic type: struct xen_livepatch_name
Most of the hypercalls employ an shared structure called `struct xen_livepatch_name`
which contains:
@@ -462,12 +462,12 @@ The structure is as follow:
uint16_t pad[3]; /* IN: MUST be zero. */
};
-### XEN\_SYSCTL\_LIVEPATCH\_UPLOAD (0)
+### XEN_SYSCTL_LIVEPATCH_UPLOAD (0)
Upload a payload to the hypervisor. The payload is verified
against basic checks and if there are any issues the proper return code
will be returned. The payload is not applied at this time - that is
-controlled by *XEN\_SYSCTL\_LIVEPATCH\_ACTION*.
+controlled by *XEN_SYSCTL_LIVEPATCH_ACTION*.
The caller provides:
@@ -480,7 +480,7 @@ payload. It can be embedded into the ELF payload at creation time
and extracted by tools.
The return value is zero if the payload was succesfully uploaded.
-Otherwise an -XEN\_EXX return value is provided. Duplicate `name` are not supported.
+Otherwise an -XEN_EXX return value is provided. Duplicate `name` are not supported.
The `payload` is the ELF payload as mentioned in the `Payload format` section.
@@ -492,7 +492,7 @@ The structure is as follow:
XEN_GUEST_HANDLE_64(uint8) payload; /* IN: ELF file. */
};
-### XEN\_SYSCTL\_LIVEPATCH\_GET (1)
+### XEN_SYSCTL_LIVEPATCH_GET (1)
Retrieve an status of an specific payload. This caller provides:
@@ -503,25 +503,25 @@ Retrieve an status of an specific payload. This caller provides:
Upon completion the `struct xen_livepatch_status` is updated.
* `status` - indicates the current status of the payload:
- * *LIVEPATCH\_STATUS\_CHECKED* (1) loaded and the ELF payload safety checks passed.
- * *LIVEPATCH\_STATUS\_APPLIED* (2) loaded, checked, and applied.
+ * *LIVEPATCH_STATUS_CHECKED* (1) loaded and the ELF payload safety checks passed.
+ * *LIVEPATCH_STATUS_APPLIED* (2) loaded, checked, and applied.
* No other value is possible.
- * `rc` - -XEN\_EXX type errors encountered while performing the last
- LIVEPATCH\_ACTION\_\* operation. The normal values can be zero or -XEN\_EAGAIN which
+ * `rc` - -XEN_EXX type errors encountered while performing the last
+ LIVEPATCH_ACTION_* operation. The normal values can be zero or -XEN_EAGAIN which
respectively mean: success or operation in progress. Other values
imply an error occurred. If there is an error in `rc`, `status` will **NOT**
have changed.
-The return value of the hypercall is zero on success and -XEN\_EXX on failure.
+The return value of the hypercall is zero on success and -XEN_EXX on failure.
(Note that the `rc` value can be different from the return value, as in
-rc=-XEN\_EAGAIN and return value can be 0).
+rc = -XEN_EAGAIN and return value can be 0).
For example, supposing there is an payload:
status: LIVEPATCH_STATUS_CHECKED
rc: 0
-We apply an action - LIVEPATCH\_ACTION\_REVERT - to revert it (which won't work
+We apply an action - LIVEPATCH_ACTION_REVERT - to revert it (which won't work
as we have not even applied it. Afterwards we will have:
status: LIVEPATCH_STATUS_CHECKED
@@ -545,7 +545,7 @@ The structure is as follow:
xen_livepatch_status_t status; /* IN/OUT: status of the payload. */
};
-### XEN\_SYSCTL\_LIVEPATCH\_LIST (2)
+### XEN_SYSCTL_LIVEPATCH_LIST (2)
Retrieve an array of abbreviated status and names of payloads that are loaded in the
hypervisor.
@@ -566,11 +566,11 @@ The caller provides:
structures. Caller *MUST* allocate up to `nr` of them.
* `name` - Virtual address of where to write the unique name of the payload.
Caller *MUST* allocate up to `nr` of them. Each *MUST* be of
- **XEN\_LIVEPATCH\_NAME\_SIZE** size. Note that **XEN\_LIVEPATCH\_NAME\_SIZE** includes
+ **XEN_LIVEPATCH_NAME_SIZE** size. Note that **XEN_LIVEPATCH_NAME_SIZE** includes
the NUL terminator.
* `len` - Virtual address of where to write the length of each unique name
of the payload. Caller *MUST* allocate up to `nr` of them. Each *MUST* be
- of sizeof(uint32\_t) (4 bytes).
+ of sizeof(uint32_t) (4 bytes).
If the hypercall returns an positive number, it is the number (upto `nr`
provided to the hypercall) of the payloads returned, along with `nr` updated
@@ -579,7 +579,7 @@ across hypercalls - if it varies the data is stale and further calls could
fail). The `status`, `name`, and `len` are updated at their designed index
value (`idx`) with the returned value of data.
-If the hypercall returns -XEN\_E2BIG the `nr` is too big and should be
+If the hypercall returns -XEN_E2BIG the `nr` is too big and should be
lowered.
If the hypercall returns an zero value there are no more payloads.
@@ -594,11 +594,11 @@ data and start from scratch. It is OK for the toolstack to use the new
The `struct xen_livepatch_status` structure contains an status of payload which includes:
* `status` - indicates the current status of the payload:
- * *LIVEPATCH\_STATUS\_CHECKED* (1) loaded and the ELF payload safety checks passed.
- * *LIVEPATCH\_STATUS\_APPLIED* (2) loaded, checked, and applied.
+ * *LIVEPATCH_STATUS_CHECKED* (1) loaded and the ELF payload safety checks passed.
+ * *LIVEPATCH_STATUS_APPLIED* (2) loaded, checked, and applied.
* No other value is possible.
- * `rc` - -XEN\_EXX type errors encountered while performing the last
- LIVEPATCH\_ACTION\_\* operation. The normal values can be zero or -XEN\_EAGAIN which
+ * `rc` - -XEN_EXX type errors encountered while performing the last
+ LIVEPATCH_ACTION_* operation. The normal values can be zero or -XEN_EAGAIN which
respectively mean: success or operation in progress. Other values
imply an error occurred. If there is an error in `rc`, `status` will **NOT**
have changed.
@@ -624,29 +624,29 @@ The structure is as follow:
Must have nr of them. */
};
-### XEN\_SYSCTL\_LIVEPATCH\_ACTION (3)
+### XEN_SYSCTL_LIVEPATCH_ACTION (3)
Perform an operation on the payload structure referenced by the `name` field.
The operation request is asynchronous and the status should be retrieved
-by using either **XEN\_SYSCTL\_LIVEPATCH\_GET** or **XEN\_SYSCTL\_LIVEPATCH\_LIST** hypercall.
+by using either **XEN_SYSCTL_LIVEPATCH_GET** or **XEN_SYSCTL_LIVEPATCH_LIST** hypercall.
The caller provides:
* A `struct xen_livepatch_name` `name` containing the unique name.
* `cmd` The command requested:
- * *LIVEPATCH\_ACTION\_UNLOAD* (1) Unload the payload.
+ * *LIVEPATCH_ACTION_UNLOAD* (1) Unload the payload.
Any further hypercalls against the `name` will result in failure unless
- **XEN\_SYSCTL\_LIVEPATCH\_UPLOAD** hypercall is perfomed with same `name`.
- * *LIVEPATCH\_ACTION\_REVERT* (2) Revert the payload. If the operation takes
+ **XEN_SYSCTL_LIVEPATCH_UPLOAD** hypercall is perfomed with same `name`.
+ * *LIVEPATCH_ACTION_REVERT* (2) Revert the payload. If the operation takes
more time than the upper bound of time the `rc` in `xen_livepatch_status`
- retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET** will be -XEN\_EBUSY.
- * *LIVEPATCH\_ACTION\_APPLY* (3) Apply the payload. If the operation takes
+ retrieved via **XEN_SYSCTL_LIVEPATCH_GET** will be -XEN_EBUSY.
+ * *LIVEPATCH_ACTION_APPLY* (3) Apply the payload. If the operation takes
more time than the upper bound of time the `rc` in `xen_livepatch_status`
- retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET** will be -XEN\_EBUSY.
- * *LIVEPATCH\_ACTION\_REPLACE* (4) Revert all applied payloads and apply this
+ retrieved via **XEN_SYSCTL_LIVEPATCH_GET** will be -XEN_EBUSY.
+ * *LIVEPATCH_ACTION_REPLACE* (4) Revert all applied payloads and apply this
payload. If the operation takes more time than the upper bound of time
- the `rc` in `xen_livepatch_status` retrieved via **XEN\_SYSCTL\_LIVEPATCH\_GET**
- will be -XEN\_EBUSY.
+ the `rc` in `xen_livepatch_status` retrieved via **XEN_SYSCTL_LIVEPATCH_GET**
+ will be -XEN_EBUSY.
* `time` The upper bound of time (ns) the cmd should take. Zero means to use
the hypervisor default. If within the time the operation does not succeed
the operation would go in error state.
@@ -670,11 +670,11 @@ The structure is as follow:
};
-## State diagrams of LIVEPATCH\_ACTION commands.
+## State diagrams of LIVEPATCH_ACTION commands.
There is a strict ordering state of what the commands can be.
-The LIVEPATCH\_ACTION prefix has been dropped to easy reading and
-does not include the LIVEPATCH\_STATES:
+The LIVEPATCH_ACTION prefix has been dropped to easy reading and
+does not include the LIVEPATCH_STATES:
/->\
\ /
@@ -682,11 +682,11 @@ does not include the LIVEPATCH\_STATES:
\ |
\-------------------<-------------/
-## State transition table of LIVEPATCH\_ACTION commands and LIVEPATCH\_STATUS.
+## State transition table of LIVEPATCH_ACTION commands and LIVEPATCH_STATUS.
Note that:
- - The CHECKED state is the starting one achieved with *XEN\_SYSCTL\_LIVEPATCH\_UPLOAD* hypercall.
+ - The CHECKED state is the starting one achieved with *XEN_SYSCTL_LIVEPATCH_UPLOAD* hypercall.
- The REVERT operation on success will automatically move to the CHECKED state.
- There are two STATES: CHECKED and APPLIED.
- There are four actions (aka commands): APPLY, REPLACE, REVERT, and UNLOAD.
@@ -721,10 +721,10 @@ All the other state transitions are invalid.
The normal sequence of events is to:
- 1. *XEN\_SYSCTL\_LIVEPATCH\_UPLOAD* to upload the payload. If there are errors *STOP* here.
- 2. *XEN\_SYSCTL\_LIVEPATCH\_GET* to check the `->rc`. If *-XEN\_EAGAIN* spin. If zero go to next step.
- 3. *XEN\_SYSCTL\_LIVEPATCH\_ACTION* with *LIVEPATCH\_ACTION\_APPLY* to apply the patch.
- 4. *XEN\_SYSCTL\_LIVEPATCH\_GET* to check the `->rc`. If in *-XEN\_EAGAIN* spin. If zero exit with success.
+ 1. *XEN_SYSCTL_LIVEPATCH_UPLOAD* to upload the payload. If there are errors *STOP* here.
+ 2. *XEN_SYSCTL_LIVEPATCH_GET* to check the `->rc`. If *-XEN_EAGAIN* spin. If zero go to next step.
+ 3. *XEN_SYSCTL_LIVEPATCH_ACTION* with *LIVEPATCH_ACTION_APPLY* to apply the patch.
+ 4. *XEN_SYSCTL_LIVEPATCH_GET* to check the `->rc`. If in *-XEN_EAGAIN* spin. If zero exit with success.
## Addendum
@@ -758,7 +758,7 @@ minimize the chance of the patch not being applied due to safety
checks failing. Safety checks such as not patching code which
is on the stack - which can lead to corruption.
-#### Rendezvous code instead of stop\_machine for patching
+#### Rendezvous code instead of stop_machine for patching
The hypervisor's time rendezvous code runs synchronously across all CPUs
every second. Using the `stop_machine` to patch can stall the time rendezvous
@@ -769,7 +769,7 @@ However the entrance point for that code is `do_softirq ->
timer_softirq_action -> time_calibration` which ends up calling
`on_selected_cpus` on remote CPUs.
-The remote CPUs receive CALL\_FUNCTION\_VECTOR IPI and execute the
+The remote CPUs receive CALL_FUNCTION_VECTOR IPI and execute the
desired function.
#### Before entering the guest code.
@@ -918,10 +918,10 @@ The implementation must also have a mechanism for (in no particular order):
the stack, make sure the payload is built with same compiler as hypervisor).
Specifically we want to make sure that live patching codepaths cannot be patched.
* NOP out the code sequence if `new_size` is zero.
- * Deal with other relocation types: R\_X86\_64\_[8,16,32,32S], R\_X86\_64\_PC[8,16,64]
+ * Deal with other relocation types: `R_X86_64_[8,16,32,32S]`, `R_X86_64_PC[8,16,64]`
in payload file.
-### Handle inlined \_\_LINE\_\_
+### Handle inlined \__LINE__
This problem is related to hotpatch construction
and potentially has influence on the design of the hotpatching
@@ -981,7 +981,7 @@ Options:
For BUG(), WARN(), etc., the line number is embedded into the bug frame, not
the function itself.
-Similar considerations are true to a lesser extent for \_\_FILE\_\_, but it
+Similar considerations are true to a lesser extent for \__FILE__, but it
could be argued that file renaming should be done outside of hotpatches.
## Signature checking requirements.
diff --git a/docs/misc/pv-drivers-lifecycle.markdown b/docs/misc/pv-drivers-lifecycle.pandoc
similarity index 100%
rename from docs/misc/pv-drivers-lifecycle.markdown
rename to docs/misc/pv-drivers-lifecycle.pandoc
diff --git a/docs/misc/pvcalls.markdown b/docs/misc/pvcalls.pandoc
similarity index 99%
rename from docs/misc/pvcalls.markdown
rename to docs/misc/pvcalls.pandoc
index d3f7f20..0c48b29 100644
--- a/docs/misc/pvcalls.markdown
+++ b/docs/misc/pvcalls.pandoc
@@ -45,7 +45,7 @@ community. If you are a Xen contributor you can skip this section.
virtio device emulators.
* VMX and SVM
-
+
On Intel processors, VMX is the CPU flag for VT-x, hardware
virtualization support. It corresponds to SVM on AMD processors.
@@ -228,7 +228,7 @@ requests are allocated on the ring using the `RING_GET_REQUEST` macro.
The list of commands below is in calling order.
The format is defined as follows:
-
+
#define PVCALLS_SOCKET 0
#define PVCALLS_CONNECT 1
#define PVCALLS_RELEASE 2
@@ -885,7 +885,7 @@ buffers for transferring data, and, together, they are the data ring.
| @4099->8196: out |
| ref[1] |
+-------------------+
-
+
#### Indexes Page Structure
@@ -950,7 +950,7 @@ buffers for transferring data, and, together, they are the data ring.
The binary layout of `struct pvcalls_data_intf` follows:
- 0 4 8 12 64 68 72 76
+ 0 4 8 12 64 68 72 76
+---------+---------+---------+-----//-----+---------+---------+---------+
| in_cons | in_prod |in_error | padding |out_cons |out_prod |out_error|
+---------+---------+---------+-----//-----+---------+---------+---------+
@@ -1003,7 +1003,7 @@ what [ring.h] does.
#### Workflow
The **in** and **out** arrays are used as circular buffers:
-
+
0 sizeof(array) == ((1<<ring_order)<<PAGE_SHIFT)/2
+-----------------------------------+
|to consume| free |to consume |
@@ -1028,16 +1028,16 @@ left unconsumed in an array:
PVCALLS_RING_IDX ring_size)
{
PVCALLS_RING_IDX size;
-
+
if (prod == cons)
return 0;
-
+
prod = _MASK_PVCALLS_IDX(prod, ring_size);
cons = _MASK_PVCALLS_IDX(cons, ring_size);
-
+
if (prod == cons)
return ring_size;
-
+
if (prod > cons)
size = prod - cons;
else {
diff --git a/docs/misc/pvh.markdown b/docs/misc/pvh.pandoc
similarity index 93%
rename from docs/misc/pvh.markdown
rename to docs/misc/pvh.pandoc
index 1c9a00b..f892e6e 100644
--- a/docs/misc/pvh.markdown
+++ b/docs/misc/pvh.pandoc
@@ -35,7 +35,7 @@ All other processor registers and flag bits are unspecified. The OS is in
charge of setting up it's own stack, GDT and IDT.
The format of the boot start info structure (pointed to by %ebx) can be found
-in xen/include/public/arch-x86/hvm/start\_info.h
+in `xen/include/public/arch-x86/hvm/start_info.h`
Other relevant information needed in order to boot a guest kernel
(console page address, xenstore event channel...) can be obtained
@@ -50,7 +50,7 @@ AP startup can be performed using hypercalls or the local APIC if present.
The following VCPU hypercalls can be used in order to bring up secondary vCPUs:
* `VCPUOP_initialise` is used to set the initial state of the vCPU. The
- argument passed to the hypercall must be of the type vcpu\_hvm\_context.
+ argument passed to the hypercall must be of the type vcpu_hvm_context.
See `public/hvm/hvm_vcpu.h` for the layout of the structure. Note that
this hypercall allows starting the vCPU in several modes (16/32/64bits),
regardless of the mode the BSP is currently running on.
@@ -68,7 +68,7 @@ PVHv2 guests that have access to hardware (either emulated or real) will also
have ACPI tables with the description of the hardware that's available to the
guest. This applies to both privileged and unprivileged guests. A pointer to
the position of the RSDP in memory (if present) can be fetched from the start
-info structure that's passed at boot time (field rsdp\_paddr).
+info structure that's passed at boot time (field `rsdp_paddr`).
Description of paravirtualized devices will come from XenStore, just as it's
done for HVM guests.
@@ -89,8 +89,8 @@ are available on native hardware.
Interrupts from paravirtualized devices are delivered using event channels, see
[Event Channel Internals][event_channels] for more detailed information about
event channels. Delivery of those interrupts can be configured in the same way
-as HVM guests, check xen/include/public/hvm/params.h and
-xen/include/public/hvm/hvm\_op.h for more information about available delivery
+as HVM guests, check `xen/include/public/hvm/params.h` and
+`xen/include/public/hvm/hvm_op.h` for more information about available delivery
methods.
## MTRR ##
diff --git a/docs/misc/x86-xenpv-bootloader.markdown b/docs/misc/x86-xenpv-bootloader.pandoc
similarity index 89%
rename from docs/misc/x86-xenpv-bootloader.markdown
rename to docs/misc/x86-xenpv-bootloader.pandoc
index ec8854e..5825223 100644
--- a/docs/misc/x86-xenpv-bootloader.markdown
+++ b/docs/misc/x86-xenpv-bootloader.pandoc
@@ -31,9 +31,9 @@ filesystem as:
Where `<ARCH>` is the first element of the GNU triplet e.g. one of:
- * i386 (nb only i386, not i686 etc), corresponding to the Xen
- x86\_32(p) arch;
- * x86\_64, corresponding to the Xen x86\_64 arch;
+ * `i386` (nb only `i386`, not `i686` etc), corresponding to the Xen
+ `x86_32(p)` arch;
+ * `x86_64`, corresponding to the Xen `x86_64` arch;
It is allowable for `/boot` to be a separate filesystem from `/` and
therefore stage 1 bootloaders should search
@@ -44,6 +44,6 @@ and therefore it is not necessary to search for /pvboot-<ARCH>.elf.
It is not in general possible under Xen for a bootloader to boot a
kernel of a different width from itself, and this extends to
chainloading from a stage one. Therefore it is permissible to have
-both `/boot/xen/pvboot-i386.elf` and `/boot/xen/pvboot-x86\_64.elf`
+both `/boot/xen/pvboot-i386.elf` and `/boot/xen/pvboot-x86_64.elf`
present in a guest to be used by the appropriate stage 1 (e.g. for
systems with 32-bit userspace and an optional 64-bit kernel).
diff --git a/docs/misc/xen-command-line.markdown b/docs/misc/xen-command-line.pandoc
similarity index 95%
rename from docs/misc/xen-command-line.markdown
rename to docs/misc/xen-command-line.pandoc
index 78b207c..a755a67 100644
--- a/docs/misc/xen-command-line.markdown
+++ b/docs/misc/xen-command-line.pandoc
@@ -104,13 +104,13 @@ Because responsibility for ACPI processing is shared between Xen and
the domain 0 kernel this option is automatically propagated to the
domain 0 command line
-### acpi\_apic\_instance
+### acpi_apic_instance
> `= <integer>`
Specify which ACPI MADT table to parse for APIC information, if more
than one is present.
-### acpi\_pstate\_strict (x86)
+### acpi_pstate_strict (x86)
> `= <boolean>`
> Default: `false`
@@ -119,12 +119,12 @@ Enforce checking that P-state transitions by the ACPI cpufreq driver
actually result in the nominated frequency to be established. A warning
message will be logged if that isn't the case.
-### acpi\_skip\_timer\_override (x86)
+### acpi_skip_timer_override (x86)
> `= <boolean>`
Instruct Xen to ignore timer-interrupt override.
-### acpi\_sleep (x86)
+### acpi_sleep (x86)
> `= s3_bios | s3_mode`
`s3_bios` instructs Xen to invoke video BIOS initialization during S3
@@ -133,7 +133,7 @@ resume.
`s3_mode` instructs Xen to set up the boot time (option `vga=`) video
mode during S3 resume.
-### allow\_unsafe (x86)
+### allow_unsafe (x86)
> `= <boolean>`
> Default: `false`
@@ -168,7 +168,7 @@ Permit Xen to use APIC Virtualisation Extensions. This is an optimisation
available as part of VT-x, and allows hardware to take care of the guests APIC
handling, rather than requiring emulation in Xen.
-### apic\_verbosity (x86)
+### apic_verbosity (x86)
> `= verbose | debug`
Increase the verbosity of the APIC code from the default value.
@@ -240,7 +240,7 @@ with a guarantee that memory allocations always provide scrubbed pages.
This option reduces boot time on machines with a large amount of RAM while
still providing security benefits.
-### bootscrub\_chunk
+### bootscrub_chunk
> `= <size>`
> Default: `128M`
@@ -334,7 +334,7 @@ The accepted name keywords for name=value pairs are:
Do note - these values are multiplied by 16.
* `data-bits` - integer between 5 and 8
* `dev` - accepted values are `pci` OR `amt`. If this option
- is used to specify if the serial device is pci-based. The io\_base
+ is used to specify if the serial device is pci-based. The io_base
cannot be specified when `dev=pci` or `dev=amt` is used.
* `io-base` - accepts integer which specified IO base port for UART registers
* `irq` - IRQ number to use
@@ -352,7 +352,7 @@ The following are examples of correct specifications:
com1=115200,8n1,0x3f8,4,reg_width=4,reg_shift=2
com1=baud=115200,parity=n,stop_bits=1,io_base=0x3f8,reg_width=4
-### conring\_size
+### conring_size
> `= <size>`
> Default: `conring_size=16k`
@@ -384,7 +384,7 @@ only available when used together with `pv-in-pvh`.
`none` indicates that Xen should not use a console. This option only
makes sense on its own.
-### console\_timestamps
+### console_timestamps
> `= none | date | datems | boot | raw`
> Default: `none`
@@ -406,7 +406,7 @@ Specify which timestamp format Xen should use for each console line.
For compatibility with the older boolean parameter, specifying
`console_timestamps` alone will enable the `date` option.
-### console\_to\_ring
+### console_to_ring
> `= <boolean>`
> Default: `false`
@@ -431,12 +431,12 @@ including omission, causes Xen to automatically switch to the dom0
console during dom0 boot. Use `conswitch=ax` to keep the default switch
character, but for xen to keep the console.
-### core\_parking
+### core_parking
> `= power | performance`
> Default: `power`
-### cpu\_type (x86)
+### cpu_type (x86)
> `= arch_perfmon`
If set, force use of the performance counters for oprofile, rather than detecting
@@ -473,7 +473,7 @@ won't offer them to guests.
> Applicability: AMD
-If none of the other **cpuid\_mask\_\*** options are given, Xen has a set of
+If none of the other **cpuid_mask_\*** options are given, Xen has a set of
pre-configured masks to make the current processor appear to be
family/revision specified.
@@ -514,13 +514,13 @@ reduction of features at Xen's disposal to manage guests.
### cpuinfo (x86)
> `= <boolean>`
-### crashinfo\_maxaddr
+### crashinfo_maxaddr
> `= <size>`
> Default: `4G`
Specify the maximum address to allocate certain structures, if used in
-combination with the `low_crashinfo` command line option.
+combination with the **low_crashinfo** command line option.
### crashkernel
> `= <ramsize-range>:<size>[,...][{@,<}<offset>]`
@@ -541,13 +541,13 @@ the address range the area should fall into.
which would otherwise require escaping of the < option
-### credit2\_balance\_over
+### credit2_balance_over
> `= <integer>`
-### credit2\_balance\_under
+### credit2_balance_under
> `= <integer>`
-### credit2\_cap\_period\_ms
+### credit2_cap_period_ms
> `= <integer>`
> Default: `10`
@@ -557,7 +557,7 @@ once every cap period interval. Default is 10 ms. The amount of budget
they receive depends on their cap. For instance, a domain with a 50% cap
will receive 50% of 10 ms, so 5 ms.
-### credit2\_load\_precision\_shift
+### credit2_load_precision_shift
> `= <integer>`
> Default: `18`
@@ -565,7 +565,7 @@ will receive 50% of 10 ms, so 5 ms.
Specify the number of bits to use for the fractional part of the
values involved in Credit2 load tracking and load balancing math.
-### credit2\_load\_window\_shift
+### credit2_load_window_shift
> `= <integer>`
> Default: `30`
@@ -590,7 +590,7 @@ also slow in responding to load changes.
The default value of `1 sec` is rather long.
-### credit2\_runqueue
+### credit2_runqueue
> `= cpu | core | socket | node | all`
> Default: `socket`
@@ -616,7 +616,7 @@ Available alternatives, with their meaning, are:
Specify the USB controller to use, either by instance number (when going
over the PCI busses sequentially) or by PCI device (must be on segment 0).
-### debug\_stack\_lines
+### debug_stack_lines
> `= <integer>`
> Default: `20`
@@ -631,7 +631,7 @@ Limits the number lines printed in Xen stack traces.
Specify the size of the console debug trace buffer in KiB. The debug
trace feature is only enabled in debugging builds of Xen.
-### dma\_bits
+### dma_bits
> `= <integer>`
Specify the bit width of the DMA heap.
@@ -686,12 +686,12 @@ This list of booleans controls the iommu usage by Dom0:
mapped when using the `map-inclusive` option. This option is available to all
Dom0 modes and is enabled by default on Intel hardware.
-### dom0\_ioports\_disable (x86)
+### dom0_ioports_disable (x86)
> `= List of <hex>-<hex>`
Specify a list of IO ports to be excluded from dom0 access.
-### dom0\_max\_vcpus
+### dom0_max_vcpus
Either:
@@ -720,13 +720,13 @@ For example, with `dom0_max_vcpus=4-8`:
> 8 | 8
> 10 | 8
-### dom0\_mem (ARM)
+### dom0_mem (ARM)
> `= <size>`
Set the amount of memory for the initial domain (dom0). It must be
greater than zero. This parameter is required.
-### dom0\_mem (x86)
+### dom0_mem (x86)
> `= List of ( min:<sz> | max:<sz> | <sz> )`
Set the amount of memory for the initial domain (dom0). If a size is
@@ -766,7 +766,7 @@ Practices](http://wiki.xen.org/wiki/Xen_Best_Practices#Xen_dom0_dedicated_memory
This option doesn't have effect if pv-shim mode is enabled.
-### dom0\_nodes (x86)
+### dom0_nodes (x86)
> `= List of [ <integer> | relaxed | strict ]`
@@ -778,7 +778,7 @@ restrictions set up here. Note that the values to be specified here are
ACPI PXM ones, not Xen internal node numbers. `relaxed` sets up vCPU
affinities to prefer but be not limited to the specified node(s).
-### dom0\_vcpus\_pin
+### dom0_vcpus_pin
> `= <boolean>`
> Default: `false`
@@ -873,7 +873,7 @@ introduced with the Nehalem architecture.
disable PML. `pml=0` can be used to prevent the use of PML on otherwise
capable hardware.
-### extra\_guest\_irqs
+### extra_guest_irqs
> `= [<domU number>][,<dom0 number>]`
> Default: `32,<variable>`
@@ -913,7 +913,7 @@ enabled by running either:
changed that setting.
* `disabled`: This causes the XSM framework to revert to the dummy module. The
dummy module provides the same security policy as is used when compiling the
- hypervisor without support for XSM. The xsm\_op hypercall can also be used to
+ hypervisor without support for XSM. The xsm_op hypercall can also be used to
switch to this mode after boot, but there is no way to re-enable FLASK once
the dummy module is loaded.
@@ -927,16 +927,16 @@ Specify the font size when using the VESA console driver.
> Default: `false`
-Allow EPT to be enabled when VMX feature VM\_ENTRY\_LOAD\_GUEST\_PAT is not
+Allow EPT to be enabled when VMX feature `VM_ENTRY_LOAD_GUEST_PAT` is not
present.
*Warning:*
-Due to CVE-2013-2212, VMX feature VM\_ENTRY\_LOAD\_GUEST\_PAT is by default
+Due to CVE-2013-2212, VMX feature `VM_ENTRY_LOAD_GUEST_PAT` is by default
required as a prerequisite for using EPT. If you are not using PCI Passthrough,
or trust the guest administrator who would be using passthrough, then the
requirement can be relaxed. This option is particularly useful for nested
virtualization, to allow the L1 hypervisor to use EPT even if the L0 hypervisor
-does not provide VM\_ENTRY\_LOAD\_GUEST\_PAT.
+does not provide `VM_ENTRY_LOAD_GUEST_PAT`.
### gdb
> `= com1[H,L] | com2[H,L] | dbgp`
@@ -960,7 +960,7 @@ guests point of view.
The usage of gnttab v2 is not security supported on ARM platforms.
-### gnttab\_max\_frames
+### gnttab_max_frames
> `= <integer>`
> Default: `64`
@@ -973,7 +973,7 @@ value settable via Xen tools.
Dom0 is using this value for sizing its grant table.
-### gnttab\_max\_maptrack\_frames
+### gnttab_max_maptrack_frames
> `= <integer>`
> Default: `1024`
@@ -986,7 +986,7 @@ value settable via Xen tools.
Dom0 is using this value for sizing its maptrack table.
-### guest\_loglvl
+### guest_loglvl
> `= <level>[/<rate-limited level>]` where level is `none | error | warning | info | debug | all`
> Default: `guest_loglvl=none/warning`
@@ -1007,7 +1007,7 @@ should be rate limited.
Flag to globally enable or disable support for Hardware Assisted
Paging (HAP)
-### hap\_1gb (x86)
+### hap_1gb (x86)
> `= <boolean>`
> Default: `true`
@@ -1015,7 +1015,7 @@ Paging (HAP)
Flag to enable 1 GB host page table support for Hardware Assisted
Paging (HAP).
-### hap\_2mb (x86)
+### hap_2mb (x86)
> `= <boolean>`
> Default: `true`
@@ -1023,7 +1023,7 @@ Paging (HAP).
Flag to enable 2 MB host page table support for Hardware Assisted
Paging (HAP).
-### hardware\_dom
+### hardware_dom
> `= <domid>`
> Default: `0`
@@ -1033,7 +1033,7 @@ intended to be used when domain 0 is a stub domain which builds a disaggregated
system including a hardware domain with the specified domain ID. This option is
supported only when compiled with XSM on x86.
-### hest\_disable
+### hest_disable
> ` = <boolean>`
> Default: `false`
@@ -1064,7 +1064,7 @@ identical to the boot CPU will be parked and not used by Xen.
### hpetbroadcast (x86)
> `= <boolean>`
-### hvm\_debug (x86)
+### hvm_debug (x86)
> `= <integer>`
The specified value is a bit mask with the individual bits having the
@@ -1085,7 +1085,7 @@ following meaning:
Recognized in debug builds of the hypervisor only.
-### hvm\_fep (x86)
+### hvm_fep (x86)
> `= <boolean>`
> Default: `false`
@@ -1100,7 +1100,7 @@ As this feature opens up the instruction emulator to arbitrary
instruction from an HVM guest, don't use this in production system. No
security support is provided when this flag is set.
-### hvm\_port80 (x86)
+### hvm_port80 (x86)
> `= <boolean>`
> Default: `true`
@@ -1109,10 +1109,10 @@ Specify whether guests are to be given access to physical port 80
(often used for debugging purposes), to override the DMI based
detection of systems known to misbehave upon accesses to that port.
-### idle\_latency\_factor (x86)
+### idle_latency_factor (x86)
> `= <integer>`
-### ioapic\_ack (x86)
+### ioapic_ack (x86)
> `= old | new`
> Default: `new` unless directed-EOI is supported
@@ -1226,7 +1226,7 @@ detection of systems known to misbehave upon accesses to that port.
>> Enable IOMMU debugging code (implies `verbose`).
-### iommu\_dev\_iotlb\_timeout
+### iommu_dev_iotlb_timeout
> `= <integer>`
> Default: `1000`
@@ -1235,7 +1235,7 @@ Specify the timeout of the device IOTLB invalidation in milliseconds.
By default, the timeout is 1000 ms. When you see error 'Queue invalidate
wait descriptor timed out', try increasing this value.
-### iommu\_inclusive\_mapping (VT-d)
+### iommu_inclusive_mapping (VT-d)
> `= <boolean>`
**WARNING: This command line option is deprecated, and superseded by
@@ -1250,18 +1250,18 @@ get a mapping established. Note that this option is only applicable to a
PV dom0. Also note that if `dom0-strict` mode is enabled then conventional
RAM pages not assigned to dom0 will not be mapped.
-### irq\_ratelimit (x86)
+### irq_ratelimit (x86)
> `= <integer>`
-### irq\_vector\_map (x86)
-### ivrs\_hpet[`<hpet>`] (AMD)
+### irq_vector_map (x86)
+### ivrs_hpet[`<hpet>`] (AMD)
> `=[<seg>:]<bus>:<device>.<func>`
Force the use of `[<seg>:]<bus>:<device>.<func>` as device ID of HPET
`<hpet>` instead of the one specified by the IVHD sub-tables of the IVRS
ACPI table.
-### ivrs\_ioapic[`<ioapic>`] (AMD)
+### ivrs_ioapic[`<ioapic>`] (AMD)
> `=[<seg>:]<bus>:<device>.<func>`
Force the use of `[<seg>:]<bus>:<device>.<func>` as device ID of IO-APIC
@@ -1274,7 +1274,7 @@ ACPI table.
Force the use of use of the local APIC on a uniprocessor system, even
if left disabled by the BIOS.
-### lapic\_timer\_c2\_ok (x86)
+### lapic_timer_c2_ok (x86)
> `= <boolean>`
### ler (x86)
@@ -1299,18 +1299,18 @@ importance will be printed.
The optional `<rate-limited level>` option instructs which severities
should be rate limited.
-### low\_crashinfo
+### low_crashinfo
> `= none | min | all`
-> Default: `none` if not specified at all, or to `min` if **low\_crashinfo** is present without qualification.
+> Default: `none` if not specified at all, or to `min` if **low_crashinfo** is present without qualification.
This option is only useful for hosts with a 32bit dom0 kernel, wishing
to use kexec functionality in the case of a crash. It represents
which data structures should be deliberately allocated in low memory,
so the crash kernel may find find them. Should be used in combination
-with **crashinfo\_maxaddr**.
+with **crashinfo_maxaddr**.
-### low\_mem\_virq\_limit
+### low_mem_virq_limit
> `= <size>`
> Default: `64M`
@@ -1325,16 +1325,16 @@ Specify the maximum number of CPUs that should be brought up.
This option is ignored in **pv-shim** mode.
-### max\_cstate (x86)
+### max_cstate (x86)
> `= <integer>`
-### max\_gsi\_irqs (x86)
+### max_gsi_irqs (x86)
> `= <integer>`
Specifies the number of interrupts to be use for pin (IO-APIC or legacy PIC)
based interrupts. Any higher IRQs will be available for use via PCI MSI.
-### max\_lpi\_bits (arm)
+### max_lpi_bits (arm)
> `= <integer>`
Specifies the number of ARM GICv3 LPI interrupts to allocate on the host,
@@ -1346,10 +1346,10 @@ Defaults to 20 bits (to cover at most 1048576 interrupts).
### mce (x86)
> `= <integer>`
-### mce\_fb (Intel)
+### mce_fb (Intel)
> `= <integer>`
-### mce\_verbosity (x86)
+### mce_verbosity (x86)
> `= verbose`
Specify verbose machine check output.
@@ -1474,7 +1474,7 @@ Defaults to booting secondary processors.
This option is ignored in **pv-shim** mode.
-### nr\_irqs (x86)
+### nr_irqs (x86)
> `= <integer>`
### numa (x86)
@@ -1525,10 +1525,10 @@ Flag to enable Memory Protection Keys.
The protection-key feature provides an additional mechanism by which IA-32e
paging controls access to usermode addresses.
-### ple\_gap
+### ple_gap
> `= <integer>`
-### ple\_window (Intel)
+### ple_window (Intel)
> `= <integer>`
### psr (Intel)
@@ -1577,7 +1577,7 @@ The following resources are available:
> Default: `true`
-Only available if Xen is compiled with CONFIG\_PV\_LINEAR\_PT support
+Only available if Xen is compiled with `CONFIG_PV_LINEAR_PT` support
enabled.
Allow PV guests to have pagetable entries pointing to other pagetables
@@ -1608,7 +1608,7 @@ Shadowing is performed at the point where a PV guest first tries to write an
L1TF-vulnerable PTE. Therefore, a PV guest kernel which has been updated with
its own L1TF mitigations will not trigger shadow mode if it is well behaved.
-If CONFIG\_SHADOW\_PAGING is not compiled in, this mitigation instead crashes
+If `CONFIG_SHADOW_PAGING` is not compiled in, this mitigation instead crashes
the guest when an L1TF-vulnerable PTE is written, which still allows updated,
well-behaved PV guests to run, despite Shadow being compiled out.
@@ -1653,7 +1653,7 @@ Specify the host reboot method.
`kbd` instructs Xen to reboot the host via the keyboard controller.
-`acpi` instructs Xen to reboot the host using RESET\_REG in the ACPI FADT.
+`acpi` instructs Xen to reboot the host using RESET_REG in the ACPI FADT.
`pci` instructs Xen to reboot the host using PCI reset register (port CF9).
@@ -1703,17 +1703,17 @@ with read and write permissions.
Choose the default scheduler.
-### sched\_credit2\_migrate\_resist
+### sched_credit2_migrate_resist
> `= <integer>`
-### sched\_credit\_tslice\_ms
+### sched_credit_tslice_ms
> `= <integer>`
Set the timeslice of the credit1 scheduler, in milliseconds. The
default is 30ms. Reasonable values may include 10, 5, or even 1 for
very latency-sensitive workloads.
-### sched\_ratelimit\_us
+### sched_ratelimit_us
> `= <integer>`
In order to limit the rate of context switching, set the minimum
@@ -1721,7 +1721,7 @@ amount of time that a vcpu can be scheduled for before preempting it,
in microseconds. The default is 1000us (1ms). Setting this to 0
disables it altogether.
-### sched\_smt\_power\_savings
+### sched_smt_power_savings
> `= <boolean>`
Normally Xen will try to maximize performance and cache utilization by
@@ -1737,7 +1737,7 @@ sockets, &c. This will reduce performance somewhat, particularly on
systems with hyperthreading enabled, but should reduce power by
enabling more sockets and cores to go into deeper sleep states.
-### serial\_tx\_buffer
+### serial_tx_buffer
> `= <size>`
> Default: `16kB`
@@ -1788,7 +1788,7 @@ hypervisors handle SErrors:
All SErrors will crash the whole system. This option will avoid all overhead
of the dsb/isb pairs.
-### shim\_mem (x86)
+### shim_mem (x86)
> `= List of ( min:<size> | max:<size> | <size> )`
Set the amount of memory that xen-shim uses. Only has effect if pv-shim mode is
@@ -1826,7 +1826,7 @@ Default: `true`
Control bring up of multiple hyper-threads per CPU core.
-### snb\_igd\_quirk
+### snb_igd_quirk
> `= <boolean> | cap | <integer>`
A true boolean value enables legacy behavior (1s timeout), while `cap`
@@ -1846,7 +1846,7 @@ Bypass Disable (SSBD) mitigation.
will not be able to control the state of the mitigation.
* `ssbd=runtime` will always turn on the mitigation when running in the
hypervisor context. The guest will be to turn on/off the mitigation for
-itself by using the firmware interface ARCH\_WORKAROUND\_2.
+itself by using the firmware interface `ARCH_WORKAROUND_2`.
* `ssbd=force-enable` will keep the mitigation permanently on. The guest will
not be able to control the state of the mitigation.
@@ -1883,13 +1883,13 @@ protect itself, and Xen's ability to virtualise support for guests to use.
* `pv=` and `hvm=` offer control over all suboptions for PV and HVM guests
respectively.
-* `msr-sc=` offers control over Xen's support for manipulating MSR\_SPEC\_CTRL
+* `msr-sc=` offers control over Xen's support for manipulating `MSR_SPEC_CTRL`
on entry and exit. These blocks are necessary to virtualise support for
guests and if disabled, guests will be unable to use IBRS/STIBP/SSBD/etc.
* `rsb=` offers control over whether to overwrite the Return Stack Buffer /
Return Address Stack on entry to Xen.
-If Xen was compiled with INDIRECT\_THUNK support, `bti-thunk=` can be used to
+If Xen was compiled with INDIRECT_THUNK support, `bti-thunk=` can be used to
select which of the thunks gets patched into the `__x86_indirect_thunk_%reg`
locations. The default thunk is `retpoline` (generally preferred for Intel
hardware), with the alternatives being `jmp` (a `jmp *%reg` gadget, minimal
@@ -1921,7 +1921,7 @@ Irrespective of Xen's setting, the feature is virtualised for HVM guests to
use. By default, Xen will enable this mitigation on hardware believed to be
vulnerable to L1TF.
-### sync\_console
+### sync_console
> `= <boolean>`
> Default: `false`
@@ -1934,7 +1934,7 @@ not suitable for production environments due to incurred overhead.
Specify the physical address of the trusted boot shared page.
-### tbuf\_size
+### tbuf_size
> `= <integer>`
Specify the per-cpu trace buffer size in pages.
@@ -1946,24 +1946,24 @@ Specify the per-cpu trace buffer size in pages.
Flag to enable TSC deadline as the APIC timer mode.
-### tevt\_mask
+### tevt_mask
> `= <integer>`
Specify a mask for Xen event tracing. This allows Xen tracing to be
enabled at boot. Refer to the xentrace(8) documentation for a list of
valid event mask values. In order to enable tracing, a buffer size (in
-pages) must also be specified via the tbuf\_size parameter.
+pages) must also be specified via the tbuf_size parameter.
-### tickle\_one\_idle\_cpu
+### tickle_one_idle_cpu
> `= <boolean>`
-### timer\_slop
+### timer_slop
> `= <integer>`
### tmem
> `= <boolean>`
-### tmem\_compress
+### tmem_compress
> `= <boolean>`
### tsc (x86)
@@ -1991,10 +1991,10 @@ microcode in the cpio name space must be:
- on Intel: kernel/x86/microcode/GenuineIntel.bin
- on AMD : kernel/x86/microcode/AuthenticAMD.bin
-### unrestricted\_guest (Intel)
+### unrestricted_guest (Intel)
> `= <boolean>`
-### vcpu\_migration\_delay
+### vcpu_migration_delay
> `= <integer>`
> Default: `0`
@@ -2072,7 +2072,7 @@ If the current cpu isn't supported a message like
is printed on the hypervisor serial log.
For some Intel Nehalem processors a quirk handling exist for an unknown
-wrong behaviour (see handle\_pmc\_quirk()).
+wrong behaviour (see `handle_pmc_quirk()`).
If 'vpmu=bts' is specified the virtualisation of the Branch Trace Store (BTS)
feature is switched on on Intel processors supporting this feature.
@@ -2117,11 +2117,11 @@ oversubscribed (i.e., in total there are more vCPUs than pCPUs).
> Default: `false`
Run an NMI watchdog on each processor. If a processor is stuck for
-longer than the **watchdog\_timeout**, a panic occurs. When `force` is
+longer than the **watchdog_timeout**, a panic occurs. When `force` is
specified, in addition to running an NMI watchdog on each processor,
unknown NMIs will still be processed.
-### watchdog\_timeout (x86)
+### watchdog_timeout (x86)
> `= <integer>`
> Default: `5`
@@ -2136,7 +2136,7 @@ the watchdog.
Permit use of x2apic setup for SMP environments.
-### x2apic\_phys (x86)
+### x2apic_phys (x86)
> `= <boolean>`
> Default: `true` if **FADT** mandates physical mode, `false` otherwise.
@@ -2145,7 +2145,7 @@ In the case that x2apic is in use, this option switches between physical and
clustered mode. The default, given no hint from the **FADT**, is cluster
mode.
-### xenheap\_megabytes (arm32)
+### xenheap_megabytes (arm32)
> `= <size>`
> Default: `0` (1/32 of RAM)
@@ -2188,7 +2188,7 @@ Permit use of the `xsave/xrstor` instructions.
> Default: selectable via Kconfig. Depends on enabled XSM modules.
Specify which XSM module should be enabled. This option is only available if
-the hypervisor was compiled with CONFIG\_XSM enabled.
+the hypervisor was compiled with `CONFIG_XSM` enabled.
* `dummy`: this is the default choice. Basic restriction for common deployment
(the dummy module) will be applied. It's also used when XSM is compiled out.
diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.pandoc
similarity index 99%
rename from docs/misc/xenstore-paths.markdown
rename to docs/misc/xenstore-paths.pandoc
index 33d2819..0a6b361 100644
--- a/docs/misc/xenstore-paths.markdown
+++ b/docs/misc/xenstore-paths.pandoc
@@ -467,11 +467,11 @@ the corresponding acpi_ feature flag is set in ~/platform.
Indicates to the guest that this platform supports the multiprocessor
suspend feature.
-#### ~/control/platform-feature-xs\_reset\_watches = (0|1) []
+#### ~/control/platform-feature-xs_reset_watches = (0|1) []
Indicates to the guest that this platform supports the
XS_RESET_WATCHES xenstore message. See
-[xen/include/public/io/xs\_wire.h][XSWIRE] for the XenStore wire
+[xen/include/public/io/xs_wire.h][XSWIRE] for the XenStore wire
protocol definition.
#### ~/control/laptop-slate-mode = (""|"laptop"|"slate") [w]
@@ -609,7 +609,7 @@ Path in xenstore to the backend, normally
Trustworthy copy of /local/domain/$DOMID/backend/$KIND/$DEVID/$NODE.
-#### /libxl/$DOMID/dm-version ("qemu\_xen"|"qemu\_xen\_traditional") = [n,INTERNAL]
+#### /libxl/$DOMID/dm-version ("qemu_xen"|"qemu_xen_traditional") = [n,INTERNAL]
The device model version for a domain.
diff --git a/docs/misc/xl-psr.markdown b/docs/misc/xl-psr.pandoc
similarity index 100%
rename from docs/misc/xl-psr.markdown
rename to docs/misc/xl-psr.pandoc
--
2.1.4
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH 3/4] docs/man: Fix/simplify generation of manpages
2019-01-02 11:43 [PATCH 0/4] docs: Multiple fixes to docs Andrew Cooper
2019-01-02 11:43 ` [PATCH 1/4] docs/pandoc: Don't escape underscores in the middle of text Andrew Cooper
2019-01-02 11:43 ` [PATCH 2/4] docs/markdown: Switch to using pandoc, and fix underscore escaping Andrew Cooper
@ 2019-01-02 11:43 ` Andrew Cooper
2019-01-02 12:30 ` Ian Jackson
2019-01-02 11:43 ` [PATCH 4/4] docs: Remove Markdown from configure.ac and the build instructions Andrew Cooper
3 siblings, 1 reply; 12+ messages in thread
From: Andrew Cooper @ 2019-01-02 11:43 UTC (permalink / raw)
To: Xen-devel
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk,
George Dunlap, Andrew Cooper, Tim Deegan, Julien Grall,
Jan Beulich, Ian Jackson
The original intent of this patch was to rename xen-vbd-interface.markdown.7
to xen-vbd-interface.pandoc.7 to remove the final markdown file from the docs/
tree.
The DOC_MANx lists are broken. They contain MANxSRC-y twice, the first half
with a partial %.pod substituation, and the second half with a partial
%.markdown substitution. This is also the root cause behind the filtering
activity in the uninstall-man$(i)-pages rule.
Furthermore, the logic for generating the manpage targets is unnecesserily
repetative, owing to the layout of source files in the man/ directory.
Therefore, tackle the problem by renaming all of our manpage source files from
"$FORMAT.$SECTION" to "$SECTION.$FORMAT". For the two xl.cfg.5 and xl.1 which
are preprocessed by autoconf to contain path information, this requires
updating configure.ac and .gitignore. The markdown to pandoc conversion is
performed as well, as it is also a straight rename.
An ancillary benefit of this renaming is that text editors stand a chance of
being able to work out the correct mode to use.
As for the makefile:
1) Break the MAN_SECTIONS list out of the GENERATE_MANPAGE_RULES loop, as we
are going to use it a second time.
2) Do away with the individaul MANxSRC-y variables. Use a single list,
derived from all *.pod and *.pandoc files, with their format suffixes
removed.
3) Use a $(foreach ...) to generate the DOC_MANx lists, filling them with the
correct content.
4) The DOC_HTML and DOC_TXT can now include all manpages with a single
substitution, as they don't need to separate the manpages by
section-numbered-directory.
5) Fix up the filenames in the manpage metarule to match the renaming.
No functional change.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: George Dunlap <George.Dunlap@eu.citrix.com>
CC: Ian Jackson <ian.jackson@citrix.com>
CC: Jan Beulich <JBeulich@suse.com>
CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Tim Deegan <tim@xen.org>
CC: Wei Liu <wei.liu2@citrix.com>
CC: Julien Grall <julien.grall@arm.com>
AFAICT, the only reason the build doesn't get a hard failure is because
the DOC_MANx lists end causing the man$(x)-page targets to gain build
dependences on the (un-substituted) source files.
---
.gitignore | 4 +-
docs/Makefile | 52 +++++++---------------
docs/configure | 6 +--
docs/configure.ac | 4 +-
...ons.pod.7 => xen-pci-device-reservations.7.pod} | 0
.../{xen-pv-channel.pod.7 => xen-pv-channel.7.pod} | 0
docs/man/{xen-tscmode.pod.7 => xen-tscmode.7.pod} | 0
...rface.markdown.7 => xen-vbd-interface.7.pandoc} | 0
docs/man/{xen-vtpm.pod.7 => xen-vtpm.7.pod} | 0
docs/man/{xen-vtpmmgr.pod.7 => xen-vtpmmgr.7.pod} | 0
.../{xenstore-chmod.pod.1 => xenstore-chmod.1.pod} | 0
docs/man/{xenstore-ls.pod.1 => xenstore-ls.1.pod} | 0
.../{xenstore-read.pod.1 => xenstore-read.1.pod} | 0
.../{xenstore-write.pod.1 => xenstore-write.1.pod} | 0
docs/man/{xenstore.pod.1 => xenstore.1.pod} | 0
docs/man/{xentop.pod.1 => xentop.1.pod} | 0
docs/man/{xentrace.pod.8 => xentrace.8.pod} | 0
...xentrace_format.pod.1 => xentrace_format.1.pod} | 0
...iguration.pod.5 => xl-disk-configuration.5.pod} | 0
...ration.pod.5 => xl-network-configuration.5.pod} | 0
...uma-placement.pod.7 => xl-numa-placement.7.pod} | 0
docs/man/{xl.pod.1.in => xl.1.pod.in} | 0
docs/man/{xl.cfg.pod.5.in => xl.cfg.5.pod.in} | 0
docs/man/{xl.conf.pod.5 => xl.conf.5.pod} | 0
.../{xlcpupool.cfg.pod.5 => xlcpupool.cfg.5.pod} | 0
25 files changed, 23 insertions(+), 43 deletions(-)
rename docs/man/{xen-pci-device-reservations.pod.7 => xen-pci-device-reservations.7.pod} (100%)
rename docs/man/{xen-pv-channel.pod.7 => xen-pv-channel.7.pod} (100%)
rename docs/man/{xen-tscmode.pod.7 => xen-tscmode.7.pod} (100%)
rename docs/man/{xen-vbd-interface.markdown.7 => xen-vbd-interface.7.pandoc} (100%)
rename docs/man/{xen-vtpm.pod.7 => xen-vtpm.7.pod} (100%)
rename docs/man/{xen-vtpmmgr.pod.7 => xen-vtpmmgr.7.pod} (100%)
rename docs/man/{xenstore-chmod.pod.1 => xenstore-chmod.1.pod} (100%)
rename docs/man/{xenstore-ls.pod.1 => xenstore-ls.1.pod} (100%)
rename docs/man/{xenstore-read.pod.1 => xenstore-read.1.pod} (100%)
rename docs/man/{xenstore-write.pod.1 => xenstore-write.1.pod} (100%)
rename docs/man/{xenstore.pod.1 => xenstore.1.pod} (100%)
rename docs/man/{xentop.pod.1 => xentop.1.pod} (100%)
rename docs/man/{xentrace.pod.8 => xentrace.8.pod} (100%)
rename docs/man/{xentrace_format.pod.1 => xentrace_format.1.pod} (100%)
rename docs/man/{xl-disk-configuration.pod.5 => xl-disk-configuration.5.pod} (100%)
rename docs/man/{xl-network-configuration.pod.5 => xl-network-configuration.5.pod} (100%)
rename docs/man/{xl-numa-placement.pod.7 => xl-numa-placement.7.pod} (100%)
rename docs/man/{xl.pod.1.in => xl.1.pod.in} (100%)
rename docs/man/{xl.cfg.pod.5.in => xl.cfg.5.pod.in} (100%)
rename docs/man/{xl.conf.pod.5 => xl.conf.5.pod} (100%)
rename docs/man/{xlcpupool.cfg.pod.5 => xlcpupool.cfg.5.pod} (100%)
diff --git a/.gitignore b/.gitignore
index f11e613..26bc583 100644
--- a/.gitignore
+++ b/.gitignore
@@ -45,8 +45,8 @@ build-*
dist/*
docs/tmp.*
docs/html/
-docs/man/xl.cfg.pod.5
-docs/man/xl.pod.1
+docs/man/xl.cfg.5.pod
+docs/man/xl.1.pod
docs/man1/
docs/man5/
docs/man7/
diff --git a/docs/Makefile b/docs/Makefile
index 8f933cf..2867efc 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -6,12 +6,10 @@ VERSION := $(shell $(MAKE) -C $(XEN_ROOT)/xen --no-print-directory xenversion)
DATE := $(shell date +%Y-%m-%d)
DOC_ARCHES := arm x86_32 x86_64
+MAN_SECTIONS := 1 5 7 8
# Documentation sources to build
-MAN1SRC-y := $(sort $(wildcard man/*.pod.1 man/*.markdown.1))
-MAN5SRC-y := $(sort $(wildcard man/*.pod.5 man/*.markdown.5))
-MAN7SRC-y := $(sort $(wildcard man/*.pod.7 man/*.markdown.7))
-MAN8SRC-y := $(sort $(wildcard man/*.pod.8 man/*.markdown.8))
+MAN-SRC-y := $(sort $(basename $(wildcard man/*.pod man/*.pandoc)))
MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
@@ -20,38 +18,20 @@ TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print))
PANDOCSRC-y := $(sort $(shell find designs/ features/ misc/ process/ specs/ -name '*.pandoc' -print))
# Documentation targets
-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))
+$(foreach i,$(MAN_SECTIONS), \
+ $(eval DOC_MAN$(i) := $(patsubst man/%.$(i),man$(i)/%.$(i), \
+ $(filter %.$(i),$(MAN-SRC-y)))))
+
DOC_HTML := html/SUPPORT.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 %,html/%.html,$(MAN-SRC-y)) \
$(patsubst %.txt,html/%.txt,$(TXTSRC-y)) \
$(patsubst %,html/hypercall/%/index.html,$(DOC_ARCHES))
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.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))
+ $(patsubst %,txt/%.txt,$(MAN-SRC-y))
DOC_PDF := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,pdf/%.pdf,$(PANDOCSRC-y))
@@ -99,7 +79,7 @@ distclean: clean
define GENERATE_MANPAGE_RULES
# Real manpages
-man$(1)/%.$(1): man/%.pod.$(1) Makefile
+man$(1)/%.$(1): man/%.$(1).pod Makefile
ifneq ($(POD2MAN),)
@$(INSTALL_DIR) $$(@D)
$(POD2MAN) --release=$(VERSION) --name=$$* -s $(1) -c "Xen" $$< $$@
@@ -107,7 +87,7 @@ else
@echo "pod2man not installed; skipping $$@"
endif
-man$(1)/%.$(1): man/%.markdown.$(1) Makefile
+man$(1)/%.$(1): man/%.$(1).pandoc Makefile
ifneq ($(PANDOC),)
@$(INSTALL_DIR) $$(@D)
$(PANDOC) --standalone -V title=$$* -V section=$(1) \
@@ -118,7 +98,7 @@ else
endif
# HTML manpages
-html/man/%.$(1).html: man/%.pod.$(1) Makefile
+html/man/%.$(1).html: man/%.$(1).pod Makefile
ifneq ($(POD2HTML),)
@$(INSTALL_DIR) $$(@D)
$(POD2HTML) --infile=$$< --outfile=$$@
@@ -126,7 +106,7 @@ else
@echo "pod2html not installed; skipping $$@"
endif
-html/man/%.$(1).html: man/%.markdown.$(1) Makefile
+html/man/%.$(1).html: man/%.$(1).pandoc Makefile
ifneq ($(PANDOC),)
@$(INSTALL_DIR) $$(@D)
$(PANDOC) --standalone $$< -t html --toc --output $$@
@@ -135,7 +115,7 @@ else
endif
# Text manpages
-txt/man/%.$(1).txt: man/%.pod.$(1) Makefile
+txt/man/%.$(1).txt: man/%.$(1).pod Makefile
ifneq ($(POD2TEXT),)
@$(INSTALL_DIR) $$(@D)
$(POD2TEXT) $$< $$@
@@ -143,7 +123,7 @@ else
@echo "pod2text not installed; skipping $$@"
endif
-txt/man/%.$(1).txt: man/%.markdown.$(1) Makefile
+txt/man/%.$(1).txt: man/%.$(1).pandoc Makefile
ifneq ($(PANDOC),)
@$(INSTALL_DIR) $$(@D)
$(PANDOC) --standalone $$< -t plain --output $$@
@@ -169,7 +149,7 @@ clean-man$(1)-pages:
# Uninstall
.PHONY: uninstall-man$(1)-pages
uninstall-man$(1)-pages:
- rm -f $(addprefix $(DESTDIR)$(mandir)/man$(1)/, $(filter-out %.pod.$(1) %.markdown.$(1), $(notdir $(DOC_MAN$(1)))))
+ rm -f $(addprefix $(DESTDIR)$(mandir)/,$(DOC_MAN$(1)))
# Link buld/install/clean to toplevel rules
man-pages: man$(1)-pages
@@ -180,7 +160,7 @@ uninstall-man-pages: uninstall-man$(1)-pages
endef
# Generate manpage rules for each section
-$(foreach i,1 5 7 8,$(eval $(call GENERATE_MANPAGE_RULES,$(i))))
+$(foreach i,$(MAN_SECTIONS),$(eval $(call GENERATE_MANPAGE_RULES,$(i))))
.PHONY: install-html
install-html: html txt figs
diff --git a/docs/configure b/docs/configure
index a3b4cb6..3e0089c 100755
--- a/docs/configure
+++ b/docs/configure
@@ -1752,7 +1752,7 @@ ac_compiler_gnu=$ac_cv_c_compiler_gnu
-ac_config_files="$ac_config_files ../config/Docs.mk man/xl.cfg.pod.5 man/xl.pod.1"
+ac_config_files="$ac_config_files ../config/Docs.mk man/xl.cfg.5.pod man/xl.1.pod"
ac_aux_dir=
for ac_dir in ../ "$srcdir"/../; do
@@ -3031,8 +3031,8 @@ for ac_config_target in $ac_config_targets
do
case $ac_config_target in
"../config/Docs.mk") CONFIG_FILES="$CONFIG_FILES ../config/Docs.mk" ;;
- "man/xl.cfg.pod.5") CONFIG_FILES="$CONFIG_FILES man/xl.cfg.pod.5" ;;
- "man/xl.pod.1") CONFIG_FILES="$CONFIG_FILES man/xl.pod.1" ;;
+ "man/xl.cfg.5.pod") CONFIG_FILES="$CONFIG_FILES man/xl.cfg.5.pod" ;;
+ "man/xl.1.pod") CONFIG_FILES="$CONFIG_FILES man/xl.1.pod" ;;
*) as_fn_error $? "invalid argument: \`$ac_config_target'" "$LINENO" 5;;
esac
diff --git a/docs/configure.ac b/docs/configure.ac
index a2929c4..5777162 100644
--- a/docs/configure.ac
+++ b/docs/configure.ac
@@ -7,8 +7,8 @@ AC_INIT([Xen Hypervisor Documentation], m4_esyscmd([../version.sh ../xen/Makefil
AC_CONFIG_SRCDIR([misc/xen-command-line.markdown])
AC_CONFIG_FILES([
../config/Docs.mk
-man/xl.cfg.pod.5
-man/xl.pod.1
+man/xl.cfg.5.pod
+man/xl.1.pod
])
AC_CONFIG_AUX_DIR([../])
diff --git a/docs/man/xen-pci-device-reservations.pod.7 b/docs/man/xen-pci-device-reservations.7.pod
similarity index 100%
rename from docs/man/xen-pci-device-reservations.pod.7
rename to docs/man/xen-pci-device-reservations.7.pod
diff --git a/docs/man/xen-pv-channel.pod.7 b/docs/man/xen-pv-channel.7.pod
similarity index 100%
rename from docs/man/xen-pv-channel.pod.7
rename to docs/man/xen-pv-channel.7.pod
diff --git a/docs/man/xen-tscmode.pod.7 b/docs/man/xen-tscmode.7.pod
similarity index 100%
rename from docs/man/xen-tscmode.pod.7
rename to docs/man/xen-tscmode.7.pod
diff --git a/docs/man/xen-vbd-interface.markdown.7 b/docs/man/xen-vbd-interface.7.pandoc
similarity index 100%
rename from docs/man/xen-vbd-interface.markdown.7
rename to docs/man/xen-vbd-interface.7.pandoc
diff --git a/docs/man/xen-vtpm.pod.7 b/docs/man/xen-vtpm.7.pod
similarity index 100%
rename from docs/man/xen-vtpm.pod.7
rename to docs/man/xen-vtpm.7.pod
diff --git a/docs/man/xen-vtpmmgr.pod.7 b/docs/man/xen-vtpmmgr.7.pod
similarity index 100%
rename from docs/man/xen-vtpmmgr.pod.7
rename to docs/man/xen-vtpmmgr.7.pod
diff --git a/docs/man/xenstore-chmod.pod.1 b/docs/man/xenstore-chmod.1.pod
similarity index 100%
rename from docs/man/xenstore-chmod.pod.1
rename to docs/man/xenstore-chmod.1.pod
diff --git a/docs/man/xenstore-ls.pod.1 b/docs/man/xenstore-ls.1.pod
similarity index 100%
rename from docs/man/xenstore-ls.pod.1
rename to docs/man/xenstore-ls.1.pod
diff --git a/docs/man/xenstore-read.pod.1 b/docs/man/xenstore-read.1.pod
similarity index 100%
rename from docs/man/xenstore-read.pod.1
rename to docs/man/xenstore-read.1.pod
diff --git a/docs/man/xenstore-write.pod.1 b/docs/man/xenstore-write.1.pod
similarity index 100%
rename from docs/man/xenstore-write.pod.1
rename to docs/man/xenstore-write.1.pod
diff --git a/docs/man/xenstore.pod.1 b/docs/man/xenstore.1.pod
similarity index 100%
rename from docs/man/xenstore.pod.1
rename to docs/man/xenstore.1.pod
diff --git a/docs/man/xentop.pod.1 b/docs/man/xentop.1.pod
similarity index 100%
rename from docs/man/xentop.pod.1
rename to docs/man/xentop.1.pod
diff --git a/docs/man/xentrace.pod.8 b/docs/man/xentrace.8.pod
similarity index 100%
rename from docs/man/xentrace.pod.8
rename to docs/man/xentrace.8.pod
diff --git a/docs/man/xentrace_format.pod.1 b/docs/man/xentrace_format.1.pod
similarity index 100%
rename from docs/man/xentrace_format.pod.1
rename to docs/man/xentrace_format.1.pod
diff --git a/docs/man/xl-disk-configuration.pod.5 b/docs/man/xl-disk-configuration.5.pod
similarity index 100%
rename from docs/man/xl-disk-configuration.pod.5
rename to docs/man/xl-disk-configuration.5.pod
diff --git a/docs/man/xl-network-configuration.pod.5 b/docs/man/xl-network-configuration.5.pod
similarity index 100%
rename from docs/man/xl-network-configuration.pod.5
rename to docs/man/xl-network-configuration.5.pod
diff --git a/docs/man/xl-numa-placement.pod.7 b/docs/man/xl-numa-placement.7.pod
similarity index 100%
rename from docs/man/xl-numa-placement.pod.7
rename to docs/man/xl-numa-placement.7.pod
diff --git a/docs/man/xl.pod.1.in b/docs/man/xl.1.pod.in
similarity index 100%
rename from docs/man/xl.pod.1.in
rename to docs/man/xl.1.pod.in
diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.5.pod.in
similarity index 100%
rename from docs/man/xl.cfg.pod.5.in
rename to docs/man/xl.cfg.5.pod.in
diff --git a/docs/man/xl.conf.pod.5 b/docs/man/xl.conf.5.pod
similarity index 100%
rename from docs/man/xl.conf.pod.5
rename to docs/man/xl.conf.5.pod
diff --git a/docs/man/xlcpupool.cfg.pod.5 b/docs/man/xlcpupool.cfg.5.pod
similarity index 100%
rename from docs/man/xlcpupool.cfg.pod.5
rename to docs/man/xlcpupool.cfg.5.pod
--
2.1.4
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply related [flat|nested] 12+ messages in thread
* [PATCH 4/4] docs: Remove Markdown from configure.ac and the build instructions
2019-01-02 11:43 [PATCH 0/4] docs: Multiple fixes to docs Andrew Cooper
` (2 preceding siblings ...)
2019-01-02 11:43 ` [PATCH 3/4] docs/man: Fix/simplify generation of manpages Andrew Cooper
@ 2019-01-02 11:43 ` Andrew Cooper
2019-01-02 12:28 ` Ian Jackson
2019-01-02 15:51 ` Andrew Cooper
3 siblings, 2 replies; 12+ messages in thread
From: Andrew Cooper @ 2019-01-02 11:43 UTC (permalink / raw)
To: Xen-devel
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk,
George Dunlap, Andrew Cooper, Tim Deegan, Julien Grall,
Jan Beulich, Ian Jackson, Doug Goldstein
Now that all use of markdown as been replaced with pandoc, drop it from
configure.ac and from the docs/ Makefile.
Instead of just deleting the markdown reference from README, adjust the line
to mention the other optional packages required for documentation.
Drop markdown from travis and the docker containers. While tweaking the
CentOS containers, pull in transfig and pandoc seeing as EPEL is set up, to
bring them in line with the Debian based containers.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
----
CC: George Dunlap <George.Dunlap@eu.citrix.com>
CC: Ian Jackson <ian.jackson@citrix.com>
CC: Jan Beulich <JBeulich@suse.com>
CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Tim Deegan <tim@xen.org>
CC: Wei Liu <wei.liu2@citrix.com>
CC: Julien Grall <julien.grall@arm.com>
CC: Doug Goldstein <cardoe@cardoe.com>
---
.travis.yml | 1 -
README | 3 +-
automation/build/centos/7.2.dockerfile | 3 +-
automation/build/centos/7.dockerfile | 3 +-
automation/build/debian/jessie-i386.dockerfile | 1 -
automation/build/debian/jessie.dockerfile | 1 -
automation/build/debian/stretch-i386.dockerfile | 1 -
automation/build/debian/stretch.dockerfile | 1 -
.../build/debian/unstable-arm64v8.dockerfile | 1 -
automation/build/debian/unstable-i386.dockerfile | 1 -
automation/build/debian/unstable.dockerfile | 1 -
automation/build/ubuntu/bionic.dockerfile | 1 -
automation/build/ubuntu/trusty.dockerfile | 1 -
automation/build/ubuntu/xenial.dockerfile | 1 -
config/Docs.mk.in | 1 -
docs/Makefile | 22 +--------
docs/configure | 57 ----------------------
docs/configure.ac | 1 -
18 files changed, 8 insertions(+), 93 deletions(-)
diff --git a/.travis.yml b/.travis.yml
index f93dd68..2266b4d 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -62,7 +62,6 @@ addons:
- libnl-3-dev
- ocaml-nox
- libfindlib-ocaml-dev
- - markdown
- transfig
- pandoc
- gcc-arm-linux-gnueabihf
diff --git a/README b/README
index 3a497fb..fd6f4f1 100644
--- a/README
+++ b/README
@@ -73,7 +73,8 @@ disabled at compile time:
ocaml-findlib). Required to build ocaml components which
includes the alternative ocaml xenstored.
* cmake (if building vtpm stub domains)
- * markdown
+ * pandoc, transfig, pod2{man,html,text} for rendering various pieces of
+ documentation into alternative formats
* figlet (for generating the traditional Xen start of day banner)
* systemd daemon development files
* Development install of libnl3 (e.g., libnl-3-200,
diff --git a/automation/build/centos/7.2.dockerfile b/automation/build/centos/7.2.dockerfile
index c2f46b6..2d82b4d 100644
--- a/automation/build/centos/7.2.dockerfile
+++ b/automation/build/centos/7.2.dockerfile
@@ -40,7 +40,8 @@ RUN rpm --rebuilddb && \
git \
wget \
acpica-tools \
- python-markdown \
+ transfig \
+ pandoc \
patch \
checkpolicy \
dev86 \
diff --git a/automation/build/centos/7.dockerfile b/automation/build/centos/7.dockerfile
index e37d9d7..f3d2d97 100644
--- a/automation/build/centos/7.dockerfile
+++ b/automation/build/centos/7.dockerfile
@@ -38,7 +38,8 @@ RUN yum -y install \
git \
wget \
acpica-tools \
- python-markdown \
+ transfig \
+ pandoc \
patch \
checkpolicy \
dev86 \
diff --git a/automation/build/debian/jessie-i386.dockerfile b/automation/build/debian/jessie-i386.dockerfile
index 7a05004..680a116 100644
--- a/automation/build/debian/jessie-i386.dockerfile
+++ b/automation/build/debian/jessie-i386.dockerfile
@@ -37,7 +37,6 @@ RUN apt-get update && \
libnl-3-dev \
ocaml-nox \
libfindlib-ocaml-dev \
- markdown \
transfig \
pandoc \
checkpolicy \
diff --git a/automation/build/debian/jessie.dockerfile b/automation/build/debian/jessie.dockerfile
index bd04209..2082cda 100644
--- a/automation/build/debian/jessie.dockerfile
+++ b/automation/build/debian/jessie.dockerfile
@@ -35,7 +35,6 @@ RUN apt-get update && \
libnl-3-dev \
ocaml-nox \
libfindlib-ocaml-dev \
- markdown \
transfig \
pandoc \
checkpolicy \
diff --git a/automation/build/debian/stretch-i386.dockerfile b/automation/build/debian/stretch-i386.dockerfile
index 65247a4..acb1749 100644
--- a/automation/build/debian/stretch-i386.dockerfile
+++ b/automation/build/debian/stretch-i386.dockerfile
@@ -37,7 +37,6 @@ RUN apt-get update && \
libnl-3-dev \
ocaml-nox \
libfindlib-ocaml-dev \
- markdown \
transfig \
pandoc \
checkpolicy \
diff --git a/automation/build/debian/stretch.dockerfile b/automation/build/debian/stretch.dockerfile
index 9be09c5..3f77001 100644
--- a/automation/build/debian/stretch.dockerfile
+++ b/automation/build/debian/stretch.dockerfile
@@ -35,7 +35,6 @@ RUN apt-get update && \
libnl-3-dev \
ocaml-nox \
libfindlib-ocaml-dev \
- markdown \
transfig \
pandoc \
checkpolicy \
diff --git a/automation/build/debian/unstable-arm64v8.dockerfile b/automation/build/debian/unstable-arm64v8.dockerfile
index 57db46a..5e0f480 100644
--- a/automation/build/debian/unstable-arm64v8.dockerfile
+++ b/automation/build/debian/unstable-arm64v8.dockerfile
@@ -35,7 +35,6 @@ RUN apt-get update && \
libnl-3-dev \
ocaml-nox \
libfindlib-ocaml-dev \
- markdown \
transfig \
pandoc \
checkpolicy \
diff --git a/automation/build/debian/unstable-i386.dockerfile b/automation/build/debian/unstable-i386.dockerfile
index ffb9f11..f3b4e10 100644
--- a/automation/build/debian/unstable-i386.dockerfile
+++ b/automation/build/debian/unstable-i386.dockerfile
@@ -37,7 +37,6 @@ RUN apt-get update && \
libnl-3-dev \
ocaml-nox \
libfindlib-ocaml-dev \
- markdown \
transfig \
pandoc \
checkpolicy \
diff --git a/automation/build/debian/unstable.dockerfile b/automation/build/debian/unstable.dockerfile
index 0ba0c05..4513b2c 100644
--- a/automation/build/debian/unstable.dockerfile
+++ b/automation/build/debian/unstable.dockerfile
@@ -35,7 +35,6 @@ RUN apt-get update && \
libnl-3-dev \
ocaml-nox \
libfindlib-ocaml-dev \
- markdown \
transfig \
pandoc \
checkpolicy \
diff --git a/automation/build/ubuntu/bionic.dockerfile b/automation/build/ubuntu/bionic.dockerfile
index 8de67ef..8a89928 100644
--- a/automation/build/ubuntu/bionic.dockerfile
+++ b/automation/build/ubuntu/bionic.dockerfile
@@ -35,7 +35,6 @@ RUN apt-get update && \
libnl-3-dev \
ocaml-nox \
libfindlib-ocaml-dev \
- markdown \
transfig \
pandoc \
checkpolicy \
diff --git a/automation/build/ubuntu/trusty.dockerfile b/automation/build/ubuntu/trusty.dockerfile
index 1d04bcc..3bb8e50 100644
--- a/automation/build/ubuntu/trusty.dockerfile
+++ b/automation/build/ubuntu/trusty.dockerfile
@@ -35,7 +35,6 @@ RUN apt-get update && \
libnl-3-dev \
ocaml-nox \
libfindlib-ocaml-dev \
- markdown \
transfig \
pandoc \
checkpolicy \
diff --git a/automation/build/ubuntu/xenial.dockerfile b/automation/build/ubuntu/xenial.dockerfile
index 37869e3..7e1cc02 100644
--- a/automation/build/ubuntu/xenial.dockerfile
+++ b/automation/build/ubuntu/xenial.dockerfile
@@ -35,7 +35,6 @@ RUN apt-get update && \
libnl-3-dev \
ocaml-nox \
libfindlib-ocaml-dev \
- markdown \
transfig \
pandoc \
checkpolicy \
diff --git a/config/Docs.mk.in b/config/Docs.mk.in
index 33bd529..e76e5cd 100644
--- a/config/Docs.mk.in
+++ b/config/Docs.mk.in
@@ -5,6 +5,5 @@ FIG2DEV := @FIG2DEV@
POD2MAN := @POD2MAN@
POD2HTML := @POD2HTML@
POD2TEXT := @POD2TEXT@
-MARKDOWN := @MARKDOWN@
PANDOC := @PANDOC@
PERL := @PERL@
diff --git a/docs/Makefile b/docs/Makefile
index 2867efc..013fa8e 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -11,8 +11,6 @@ MAN_SECTIONS := 1 5 7 8
# Documentation sources to build
MAN-SRC-y := $(sort $(basename $(wildcard man/*.pod man/*.pandoc)))
-MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
-
TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print))
PANDOCSRC-y := $(sort $(shell find designs/ features/ misc/ process/ specs/ -name '*.pandoc' -print))
@@ -23,17 +21,14 @@ $(foreach i,$(MAN_SECTIONS), \
$(filter %.$(i),$(MAN-SRC-y)))))
DOC_HTML := html/SUPPORT.html \
- $(patsubst %.markdown,html/%.html,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,html/%.html,$(PANDOCSRC-y)) \
$(patsubst %,html/%.html,$(MAN-SRC-y)) \
$(patsubst %.txt,html/%.txt,$(TXTSRC-y)) \
$(patsubst %,html/hypercall/%/index.html,$(DOC_ARCHES))
DOC_TXT := $(patsubst %.txt,txt/%.txt,$(TXTSRC-y)) \
- $(patsubst %.markdown,txt/%.txt,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,txt/%.txt,$(PANDOCSRC-y)) \
$(patsubst %,txt/%.txt,$(MAN-SRC-y))
-DOC_PDF := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y)) \
- $(patsubst %.pandoc,pdf/%.pdf,$(PANDOCSRC-y))
+DOC_PDF := $(patsubst %.pandoc,pdf/%.pdf,$(PANDOCSRC-y))
# Top level build targets
.PHONY: all
@@ -181,14 +176,6 @@ uninstall: uninstall-man-pages uninstall-html
html/index.html: $(DOC_HTML) $(CURDIR)/gen-html-index INDEX
$(PERL) -w -- $(CURDIR)/gen-html-index -i INDEX html $(DOC_HTML)
-html/%.html: %.markdown
-ifneq ($(MARKDOWN),)
- @$(INSTALL_DIR) $(@D)
- $(MARKDOWN) $< > $@
-else
- @echo "markdown not installed; skipping $@"
-endif
-
html/%.txt: %.txt
@$(INSTALL_DIR) $(@D)
$(INSTALL_DATA) $< $@
@@ -213,10 +200,6 @@ txt/%.txt: %.txt
@$(INSTALL_DIR) $(@D)
$(INSTALL_DATA) $< $@
-txt/%.txt: %.markdown
- @$(INSTALL_DIR) $(@D)
- $(INSTALL_DATA) $< $@
-
# Metarule for generating pandoc rules.
define GENERATE_PANDOC_RULE_RAW
$(1): $(2)
@@ -234,9 +217,8 @@ endef
$(eval $(call GENERATE_PANDOC_RULE,pdf,pandoc)) # pdf/%.pdf: %.pandoc
$(eval $(call GENERATE_PANDOC_RULE,txt,pandoc)) # txt/%.txt: %.pandoc
$(eval $(call GENERATE_PANDOC_RULE,html,pandoc)) # html/%.html: %.pandoc
-$(eval $(call GENERATE_PANDOC_RULE,pdf,markdown)) # pdf/%.pdf: %.markdown
-$(eval $(call GENERATE_PANDOC_RULE_RAW,html/SUPPORT.html,$(XEN_ROOT)/SUPPORT.md)) # pdf/%.pdf: %.markdown
+$(eval $(call GENERATE_PANDOC_RULE_RAW,html/SUPPORT.html,$(XEN_ROOT)/SUPPORT.md))
ifeq (,$(findstring clean,$(MAKECMDGOALS)))
$(XEN_ROOT)/config/Docs.mk:
diff --git a/docs/configure b/docs/configure
index 3e0089c..7b90da0 100755
--- a/docs/configure
+++ b/docs/configure
@@ -588,7 +588,6 @@ ac_unique_file="misc/xen-command-line.markdown"
ac_subst_vars='LTLIBOBJS
LIBOBJS
PERL
-MARKDOWN
PANDOC
POD2TEXT
POD2HTML
@@ -673,7 +672,6 @@ POD2MAN
POD2HTML
POD2TEXT
PANDOC
-MARKDOWN
PERL'
@@ -1316,7 +1314,6 @@ Some influential environment variables:
POD2HTML Path to pod2html tool
POD2TEXT Path to pod2text tool
PANDOC Path to pandoc tool
- MARKDOWN Path to markdown tool
PERL Path to Perl parser
Use these variables to override the choices made by `configure' or to help
@@ -2224,60 +2221,6 @@ fi
- for ac_prog in markdown markdown_py
-do
- # Extract the first word of "$ac_prog", so it can be a program name with args.
-set dummy $ac_prog; ac_word=$2
-{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
-$as_echo_n "checking for $ac_word... " >&6; }
-if ${ac_cv_path_MARKDOWN+:} false; then :
- $as_echo_n "(cached) " >&6
-else
- case $MARKDOWN in
- [\\/]* | ?:[\\/]*)
- ac_cv_path_MARKDOWN="$MARKDOWN" # Let the user override the test with a path.
- ;;
- *)
- as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
-for as_dir in $PATH
-do
- IFS=$as_save_IFS
- test -z "$as_dir" && as_dir=.
- for ac_exec_ext in '' $ac_executable_extensions; do
- if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
- ac_cv_path_MARKDOWN="$as_dir/$ac_word$ac_exec_ext"
- $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
- break 2
- fi
-done
- done
-IFS=$as_save_IFS
-
- ;;
-esac
-fi
-MARKDOWN=$ac_cv_path_MARKDOWN
-if test -n "$MARKDOWN"; then
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: $MARKDOWN" >&5
-$as_echo "$MARKDOWN" >&6; }
-else
- { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
-$as_echo "no" >&6; }
-fi
-
-
- test -n "$MARKDOWN" && break
-done
-
- if ! test -x "$ac_cv_path_MARKDOWN"; then :
-
- { $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: markdown is not available so some documentation won't be built" >&5
-$as_echo "$as_me: WARNING: markdown is not available so some documentation won't be built" >&2;}
-
-fi
-
-
-
# Extract the first word of "perl", so it can be a program name with args.
set dummy perl; ac_word=$2
{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
diff --git a/docs/configure.ac b/docs/configure.ac
index 5777162..4927b97 100644
--- a/docs/configure.ac
+++ b/docs/configure.ac
@@ -25,7 +25,6 @@ AX_DOCS_TOOL_PROG([POD2MAN], [pod2man])
AX_DOCS_TOOL_PROG([POD2HTML], [pod2html])
AX_DOCS_TOOL_PROG([POD2TEXT], [pod2text])
AX_DOCS_TOOL_PROG([PANDOC], [pandoc])
-AX_DOCS_TOOL_PROGS([MARKDOWN], [markdown], [markdown markdown_py])
AC_ARG_VAR([PERL], [Path to Perl parser])
AX_PATH_PROG_OR_FAIL([PERL], [perl])
--
2.1.4
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: [PATCH 4/4] docs: Remove Markdown from configure.ac and the build instructions
2019-01-02 11:43 ` [PATCH 4/4] docs: Remove Markdown from configure.ac and the build instructions Andrew Cooper
@ 2019-01-02 12:28 ` Ian Jackson
2019-01-02 15:51 ` Andrew Cooper
1 sibling, 0 replies; 12+ messages in thread
From: Ian Jackson @ 2019-01-02 12:28 UTC (permalink / raw)
To: Andrew Cooper
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk,
Doug Goldstein, Tim (Xen.org),
George Dunlap, Xen-devel, Julien Grall, Jan Beulich
Andrew Cooper writes ("[PATCH 4/4] docs: Remove Markdown from configure.ac and the build instructions"):
> Now that all use of markdown as been replaced with pandoc, drop it from
> configure.ac and from the docs/ Makefile.
>
> Instead of just deleting the markdown reference from README, adjust the line
> to mention the other optional packages required for documentation.
>
> Drop markdown from travis and the docker containers. While tweaking the
> CentOS containers, pull in transfig and pandoc seeing as EPEL is set up, to
> bring them in line with the Debian based containers.
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 1/4] docs/pandoc: Don't escape underscores in the middle of text
2019-01-02 11:43 ` [PATCH 1/4] docs/pandoc: Don't escape underscores in the middle of text Andrew Cooper
@ 2019-01-02 12:28 ` Ian Jackson
0 siblings, 0 replies; 12+ messages in thread
From: Ian Jackson @ 2019-01-02 12:28 UTC (permalink / raw)
To: Andrew Cooper
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk, Tim (Xen.org),
George Dunlap, Xen-devel, Julien Grall, Jan Beulich
Andrew Cooper writes ("[PATCH 1/4] docs/pandoc: Don't escape underscores in the middle of text"):
> Pandoc deliberately (and contrary to markdown) doesn't treat underscores in
> the middle of normal text as emphasis markers, as this is almost always the
> unhelpful interpretation.
>
> For text which is emphasised using _, an underscore in the middle is
> interpreted, but the emphasis marker can be switched to * instead.
>
> One problem case is where we use {} globbing with identifier names, as it
> counts as a word break. Therefore, we do need to retain the escaped
> underscore immediately following a closing brace.
I'm happy to take your word for this.
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 2/4] docs/markdown: Switch to using pandoc, and fix underscore escaping
2019-01-02 11:43 ` [PATCH 2/4] docs/markdown: Switch to using pandoc, and fix underscore escaping Andrew Cooper
@ 2019-01-02 12:28 ` Ian Jackson
0 siblings, 0 replies; 12+ messages in thread
From: Ian Jackson @ 2019-01-02 12:28 UTC (permalink / raw)
To: Andrew Cooper
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk, Tim (Xen.org),
George Dunlap, Xen-devel, Julien Grall, Jan Beulich
Andrew Cooper writes ("[PATCH 2/4] docs/markdown: Switch to using pandoc, and fix underscore escaping"):
> c/s a3a99df44 "docs/cmdline: Rewrite the cpuid_mask_* section" completely
> forgot about how markdown gets rendered to HTML (as opposed to PDF), because
> we use different translators depending on the destination format.
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 3/4] docs/man: Fix/simplify generation of manpages
2019-01-02 11:43 ` [PATCH 3/4] docs/man: Fix/simplify generation of manpages Andrew Cooper
@ 2019-01-02 12:30 ` Ian Jackson
2019-01-02 12:45 ` Andrew Cooper
0 siblings, 1 reply; 12+ messages in thread
From: Ian Jackson @ 2019-01-02 12:30 UTC (permalink / raw)
To: Andrew Cooper
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk, Tim (Xen.org),
George Dunlap, Xen-devel, Julien Grall, Jan Beulich
Andrew Cooper writes ("[PATCH 3/4] docs/man: Fix/simplify generation of manpages"):
> The DOC_MANx lists are broken. They contain MANxSRC-y twice, the first half
> with a partial %.pod substituation, and the second half with a partial
> %.markdown substitution. This is also the root cause behind the filtering
> activity in the uninstall-man$(i)-pages rule.
...
> As for the makefile:
>
> 1) Break the MAN_SECTIONS list out of the GENERATE_MANPAGE_RULES loop, as we
> are going to use it a second time.
> 2) Do away with the individaul MANxSRC-y variables. Use a single list,
> derived from all *.pod and *.pandoc files, with their format suffixes
> removed.
> 3) Use a $(foreach ...) to generate the DOC_MANx lists, filling them with the
> correct content.
> 4) The DOC_HTML and DOC_TXT can now include all manpages with a single
> substitution, as they don't need to separate the manpages by
> section-numbered-directory.
> 5) Fix up the filenames in the manpage metarule to match the renaming.
>
> No functional change.
How confident are you that this does not break -j-safety ?
I very briefly eyeballed it and nothing jumped out at me. I wonder
if I should review it properly. What do you think ?
Thanks,
Ian.
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 3/4] docs/man: Fix/simplify generation of manpages
2019-01-02 12:30 ` Ian Jackson
@ 2019-01-02 12:45 ` Andrew Cooper
2019-01-02 15:21 ` Ian Jackson
0 siblings, 1 reply; 12+ messages in thread
From: Andrew Cooper @ 2019-01-02 12:45 UTC (permalink / raw)
To: Ian Jackson
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk, Tim (Xen.org),
George Dunlap, Xen-devel, Julien Grall, Jan Beulich
On 02/01/2019 12:30, Ian Jackson wrote:
> Andrew Cooper writes ("[PATCH 3/4] docs/man: Fix/simplify generation of manpages"):
>> The DOC_MANx lists are broken. They contain MANxSRC-y twice, the first half
>> with a partial %.pod substituation, and the second half with a partial
>> %.markdown substitution. This is also the root cause behind the filtering
>> activity in the uninstall-man$(i)-pages rule.
> ...
>> As for the makefile:
>>
>> 1) Break the MAN_SECTIONS list out of the GENERATE_MANPAGE_RULES loop, as we
>> are going to use it a second time.
>> 2) Do away with the individaul MANxSRC-y variables. Use a single list,
>> derived from all *.pod and *.pandoc files, with their format suffixes
>> removed.
>> 3) Use a $(foreach ...) to generate the DOC_MANx lists, filling them with the
>> correct content.
>> 4) The DOC_HTML and DOC_TXT can now include all manpages with a single
>> substitution, as they don't need to separate the manpages by
>> section-numbered-directory.
>> 5) Fix up the filenames in the manpage metarule to match the renaming.
>>
>> No functional change.
> How confident are you that this does not break -j-safety ?
> I very briefly eyeballed it and nothing jumped out at me. I wonder
> if I should review it properly. What do you think ?
I'm fairly sure I haven't touched anything which affects -j-safety.
The only content which has changed is to lose the mal-substituted origin
source files from DOC_MANx. These caused unnecessary dependencies
between man$(1)-pages and the original source files, which have no rule
to trigger, and will be considered up to date.
All the properly substituted content in DOC_MANx is identical to what it
was before. Other earlier lists were just intermediate processing
between the $(wildcard ) and the DOC_* lists, and are evaluated
immediately with :=.
~Andrew
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 3/4] docs/man: Fix/simplify generation of manpages
2019-01-02 12:45 ` Andrew Cooper
@ 2019-01-02 15:21 ` Ian Jackson
0 siblings, 0 replies; 12+ messages in thread
From: Ian Jackson @ 2019-01-02 15:21 UTC (permalink / raw)
To: Andrew Cooper
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk, Tim (Xen.org),
George Dunlap, Xen-devel, Julien Grall, Jan Beulich
Andrew Cooper writes ("Re: [PATCH 3/4] docs/man: Fix/simplify generation of manpages"):
> I'm fairly sure I haven't touched anything which affects -j-safety.
>
> The only content which has changed is to lose the mal-substituted origin
> source files from DOC_MANx. These caused unnecessary dependencies
> between man$(1)-pages and the original source files, which have no rule
> to trigger, and will be considered up to date.
>
> All the properly substituted content in DOC_MANx is identical to what it
> was before. Other earlier lists were just intermediate processing
> between the $(wildcard ) and the DOC_* lists, and are evaluated
> immediately with :=.
OK. You have convinced me that you have thought about this in roughly
the right kind of way :-), even though I haven't followed your
reasoning through the code so that I could actually verify it.
Thanks.
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 4/4] docs: Remove Markdown from configure.ac and the build instructions
2019-01-02 11:43 ` [PATCH 4/4] docs: Remove Markdown from configure.ac and the build instructions Andrew Cooper
2019-01-02 12:28 ` Ian Jackson
@ 2019-01-02 15:51 ` Andrew Cooper
1 sibling, 0 replies; 12+ messages in thread
From: Andrew Cooper @ 2019-01-02 15:51 UTC (permalink / raw)
To: Xen-devel
Cc: Stefano Stabellini, Wei Liu, Konrad Rzeszutek Wilk,
George Dunlap, Doug Goldstein, Tim Deegan, Julien Grall,
Jan Beulich, Ian Jackson
On 02/01/2019 11:43, Andrew Cooper wrote:
> Now that all use of markdown as been replaced with pandoc, drop it from
> configure.ac and from the docs/ Makefile.
>
> Instead of just deleting the markdown reference from README, adjust the line
> to mention the other optional packages required for documentation.
>
> Drop markdown from travis and the docker containers. While tweaking the
> CentOS containers, pull in transfig and pandoc seeing as EPEL is set up, to
> bring them in line with the Debian based containers.
>
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
> ----
> CC: George Dunlap <George.Dunlap@eu.citrix.com>
> CC: Ian Jackson <ian.jackson@citrix.com>
> CC: Jan Beulich <JBeulich@suse.com>
> CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
> CC: Stefano Stabellini <sstabellini@kernel.org>
> CC: Tim Deegan <tim@xen.org>
> CC: Wei Liu <wei.liu2@citrix.com>
> CC: Julien Grall <julien.grall@arm.com>
> CC: Doug Goldstein <cardoe@cardoe.com>
> ---
> .travis.yml | 1 -
> README | 3 +-
> automation/build/centos/7.2.dockerfile | 3 +-
> automation/build/centos/7.dockerfile | 3 +-
> automation/build/debian/jessie-i386.dockerfile | 1 -
> automation/build/debian/jessie.dockerfile | 1 -
> automation/build/debian/stretch-i386.dockerfile | 1 -
> automation/build/debian/stretch.dockerfile | 1 -
> .../build/debian/unstable-arm64v8.dockerfile | 1 -
> automation/build/debian/unstable-i386.dockerfile | 1 -
> automation/build/debian/unstable.dockerfile | 1 -
> automation/build/ubuntu/bionic.dockerfile | 1 -
> automation/build/ubuntu/trusty.dockerfile | 1 -
> automation/build/ubuntu/xenial.dockerfile | 1 -
> config/Docs.mk.in | 1 -
> docs/Makefile | 22 +--------
> docs/configure | 57 ----------------------
> docs/configure.ac | 1 -
> 18 files changed, 8 insertions(+), 93 deletions(-)
Having discussed this with Wei, the docker containers are also used by
staging-4.11, so markdown should be. It is an optional dependency, but
we should still try building the docs in older branches.
~Andrew
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2019-01-02 15:51 UTC | newest]
Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-01-02 11:43 [PATCH 0/4] docs: Multiple fixes to docs Andrew Cooper
2019-01-02 11:43 ` [PATCH 1/4] docs/pandoc: Don't escape underscores in the middle of text Andrew Cooper
2019-01-02 12:28 ` Ian Jackson
2019-01-02 11:43 ` [PATCH 2/4] docs/markdown: Switch to using pandoc, and fix underscore escaping Andrew Cooper
2019-01-02 12:28 ` Ian Jackson
2019-01-02 11:43 ` [PATCH 3/4] docs/man: Fix/simplify generation of manpages Andrew Cooper
2019-01-02 12:30 ` Ian Jackson
2019-01-02 12:45 ` Andrew Cooper
2019-01-02 15:21 ` Ian Jackson
2019-01-02 11:43 ` [PATCH 4/4] docs: Remove Markdown from configure.ac and the build instructions Andrew Cooper
2019-01-02 12:28 ` Ian Jackson
2019-01-02 15:51 ` Andrew Cooper
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.