VSCHED 0.9
==========

Bin Lin and Peter A. Dinda
Department of Computer Science
Northwestern University

Copyright (c) 2004 by Bin Lin and Peter Dinda

{binlin, pdinda}@cs.northwestern.edu

http://virtuoso.cs.northwestern.edu


Contents:
=========

1. Description
2. Licensing
3. Files
4. Installation
5. Usage
6. Protocol
7. Example Scenario
8. Note


1. Description
--------------

VSCHED is a soft real-time scheduling daemon for virtual machines and
other processes running on Linux.  A user can connect to VSCHED and
request that any process be executed according to a period and
slice. For example, the specification (3333, 1000ms,200ms) would mean
that process 3333 should be run for 200 ms every 1000ms.  VSCEHD will
determine whether the request is feasible, and then enforce it.

VSCHED is based on the following elements:

=> Linux's SCHED_FIFO scheduling class and its fixed priorities
=> SIGSTOP/SIGCONT
=> KURT high resolution event timers (optional)

The first two elements exist out of the box on any Linux system.  If
RTAI or KURT is available, VSCHED will be able to accept higher
resolution period and slice requests.  

If you are using the 2.6 version of the Linux kernel, you will get
higher resolution than with the 2.4 version.  On the 2.6 kernel, the
default timer interrupt rate is 1000 Hz, while on 2.4 it is only 100
Hz. 


2. Licensing
------------

Please see the included file LICENSE


3. Files
--------

README          This file
LICENSE         Licensing information

Makefile        Makefile for the VSCHED server and client

vsched.cc       VSCHED server
client.cc       VSCHED client

admit.h
admit.cc        Admission control
config.h        
config.cc       Configuration
util.h
util.cc         Utilities
socks.h
socks.cc        Sockets
sched.h
sched.cc        Scheduling core


4. Installation
---------------

VSCHED needs to be installed as root. The Makefile will install it as
a setuid root program in /usr/bin.

To build VSCHED, you need a recent version of GCC. 
gcc version 3.3.2 on Linux version 2.6.3-7mdk  (Mandrake Linux 10.0)
gcc version 3.2.2 on Linux version 2.6.8.1 (Red Hat Linux 9.0)
gcc version 2.96 on Linux version 2.4.18 (Red Hat Linux 7.3)
For KURT support, we compile it with KURT 2.4.18 (gcc version 2.96 on
Linux version 2.4.18 (Red Hat Linux 7.3)) 

You will also need OpenSSL.  

The distribution includes binaries for RH 9.0.

1. tar -xzvf vsched-0.9.tgz
untar and unzip the file

2. cd vsched-0.9

3. make clean
create all the executables

4. make [KURT=1] | [KERNEL=260]
If your Linux was pathced with KURT, you may compile vsched with
"KURT=1" to makqe use of KURT's high-resolution timer (~50
microseconds). If your Linux has 2.6 kernel, you may compile vsched
with "KERNEL=260" to make use of Linux's new finer timer (~1
millisecond) compared with older kernel (version<=2.4) (~10
milliseconds).  By default, vsched will be compiled, assuming you have
a 2.4 or 2.6 Linux kernel.

5. make install  (this must be run as root)
sets the executable vsched to run as root
intsall the executables in /usr/bin/


5. Usage
--------

VSCHED server:

vsched password [-s] [-a] [-p1 <gui_prio>] [-p2 <sched_prio>] 
                [-h <IP|hostname>] [-p <port>] [-o <percentage>] 
                [-n <numproc>] 

password        - password needed to connect to VSCHED
-s              - encrypt the TCP connection (required)
-a		- schedule processes using absolute run/stop instead
 		  of pure FIFO (default: false (off))
-g <gui_prio>	- the FIFO priority of the client/server 
                  interface (default: 95 (1-99))
-e <sched_prio>	- the FIFO priority of the scheduler (default: 98 (1-99))
-h <IP|hostname>- bind address (IP address or hostname)
-p <port>       - bind port (default: 4456)
-o <percentage> - percentage of time that must be left available 
                  for SCHED_OTHER processes (default: 35 (35%))
-n <numproc>    - number of processes that can be controlled (default: 128)

VSCHED client

vschedclient [-s] [-p password] [-o port] 
             -h <host> -c <command> -d <pid> -i <period> -l <slice>

-s              - encrypt the TCP connection (required)
-p <password>   - the password to the VSCHED server the client is 
                  connecting to (default action is prompting for password)
-o <por1>       - the port on the VSCHED server the 
                  client is connecting to (required, default: 4456)
-h <hos1>       - the host on which the VSCHED server is running
-c <command>    - the command to be issued to the VSCHED server

command can be one of the following:

echo            - open an interactive session with the VSCHED server to 
                  issue commands interactively
config          - get the VSCHED configuration
processes       - get a list of processes under VSCHED control
detach -d <id>  - stop VSCHED from scheduling a process, setting it to
                  SCHED_OTHER
schedule -d <id> -i <period> -l <slice>   
                - request that VSCHED begin scheduling a process
                  according to the slice and period.  This is also
                  how to change the schedule of a process.
stop -d <id>    - stop the execution of a process
resume -d <id>  - resume the execution of a process

6. Protocol
-----------

client<->VSCHED server communication is all text-based. 

The protocol is driven by the client that initiates the communication.
In response to client requests, the VSCHED server responds with "OK"
for success and "NOK" for failure.

All TCP connections have the option of being encrypted using SSL.

Connection establishment
========================

client does active open to VSCHED server.

client:

HELLO_VSCHED password version

vsched server:

OK version    

or

NOK string


Connection teardown
===================

Initiated by client.  

client:

DONE

vsched server:

OK string

or

NOK string


Configuration requests
======================

Get the configuration of the VSCHED server
------------------------------------------

client:

config

vsched server:

OK string
num_lines
period_min
period_max
period_res
slice_min
slice_max
slice_res
sched_other_percent
allocated_time_percent
.. other info
..

or

NOK string



Get a list of currently scheduled processes
-------------------------------------------

client:

processes

vsched server:

OK string 
number_of_processes
identifier R|S period_ms slice_ms sched_admit_time_s pathname
...

or

NOK string


Returning a process to SCHED_OTHER scheduling
---------------------------------------------

client:

detach -d identifier

vsched server:

OK string

or

NOK string


Scheduling a process according to period/slice
----------------------------------------------

client:

schedule -d identifer -i period_ms -l slice_ms

vsched server:

Attempts to establish or change the schedule to the one given.

OK string

or

NOK string


Stopping a process (only those under VSCHED control)
----------------------------------------------------

client:

stop -d identifer

vsched server:

OK string

or

NOK string


Resuming a process (only those under VSCHED control)
----------------------------------------------------

client:

resume -d identifer

vsched server:

OK string

or

NOK string

7. Example Scenario
-------------------

Suppose you want to run vsched on the machine 129.105.42.56.  We want
the server password to be 123 and communicate with clients using
SSL. We also want the server interface to have FIFO priority 95 while
the scheduler has FIFO priority 98.  To start vsched, you would run:

./vsched 123 -s -g 95 -e 98

The client can be run on any machine. The following command line tries
to schedule a process with pid 2020 to run 200 microseconds every 1
millisecond:

./vschedclient -s -p 123 -o 4456 -h 129.105.42.56 -c schedule -d 2020 -i 1 -l 0.2

8. Note
-------------------

Try to schedule a process with smaller time resolution beyond the
system's capability might make the system too busy to respond to any
input.
