xspice: README, TODO, config, xspice launcher script

xspice is placed under scripts, adding a new Makefile.am, only
installed if --enable-xspice.
spiceqxl.xorg.conf.example is placed under examples to be installed
to share/doc if --enable-xspice.

8 files changed, 393 insertions, 2 deletions

diff --git a/Makefile.am b/Makefile.am
index 781f29b..736b3c3 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -18,7 +18,7 @@
 #  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 #  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-SUBDIRS = src
+SUBDIRS = src scripts examples
 
 MAINTAINERCLEANFILES = ChangeLog INSTALL
 .PHONY: ChangeLog INSTALL
diff --git a/README.xspice b/README.xspice
new file mode 100644
index 0000000..6efd351
--- /dev/null
+++ b/README.xspice
@@ -0,0 +1,114 @@
+1. Introduction
+2. Building
+2.1 Building from source on fedora
+2.2 Building from source with your own Xserver
+3. Running
+
+= 1. Introduction =
+Xspice is an X server and Spice server in one. It consists of a wrapper script
+for executing Xorg with the right parameters and environment variables, a
+module names spiceqxl_drv.so implementing three drivers: a video mostly
+code identical to the guest qxl X driver, and keyboard and mouse reading from
+the spice inputs channel.
+
+Xspice allows regular X connections, while a spice client provides the keyboard
+and mouse and video output.
+
+Spice client disconnections don't impact X client connections.
+
+Xserver's select loop is reused to service spice client sockets
+and the qxl driver is reused together with some of the qemu qxl device code
+
+The following changes have been done to the qxl driver.
+ * it creates only one memslot, covering the whole of memory (much like
+  spice does in simple display mode, i.e. vga, and the tester does)
+ * it invokes the whole of the qxl device from qemu, patching in both
+  directions.
+  * io becomes a function call instead of iob
+  * irq becomes a function call instead of setting a flag
+  * it runs spice server directly
+   * it is linked with spice-server.
+
+The protocol is unchanged.
+
+= 2. Building =
+== 2.1 Building from source on fedora ==
+
+The changes for ubuntu/debian should be minimal:
+ * location of drivers for Xorg (just where you put any qxl_drv.so etc.)
+ * location of Xorg config files
+
+In fedora they are: (note the lib64 - replace with lib if running on 32 bit
+fedora)
+
+DRV_DIR=/usr/lib64/xorg/modules/drivers
+XORG_CONF_DIR=/etc/X11
+
+git clone git://anongit.freedesktop.org/~alon/xspice
+sudo yum install spice-server-devel spice-protocol
+
+cd xspice
+autoreconf -i && ./configure --enable-xspice && make
+sudo cp src/.libs/spiceqxl_drv.so $DRV_DIR
+sudo cp spiceqxl.xorg $XORG_CONF_DIR
+
+Note: spiceqxl.org is copied to $XORG_CONF_DIR because Xorg only looks in a
+very particular config file path, and "." is not there (nor are absolute file
+names allowed unless Xorg is run as root).
+
+== 2.2 Building from source with your own Xserver ==
+
+Building the whole xserver is lengthier but can be done without
+any root permissions.
+
+This assumes you already have spice-protocol and spice-server
+installed into $TEST prefix below.
+
+TEST=/store/test
+grab xserver, xspice, xextproto and xkbcomp
+
+for src in git://anongit.freedesktop.org/xorg/proto/xextproto \
+git://anongit.freedesktop.org/xorg/app/xkbcomp \
+git://anongit.freedesktop.org/xorg/xserver \
+git://anongit.freedesktop.org/xorg/lib/libxkbfile \
+git://git.freedesktop.org/git/spice/spice-protocol
+git://anongit.freedesktop.org/~alon/xspice; do git clone $src; done
+
+build and install into some non common prefix (not to overwrite
+your existing server) - note that this is just for testing. This
+should all work with the default server as well, but that server
+requires root generally and this is undesireable for testing (and
+running actually).
+
+export PKG_CONFIG_PATH=${TEST}/lib/pkgconfig
+(cd xextproto; ./autogen.sh --prefix=$TEST --without-xmlto && make install)
+(cd xserver; ./autogen.sh --prefix=$TEST && make install)
+(cd xkbcomp; ./autogen.sh --prefix=$TEST && make install)
+(cd libxkbfile; ./autogen.sh --prefix=$TEST && make install)
+(cd spice-protocol; ./autogen.sh --prefix=$TEST  --datadir=$TEST/lib && make install)
+(cd xspice; ./autogen.sh --prefix=$TEST && make install)
+
+mkdir -p $TEST/etc/X11
+
+place the tested config below in $TEST/etc/X11/spiceqxl.xorg.conf.
+
+last bit is a little ugly (FIXME), copy over the xkb bits from the existing X11
+installation:
+mkdir -p $TEST/share/X11
+cp -R /usr/share/X11/xkb $TEST/share/X11
+
+= 3. Running =
+$XORG is either your own built $TEST/bin/Xorg or just the default Xorg
+
+Run server with:
+export XSPICE_PORT=6000
+$XORG -noreset -config spiceqxl.xorg.conf :3.0
+
+Or equivalently:
+./xspice --port 6000 :3.0
+
+Run X clients as usual by setting DISPLAY=:3.0
+Run spice client with port 5912 (hardcoded currently):
+
+spicec -h localhost -p 5912
+
diff --git a/TODO.xspice b/TODO.xspice
new file mode 100644
index 0000000..5793b76
--- /dev/null
+++ b/TODO.xspice
@@ -0,0 +1,23 @@
+TODO:
+
+ OOM. Not releasing?
+  Out of memory allocating 3145748 bytes
+  Out of mem - stats
+
+ Cursor channel missing.
+ No copy paste.
+ No agent at all.
+  agent should probably be thought to run with Xspice too. That way
+   mouse emulation in Xspice can be avoided entirely. But how do you
+   get an input device to belong to Xspice :1.0 and not to Xorg :0.0?
+
+ Keyboard:
+  * repeat (xset r 100) does nothing. This is because spice client
+   of course does repeat. But would be nice to transmit this.
+ 
+ Video: youtube seemed choppy, some frames were repeating (cpu 30%~, so not
+  cpu bound). Possible multimedia time? Isn't this set by the driver, i.e.
+  should be identical with in vm qxl driver?
+
+ Performance:
+  didn't check.
diff --git a/configure.ac b/configure.ac
index f95221a..c2bcc7d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -116,7 +116,9 @@ AC_CHECK_FILE(.git, [
 AC_CONFIG_FILES([
                 Makefile
                 src/Makefile
-		src/uxa/Makefile
+                src/uxa/Makefile
+                scripts/Makefile
+                examples/Makefile
 ])
 AC_OUTPUT
 
diff --git a/examples/Makefile.am b/examples/Makefile.am
new file mode 100644
index 0000000..75e61ea
--- /dev/null
+++ b/examples/Makefile.am
@@ -0,0 +1,24 @@
+#  Copyright 2011 Red Hat, Inc.
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a
+#  copy of this software and associated documentation files (the "Software"),
+#  to deal in the Software without restriction, including without limitation
+#  on the rights to use, copy, modify, merge, publish, distribute, sub
+#  license, and/or sell copies of the Software, and to permit persons to whom
+#  the Software is furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice (including the next
+#  paragraph) shall be included in all copies or substantial portions of the
+#  Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.  IN NO EVENT SHALL
+#  THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+#  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+#  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+if BUILD_XSPICE
+doc_DATA = spiceqxl.xorg.conf.example
+endif
+EXTRA_DIST = spiceqxl.xorg.conf.example
diff --git a/examples/spiceqxl.xorg.conf.example b/examples/spiceqxl.xorg.conf.example
new file mode 100644
index 0000000..5e37f9c
--- /dev/null
+++ b/examples/spiceqxl.xorg.conf.example
@@ -0,0 +1,101 @@
+Section "Device"
+    Identifier "XSPICE"
+    Driver "spiceqxl"
+
+    # Enable regular port. Either this or SpiceTlsPort, or one of XSPICE_PORT or
+    # XSPICE_TLS_PORT environment variables must be specified
+    # Defaults to 5900.
+    #Option "SpicePort" "5900"
+
+    # Enable a TLS (encrypted) port. Either this or SpicePort must be specified,
+    # either here or via environment varialbes or via xspice --port or --tls-port
+    #Option "SpiceTlsPort" "5901"
+    
+    # Listen to a specific inteface. Default is to listen to all (0.0.0.0)
+    #Option "SpiceAddr" ""
+
+    # Enable usage of SASL supported by spice-gtk client. Not required,
+    # defaults to false.
+    #Option "SpiceSasl" "True"
+
+    # Do not request any password from client
+    #Option "SpiceDisableTicketing" "0"
+
+    # Set directory where cacert, server key and server cert are searched
+    # using the same predefined names qemu uses:
+    #   cacert.pem, server-key.pem, server-cert.pem
+    #Option "SpiceX509Dir" ""
+
+    # Set password client will be required to produce.
+    #Option "SpicePassword" ""
+
+    # Set spice server key file.
+    #Option "SpiceX509KeyFile" ""
+
+    # Set streaming video method. Options are filter, off, all
+    # defaults to filter.
+    #Option "SpiceStreamingVideo" ""
+
+    # Set zlib glz wan compression. Options are auto, never, always.
+    # defaults to auto.
+    #Option "SpiceZlibGlzWanCompression" ""
+
+    # Set jpeg wan compression. Options are auto, never, always
+    # defaults to auto.
+    #Option "SpiceJpegWanCompression" ""
+
+    # Set image compression. Options are off,auto_glz,auto_lz,quic,glz,lz.
+    # defaults to auto_glz.
+    #Option "SpiceImageCompression" ""
+
+    # Set to true to only listen on ipv4 interfaces.
+    # defaults to false.
+    #Option "SpiceIPV4Only" ""
+
+    # Set to true to only listen on ipv6 interfaces.
+    # defaults to false.
+    #Option "SpiceIPV6Only" ""
+
+    # Set cert file location.
+    #Option "SpiceX509CertFile" ""
+
+    # Set key file password.
+    #Option "SpiceX509KeyPassword" ""
+
+    # Set tls ciphers used.
+    #Option "SpiceTlsCiphers" ""
+
+    # Set cacert file.
+    #Option "SpiceCacertFile" ""
+
+    # Set dh file used.
+    #Option "SpiceDhFile" ""
+EndSection
+
+Section "InputDevice"
+    Identifier "XSPICE POINTER"
+    Driver     "xspice pointer"
+EndSection
+
+Section "InputDevice"
+    Identifier "XSPICE KEYBOARD"
+    Driver     "xspice keyboard"
+EndSection
+
+Section "Monitor"
+    Identifier    "Configured Monitor"
+EndSection
+
+Section "Screen"
+    Identifier     "XSPICE Screen"
+    Monitor        "Configured Monitor"
+    Device        "XSPICE"
+    DefaultDepth    24
+EndSection
+
+Section "ServerLayout"
+    Identifier "XSPICE Example"
+    Screen "XSPICE Screen"
+    InputDevice "XSPICE KEYBOARD"
+    InputDevice "XSPICE POINTER"
+EndSection
diff --git a/scripts/Makefile.am b/scripts/Makefile.am
new file mode 100644
index 0000000..c03b573
--- /dev/null
+++ b/scripts/Makefile.am
@@ -0,0 +1,24 @@
+#  Copyright 2011 Red Hat, Inc.
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a
+#  copy of this software and associated documentation files (the "Software"),
+#  to deal in the Software without restriction, including without limitation
+#  on the rights to use, copy, modify, merge, publish, distribute, sub
+#  license, and/or sell copies of the Software, and to permit persons to whom
+#  the Software is furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice (including the next
+#  paragraph) shall be included in all copies or substantial portions of the
+#  Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.  IN NO EVENT SHALL
+#  THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+#  IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+#  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+if BUILD_XSPICE
+bin_SCRIPTS = xspice
+endif
+EXTRA_DIST = xspice
diff --git a/scripts/xspice b/scripts/xspice
new file mode 100755
index 0000000..f6146b4
--- /dev/null
+++ b/scripts/xspice
@@ -0,0 +1,103 @@
+#!/usr/bin/python
+
+"""
+xspice
+
+xspice is a standard X server that is also a Spice server.
+
+It is implemented as a module with video, mouse and keyboard drivers.
+
+The video driver is mostly the same code as the qxl guest driver, hence
+xspice is kept in the same repository. It can also be used to debug the qxl
+driver.
+
+xspice (this executable) will set a bunch of environment variables that are
+used by spiceqxl_drv.so, and then exec Xorg, giving it the default config file,
+which can be overridden as well.
+"""
+
+import argparse
+import os
+import sys
+
+def which(x):
+    for p in os.environ['PATH'].split(':'):
+        candidate = os.path.join(p, x)
+        if os.path.exists(candidate):
+            return candidate
+    return None
+
+cgdb = which('cgdb') and os.path.exists(
+    os.path.join(os.path.dirname(sys.modules[__name__].__file__),
+                 'configure.ac'))
+
+def add_boolean(flag, *args, **kw):
+    parser.add_argument(flag, action='store_const', const='1', default='0',
+                        *args, **kw)
+
+wan_compression_options = ['auto', 'never', 'always']
+parser = argparse.ArgumentParser("xspice",
+    description="X and Spice server. example usage: xspice --port 5900 :1.0",
+    usage="xspice [xspice and Xorg options intermixed]",
+    epilog="Any options not parsed by xspice get passed to Xorg as is.")
+parser.add_argument('--xorg', default=which('Xorg'))
+parser.add_argument('--config', default='spiceqxl.xorg.conf')
+# Don't use any options that are already used by Xorg (unless we must)
+# specifically, don't use -p and -s.
+parser.add_argument('--port', type=int, help='standard spice port')
+parser.add_argument('--tls-port', type=int, help='spice tls port')
+add_boolean('--disable-ticketing', help="do not require a client password")
+add_boolean('--sasl', help="enable sasl")
+parser.add_argument('--x509-dir', help="x509 directory for tls")
+parser.add_argument('--cacert-file', help="ca certificate file for tls")
+parser.add_argument('--x509-key-file', help="key file for tls")
+parser.add_argument('--x509-key-password', help="key file password for tls")
+parser.add_argument('--tls-ciphers')
+parser.add_argument('--dh-file')
+parser.add_argument('--password', help="set password required to connect to server")
+parser.add_argument('--image-compression',
+                    choices = ['off', 'auto_glz', 'auto_lz', 'quic',
+                               'glz', 'lz'],
+                    default='auto_glz', help='auto_glz by default')
+parser.add_argument('--jpeg-wan-compression',
+                    choices=wan_compression_options,
+                    default='auto', help='auto by default')
+parser.add_argument('--zlib-glz-wan-compression',
+                    choices=wan_compression_options,
+                    default='auto', help='auto by default')
+# TODO - sound support
+#parser.add_argument('--playback-compression', choices=['0', '1'], default='1', help='enabled by default')
+parser.add_argument('--streaming-video', choices=['off', 'all', 'filter'],
+                    default='filter', help='filter by default')
+add_boolean('--ipv4-only')
+add_boolean('--ipv6-only')
+
+if cgdb:
+    parser.add_argument('--cgdb', action='store_true', default=False)
+# TODO:
+#add_boolean(parser, '--agent-mouse')
+
+args, xorg_args = parser.parse_known_args(sys.argv[1:])
+
+def error(msg, exit_code=1):
+    print "xspice: %s" % msg
+    sys.exit(exit_code)
+
+if not args.xorg:
+    error("Xorg missing")
+
+var_args = ['port', 'tls_port', 'disable_ticketing',
+    'x509_dir', 'sasl', 'cacert_file', 'x509_key_file', 'x509_key_password',
+    'tls_ciphers', 'dh_file', 'password', 'image_compression',
+    'jpeg_wan_compression', 'zlib_glz_wan_compression',
+    'playback_compression', 'streaming_video']
+for arg in var_args:
+    if getattr(args, arg):
+        os.environ['XSPICE_' + arg.upper()] = str(getattr(args, arg))
+
+exec_args = [args.xorg, '-config', args.config]
+if cgdb and args.cgdb:
+    exec_args = [cgdb, '--args'] + exec_args
+    args.xorg = cgdb
+
+os.execv(args.xorg, exec_args + xorg_args)