From 46c4ab0b67793daa9bfe6762c52ff1e006b90925 Mon Sep 17 00:00:00 2001 From: elvez Date: Mon, 11 Sep 2006 23:50:56 +0000 Subject: [PATCH] - Updated section "From the commandline" git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@1099 3ecf2c5c-341e-0410-92b4-d18e462d057c --- doc/sgpem2uman.texi | 170 +++++++++++++++++++++++++++++++++----------- 1 file changed, 129 insertions(+), 41 deletions(-) diff --git a/doc/sgpem2uman.texi b/doc/sgpem2uman.texi index cf2c85d..c8fd4a6 100644 --- a/doc/sgpem2uman.texi +++ b/doc/sgpem2uman.texi @@ -88,7 +88,9 @@ Free Documentation License''. @node History, Overview of SGPEM, Top, Top @unnumbered History -@table @strong +@table @strong +@item 2006, September 12th @r{--- Luca Vezzaro} +Updated section "From the commandline" @item 2006, September 9th @r{--- Luca Vezzaro} Written documentation for section "The Schedulables/Requests tree" and section "The Resources list" @@ -788,11 +790,11 @@ You can interact with this widget in the same way you interact with the list, not a tree, it's much more simpler. So let's get to the hot stuff: when the simulation moves from the boring stopped state -to a running or paused state, below each resource will be displayed the requests queue. -Since a request has no name, the name of the thread owning that request will be displayed, +to a running or paused state, below each resource will be displayed the subrequests queue. +Since a subrequest has no name, the name of the thread owning that subrequest will be displayed, instead.@* As if that wasn't cool enough, the thread name in the queue is colored accordingly with the state of the -request! +subrequest! @c % ------------------------------------------------- @node The Simulation widget, The Holt graph, The Resources list, From the GUI @@ -920,8 +922,6 @@ Otherwise the items are disposed along a circle. @subsection The Preferences dialog @cindex preferences -@strong{TODO:} Spiegare: - The preferences window allow the user to set the simulation speed. The simulation speed is minimum waiting time between a step and an other; since computing the next step of the simulation may require the allocation of many resources, the specified @@ -962,38 +962,98 @@ button of the dialogis pressed. @subsection SGPEM Commands @cindex commands +SGPEMv2 commands are case-insensitive, and use extensively numerical identifiers, which is annoying, but +since there is no restriction to the name of the entities, it is the only way to be sure they're uniquely +identifiable.@* +Use the @command{show} command to obtain the numerical identifiers you need. For most kind of entities, +identifiers should not be influenced by additions, but they may be affected by removals. Also, policies +are dynamically loaded at startup, so it is highly recommended you don't make assumptions on the relation +between policies and their identifiers if the application is run several times.@* + +A list of the commands, with a detailed description follows: @table @strong -@item help @command{} -If is a valid command, it prints the usage instructions for that specific command +@item @command{help } +If is a valid command, it prints the usage instructions for that specific command, otherwise prints the +list of supported commands + @item @command{run} - Advances the simulation by one or more steps, depending on the actual state and on the value set ed with setmode +Starts the simulation. It can be continuous or step-by-step depending on the mode configured +with set continuous (default=true).@* + +The output of run is a snapshot of the state of the simulation at each instant.@* +The instant 0 represents the initial state, during which no process is running. The scheduler activity begins at instant 1. + @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. +Pauses the simulation. The next call to run will continue it. + @item @command{stop} - Stops the simulation. -@item @command{setmode } - 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 } - 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 } - 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 +Stops the simulation. The next call to run will bring the simulation to the first instant and start it. + +@item @command{configure } +Where may be cpu-policy or resource-policy.@* +This is currently the only way to control the behaviour of policies without modifying their source code. + +@item @command{get } +Where may be simulation-tick or continuous. + +@item @command{set [=] } +Where may be simulation-tick, continuous, cpu-policy or resource-policy.@* +@strong{simulation-tick} is the time between steps in a continuous simulation, in milliseconds, @strong{continuous} +is a boolean ("true" or "false") indicating whether the simulation should advance continuosly or step-by-step. +By default it's value is "true". + +@item @command{show} +Displays the name of the entities (if available) and other informations prefixed by its numeric identifier.@* +Syntax depends from entities being displayed: +@itemize + @item @command{show processes | resources | cpu-policies | resource-policies} + @item @command{show threads } + With being the numeric identifier of the parent process + @item @command{show requests } + With being the numeric identifier of the thread child of process identified by + @item @command{show subrequests } + Where the numeric ids follow the same logic of the previous commands +@end itemize + +@item @command{add} +Adds an entity by using a questionary-like approach.@* +Syntax depends from entity being added: +@itemize + @item @command{add process | resource} + @item @command{add thread } + With being the numeric identifier of the parent process + @item @command{add request } + With being the numeric identifier of the thread child of process identified by + @item @command{add subrequest } + Where the numeric ids follow the same logic of the previous commands +@end itemize + +@item @command{remove} +Removes an entity.@* +Syntax depends from entity being removed: +@itemize + @item @command{remove process | resource } + Where is the process or resource identifier + @item @command{remove thread } + With being the identifier of the parent process, and the id of the thread to be removed + @item @command{remove request } + Where the numeric ids follow the same logic of the previous commands + @item @command{remove subrequest } + Where the numeric ids follow the same logic of the previous commands +@end itemize +@item @command{save } +Saves the simulation to file , which may be a path in a format suitable for the operating system used. + +@item @command{load } +Loads a simulation from file , which may be a path in a format suitable for the operating system used. + +@item @command{quit} +Gently closes the program. You may also use the @kbd{C-d} combination to obtain the same effect, but only from +the "main" command prompt, not inside wizards for adding entities or for configuring policies. + @end table @c % ------------------------------------------------- @@ -1002,19 +1062,47 @@ If is a valid command, it prints the usage instructions for that specif @subsection 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: +The output of RUN is pretty complex.@* +Example: +@verbatim +>>>> 4 +READY QUEUE: { Anassimandro ~ } +RESOURCES: + 0. forchetta, with 1 places + queue: { [Anassimene] || Pitagora ~ Pitagora } -@itemize - -@item instant 0 - represents the INITIAL STATE during which no process is running. -@item instant 1 - the scheduler activity begins. +PROCESSES: state arrival requiring elapsed priority resource_id + 1. Pitagorici BLOCKED 0 4 0 0 + 1. Pitagora BLOCKED 0 4 0 0 + 1.1 forchetta UNALLOCABLE 0 4 0 0 + 1.2 forchetta UNALLOCABLE 0 4 0 0 + 2.1 forchetta FUTURE 2 4 0 0 + 2. Scuola di Mileto >> RUNNING << 3 8 1 0 + 1. Anassimene >> RUNNING << 0 6 1 0 + 1.1 forchetta ALLOCATED 0 2 1 0 + 2. Anassimandro READY 0 2 0 0 + 1.1 forchetta FUTURE 0 2 0 0 +@end verbatim -@end itemize +The first number (4, in this example) is the current instant of the simulation. @* +Just below there's the ready queue, containing the threads ready to be executed, it'll be up to the scheduling policy +to decide what to do with them.@* -Each schedulable entity is represented by its name followed by its priority enclosed between round parenthesis. +Then there are resources. The number just before their name is their numerical identifier (the one displayed also by +@command{show}). Each resource has its subrequests queue, where the leftmost element is the first in the queue +(since subrequests have no name, the name of the thread issuing it is used). +Elements in the queue are normally separated by a "~", +while a "||" is used to separate allocable subrequest from unallocable ones (allocables are to the left of the separator, +unallocables to the right).@* + +Finally there are processes, threads and requests. The hieararchy is similar to the one used for the +@ref{The Schedulables/Requests tree, schedulables tree}, except that requests are expanded, and only subrequests are shown. +The number used for processes and threads is simply their numerical identifier, as it is for resources.@* +There are two number separated by a dot for subrequests, the first is the numerical identifier of the request, the second +is the indentifier of the subrequest itself.@* + +For this kind of entities, a tabular format is used, and fields are left blank if the +information is not available for an entity. The name of the columns should be self-explaining.@* @c % ------------------------------------------------