Re: [Xen-devel] [PATCH v2 1/3] docs: add pod variant of xen-pv-channel.7

[Wei Liu]

On Tue, Jul 25, 2017 at 02:17:59PM +0100, Ian Jackson wrote:
> Olaf Hering writes ("[PATCH v2 1/3] docs: add pod variant of 
> xen-pv-channel.7"):
> > Convert source for xen-pv-channel.7 from markdown to pod.
> > This removes the buildtime requirement for pandoc, and subsequently the
> > need for ghc, in the chain for BuildRequires of xen.rpm.
> 
> Thanks.  Thanks also for the explanations.  I'm happy that this series
> is fine in principle.  Now onto the details:
> 
> I applied your patches to see what they looked like and I noticed that
> git-am complains about whitespace errors.
> 
> >  docs/man/xen-pv-channel.pod.7  | 189 
> > +
> 
> These manpages are not quite in the conventional manpage structure,
> and your work reveals that are documentation is disorganised.
> Reorganising the pages to put things in more sensible places, add a
> SYNOPSYS near the top, etc. is probably out of scope.  I just thought
> I'd mention it.
> 
> But can you please change the headings to caps so they look like other
> manpages ?
> 
> I wonder if I should ask you to add a NAME section, as that seems to
> be very conventional in other projects' manpages.  See this for
> example
>   https://manpages.debian.org/stretch/dgit/dgit.7.en.html
> What do others think ?
> 

+1

___
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

Re: [Xen-devel] [PATCH v2 1/3] docs: add pod variant of xen-pv-channel.7

[Ian Jackson]

Olaf Hering writes ("[PATCH v2 1/3] docs: add pod variant of xen-pv-channel.7"):
> Convert source for xen-pv-channel.7 from markdown to pod.
> This removes the buildtime requirement for pandoc, and subsequently the
> need for ghc, in the chain for BuildRequires of xen.rpm.

Thanks.  Thanks also for the explanations.  I'm happy that this series
is fine in principle.  Now onto the details:

I applied your patches to see what they looked like and I noticed that
git-am complains about whitespace errors.

>  docs/man/xen-pv-channel.pod.7  | 189 
> +

These manpages are not quite in the conventional manpage structure,
and your work reveals that are documentation is disorganised.
Reorganising the pages to put things in more sensible places, add a
SYNOPSYS near the top, etc. is probably out of scope.  I just thought
I'd mention it.

But can you please change the headings to caps so they look like other
manpages ?

I wonder if I should ask you to add a NAME section, as that seems to
be very conventional in other projects' manpages.  See this for
example
  https://manpages.debian.org/stretch/dgit/dgit.7.en.html
What do others think ?

Ian.

___
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

[Xen-devel] [PATCH v2 1/3] docs: add pod variant of xen-pv-channel.7

[Olaf Hering]

Convert source for xen-pv-channel.7 from markdown to pod.
This removes the buildtime requirement for pandoc, and subsequently the
need for ghc, in the chain for BuildRequires of xen.rpm.

Signed-off-by: Olaf Hering 
---
 docs/man/xen-pv-channel.markdown.7 | 106 -
 docs/man/xen-pv-channel.pod.7  | 189 +
 2 files changed, 189 insertions(+), 106 deletions(-)
 delete mode 100644 docs/man/xen-pv-channel.markdown.7
 create mode 100644 docs/man/xen-pv-channel.pod.7

diff --git a/docs/man/xen-pv-channel.markdown.7 
b/docs/man/xen-pv-channel.markdown.7
deleted file mode 100644
index 1c6149dae0..00
--- a/docs/man/xen-pv-channel.markdown.7
+++ /dev/null
@@ -1,106 +0,0 @@
-Xen PV Channels
-===
-
-A channel is a low-bandwidth private byte stream similar to a serial
-link. Typical uses of channels are
-
-  1. to provide initial configuration information to a VM on boot
- (example use: CloudStack's cloud-early-config service)
-  2. to signal/query an in-guest agent
- (example use: oVirt's guest agent)
-
-Channels are similar to virtio-serial devices and emulated serial links.
-Channels are intended to be used in the implementation of libvirt s
-when running on Xen.
-
-Note: if an application requires a high-bandwidth link then it should use
-vchan instead.
-
-How to use channels: an example

-
-Consider a cloud deployment where VMs are cloned from pre-made templates,
-and customised on first boot by an in-guest agent which sets the IP address,
-hostname, ssh keys etc. To install the system the cloud administrator would
-first:
-
-  1. Install a guest as normal (no channel configuration necessary)
-  2. Install the in-guest agent specific to the cloud software. This will
- prepare the guest to communicate over the channel, and also prepare
- the guest to be cloned safely (sometimes known as "sysprepping")
-  3. Shutdown the guest
-  4. Register the guest as a template with the cloud orchestration software
-  5. Install the cloud orchestration agent in dom0
-
-At runtime, when a cloud tenant requests that a VM is created from the 
template,
-the sequence of events would be: (assuming a Linux domU)
-
-  1. A VM is "cloned" from the template
-  2. A unique Unix domain socket path in dom0 is allocated
- (e.g. /my/cloud/software/talk/to/domain/)
-  3. Domain configuration is created for the VM, listing the channel
- name expected by the in-guest agent. In xl syntax this would be:
-
- channel = [ "connection=socket, name=org.my.cloud.software.agent.version1,
-  path = /my/cloud/software/talk/to/domain/" ]
-
-  4. The VM is started
-  5. In dom0 the cloud orchestration agent connects to the Unix domain
- socket, writes a handshake message and waits for a reply
-  6. Assuming the guest kernel has CONFIG_HVC_XEN_FRONTEND set then the console
- driver will generate a hotplug event
-  7. A udev rule is activated by the hotplug event.
-
- The udev rule would look something like:
-
- SUBSYSTEM=="xen", DEVPATH=="/devices/console-[0-9]", 
RUN+="xen-console-setup"
-
- where the "xen-console-setup" script would read the channel name and
- make a symlink in /dev/xen-channel/org.my.cloud.software.agent.version1
-
-  8. The in-guest agent uses inotify to see the creation of the 
/dev/xen-channel
- symlink and opens the device.
-  9. The in-guest agent completes the handshake with the dom0 agent
- 10. The dom0 agent transmits the unique VM configuration: hostname, IP
- address, ssh keys etc etc
- 11. The in-guest agent receives the configuration and applies it.
-
-Using channels avoids having to use a temporary disk device or network
-connection.
-
-Design recommendations and pitfalls

-
-It's necessary to install channel-specific software (an "agent") into the guest
-before you can use a channel. By default a channel will appear as a device
-which could be mistaken for a serial port or regular console. It is known
-that some software will proactively seek out serial ports and issue AT commands
-at them; make sure such software is disabled!
-
-Since channels are identified by names, application authors must ensure their
-channel names are unique to avoid clashes. We recommend that channel names
-include parts unique to the application such as a domain names. To assist
-prevent clashes we recommend authors add their names to our global channel
-registry at the end of this document.
-
-Limitations

-
-Hotplug and unplug of channels is not currently implemented.
-
-Channel name registry
--
-
-It is important that channel names are globally unique. To help ensure
-that no-one's name clashes with yours, please add yours to this list.
-
-Key:
-N: Name
-C: Contact
-D: Short description of use, possibly including a URL to your software
-   or API
-
-N: