sgpemv2/doc/sgpem2uman.texi

\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename sgpem2uman.info
@settitle SGPEMv2 User Manual
@include vers-uman.texi
@c %**end of header

@dircategory SGPEM v2 - A Process Scheduling Simulator
@direntry
* Users: (sgpem2uman)Top
@end direntry

@c % --------------------------------------------------

@copying 
This is SGPEMv2 User Manual (version @value{VERSION}, 
@value{UPDATED}).

Copyright @copyright{} 2005 University of Padova, dept. of Pure 
and Applied Mathematics

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.  A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end copying

@c % --------------------------------------------------

@titlepage
@title  SGPEMv2 User Manual
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Giovanni Giacobbi (@email{ggiacobb@@studenti.math.unipd.it})
@author Filippo Paparella (@email{ironpipp@@gmail.com})
@author Paolo Santi (@email{psanti@@studenti.math.unipd.it})
@author Matteo Settenvini (@email{matteo@@member.fsf.org})
@author Marco Trevisan (@email{evenjn@@gmail.com})
@author Djina Verbanac (@email{betalgez@@yahoo.com})
@author Luca Vezzaro (@email{lvezzaro@@studenti.math.unipd.it})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
  
@c Output the table of contents at the beginning.
@contents

@c % --------------------------------------------------

@c SGPEMv2 User Manual

@c % --------------------------------------------------

@ifnottex
@node Top, History, (none), (dir)
@top Learn how to operate SGPEMv2
  
@insertcopying
@end ifnottex

@menu

* History::       The history of changes to this document.

* Overview of SGPEM:: Description and objectives of SGPEM v2.

* Installation::  Here we explain how to install SGPEM v2,
		  as well as providing some advice for 
                  believed-to-be useful compilation options.

* Starting with SGPEM:: Insructions on how to use SGPEM. 

* License:: A full copy of the GNU Free Documentation License 
            this manual is licensed into.

* Concept index:: Complete index.
@end menu


@c % --------------------------------------------------

@node       History, Overview of SGPEM, Top, Top
@unnumbered History

@table @strong
@item 2006, March 10th @r{--- Djina Verbanac}
Added chapter Writing new policies
@item 2006, March 9th @r{--- Djina Verbanac}
Add chapters Overview of SGPEM and Starting with SGPEM.
@item 2006, January 26th @r{--- Matteo Settenvini}
Add subsection about how to generate code documentation
via Doxygen.

@item 2005, December 11th @r{--- Matteo Settenvini}
Added full license text.

@item 2005, November 8th @r{--- Matteo Settenvini}
First draft of this document.

@end table


@c % --------------------------------------------------

@node    Overview of  SGPEM, Installation, History, Top
@chapter Overview of  SGPEM


@menu
* Description and aims::
* How to read this manual?::
* Reporting Bugs::
* Features::
@end menu

@c % --------------------------------------------------

@node    Description and aims, How to read this manual?, Overview of SGPEM, Overview of SGPEM
@section Description and aims
@cindex  SGPEM
@cindex  description

SGPEM is an Italian acronym, standing for ``@emph{Simulatore della Gestione dei Processi 
in un Elaboratore Multiprogrammato}'' (in English, ``@emph{Multitasking Computer Process 
Management Simulator}'').
It was initially developed for use inside the ``Operating Systems'' teaching,
part of the Computer Science course of the University of Padova, Italy. 
The aim of SGPEM is to provide an  for simulating policies applied to sort processes, and for assigning resources in a multitasking computer. SGPEMv2 is a didactic software, and it can help students to understand better the functionality of Operating Systems.


@c % --------------------------------------------------

@node    How to read this manual?, Reporting Bugs, Description and aims, Overview of SGPEM
@section How to read this manual?
@cindex  manual

We recommend that you read the manual following the the structure that we imposed for it. 
You will be guided trough the Installation, Configuration and Usage process of SGPEM v2.
If you find yourself in trouble reading the manual, please don't hesitate to contact us at
@email{swe@@thgnet.it}. 

@c % --------------------------------------------------

@node    Reporting Bugs,Features, How to read this manual?, Overview of SGPEM
@section Reporting Bugs
@cindex  bugs
@cindex reporting

We welcome bug reports and suggestions for any aspect of the SGPEM v2 system, program in general,
documentation, installation, anything.Please email us at @email{swe@@thgnet.it}.
For bug reporters, include enough information for us to reproduce the problem. In general:
@itemize
@item
version and number of SGPEM v2.
@item
hardware and operating system name and version.
@item
the content of any file neccesary to reproduce the bug.
@item
description of the problem and any erroneous output.
@item
any unusual option you gave to configure.
@item
anything else you think might be helpful.
@end itemize
If you are ambitious you can try to fix the problem yourself, but we warmly recommend that you read the
Developer Manual first.


@c % --------------------------------------------------


@node    Features, (none), Reporting Bugs, Overview of SGPEM
@section Features
@cindex  features

