- Updated section "From the commandline"

git-svn-id: svn://svn.gna.org/svn/sgpemv2/trunk@1099 3ecf2c5c-341e-0410-92b4-d18e462d057c

doc/sgpem2uman.texi

@@ -89,6 +89,8 @@ Free Documentation License''.
 @unnumbered History
 
 @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.
+to a running or paused state, below each resource will be displayed the subrequests queue.
-Since a request has no name, the name of the thread owning that request will be displayed, 
+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,37 +962,97 @@ 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{<string>}
+@item @command{help <string>}
-If <string> is a valid command, it prints the usage instructions for that specific command
+If <string> 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.
+Stops the simulation. The next call to run will bring the simulation to the first instant and start it.
-@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 
+@item @command{configure <entity>}
- input value is 1 (true), the simulation will advance contiuosly, waiting the time defined with settimer between each step, until all processes terminate, 
+Where <entity> may be cpu-policy or resource-policy.@*
- or some error occurs. 
+This is currently the only way to control the behaviour of policies without modifying their source code.
-@item @command{getmode}
+
- Prints the simulation advancement mode: 0 if step-to-step, 1 if continue.
+@item @command{get <attr_name>}
-@item @command{settimer <int>}
+Where <attr_name> may be simulation-tick or continuous.
- 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{set <attr_name> [=] <value>}
-@item @command{gettimer}
+Where <attr_name> may be simulation-tick, continuous, cpu-policy or resource-policy.@*
- Prints the value of the current timer
+@strong{simulation-tick} is the time between steps in a continuous simulation, in milliseconds, @strong{continuous} 
-@item @command{reset}
+is a boolean ("true" or "false") indicating whether the simulation should advance continuosly or step-by-step. 
- 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 
+By default it's value is "true".
- a clean and stable state. 
+
-@item @command{jumpto <int>}
+@item @command{show}
- Causes the simulation to jump to a given time unit.
+Displays the name of the entities (if available) and other informations prefixed by its numeric identifier.@*
-@item @command{getpolicy}
+Syntax depends from entities being displayed:
- Prints the current policy.
+@itemize
-@item @command{getpolicyattributes}
+  @item @command{show processes | resources | cpu-policies | resource-policies}
- Prints the name and the value of the policy's attributes
+  @item @command{show threads <process_id>} 
+  With <process_id> being the numeric identifier of the parent process
+  @item @command{show requests <process_id> <thread_id>} 
+  With <thread_id> being the numeric identifier of the thread child of process identified by <process_id>
+  @item @command{show subrequests <process_id> <thread_id> <request_id>} 
+  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 <process_id>} 
+  With <process_id> being the numeric identifier of the parent process
+  @item @command{add request <process_id> <thread_id>} 
+  With <thread_id> being the numeric identifier of the thread child of process identified by <process_id>
+  @item @command{add subrequest <process_id> <thread_id> <request_id>} 
+  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 <id>} 
+  Where <id> is the process or resource identifier
+  @item @command{remove thread <process_id> <thread_id>} 
+  With <process_id> being the identifier of the parent process, and <thread_id> the id of the thread to be removed
+  @item @command{remove request <process_id> <thread_id> <request_id>} 
+  Where the numeric ids follow the same logic of the previous commands
+  @item @command{remove subrequest <process_id> <thread_id> <request_id> <subrequest_id>} 
+  Where the numeric ids follow the same logic of the previous commands
+@end itemize
+ 
+@item @command{save <filename>}
+Saves the simulation to file <filename>, which may be a path in a format suitable for the operating system used.
+
+@item @command{load <filename>}
+Loads a simulation from file <filename>, 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
 
@@ -1002,19 +1062,47 @@ If <string> 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 is pretty complex.@*
-The output of RUN gives you one or more rows, each one representing the state of schedulable entities. 
+Example:
-The possible states are: @emph{RUNNING}, @emph{READY}, @emph{BLOCKED}, @emph{FUTURE} or @emph{TERMINATED}.
+@verbatim                               
-The row begins with the number of the instant described by the following lists of states:
+>>>> 4
+READY QUEUE: { Anassimandro ~ }
+RESOURCES:
+  0. forchetta, with 1 places
+         queue: { [Anassimene] || Pitagora ~ Pitagora }
 
-@itemize
+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
 
-@item instant 0 - represents the INITIAL STATE during which no process is running. 
+The first number (4, in this example) is the current instant of the simulation. @*
-@item instant 1 - the scheduler activity begins. 
+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.@*
 
-@end itemize
+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).@*
 
-Each schedulable entity is represented by its name followed by its priority enclosed between round parenthesis.
+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 % ------------------------------------------------