X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/d55d91ed057b45ff15d00ea7d503132f7d174bac..d4c8c79a8d299472d3a775b7670615fdccb0b7ee:/doc/doxygen/options.doc diff --git a/doc/doxygen/options.doc b/doc/doxygen/options.doc index d8966600b4..9d08d718d9 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 @@ -52,18 +63,118 @@ SimGrid. @code #include -extern xbt_cfg_t _sg_cfg_set; - int main(int argc, char *argv[]) { SD_init(&argc, argv); /* Prefer MSG_config() if you use MSG!! */ - xbt_cfg_set_parse(_sg_cfg_set,"Item:Value"); + xbt_cfg_set_parse("Item:Value"); // Rest of your code } @endcode +\section options_index Index of all existing configuration options + +\note + The full list can be retrieved by passing "--help" and + "--help-cfg" to an executable that uses SimGrid. + +- \c clean-atexit: \ref options_generic_clean_atexit + +- \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/stack-size: \ref options_virt_stacksize +- \c contexts/synchro: \ref options_virt_parallel + +- \c cpu/maxmin-selective-update: \ref options_model_optim +- \c cpu/model: \ref options_model_select +- \c cpu/optim: \ref options_model_optim + +- \c exception/cutpath: \ref options_exception_cutpath + +- \c host/model: \ref options_model_select + +- \c maxmin/precision: \ref options_model_precision +- \c maxmin/concurrency-limit: \ref options_concurrency_limit + +- \c msg/debug-multiple-use: \ref options_msg_debug_multiple_use + +- \c model-check: \ref options_modelchecking +- \c model-check/checkpoint: \ref options_modelchecking_steps +- \c model-check/communications-determinism: \ref options_modelchecking_comm_determinism +- \c model-check/dot-output: \ref options_modelchecking_dot_output +- \c model-check/hash: \ref options_modelchecking_hash +- \c model-check/property: \ref options_modelchecking_liveness +- \c model-check/max-depth: \ref options_modelchecking_max_depth +- \c model-check/record: \ref options_modelchecking_recordreplay +- \c model-check/reduction: \ref options_modelchecking_reduction +- \c model-check/replay: \ref options_modelchecking_recordreplay +- \c model-check/send-determinism: \ref options_modelchecking_comm_determinism +- \c model-check/sparse-checkpoint: \ref options_modelchecking_sparse_checkpoint +- \c model-check/termination: \ref options_modelchecking_termination +- \c model-check/timeout: \ref options_modelchecking_timeout +- \c model-check/visited: \ref options_modelchecking_visited + +- \c network/bandwidth-factor: \ref options_model_network_coefs +- \c network/crosstraffic: \ref options_model_network_crosstraffic +- \c network/latency-factor: \ref options_model_network_coefs +- \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/TCP-gamma: \ref options_model_network_gamma +- \c network/weight-S: \ref options_model_network_coefs + +- \c ns3/TcpModel: \ref options_pls +- \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 + +- \c For collective operations of SMPI, please refer to Section \ref options_index_smpi_coll +- \c smpi/async-small-thresh: \ref options_model_network_asyncsend +- \c smpi/bw-factor: \ref options_model_smpi_bw_factor +- \c smpi/coll-selector: \ref options_model_smpi_collectives +- \c smpi/comp-adjustment-file: \ref options_model_smpi_adj_file +- \c smpi/cpu-threshold: \ref options_smpi_bench +- \c smpi/display-timing: \ref options_smpi_timing +- \c smpi/grow-injected-times: \ref options_model_smpi_test +- \c smpi/host-speed: \ref options_smpi_bench +- \c smpi/IB-penalty-factors: \ref options_model_network_coefs +- \c smpi/iprobe: \ref options_model_smpi_iprobe +- \c smpi/iprobe-cpu-usage: \ref options_model_smpi_iprobe_cpu_usage +- \c smpi/init: \ref options_model_smpi_init +- \c smpi/keep-temps: \ref options_smpi_temps +- \c smpi/lat-factor: \ref options_model_smpi_lat_factor +- \c smpi/ois: \ref options_model_smpi_ois +- \c smpi/or: \ref options_model_smpi_or +- \c smpi/os: \ref options_model_smpi_os +- \c smpi/papi-events: \ref options_smpi_papi_events +- \c smpi/privatization: \ref options_smpi_privatization +- \c smpi/privatize-libs: \ref options_smpi_privatize_libs +- \c smpi/send-is-detached-thresh: \ref options_model_smpi_detached +- \c smpi/shared-malloc: \ref options_model_smpi_shared_malloc +- \c smpi/shared-malloc-hugepage: \ref options_model_smpi_shared_malloc +- \c smpi/simulate-computation: \ref options_smpi_bench +- \c smpi/test: \ref options_model_smpi_test +- \c smpi/wtime: \ref options_model_smpi_wtime + +- \c Tracing configuration options can be found in Section \ref tracing_tracing_options. + +- \c storage/model: \ref options_storage_model +- \c verbose-exit: \ref options_generic_exit + +- \c vm/model: \ref options_vm_model + +\subsection options_index_smpi_coll Index of SMPI collective algorithms options + +TODO: All available collective algorithms will be made available via the ``smpirun --help-coll`` command. + \section options_model Configuring the platform models \anchor options_storage_model @@ -92,8 +203,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. @@ -118,8 +229,8 @@ described in If you compiled SimGrid accordingly, you can use packet-level network simulators as network models (see \ref pls_ns3). In that case, you have -two extra models, described below, and some \ref options_pls "specific -additional configuration flags". +two extra models, described below, and some +\ref options_pls "specific additional configuration flags". - \b NS3: Network pseudo-model using the NS3 tcp model Concerning the CPU, we have only one model for now: @@ -144,24 +255,31 @@ when using SimDag. \subsection options_generic_plugin Plugins -SimGrid supports the use of plugins; currently, no known plugins -can be activated but there are use-cases where you may want to write -your own plugin (for instance, for logging). +SimGrid plugins allow to extend the framework without changing its +source code directly. Read the source code of the existing plugins to +learn how to do so (in ``src/plugins``), and ask your questions to the +usual channels (Stack Overflow, Mailing list, IRC). The basic idea is +that plugins usually register callbacks to some signals of interest. +If they need to store some information about a given object (Link, CPU +or Actor), they do so through the use of a dedicated object extension. -Plugins can for instance define own classes that inherit from -existing classes (for instance, a class "CpuEnergy" inherits from -"Cpu" to assess energy consumption). - -The plugin connects to the code by registering callbacks using -``signal.connect(callback)`` (see file ``src/surf/plugins/energy.cpp`` for -details). +Some of the existing plugins can be activated from the command line, +meaning that you can activate them from the command line without any +modification to your simulation code. For example, you can activate +the host energy plugin by adding the following to your command line: \verbatim - --cfg=plugin:Energy + --cfg=plugin:host_energy \endverbatim -\note - This option is case-sensitive: Energy and energy are not the same! +Here is the full list of plugins that can be activated this way: + + - \b host_energy: keeps track of the energy dissipated by + computations. More details in @ref plugin_energy. + - \b link_energy: keeps track of the energy dissipated by + communications. More details in @ref SURF_plugin_energy. + - \b host_load: keeps track of the computational load. + More details in @ref plugin_load. \subsection options_model_optim Optimization level of the platform models @@ -219,7 +337,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 @@ -275,15 +393,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) @@ -387,13 +496,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. @@ -415,7 +526,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 @@ -564,7 +675,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 @@ -908,53 +1019,43 @@ 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 pass it as an argument to smpirun. + +\subsection options_smpi_privatize_libs smpi/privatize-libs: Automatic privatization of + global variables inside external libraries + +Linux/BSD only: When using dlopen (default) privatization, privatize specific +shared libraries with internal global variables, if they can't be linked statically. +For example libgfortran is usually used for Fortran I/O and indexes in files +can be mixed up. + +\warning + This configuration option can only use either full paths to libraries, or full names. + Check with ldd the name of the library you want to use. + Example: + ldd allpairf90 + libgfortran.so.3 => /usr/lib/x86_64-linux-gnu/libgfortran.so.3 (0x00007fbb4d91b000) + Then you can use --cfg=smpi/privatize-libs:"libgfortran.so.3" or --cfg=smpi/privatize-libs:"/usr/lib/x86_64-linux-gnu/libgfortran.so.3", but not "libgfortran" or "libgfortran.so". + Multiple libraries can be given, semicolon separated. + \subsection options_model_smpi_detached Simulating MPI detached send @@ -1182,15 +1283,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 @@ -1202,7 +1320,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 @@ -1216,104 +1334,4 @@ hence, the output would mismatch, causing the test to fail. It can be done by using XBT. Go to \ref XBT_log for more details. -\section options_index Index of all existing configuration options - -\note - The full list can be retrieved by passing "--help" and - "--help-cfg" to an executable that uses SimGrid. - -- \c clean-atexit: \ref options_generic_clean_atexit - -- \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/stack-size: \ref options_virt_stacksize -- \c contexts/synchro: \ref options_virt_parallel - -- \c cpu/maxmin-selective-update: \ref options_model_optim -- \c cpu/model: \ref options_model_select -- \c cpu/optim: \ref options_model_optim - -- \c exception/cutpath: \ref options_exception_cutpath - -- \c host/model: \ref options_model_select - -- \c maxmin/precision: \ref options_model_precision -- \c maxmin/concurrency-limit: \ref options_concurrency_limit - -- \c msg/debug-multiple-use: \ref options_msg_debug_multiple_use - -- \c model-check: \ref options_modelchecking -- \c model-check/checkpoint: \ref options_modelchecking_steps -- \c model-check/communications-determinism: \ref options_modelchecking_comm_determinism -- \c model-check/dot-output: \ref options_modelchecking_dot_output -- \c model-check/hash: \ref options_modelchecking_hash -- \c model-check/property: \ref options_modelchecking_liveness -- \c model-check/max-depth: \ref options_modelchecking_max_depth -- \c model-check/record: \ref options_modelchecking_recordreplay -- \c model-check/reduction: \ref options_modelchecking_reduction -- \c model-check/replay: \ref options_modelchecking_recordreplay -- \c model-check/send-determinism: \ref options_modelchecking_comm_determinism -- \c model-check/sparse-checkpoint: \ref options_modelchecking_sparse_checkpoint -- \c model-check/termination: \ref options_modelchecking_termination -- \c model-check/timeout: \ref options_modelchecking_timeout -- \c model-check/visited: \ref options_modelchecking_visited - -- \c network/bandwidth-factor: \ref options_model_network_coefs -- \c network/crosstraffic: \ref options_model_network_crosstraffic -- \c network/latency-factor: \ref options_model_network_coefs -- \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 - -- \c ns3/TcpModel: \ref options_pls -- \c path: \ref options_generic_path -- \c plugin: \ref options_generic_plugin - -- \c storage/max_file_descriptors: \ref option_model_storage_maxfd - -- \c surf/precision: \ref options_model_precision - -- \c For collective operations of SMPI, please refer to Section \ref options_index_smpi_coll -- \c smpi/async-small-thresh: \ref options_model_network_asyncsend -- \c smpi/bw-factor: \ref options_model_smpi_bw_factor -- \c smpi/coll-selector: \ref options_model_smpi_collectives -- \c smpi/comp-adjustment-file: \ref options_model_smpi_adj_file -- \c smpi/cpu-threshold: \ref options_smpi_bench -- \c smpi/display-timing: \ref options_smpi_timing -- \c smpi/grow-injected-times: \ref options_model_smpi_test -- \c smpi/host-speed: \ref options_smpi_bench -- \c smpi/IB-penalty-factors: \ref options_model_network_coefs -- \c smpi/iprobe: \ref options_model_smpi_iprobe -- \c smpi/iprobe-cpu-usage: \ref options_model_smpi_iprobe_cpu_usage -- \c smpi/init: \ref options_model_smpi_init -- \c smpi/keep-temps: \ref options_smpi_temps -- \c smpi/lat-factor: \ref options_model_smpi_lat_factor -- \c smpi/ois: \ref options_model_smpi_ois -- \c smpi/or: \ref options_model_smpi_or -- \c smpi/os: \ref options_model_smpi_os -- \c smpi/papi-events: \ref options_smpi_papi_events -- \c smpi/privatization: \ref options_smpi_privatization -- \c smpi/send-is-detached-thresh: \ref options_model_smpi_detached -- \c smpi/shared-malloc: \ref options_model_smpi_shared_malloc -- \c smpi/shared-malloc-hugepage: \ref options_model_smpi_shared_malloc -- \c smpi/simulate-computation: \ref options_smpi_bench -- \c smpi/test: \ref options_model_smpi_test -- \c smpi/wtime: \ref options_model_smpi_wtime - -- \c Tracing configuration options can be found in Section \ref tracing_tracing_options. - -- \c storage/model: \ref options_storage_model -- \c verbose-exit: \ref options_generic_exit - -- \c vm/model: \ref options_vm_model - -\subsection options_index_smpi_coll Index of SMPI collective algorithms options - -TODO: All available collective algorithms will be made available via the ``smpirun --help-coll`` command. - */