Main features are:
@itemize
@item
For now you can use only prompt commands to start the simulation and change some parameters.
For more information see @ref{SGPEM Commands}. 
@item
You can use the program from your own shell, or if you prefer you can use the minimal GUI that SGPEM offers, at this moment.
@item
The output of the simulation is textual, and you can see it on the main GUI window or on your Terminal window.
@item
The policy in use if First Come First Served.
@item
You can write your own policies.
For more information see @ref{Writing new policies}.
@end itemize



@c % --------------------------------------------------

@node    Installation, Starting with SGPEM, Overview of SGPEM, Top
@chapter Installation
@cindex  installation

@menu
* Prerequisites:: Programs and libraries needed to 
		  compile and run SGPEM

* Building::      Help for compiling SGPEM on 
		  your platform.

@end menu

@c % --------------------------------------------------

@node    Prerequisites, Building, Installation, Installation
@section Prerequisites
@cindex  requirements

Some software is needed in order to build and install SGPEM on your
personal computer. You will have the need of different pieces of
software installed, whether you are a developer, a user building it
from sources, or just a user that's running the binary a packager
has given to him.

And if you find this section misses something / it lists 
the wrong version of a program, please let us know!

@c % ---- new subsection
@subsection Developers

Other than the tools needed by users building from sources, 
you'll need:

@table @emph
@item GCC with C++ support
as well as the other standard GNU binutils and tools: make, sed, ld... 
GCC version >=3.4 is highly recommended. Please don't report 
compiling-related problems with any previous version.

