446 lines
14 KiB
Plaintext
446 lines
14 KiB
Plaintext
\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 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.
|
|
|
|
SGPEMv2 is a didactic software, so the main product users are professors and students interested in the simulation of processes.
|
|
|
|
|
|
@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 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 sett 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 seg the textual output of the simulation in your console window or on the GUI window provided with SGPEM v2.
|
|
The output of RUN is one or more rows each of which represents the state of the schedulable entities.
|
|
It can be RUNNING, READY, BLOCKED, FUTURE or TERMINATED.
|
|
The row begins with the number of the instant described by the following lists of states.
|
|
The instant 0 represents the INITIAL STATE during which no process is running.
|
|
The scheduler activity begins at instant 1. 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
|
|
|
|
|
|
@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
|
|
|