     [file vers-uman.texi not included]

Learn how to operate SGPEMv2
****************************

This is SGPEMv2 User Manual (version VERSION, UPDATED).

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''.

History
*******

2006, March 10th --- Djina Verbanac
     Added chapter Writing new policies

2006, March 9th --- Djina Verbanac
     Add chapters Overview of SGPEM and Starting with SGPEM.

2006, January 26th --- Matteo Settenvini
     Add subsection about how to generate code documentation via Doxygen.

2005, December 11th --- Matteo Settenvini
     Added full license text.

2005, November 8th --- Matteo Settenvini
     First draft of this document.

Overview of SGPEM
*****************

Description and aims
====================

SGPEM is an Italian acronym, standing for ``Simulatore della Gestione dei Processi in un Elaboratore Multiprogrammato'' (in English, ``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.

How to read this 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 swe@thgnet.it.

Reporting Bugs
==============

We welcome bug reports and suggestions for any aspect of the SGPEM v2 system, program in general, documentation, installation, anything.Please email us at swe@thgnet.it. For bug reporters, include enough information for us to reproduce the problem. In general:

  * version and number of SGPEM v2.

  * hardware and operating system name and version.

  * the content of any file neccesary to reproduce the bug.

  * description of the problem and any erroneous output.

  * any unusual option you gave to configure.

  * anything else you think might be helpful.

If you are ambitious you can try to fix the problem yourself, but we warmly recommend that you read the Developer Manual first.

Features
========

Main features are:

  * For now you can use only prompt commands to start the simulation and change some parameters. For more information see SGPEM Commands.

  * 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.

  * The output of the simulation is textual, and you can see it on the main GUI window or on your Terminal window.

  * The policy in use if First Come First Served.

  * You can write your own policies. For more information see Writing new policies.

Installation
************

Prerequisites
=============

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!

Developers
----------

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

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.

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

Autoconf, libtool, autopoint ...
     The standard autotool family.

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.

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

Building from source
--------------------

Other than the runtime dependencies, you'll need:

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

Runtime dependencies
--------------------

To run SGPEMv2, you require:

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.

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

Building
========

To ensure a clean build, follow these steps:

     cd <this directory>
     mkdir =build
     cd =build
     CXXFLAGS="what you want" ../configure --prefix=/usr/local

This will check you have all the needed software installed.

Choosing good CXXFLAGS to optimize your build. For example, on my machine, I would use:

     CXXFLAGS="-O3 -pipe -march=pentium4" ../configure --prefix=/usr/local

Being a developer, though, if I had to debug SGPEM, I would type:

     CXXFLAGS="-O0 -g -ggdb -pg" ../configure \
                  --prefix=`pwd`/_inst

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

Once succesfully configured SGPEMv2, just type:

     make

And upon a succesful build, you can install it just by:

     su -c "make install"

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 ``make install'' will sufficit).

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

Generating API documentation
----------------------------

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

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

Starting with SGPEM
*******************

SGPEM Commands
==============

help <string>
     If <string> is a valid command, it prints the usage instructions for that specific command

run
     Advances the simulation by one or more steps, depending on the actual state and on the value set ed with setmode

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.

stop
     Stops the simulation.

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.

getmode
     Prints the simulation advancement mode: 0 if step-to-step, 1 if continue.

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].

gettimer
     Prints the value of the current timer

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.

jumpto <int>
     Causes the simulation to jump to a given time unit.

getpolicy
     Prints the current policy.

getpolicyattributes
     Prints the name and the value of the policy's attributes

SGPEM 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: RUNNING, READY, BLOCKED, FUTURE or TERMINATED. The row begins with the number of the instant described by the following lists of states:

  * instant 0 - represents the INITIAL STATE during which no process is running.

  * instant 1 - the scheduler activity begins.

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

Writing new 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.

     01 from Policy import Policy
     02 class fcfs(Policy) :
     03     def __init__(self):
     04         pass;

     05     def configure(self):
     06         print 'No options to configure for fcfs'

     07     def is_preemptive(self):
     08         return False

     09     def get_time_slice(self):
     10         return -1

     11     def sort_queue(self, event, queue):
     12         cmpf = lambda a, b: \
                   a.get_schedulable().get_arrival_time() < \
                   b.get_schedulable().get_arrival_time()
     13         self.sort(queue,cmpf)

  * body of 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.

  * body of 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:

      1. 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

      2. 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.

     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.

  * body of 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.

  * body of 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.

     [file fdl.texi not included]