This is UMView Remote System Call (RSC) service module

(C) 2007 Andrea Forni

This is FREE software: this work has been released under the GPLv2 
license (see the file COPYING and the header note in the source files).


This project provides a UMView service module that permits to
execute the system calls generated by a process in different machine 
from the one where the process resides. 

The directory structure is:
- module/ : the UMView service module directory
- server/ : the RSC server directory 
- librsc/ : the Remote System Call library
- librsc_templates/ : the Ruby script and templates to generate some librsc's files

######################################
## Howto compile the project
######################################
There is a global Makefile in the root directory, call it without arguments to compile 
the library, the module and the server. 
The Makefile has a variable called RELEASE, if it's set to 'true' the code is compiled
without debug messages; if you want them set it to 'false'.


######################################
## The module
######################################
The module can be uploaded into UMView using the 'um_add_service' command.
Without extra arguments the module tries to connect to the server at localhost, ports
8050 and 8051. The module needs to establish two connections with the server:
one used to exchange all the data (syscall execution requests/response and 
ioctl management), the other is used for event subscription management.
The module accepts 3 arguments to change these default values:
- 'sa'  : permits to change the Server Address
- 'sp'  : permits to change the Server Port
- 'essp': permits to change the Event Subscription Server Port

For example, if the server is in execution on 'example.com' at ports
8050 (for normal traffic) and 9090 (for event subscription traffic),
you can connect the module in the following way:

$ um_add_service um_rsc.so,sa=example.com,essp=9090

The arguments follow the module and are separated by commas, white spaces
between options and between option name, equal symbol and option value
are not allowed.

######################################
## The Server
######################################
There isn't much to say, when executed without arguments the server waits
any inbound connection from 8050 and 8051 ports; as for the module
the server address and ports can be changed. To know the name of the options
type:

$ rsc_server -h 


######################################
## The RSC Library
######################################
The structure of the directory librsc/ is:
- include/ : contains the global headers of the library. The client (module) needs
             to include only the header 'rsc_client.h'; the server 'rsc_server.h'
- src/ : contains the source files of the library.
- src/include/ : contains some local headers 
- tests/ : contains some tests to verify the correctness of the library. Running the
           Makefile inside that directory produce 3 executable: client, server and selftests.
           'server' implements a very simple server waiting a 'client' connection; some 
           tests need client-server interaction and others no, but the first things client and
           server do is to establish a connection, so the connection is needed also for tests that 
           don't need it. 'server' and 'client' are useful if you want to test the library between 
           different architecture (running the server in one and the client in the other);
           if you want to execute 'server' and 'client' on the same machine, use 'selftests'.
           'selftests' creates two threads, one for the client tests and one for the server tests.

           NOTE: to compile, the programs need a debug version of librsc with no debug messages
                 (RELEASE=false and RSCDEBUGLEVEL=0), to obtain it type:
                 
                 $ make cleanlib; make
                
                 'make cleanlib' remove librsc/librsc.a library and 'make' builds the right version
                 of the library needed by the tests.
                 The tests need a debug version of the library because in this version some static
                 functions are exposed so the be can testes. 
                 If you use the librsc/Makefile with RELEASE=false, you obtain a debug version of 
                 the library, but this version contains debug message that can complicate the 
                 tests output.

NOTE: the marshaling support is still under-development and testing, so running the module and the server
      in two host with different architecture doesn't work well (for now).

NOTE2: The interaction of the module and server has been tested on a machine with x86 architecture.
       The code compile also into powerpc and x86_64 architectures but more tests are needed to
       see if they work correctly on these architectures.

######################################
## The librsc template directory
######################################
The librsc_templates/ directory contains the Ruby script 'rsc_file_gen.rb' used
to generate some librsc source files in a automatic way.
The directory contains two sub-dirs: 
- 'program' : contains the Ruby script
- 'input'   : the files passed in input at the script

The contents of the program directory are:
- rsc_file_gen.rb : the ruby script
- src : some additional module needed by the script
- tests : some unit tests
- Rakefile.rb : a Makefile written in Ruby. The tasks (tasks are equivalent to Makefile's targets) 
                offered by this rakefile are:
                - 'doc' (the default) : it creates a doc/ directory with HTML documentation of
                        the classes and modules.
                - 'test' : execute the tests inside the tests/ directory
                - 'clean' : guess...
                
Executing the rsc_file_gen.rb with the '-h' option produce the usage message. The scripts
need 4 arguments, 3 of them are input argument the last is the base directory of librsc.
The 3 input arguments are:
- the syscall_list_file a text file describing the system calls.
- a unistd directory where the script search 3 files: unistd_ppc.h, unistd_x86_64.h and unistd_x86.h
  used to get information about the number and the type of system call in each architecture 
- a template directory containing the template. The script search and load only the templates
  with extension '.c' or '.h'

The librsc_templates/input/ contains the 3 arguments needed by the script. 
The librsc_templates/Makefile call the script with the right arguments, so to generate
the files is sufficient to type 'make' inside the librsc_templates/ directory.

NOTE: The global Makefile doesn't call this makefile to update the generated files
NOTE2: rsc_file_gen.rb process each template and if the generated file isn't different
       from the one already existing it doesn't do anything and pass to the next template.
       If there are some changes the old file is overwritten but a backup copy is saved 
       in a hidden file in the same directory. The hidden file has the following name
       format:
       .<original file name>-bak_<seconds since epoch>_<date>_<time>
       
       For example a backup copy of the the file 'librsc/src/rsc_client.c' is:
       librsc/src/.rsc_client.c-bak_1180978640.26152_04-Jun-07_19-37

Andrea Forni
