X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/befbbbe1fbb31663a8f91e24ce12df271cf4ae79..effadf994078b5f7bbc589d3ac0ba2aae8aaa59f:/doc/doxygen/options.doc diff --git a/doc/doxygen/options.doc b/doc/doxygen/options.doc index 4739cf5def..dff9c9c7ed 100644 --- a/doc/doxygen/options.doc +++ b/doc/doxygen/options.doc @@ -1,5 +1,16 @@ /*! \page options Configure SimGrid +\htmlonly +
+\endhtmlonly +\htmlinclude graphical-toc.svg +\htmlonly +
+ +\endhtmlonly + A number of options can be given at runtime to change the default SimGrid behavior. For a complete list of all configuration options accepted by the SimGrid version used in your simulator, simply pass @@ -42,7 +53,7 @@ file: A last solution is to pass your configuration directly using the C interface. If you happen to use the MSG interface, this is very easy -with the MSG_config() function. If you do not use MSG, that's a bit +with the simgrid::s4u::Engine::setConfig() or MSG_config() functions. If you do not use MSG, that's a bit more complex, as you have to mess with the internal configuration set directly as follows. Check the \ref XBT_config "relevant page" for details on all the functions you can use in this context, \c @@ -73,7 +84,7 @@ int main(int argc, char *argv[]) { - \c contexts/factory: \ref options_virt_factory - \c contexts/guard-size: \ref options_virt_guard_size - \c contexts/nthreads: \ref options_virt_parallel -- \c contexts/parallel_threshold: \ref options_virt_parallel +- \c contexts/parallel-threshold: \ref options_virt_parallel - \c contexts/stack-size: \ref options_virt_stacksize - \c contexts/synchro: \ref options_virt_parallel @@ -112,7 +123,6 @@ int main(int argc, char *argv[]) { - \c network/maxmin-selective-update: \ref options_model_optim - \c network/model: \ref options_model_select - \c network/optim: \ref options_model_optim -- \c network/sender_gap: \ref options_model_network_sendergap - \c network/TCP-gamma: \ref options_model_network_gamma - \c network/weight-S: \ref options_model_network_coefs @@ -120,6 +130,8 @@ int main(int argc, char *argv[]) { - \c path: \ref options_generic_path - \c plugin: \ref options_generic_plugin +- \c simix/breakpoint: \ref options_generic_breakpoint + - \c storage/max_file_descriptors: \ref option_model_storage_maxfd - \c surf/precision: \ref options_model_precision @@ -190,8 +202,8 @@ described in Accuracy Study and Improvement of Network Simulation in the SimGrid Framework. - \b LV08 (default one): Realistic network analytic model - (slow-start modeled by multiplying latency by 10.4, bandwidth by - .92; bottleneck sharing uses a payload of S=8775 for evaluating RTT) + (slow-start modeled by multiplying latency by 13.01, bandwidth by + .97; bottleneck sharing uses a payload of S=20537 for evaluating RTT) - \anchor options_model_select_network_constant \b Constant: Simplistic network model where all communication take a constant time (one second). This model provides the lowest realism, but is (marginally) faster. @@ -317,7 +329,7 @@ setting on regular (less constrained) scenarios so it is off by default. \subsubsection options_model_network_gamma Maximal TCP window size The analytical models need to know the maximal TCP window size to take -the TCP congestion mechanism into account. This is set to 20000 by +the TCP congestion mechanism into account. This is set to 4194304 by default, but can be changed using the \b network/TCP-gamma item. On linux, this value can be retrieved using the following @@ -373,15 +385,6 @@ can be set to 0 (disable this feature) or 1 (enable it). Note that with the default host model this option is activated by default. -\subsubsection options_model_network_sendergap Simulating sender gap - -(this configuration item is experimental and may change or disapear) - -It is possible to specify a timing gap between consecutive emission on -the same network card through the \b network/sender-gap item. This -is still under investigation as of writting, and the default value is -to wait 10 microseconds (1e-5 seconds) between emissions. - \subsubsection options_model_network_asyncsend Simulating asyncronous send (this configuration item is experimental and may change or disapear) @@ -485,13 +488,15 @@ For now, this configuration variable can take 2 values: \subsection options_modelchecking_visited model-check/visited, Cycle detection In order to detect cycles, the model-checker needs to check if a new explored -state is in fact the same state than a previous one. In order to do this, +state is in fact the same state than a previous one. For that, the model-checker can take a snapshot of each visited state: this snapshot is then used to compare it with subsequent states in the exploration graph. -The \b model-check/visited is the maximum number of states which are stored in -memory. If the maximum number of snapshotted state is reached some states will -be removed from the memory and some cycles might be missed. +The \b model-check/visited option is the maximum number of states which are stored in +memory. If the maximum number of snapshotted state is reached, some states will +be removed from the memory and some cycles might be missed. Small +values can lead to incorrect verifications, but large value can +exhaust your memory, so choose carefully. By default, no state is snapshotted and cycles cannot be detected. @@ -513,7 +518,7 @@ liveness violation) as well as the cycle for liveness properties. This dot file can then fed to the graphviz dot tool to generate an corresponding graphical representation. -\subsection options_modelchecking_max_depth model-check/max_depth, Depth limit +\subsection options_modelchecking_max_depth model-check/max-depth, Depth limit The \b model-checker/max-depth can set the maximum depth of the exploration graph of the model-checker. If this limit is reached, a logging message is @@ -662,7 +667,7 @@ the slowest to the most efficient: - \b ucontext: fast factory using System V contexts (Linux and FreeBSD only) - \b boost: This uses the [context implementation](http://www.boost.org/doc/libs/1_59_0/libs/context/doc/html/index.html) of the boost library for a performance that is comparable to our - raw implementation.\nInstall the relevant library (e.g. with the + raw implementation.\n Install the relevant library (e.g. with the libboost-contexts-dev package on Debian/Ubuntu) and recompile SimGrid. Note that our implementation is not compatible with recent implementations of the library, and it will be hard to fix this since @@ -1006,49 +1011,21 @@ of counters, the "default" set. \subsection options_smpi_privatization smpi/privatization: Automatic privatization of global variables -MPI executables are usually meant to be executed in separated processes, but SMPI is -executed in only one process. Global variables from executables will be placed -in the same memory zone and shared between processes, causing intricate bugs. -Several options are possible to avoid this, as described in the main -SMPI publication. -SimGrid provides two ways of automatically privatizing the globals, -and this option allows to choose between them. - - - no (default): Do not automatically privatize variables. - - mmap or yes: Runtime automatic switching of the data segments.\n - SMPI stores a copy of each global data segment for each process, - and at each context switch replaces the actual data with its copy - from the right process. No copy actually occures as this mechanism - uses mmap for efficiency. As such, it is for now limited to - systems supporting this functionnality (all Linux and most BSD).\n - Another limitation is that SMPI only accounts for global variables - defined in the executable. If the processes use external global - variables from dynamic libraries, they won't be switched - correctly. The easiest way to solve this is to statically link - against the library with these globals (but you should never - statically link against the simgrid library itself). - - dlopen: Link multiple times against the binary.\n - SMPI loads several copy of the same binary in memory, resulting in - the natural duplication global variables. Since the dynamic linker - refuses to link the same file several times, the binary is copied - in a temporary file before being dl-loaded (it is erased right - after loading).\n - Note that this feature is somewhat experimental at time of writing - (v3.16) but seems to work.\n - This approach greatly speeds up the context switching, down to - about 40 CPU cycles with our raw contextes, instead of requesting - several syscalls with the \c mmap approach. Another advantage is - that it permits to run the SMPI contexts in parallel, which is - obviously not possible with the \c mmap approach.\n - Further work may be possible to alleviate the memory and disk - overconsumption. It seems that we could - punch holes - in the files before dl-loading them to remove the code and - constants, and mmap these area onto a unique copy. This require - to understand the ELF layout of the file, but would - reduce the disk- and memory- usage to the bare minimum. In - addition, this would reduce the pressure on the CPU caches (in - particular on instruction one). +MPI executables are usually meant to be executed in separated +processes, but SMPI is executed in only one process. Global variables +from executables will be placed in the same memory zone and shared +between processes, causing intricate bugs. Several options are +possible to avoid this, as described in the main +SMPI publication and in +the @ref SMPI_what_globals "SMPI documentation". SimGrid provides two +ways of automatically privatizing the globals, and this option allows +to choose between them. + + - no (default when not using smpirun): Do not automatically privatize variables. + Pass \c -no-privatize to smpirun to disable this feature. + - dlopen or yes (default when using smpirun): Link multiple times against the binary. + - mmap (slower, but maybe somewhat more stable): + Runtime automatic switching of the data segments. \warning This configuration option cannot be set in your platform file. You can only @@ -1280,15 +1257,32 @@ is registered and will clean up some variables and terminate/cleanup the tracing TODO: Add when this should be used. -\subsection options_generic_path XML file inclusion path +\subsection options_generic_path Profile files' search path It is possible to specify a list of directories to search into for the -\ tag in XML files by using the \b path configuration +trace files (see @ref pf_trace) by using the \b path configuration item. To add several directory to the path, set the configuration item several times, as in \verbatim --cfg=path:toto --cfg=path:tutu \endverbatim +\subsection options_generic_breakpoint Set a breakpoint + +\verbatim +--cfg=simix/breakpoint:3.1416 +\endverbatim + +This configuration option sets a breakpoint: when the simulated clock reaches +the given time, a SIGTRAP is raised. This can be used to stop the execution and +get a backtrace with a debugger. + +It is also possible to set the breakpoint from inside the debugger, by writing +in global variable simgrid::simix::breakpoint. For example, with gdb: + +\verbatim +set variable simgrid::simix::breakpoint = 3.1416 +\endverbatim + \subsection options_generic_exit Behavior on Ctrl-C By default, when Ctrl-C is pressed, the status of all existing @@ -1300,7 +1294,7 @@ when \b verbose-exit is set to 0 (it is to 1 by default). \subsection options_exception_cutpath Truncate local path from exception backtrace \verbatim ---cfg=exceptions/cutpath:1 +--cfg=exception/cutpath:1 \endverbatim This configuration option is used to remove the path from the