@item Automake >= 1.9
We use a single @file{Makefile.am} to avoid
recursive make. Older versions of automake didn't play right 
with it. See @url{http://aegis.sourceforge.net/auug97.pdf} for
the motivations that led to this choice.

@item Autoconf, libtool, autopoint @dots{}
The standard autotool family.

@item Subversion >= 1.2
If you need to update the sources from our repository, or commit
your changes, you'll need Subversion built with SSL support.

@item Dejagnu >= 1.4
The testsuite framework we use as a platform for running tests.

@end table

@c % ---- new subsection
@subsection Building from source

Other than the runtime dependencies, you'll need:

@table @emph

@item SWIG >= 1.3.21
SWIG generates the C++ sources needed to build a module that 
Python can use, starting from a simple interface specification.

@end table

@c % ---- new subsection
@subsection Runtime dependencies

To run SGPEMv2, you require:

@table @emph

@item Gtkmm >= 2.8 with Cairo support
The popular C++ jacket for the even-more popular GIMP 
ToolKit. We use Cairo to draw our custom widgets.

@item Python >= 2.3
We use Python to let the user write her own policies
in a simple and complete language.

@end table


@c % --------------------------------------------------

@node    Building, (none), Prerequisites, Installation
@section Building
@cindex  compiling

@noindent To ensure a clean build, follow these steps:

@example 
@code{cd <this directory>}
@code{mkdir =build}
@code{cd =build}
@code{CXXFLAGS="what you want" ../configure --prefix=/usr/local}
@end example
@sp 2

@noindent This will check you have all the needed software installed.

@noindent Choosing good @env{CXXFLAGS} to optimize your build. 
For example, on my machine, I would use: 
@example 
@code{CXXFLAGS="-O3 -pipe -march=pentium4" ../configure --prefix=/usr/local}
@end example
@sp 2

@noindent Being a developer, though, if I had to debug SGPEM, I would type:
@example
@code{CXXFLAGS="-O0 -g -ggdb -pg" ../configure \}
@code{             --prefix=`pwd`/_inst}
@end example
@sp 2

@strong{Warning}: at the moment, we are aware that passing 
@option{--disable-shared} to configure doesn't work. We'll look into it
sooner or later, but in the meantime just build shared libraries.

@noindent Once succesfully configured SGPEMv2, just type:
@example
@command{make}
@end example
@sp 2

@noindent And upon a succesful build, you can install it just by:
@example
@code{su -c "make install"}
@end example
@sp 2

@noindent Root password will be required (of course, if you're 
installing it with a prefix placed inside your home directory, 
you won't need administrative rights, and just ``@samp{make install}'' 
will sufficit).

See the ``@file{INSTALL}'' file in this folder for an overview of other 
(less common) autoconf options.

@subsection Generating API documentation

We added Doxygen support to the project. If you've installed it, 
you can simply run @command{make apidox} from the package 
top source directory. The documentation will be outputted into
the @samp{$@{BUILD_DIR@}/docs/API/} directory.

If you'd like to generate nicier inheritance graphs, you've just to
install @command{dot}, part of the @emph{Graphviz} package.

@c % --------------------------------------------------



@node Starting with SGPEM, License, Installation, Top
@chapter Starting with SGPEM
@cindex starting

@menu

* SGPEM Commands:: Here you'll find a set of commands available 
                        from the command line
* SGPEM Output:: Interpretation of the output 
* Writing new policies:: Steps that must be followed to insert a new policy

@end menu

@c % -------------------------------------------------
@node SGPEM Commands, SGPEM Output, Starting with SGPEM, Starting with SGPEM
@section SGPEM Commands
@cindex commands


@table @strong

@item help @command{<string>}
If <string> is a valid command, it prints the usage instructions for that specific command
@item @command{run}
 Advances the simulation by one or more steps, depending on the actual state and on the value set ed with setmode
@item @command{pause}
 It is useful only when the advancement mode is continue. Calling again run will cause the simulation to start from the current simulation step.
@item @command{stop}
 Stops the simulation.
@item @command{setmode <bool>}
 This methods allows to change the way the simulation progresses. If the input value is 0 (false), the simulation will advance a single time step for each call to run. If the 
 input value is 1 (true), the simulation will advance contiuosly, waiting the time defined with settimer between each step, until all processes terminate, 
 or some error occurs. 
@item @command{getmode}
 Prints the simulation advancement mode: 0 if step-to-step, 1 if continue.
@item @command{settimer <int>}
 This command is used to define how a single time unit is to be interpreted when the simulation advancement mode is continue. 
 The input value is in milliseconds, and it must be in range [0, 10000]. 
@item @command{gettimer}
 Prints the value of the current timer
@item @command{reset}
 Resets the simulation.Erases the state of the simulation, and takes care of removing any residual or temporary data to ensure the simulation has reached 
 a clean and stable state. 
@item @command{jumpto <int>}
 Causes the simulation to jump to a given time unit.
@item @command{getpolicy}
 Prints the current policy.
@item @command{getpolicyattributes}
 Prints the name and the value of the policy's attributes
 
@end table

@c % -------------------------------------------------

@node SGPEM Output, Writing new policies, SGPEM Commands,Starting with SGPEM
@section SGPEM Output
@cindex output

You can see the textual output of the simulation in your console window or on the GUI window provided with SGPEM v2.
The output of RUN gives you one or more rows, each one representing the state of schedulable entities. 
The possible states are: @emph{RUNNING}, @emph{READY}, @emph{BLOCKED}, @emph{FUTURE} or @emph{TERMINATED}.
The row begins with the number of the instant described by the following lists of states:

@itemize
 
@item instant 0 - represents the INITIAL STATE during which no process is running. 
@item instant 1 - the scheduler activity begins. 

@end itemize

Each schedulable entity is represented by its name followed by its priority enclosed between round parenthesis.

@c % ------------------------------------------------

@node Writing new policies, (none), SGPEM Output, Starting with SGPEM
@section Writing new policies
@cindex policies

All policies are implemented in Python, but don't worry (be happy!). You don't have to be a Python expert to write a new policy.
We'll explain you how to write a new policy on an simple example of FCFS policy. Now let's start, all you have to do is change the few bold-ed lines, of the following example.
@sp 1

@example
01 from Policy import Policy
02 class fcfs(Policy) :
03     def __init__(self):
04         pass;
 
05     def configure(self):
@strong{06         print 'No options to configure for fcfs'}
 
07     def is_preemptive(self):
@strong{08         return False}
 
09     def get_time_slice(self):
@strong{10         return -1}
 
11     def sort_queue(self, event, queue):
@strong{12         cmpf = lambda a, b: \
              a.get_schedulable().get_arrival_time() < \
              b.get_schedulable().get_arrival_time()
13         self.sort(queue,cmpf)}
@end example
@sp 2


@itemize
@item body of @code{def configure(self):} line 06 - Configure policy to initial values. 
This is called just before a simulation starts, and is responsible to define 
the parameters the policy wants to expose to the user. For example, it may make 
the return value of is_preemptive configurable, or register an integer value for 
a the time slice duration.
@sp 1
@item body of @code{def is_preemptive(self):} line 08 - It says whether the policy wants to be preemptive, other than by normal time slice termination.

The possible return values are:
 @enumerate 
@item True 
If the policy declares it wants the running process to be released if a process at higher priority is put at the beginning of the ready processes queue 

@item False 
If the policy always waits the end of the time slice (or a process blocking/termination, of course) before selecting a new running process, even if it has greater priority than the current one.
@end enumerate
 
Please note how the word ``priority'' here has a general meaning: it indicates every process than 
can bubble up the sorted ready queue and come before another. So it's up 
to Policy.sort_queue() to give it a precise meaning.

@sp 1
@item body of @code{def get_time_slice(self):} line 10 - Returns how long is a time-slice for this policy. 
A time sliced policy should return a positive integer value, a policy which doesn't use slices should instead 
return -1. You're encouraged to use a user-configurable parameter via Policy.configure() if the policy is 
time-sliced, to ensure greater flexibility.
@sp 1
@item body of 
@code{ def sort_queue(self, event, queue):} 
line 12,13 - Sort ready processes queue. 
This method is called by the scheduler at each step of the simulation to sort the ready processes queue. 

@end itemize



@c % -------------------------------------------------
@c include license text
@node License, Concept index, Starting with SGPEM, Top
@include fdl.texi

@c % --------------------------------------------------

@node   Concept index, (none), License, Top
@unnumbered Index
     
@printindex cp
     
@bye