   9.4.1. QEMU - QEMU Emulator
   ===========================

   9.4.1.1. Description
    ------------------

    This plugin adds support for QEMU sessions. The current supported
    standard client types of this package are CLI, X11 and
    VNC. Dependant of the called qemu-version and the embedded OS the
    actual resulting support for the console could vary.

    Specifics like the attachement of gdb are not supported within the
    command set of ctys, even though could be configured by the config
    file-script and will be forwarded to caller's machine by
    "DisplayForwarding".



    ****************************************************************
    *                                                              *
    *  REMARK: QEMU is currently a pre-release, thus not yet       *
    *          finished. Will be finalized soon.                   *
    *                                                              *
    ****************************************************************


    Networking
    ----------
            
      Even though there might be other viable solutions for the
      networking interconnection of QEMU, the "author gave it up" to
      continue with trial-and-error.

      The QEMU plugin requires the package vde or vde2 as a mandatory
      prerequisite. This is due to the following two features mainly:


        - Availibility of tunctl, which is named "vde_tunctl" within
          vde. This works on CentOS-5.0 perfectly.

          A TAP device is mandatory for QEMU to be interconnected in a
          transparent bridging mode as applied within this version at
          least.

        - The User-Space virtual switch "vde_switch", which just
          requires one tap-device to attachitself to the "external"
          network, whereas the users can attach to it's internal ports
          with their own permissions. 

          This is permitted due to pre-assigment of it's owner by usage of
          "vde_tunctl".



      A short description of the install process for QEMU with network
      support, pxe-boot/install, and cdrom-boot/support based on the
      examples from QEMU is given in the next chapter "Examples". A
      description is available in the general examples chapter too.



    Configuration File
    ------------------

      Due to the primarily CLI oriented and pure call-options based
      configuration a standard file is defined within ctys, which
      supports all entries for the start call and for the enumeration
      of available VMs. Therefore first of all a file is defined. 
      Second the standard notation of additional configuration values
      is adapted to this file.

      So, the UnifiedSessionsManager requires mandatory the presence
      of a configuration file to be able to handle QEMU VMs.

      Therefore a standard subset of suboptions for the CREATE call is
      provided. This is similar to the other supported VMs.

      The syntax of this file concerning the value assignments is
      described in the Appendix. In addition it is an exeutable script,
      which performs some final evaluation of parameters to be passed to
      QEMU. This is pure bash-shell syntax.

      The naming convention is as for all.

      For most of the QEMU provided test VMs a suitable configuration
      file is supported under the ".ctys/templates/qemu" directory.

      The expected directory structure for assembly of the runtime
      call is as given:

        $HOME
         +-qemu
           | 
           +-ctys      (new VMs)
           | 
           +-pc-bios   (supported bios files, e.g. pxe/ether-boot)
           | 
           +-tst       (supported ready-to-use test VMs of QEMU with 
                        ctys-config-files)



    Supported CPUs
    --------------

      The whole set of QEMU's CPUs is supported, which includes for
      version 0.9.1:

        - x86, AMD64, ARM, MIPS, PPC, PPC64, SH4, M68K, ALPHA, SPARK
  
      The appropriate call has to be configured within the appropriate
      configuration file. Templates as ready-to-use templates for the
      provided QEMU tests are included for x86, arm, coldfire, and
      SPARC. Running linux, uclinux, and NetBSD.




    Some additional remarks/reminder.
    ---------------------------------

     - When terminating a CLI session, the prompt will be released by
       a monitor short-cut: "Ctrl-a x".

       In some cases a "Ctrl-c" is sufficient.


   9.4.1.2. Options
    ---------------

    -a <action>[=<action-suboptions>]

        CREATE

           All standard parameteres not listed here could be applied.


           Additional keywords, some will be brought to the standard
           pool:

             NOCACHE
             NOPOLL
             CONSOLE:(SDL|CLI|XTERM|GTERM|VNC)

             PXE


           SDL
             This is the standard graphical console of QEMU.


           PXE
             This is boots a ROM image into PXE, currently only for
             x86 platforms supported.


        LIST

          Due to various output some assumption has to be made for
          processing. One point is, that for now the output of "ps"
          command is analysed for retrival of the active
          sessions. 

          The other aspect is the access permission to files which are
          not owned by the caller. So it is a design decision to bring
          as much information as possible to the command line.

          Is this a security flaw? Maybe, but the main aspect of ctys
          tools is to prevent the loacl access to a ps call, if the
          caller is not welcome. Therefore the information within the
          ps-output is not seen as more compromising, as the UNIX
          system is anyway or not.

          One important definition is the usage of vde tools as a
          general wrapper dor qemu. This is due to the main target of
          production and software development usage of Qemu, more than
          HW development. Therefore a easy to use userland wrapper for
          "TAN" device is required. The userland switch and the
          vde_tunctl are what is required.

          The conseqence is that the "vdeq|vdeqemu" strings are used
          as key for scan of ps-output. Thus native qemu calls will
          not be matched.

          Due to transformation information into ps-output the MAC
          address will be used in any case, which might not be much
          more than required anyway.

          For the same reason the label, which is a valid selector,
          has to be identical with the directory name, in which the
          QEMU-VM is contained.

          Another convention to be fulfilled is that the last
          pathname of the call has to be related to the VM, "-L"
          option and other pathnames have be left-of. This is
          tremendously simplifying any regexpr match and should be for
          the developer of a configuration file easy to handle. 


              REMINDER: Spaces in any entry are not supported.


          The following split between dynamic and static retrival is
          made:

            ps-only
              PID, UID, GID, DISPLAY, MAC, LABEL

            config-file
              UUID

            miscellaneous

              ID, HOST, SESSIONTYPE, CPORT, SPORT, CSTYPE



    -g <geometry>|<geometryExtended>

       The geometry could be set for the clients only, the resolution
       parameter "-r" is not applicable:

         SDL|CLI
           Not applicable.

         XTERM|GTERM
           The size Xsiz and Ysiz provide the UNIT of CHARACTERS only.

         VNC
           As expected.


    -r <resolution>

       Not supported.
 
