[PATCH v2 6/6] Add a general description of the channel mechanism to docs/misc/

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

Signed-off-by: David Scott <dave.scott@citrix.com>
---
 docs/misc/channel.txt |   49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 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..b5ab385
--- /dev/null
+++ b/docs/misc/channel.txt
@@ -0,0 +1,49 @@
+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 is configured by 2 xenstore keys:
+
+  type = (NONE | FILE | PTY | SOCKET | ... )
+  path = <some path>
+
+In the default implementation where the backend is run in the toolstack
+domain, the qemu "chardev" mechanism is used. This implementation
+interprets the configuration as follows:
+
+  type = NONE: the backend will be connected to /dev/null
+  type = FILE: the channel will be read the the output appended
+    to the file given by 'path'
+  type = PTY: the backend will connect to a PTY like a regular console
+  type = SOCKET: the backend will accept a connection on the Unix
+    domain socket given by 'path' and proxy data to and from the device.
+
+If the implementation is in another domain (for example via a Mirage
+console backend) then the behaviour will be defined by this other domain.
-- 
1.7.10.4