From: Christian Heinrich Date: Wed, 20 Jan 2016 22:01:51 +0000 (+0100) Subject: [Docs] Fixed doc generation errors. X-Git-Tag: v3_13~1169 X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/029f4e3fda0aaddabf8312586a1a6d73643967fc [Docs] Fixed doc generation errors. --- diff --git a/doc/doxygen/FAQ.doc b/doc/doxygen/FAQ.doc index f70f833be5..2bb4121a7b 100644 --- a/doc/doxygen/FAQ.doc +++ b/doc/doxygen/FAQ.doc @@ -498,7 +498,7 @@ libsimgrid are expressed directly in the dynamic library, so it's quite impossible that you see this message when doing dynamic linking. If you compile your code statically (and if you use a pthread version -of SimGrid), you must absolutely +of SimGrid -- see \ref faq_more_processes), you must absolutely specify -lpthread on the linker command line. As usual, this should come after -lsimgrid on this command line. diff --git a/doc/doxygen/bindings.doc b/doc/doxygen/bindings.doc index c0603e3331..d89e426c76 100644 --- a/doc/doxygen/bindings.doc +++ b/doc/doxygen/bindings.doc @@ -1,8 +1,5 @@ /*! \page bindings Bindings -\section MSG_Ruby Ruby Binding -Check online for our specific [Simgrid-Ruby documentation](http://simgrid.gforge.inria.fr/documentation.html). - \section MSG_Java Java Binding Simgrid-java is a java API that let you use [Simgrid](http://simgrid.gforge.inria.fr/) MSG and SURF API in your favorite language (java). Without it, you would be forced to @@ -237,12 +234,6 @@ sysctl after each reboot. \section bindings_binding_lua Lua Binding -Most of Simgrid modules require a good level in C programming, since simgrid is used to be as standard C library. - Sometime users prefer using some kind of “easy scripts” or a language easier to code with, for their works, - which avoid dealing with C errors, and sometime an important gain of time. -Besides Java Binding, Lua and Ruby bindings are available since version 3.4 of Simgrid -for MSG Module, and we are currenlty working on bindings for other modules. - \subsection bindings_binding_lua_about What is lua ? Lua is a lightweight, reflective, imperative and functional programming language, designed as a scripting language with extensible semantics as a primary goal (see official web site here). @@ -252,234 +243,5 @@ it combines procedural features with powerful data description facilities, by using a simple, yet powerful, mechanism of tables. Lua has a relatively simple C API compared to other scripting languages, and accordingly it provides a robust, easy to use it. -\subsubsection bindings_binding_lua_simgrid How to use lua in Simgrid ? -Actually, the use of lua in Simgrid is quite simple, you have just to follow the same steps as coding with C in Simgird : - - Coding functions coresponding to each process - - loading the platforme/deployment XML file that describe the environment of simulation - - and … Running the Simulation. - -\dontinclude lua/masterslave/master.lua -\subsection bindings_binding_lua_example_master_slave Master/Slave Example - - \li Master Code - \until end_of_master -we mainly use simgrid.Task.new(task_name,computation_size,communication_size) to create our MSG Task, - then simgrid.Task.send(task,alias) to send it. -we use also simgrid.Task.name(task), to get the task's name. - -\dontinclude lua/masterslave/slave.lua -\li Slave Code -\until end_of_slave -Here, we see the use of simgrid.Task.recv(alias) to receive a task with a specific alias, -this function return directly the task recevied. - -\dontinclude lua/masterslave/master_slave.lua -\li Set Environmenet and run application -\until end-of-master-slave - -\subsection bindings_binding_lua_example_data Exchanging Data -You can also exchange data between Process using lua. for that, you have to deal with lua task as a table, -since lua is based itself on a mechanism of tables, -so you can exchange any kind of data (tables, matrix, strings,…) between process via tasks. - -\li Sender process -\verbatim - task = simgrid.Task.new("data_task",task_comp,task_comm); - task['matrix'] = my_matrix; - task['table'] = my_table; - task['message'] = "Hello from (Lua || Simgrid ) !! " - … - simgrid.Task.send(task,alias) -\endverbatim - After creating task, we associate to it various kind of data with a specific key (string in this case) - to distinguish between data variables. The receiver will use this key to access easily to datas. - - -\li Receiver processe -\verbatim - task = simgrid.Task.recv(alias); - sender_matrix = task['matrix']; - sender_table = task['table']; - sender_message = task['message'] - ... -\endverbatim - Note that in lua, both sender and receiver share the same lua task. - So that the receiver could joint data directly on the received task without sending it back. - You can find a complet example (matrix multiplication case) in the file example/lua/mult_matrix.lua. - - -\subsection bindings_binding_lua_example_bypass Bypass XML - maybe you wonder if there is a way to bypass the XML files, - and describe your platform directly from the code, with lua bindings it's Possible !! how ? - We provide some additional (tricky?) functions in lua that allows you to set up your own platform without using the XML files - ( this can be useful for large platforms, so a simple for loop will avoid you to deal with an annoying XML File ;) ) - - -\li set Routing mode -\verbatim - simgrid.AS.new{id="AS0",mode="Full"}; -\endverbatim - -\li set Hosts -\verbatim - simgrid.Host.new{id="Tremblay",power=98095000}; - simgrid.Host.new{id="Jupiter",power=76296000}; - simgrid.Host.new{id="Fafard",power=76296000}; - simgrid.Host.new{id="Ginette",power=48492000}; - simgrid.Host.new{id="Bourassa",power=48492000}; -\endverbatim - we use simgrid.Host.new{id=id_host,power=power_host} to instanciate our hosts. - -\li set Links -\verbatim - for i=0,11 do - simgrid.Link.new{id=i,bandwidth=252750+ i*768,latency=0.000270544+i*0.087}; -- some crazy values ;) - end -\endverbatim - we used simgrid.Link.new{id=link_id,bandwidth=bw,latency=lat} with a simple for loop to create all links we need (much easier than XML hein ?) - -\li set Routes -\verbatim --- simgrid.Route.new(src_id,des_id,links_nb,links_list) - simgrid.Route.new("Tremblay","Jupiter",1,{"1"}); - simgrid.Route.new("Tremblay","Fafard",6,{"0","1","2","3","4","8"}); - simgrid.Route.new("Tremblay","Ginette",3,{"3","4","5"}); - simgrid.Route.new("Tremblay","Bourassa",7,{"0","1","3","2","4","6","7"}); - - simgrid.Route.new("Jupiter","Tremblay",1,{"1"}); - simgrid.Route.new("Jupiter","Fafard",7,{"0","1","2","3","4","8","9"}); - simgrid.Route.new("Jupiter","Ginette",4,{"3","4","5","9"}); - simgrid.Route.new("Jupiter","Bourassa",8,{"0","1","2","3","4","6","7","9"}); - ... -\endverbatim - for each host you have to specify which route to choose to access to the rest of hosts connected in the grid. - -\li Save platform -\verbatim - simgrid.register_platform(); -\endverbatim -Don't forget to register your platform, that SURF callbacks starts their work ;) - -\li set application -\verbatim - simgrid.Host.setFunction("Tremblay","Master",4,{"20","550000000","1000000","4"}); - simgrid.Host.setFunction("Bourassa","Slave",1,{"0"}); - simgrid.Host.setFunction("Jupiter","Slave",1,{"1"}); - simgrid.Host.setFunction("Fafard","Slave",1,{"2"}); - simgrid.Host.setFunction("Ginette","Slave",1,{"3"}); -\endverbatim - you don't need to use a deployment XML file, thanks to simgrid.Host.setFunction(host_id,function,args_number,args_list) - you can associate functions for each host with arguments if needed . - -\li -\verbatim - simgrid.register_application(); -\endverbatim -Yes, Here too you have to register your application before running the simulation. - -the full example is distributed in the file examples/lua/master_slave_bypass.lua - -\subsection MSG_ex_master_slave_lua Master/slave Lua application - -Simulation of a master-slave application using lua bindings -- \ref MSG_ext_ms_master_lua -- \ref MSG_ext_ms_slave_lua -- \ref MSG_ext_ms_core_lua -- \ref MSG_ext_ms_helping -- \ref MSG_ext_ms_application -- \ref MSG_ext_ms_platform - - - -\subsubsection MSG_ext_ms_master_lua Master code - -as described in the C native master/Slave example, this function has to be assigned to a msg_process_t that will behave as the master. - -Lua style arguments (...) in for the master are interpreted as: -- the number of tasks to distribute -- the computation size of each task -- the size of the files associated to each task -- a list of host that will accept those tasks. - -Tasks are dumbly sent in a round-robin style. -\dontinclude lua/masterslave/master.lua -\skip Dispatch the tasks -\until Done sending -\until end - - -\subsubsection MSG_ext_ms_slave_lua Slave code - -This function has to be assigned to a #msg_process_t that has to behave as a slave. -This function keeps waiting for tasks and executes them as it receives them. -\dontinclude lua/masterslave/slave.lua -\until end_of_slave -\subsubsection MSG_ext_ms_core_lua Simulation core - -in this section the core of the simulation which start by including the simgrid lib for bindings -: require "simgrid" - --# Simulation settings : simgrid.platform creates a realistic - environment --# Application deployment : create the processes on the right locations with - simgrid.application --# The simulation is run with simgrid.run - -Its arguments are: -- platform_file: the name of a file containing an valid surfxml platform description.( first command line argument) -- application_file: the name of a file containing a valid surfxml application description ( second commande line argument ) -\dontinclude lua/masterslave/master_slave.lua -\skip platform -\until run - - -\subsection MSG_ex_master_slave_lua_bypass Master/slave Bypass Lua application - -Simulation of a master-slave application using lua bindings, Bypassing the XML parser -- \ref MSG_ext_ms_bp_master_lua -- \ref MSG_ext_ms_bp_slave_lua -- \ref MSG_ext_ms_bp_core_lua - - - -\subsubsection MSG_ext_ms_bp_master_lua Master code - -as described in the C native master/Slave example, this function has to be assigned to a msg_process_t that will behave as the master. - -Lua style arguments (...) in for the master are interpreted as: -- the number of tasks to distribute -- the computation size of each task -- the size of the files associated to each task -- a list of host that will accept those tasks. - -Tasks are dumbly sent in a round-robin style. - -\dontinclude lua/console/master.lua -\until end_of_master - -\subsubsection MSG_ext_ms_bp_slave_lua Slave code - -This function has to be assigned to a #msg_process_t that has to behave as a slave. -This function keeps waiting for tasks and executes them as it receives them. - -\dontinclude lua/console/slave.lua -\until end_of_slave - -\subsubsection MSG_ext_ms_bp_core_lua Simulation core - -in this section the core of the simulation which start by including the simgrid lib for bindings, then create the resources we need to set up our environment bypassing the XML parser. -: require "simgrid" - --# Hosts : simgrid.Host.new instanciate a new host with an id, and power. --# Links : simgrid.Link.new instanictae a new link that will require an id, bandwith and latency values. --# Route : simgrid.Route.new define a route between two hosts specifying the links to use. --# Simulation settings : simgrid.register_platform(); register own platform without using the XML SURF parser. - -we can also bypass the XML deployment file, and associate functions for each of defined hosts. -- simgrid.Host.setFunction: associate a function to a host, specifying arguments if needed. -- simgrid.register_application(): saving the deployment settings before running the simualtion. - -\include lua/console/master_slave_bypass.lua - */ diff --git a/doc/doxygen/module-msg.doc b/doc/doxygen/module-msg.doc index b27ec73ce4..f05e35ff04 100644 --- a/doc/doxygen/module-msg.doc +++ b/doc/doxygen/module-msg.doc @@ -7,8 +7,7 @@ simplification of the reality of distributed systems. It can be used to build rather realistic simulations, but remains simple to use: most unpleasant technical elements can be abstracted away rather easily. If you want to use the C programming language, your are in the right section. If you prefer not to use -this venerable but demanding language, please refer to the @ref MSG_Java, the -@ref MSG_LUA, or the @ref MSG_Ruby (that are distributed separately). +this venerable but demanding language, please refer to the @ref MSG_Java section. If you think that MSG may not be the interface you need, please consider the other user interfaces provided by SimGrid: If you want to use DAGs, have a look @@ -157,43 +156,6 @@ Check the examples in examples/msg/actions/actions.c for details. */ - -/** -@defgroup MSG_LUA Lua bindings -@ingroup MSG_API -@brief Lua bindings to MSG (\ref MSG_API) - -@htmlonly @endhtmlonly - -This is the lua bindings of the \ref MSG_API interface. - -\section lMSG_who Who should use this (and who shouldn't) - -If you want to use MSG to study your algorithm, but you don't want to use the C -language (using \ref MSG_API), then you should use some bindings such as this -one. Just like the \ref MSG_Java, the advantage of the lua bindings is that they -are distributed directly with the main archive (in contrary to Ruby bindings, -that are distributed separately). Another advantage of lua is that there is -almost no performance loss with regard to the C version (at least there -shouldn't be any -- it is still to be precisely assessed). - -\section MSG_Lua_funct Lua offered functionnalities in MSG - -Almost all important features of the MSG interface are available from -the lua bindings. Unfortunately, since doxygen does not support the -lua modules implemented directly in C as we are using, there is no -ready to use reference documentation for this module. Even more than -for the other modules, you will have to dig into the source code of -the examples to learn how to use it. - -\section Lua_examples Examples of lua MSG - - - \ref MSG_ex_master_slave_lua - - \ref MSG_ex_master_slave_lua_bypass - - Also, the lua version of the Chord example (in the source tree) - is a working non-trivial example of use of the lua bindings -*/ - /** @defgroup MSG_examples MSG examples @ingroup MSG_API diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc index f779c600bd..1d4a719b3b 100644 --- a/doc/doxygen/platform.doc +++ b/doc/doxygen/platform.doc @@ -9,14 +9,14 @@ process: Which process should be deployed to which processor/core? For the last two items, there are essentially two possible ways you can provide this information as an input: -\li You can program it, either by using the Lua console ( - \ref MSG_Lua_funct) or, if you're using MSG, some of MSG's platform and +\li You can program, if you're using MSG, some of MSG's platform and deployment functions (\ref msg_simulation). If you want to use this, check the particular documentation. (You can also check the section \ref pf_flexml_bypassing, however, this documentation is deprecated; there is a new, but undocumented, way to do it properly). \li You can use two XML files: one contains the platform description while - the other contains the deployment instructions. + the other contains the deployment instructions. The platform description + can also be in Lua format. For more information on SimGrid's deployment features, please refer to the \ref deployment documentation. @@ -344,7 +344,7 @@ state_file | no | string | Allows you to use a file as input for sta loopback_bw | no | int | Bandwidth for loopback (if any). See link section for syntax/details. If loopback_bw and loopback_lat (see below) attributes are omitted, no loopback link is created and all intra-node communication will use the main network link of the node. Loopback link is a \ref pf_sharing_policy_fatpipe "\b FATPIPE". loopback_lat | no | int | Latency for loopback (if any). See link section for syntax/details. See loopback_bw for more info. topology | no | FLAT\|TORUS\|FAT_TREE (default: FLAT) | Network topology to use. SimGrid currently supports FLAT (with or without backbone, as described before), TORUS and FAT_TREE attributes for this tag. -topo_parameters | no | string | Specific parameters to pass for the topology defined in the topology tag. For torus networks, comma-separated list of the number of nodes in each dimension of the torus. For fat trees, refer to \ref AsClusterFatTree "AsClusterFatTree documentation". +topo_parameters | no | string | Specific parameters to pass for the topology defined in the topology tag. For torus networks, comma-separated list of the number of nodes in each dimension of the torus. For fat trees, refer to \ref simgrid::surf::AsClusterFatTree "AsClusterFatTree documentation". TODO diff --git a/src/msg/msg_vm.cpp b/src/msg/msg_vm.cpp index a78290c25f..cbfb739ae8 100644 --- a/src/msg/msg_vm.cpp +++ b/src/msg/msg_vm.cpp @@ -164,6 +164,9 @@ int MSG_vm_is_restoring(msg_vm_t vm) /** @brief Create a new VM with specified parameters. * @ingroup msg_VMs* * @param pm Physical machine that will host the VM + * @param name [TODO] + * @param ncpus [TODO] + * @param ramsize [TODO] * @param net_cap Maximal bandwidth that the VM can consume (in MByte/s) * @param disk_path (unused) Path to the image that boots * @param disksize (unused) will represent the size of the VM (will be used during migrations) diff --git a/src/simix/RawContext.cpp b/src/simix/RawContext.cpp index 31a950fc7a..98c07e84d9 100644 --- a/src/simix/RawContext.cpp +++ b/src/simix/RawContext.cpp @@ -4,7 +4,7 @@ /* This program is free software; you can redistribute it and/or modify it * under the terms of the license (GNU LGPL) which comes with this package. */ -/** \file Rawcontext.cpp +/** \file RawContext.cpp * Fast context switching inspired from SystemV ucontexts. * * In contrast to System V context, it does not touch the signal mask diff --git a/src/surf/cpu_interface.hpp b/src/surf/cpu_interface.hpp index 4ba92de8bc..699237c05e 100644 --- a/src/surf/cpu_interface.hpp +++ b/src/surf/cpu_interface.hpp @@ -42,13 +42,13 @@ public: /** * @brief Create a Cpu * - * @param name The name of the Cpu + * @param host The host that will have this CPU * @param speedPeak The peak spead (max speed in Flops) * @param pstate [TODO] * @param speedScale The speed scale (in [O;1] available speed from peak) * @param speedTrace Trace variations * @param core The number of core of this Cpu - * @param state_initial [TODO] + * @param initiallyOn [TODO] * @param state_trace [TODO] */ virtual Cpu *createCpu(simgrid::s4u::Host *host, xbt_dynar_t speedPeak, @@ -78,10 +78,12 @@ public: * @param model The CpuModel associated to this Cpu * @param host The host in which this Cpu should be plugged * @param constraint The lmm constraint associated to this Cpu if it is part of a LMM component + * @param speedPeakList [TODO] + * @param pstate [TODO] * @param core The number of core of this Cpu * @param speedPeak The speed peak of this Cpu in flops (max speed) * @param speedScale The speed scale of this Cpu in [0;1] (available amount) - * @param stateInitial whether it is created running or crashed + * @param initiallyOn whether it is created running or crashed */ Cpu(simgrid::surf::Model *model, simgrid::s4u::Host *host, lmm_constraint_t constraint, @@ -94,10 +96,12 @@ public: * * @param model The CpuModel associated to this Cpu * @param host The host in which this Cpu should be plugged + * @param speedPeakList [TODO] + * @param pstate * @param core The number of core of this Cpu * @param speedPeak The speed peak of this Cpu in flops (max speed) * @param speedScale The speed scale of this Cpu in [0;1] (available amount) - * @param stateInitial whether it is created running or crashed + * @param initiallyOn whether it is created running or crashed */ Cpu(simgrid::surf::Model *model, simgrid::s4u::Host *host, xbt_dynar_t speedPeakList, int pstate, diff --git a/src/surf/network_interface.hpp b/src/surf/network_interface.hpp index 93442c15bb..5b9f960a37 100644 --- a/src/surf/network_interface.hpp +++ b/src/surf/network_interface.hpp @@ -84,7 +84,7 @@ public: * @param bw_trace The trace associated to the Link bandwidth * @param lat_initial The initial latency of the Link in seconds * @param lat_trace The trace associated to the Link latency - * @param state_initial The initial Link (state)[e_surf_resource_state_t] + * @param initiallyOn The initial Link (state)[e_surf_resource_state_t] * @param state_trace The trace associated to the Link (state)[e_surf_resource_state_t] * @param policy The sharing policy of the Link * @param properties Dictionary of properties associated to this Resource diff --git a/src/surf/plugins/energy.cpp b/src/surf/plugins/energy.cpp index 5823df6d5a..133f5017e1 100644 --- a/src/surf/plugins/energy.cpp +++ b/src/surf/plugins/energy.cpp @@ -46,9 +46,9 @@ It starts at pstate 0 (ie, at 100 Mflop/s). In this case, you have to specify on In this example, the idle consumption is 95 Watts, 93 Watts and 90 Watts in each pstate while the CPU burn consumption are at 200 Watts, 170 Watts and 150 Watts respectively. -To change the pstate of a given CPU, use the following functions: #MSG_host_get_nb_pstates(), #MSG_host_set_pstate(), #MSG_host_get_power_peak_at(). +To change the pstate of a given CPU, use the following functions: #MSG_host_get_nb_pstates(), simgrid#s4u#Host#set_pstate(), #MSG_host_get_power_peak_at(). -To simulate the energy-related elements, first call the #sg_energy_plugin_init() before your #MSG_init(), +To simulate the energy-related elements, first call the simgrid#energy#sg_energy_plugin_init() before your #MSG_init(), and then use the following function to retrieve the consumption of a given host: #MSG_host_get_consumed_energy(). */ diff --git a/src/surf/surf_routing_cluster_fat_tree.hpp b/src/surf/surf_routing_cluster_fat_tree.hpp index 9b5d8873a8..af8e8ad691 100644 --- a/src/surf/surf_routing_cluster_fat_tree.hpp +++ b/src/surf/surf_routing_cluster_fat_tree.hpp @@ -91,7 +91,10 @@ public: }; -/** \brief Fat tree representation and routing. +/** + * \class AsClusterFatTree + * + * \brief Fat tree representation and routing. * * Generate fat trees according to the topology asked for. Almost everything * is based on the work of Eitan Zahavi in "D-Mod-K Routing Providing diff --git a/src/surf/virtual_machine.hpp b/src/surf/virtual_machine.hpp index 30e4938bbb..26f37117a1 100644 --- a/src/surf/virtual_machine.hpp +++ b/src/surf/virtual_machine.hpp @@ -59,8 +59,7 @@ public: * @param model VMModel associated to this VM * @param name The name of the VM * @param props Dictionary of properties associated to this VM - * @param netElm The RoutingEdge associated to this VM - * @param cpu The Cpu associated to this VM + * @param host The host */ VirtualMachine(simgrid::surf::HostModel *model, const char *name, xbt_dict_t props, simgrid::s4u::Host *host);