From mboxrd@z Thu Jan 1 00:00:00 1970 From: David Scott Subject: [PATCH v3 1/3] docs: add a document describing the 'channels' mechanism Date: Mon, 23 Jun 2014 09:28:59 +0100 Message-ID: <1403512141-12283-2-git-send-email-dave.scott@citrix.com> References: <1403512141-12283-1-git-send-email-dave.scott@citrix.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: Received: from mail6.bemta14.messagelabs.com ([193.109.254.103]) by lists.xen.org with esmtp (Exim 4.72) (envelope-from ) id 1Wyzcp-0001Yp-0b for xen-devel@lists.xenproject.org; Mon, 23 Jun 2014 08:29:15 +0000 In-Reply-To: <1403512141-12283-1-git-send-email-dave.scott@citrix.com> List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org To: xen-devel@lists.xenproject.org Cc: ian.jackson@eu.citrix.com, David Scott , wei.liu2@citrix.com, ian.campbell@citrix.com, stefano.stabellini@eu.citrix.com List-Id: xen-devel@lists.xenproject.org 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 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 --- 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 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='. 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