[PATCH v3 1/3] docs: add a document describing the 'channels' mechanism

[David Scott <dave.scott@citrix.com>]

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 are intended to be
used in the implementation of libvirt <channel>s when running on Xen.

Note: if an application requires a high-bandwidth link then it should use
vchan instead.

Signed-off-by: David Scott <dave.scott@citrix.com>
---
 docs/misc/channel.txt |   52 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 docs/misc/channel.txt

diff --git a/docs/misc/channel.txt b/docs/misc/channel.txt
new file mode 100644
index 0000000..26c2289
--- /dev/null
+++ b/docs/misc/channel.txt
@@ -0,0 +1,52 @@
+Xen PV Channels
+------------------------------------------------------------------------
+                                                             David Scott
+                                                   dave.scott@citrix.com
+
+
+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 are intended to be
+used in the implementation of libvirt <channel>s when running on Xen.
+
+Note: if an application requires a high-bandwidth link then it should use
+vchan instead.
+
+From the frontend's point of view, a channel is a PV console with a
+name, a where the name can be used to locate the correct device. The
+name is stored in the frontend xenstore directory:
+
+  /local/domain/$DOMID/device/console/$DEVID/name
+
+The frontend can check for this key when the console is hotplugged,
+and handle the device appropriately. For example the frontend could
+spawn a guest agent when a channel with a well-known name is created,
+and still spawn regular getty processes when a normal console is created.
+
+The backend has an associated 'kind' which describes what the backend
+should do with the data. Thee are two defined values: 'pty' and 'socket'.
+
+If 'kind=pty' then the backend will connect to a PTY like a regular
+console. The pty device will be written into the 'tty' key in the
+frontend.
+
+If 'kind=socket' then the backend will create a listening Unix domain
+socket in the path given by 'path=<path>'. Connections will be
+accepted and the data proxied in both directions.
+
+In the default implementation the backend is implemented via qemu
+in "xenpv" mode (i.e. the 'console' device in xenstore will have
+'type=ioemu'). Futhermore if 'kind=socket' then the console 'output'
+in xenstore will be set to:
+ 
+  output = chardev:libxl-channel$DEVID
+
+The qemu commandline contains one "-chardev id=libxl-channel$DEVID,..."
+option per channel.
+
-- 
1.7.10.4