doc/doxygen/inside_extending.doc

   1 /*!
   2 \page inside_extending Extending SimGrid
   3
   4 \tableofcontents
   5
   6 \section simgrid_dev_guide_model How to add a new model in surf?
   7 The figure below shows the architecture of the SURF layer. This layer is composed
   8 of different kinds of models representing the different systems we want to
   9 model (i.e., cpu, network, storage, workstation, virtual machine).
  10
  11 A model in simgrid is composed of three classes: Model, Resource and Action
  12 (\ref SURF_interface "surf_interface.hpp").
  13
  14 \image html surf++.png
  15 \image latex surf++.pdf "surf++" width=\textwidth
  16
  17 Actually there are five kind of models: CpuModel, NetworkModel, WorkstationModel,
  18 WorkstationVMModel and StorageModel. For each kind of model, there is an
  19 interface (e.g.: \ref SURF_cpu_interface "cpu_interface.hpp") and some implementations (e.g.: cpu_cas01.hpp,
  20 cpu_ti.hpp).
  21
  22 The CPU model Cas01, for instance, is initialized by the function
  23     void surf_cpu_model_init_Cas01()
  24
  25 The different network models that are offered by simgrid are stored in the array
  26 that is defined as follows:
  27
  28 s_surf_model_description_t surf_network_model_description[] = {
  29
  30 \subsection simgrid_dev_guide_model_implem How to add a new model implementation in surf?
  31
  32 If you want to create a new implementation of a kind of model you must extend
  33 the classes of the corresponding interfaces.
  34
  35 For instance, if you want to add a new cup model called `Plop`, create two files
  36 cpu_plop.hpp and cpu_plop_cpp which contains classes CpuPlopModel, CpuPlop and
  37 CpuPlopAction implementating respectively the interfaces CpuModel, Cpu and
  38 CpuAction. You also need to define a initializing function like this:
  39
  40 ~~~~
  41 void surf_cpu_model_init_plop()
  42 {
  43   xbt_assert(!surf_cpu_model_pm);
  44
  45   surf_cpu_model_pm = new CpuPlopModel();
  46
  47   sg_platf_host_add_cb(cpu_parse_init);
  48   sg_platf_postparse_add_cb(cpu_add_traces);
  49
  50   xbt_dynar_push(model_list, &surf_cpu_model_pm);
  51 }
  52 ~~~~
  53
  54 and add an entry in the corresponding array in surf_interface.cpp
  55
  56 ~~~~
  57 s_surf_model_description_t surf_cpu_model_description[] = {
  58   {"Cas01",
  59    "Simplistic CPU model (time=size/power).",
  60    surf_cpu_model_init_Cas01},
  61   {"Plop",
  62    "The new plop CPU model.",
  63    surf_cpu_model_init_plop},
  64   {NULL, NULL, NULL}      // this array must be NULL terminated
  65 };
  66 ~~~~
  67
  68 \subsection simgrid_dev_guide_model_kind How to add a new kind of model in surf?
  69
  70 If you want to create a new kind of model, you must create a new interface
  71 where you extend the classes Model, Resource and Action, and then create an
  72 implementation of this interface.
  73
  74
  75 \section simgrid_dev_guide_surf_callbacks How to use surf callbacks?
  76
  77 Adding features to surf could also be handle by using surf callbacks (instead
  78 of adding new implementation model). The list of available callbacks is
  79 accessible there \ref SURF_callbacks. An example of using surf callbacks is the
  80 energy plugin. If you want to add a plugin you need to define callback function
  81 and to connect them to callbacks handler in an initialization function.
  82
  83 ~~~~
  84 static void MyNetworkLinkCreatedCallback(NetworkLinkPtr cpu){
  85   // your code
  86 }
  87
  88 static void MyNetworkLinkDestructedCallback(NetworkLinkPtr cpu){
  89   // your code
  90 }
  91
  92 static void MyNetworkCommunicationCallback(NetworkActionPtr cpu,
  93                                            RoutingEdgePtr src,
  94                                            RoutingEdgePtr dst){
  95   // your code
  96 }
  97
  98 void sg_my_network_plugin_init() {
  99   surf_callback_connect(networkLinkCreatedCallbacks,
 100                         MyNetworkLinkCreatedCallback);
 101   surf_callback_connect(networkLinkDestructedCallbacks,
 102                         MyNetworkLinkDestructedCallback);
 103   surf_callback_connect(networkCommunicationCallbacks,
 104                         MyNetworkCommunicationCallback);
 105 }
 106 ~~~~
 107
 108 Then you need to add an entry in surf_interface.cpp refering to your
 109 initialization function.
 110
 111 ~~~~
 112 s_surf_model_description_t surf_plugin_description[] = {
 113                   {"Energy",
 114                    "Cpu energy consumption.",
 115                    sg_energy_plugin_init},
 116                   {"MyNetworkPlugin",
 117                    "My network plugin.",
 118                    sg_my_network_plugin_init},
 119                   {NULL, NULL, NULL}      // this array must be NULL terminated
 120 };
 121 ~~~~
 122
 123 \section simgrid_dev_guide_simcall How to add a new simcall?
 124
 125 A simcall is used to go from user mode to kernel mode. There is some
 126 sort of popping dance involved, as we want to isolate the user
 127 contextes from their environment (so that they can run in parallel).
 128
 129 The workflow of a simcall is the following:
 130
 131 - `<ret> simcall_<name>(<args>)`
 132  - `simcall_BODY_<name>(<args>)`
 133   - Initializes the simcall (store the arguments in position)
 134   - If maestro, executes the simcall directly (and return)
 135   - If not, call `SIMIX_process_yield` to give back the control to maestro
 136   - ========== KERNEL MODE ==========
 137   - `SIMIX_simcall_handle` large switch (on simcall) doing for each:
 138    - `simcall_HANDLER_<name>(simcall, <args>)` (the manual code handling the simcall)
 139    - If the simcall is not marked as "blocking" in its definition,
 140      call `SIMIX_simcall_answer(simcall)` that adds back the issuer
 141      process to the list of processes to run in the next scheduling round.
 142      It is thus the responsability of the blocking simcalls to call
 143      `SIMIX_simcall_answer(simcall)` themselves in their handler.
 144
 145 Note that empty HANDLERs can be omitted. These functions usually do
 146 some parameter checking, or retrieve some information about the
 147 simcall issuer, but when there no need for such things, the handler
 148 can be omited. In that case, we directly call the function
 149 `simcall_<name>(<args>)`.
 150
 151 To simplify the simcall creation, a python script generates most of
 152 the code and give helpers for the remaining stuff. That script reads
 153 the simcall definitions from src/simix/simcalls.in, checks that both
 154 `simcall_<name>()` and `simcall_HANDLER()` are defined somewhere, and
 155 generates the following files:
 156
 157 - smx_popping_accessors.h:
 158   Helper functions to get and set simcall arguments and results
 159 - smx_popping_bodies.c:
 160   The BODY function of each simcall
 161 - smx_popping_enum.c:
 162   Definition of type `enum e_smx_simcall_t` (one value per existing simcall)
 163 - smx_popping_generated.c:
 164   Definitions of `simcall_names[]` (debug name of each simcall), and
 165   SIMIX_simcall_enter() that deals with the simcall from within the kernel
 166
 167 The simcall.in file list all the simcalls in sections. A line starting by "##"
 168 define a new section which will be replace by a "ifdef" in the generated code.
 169 There is a simcall by line which follow this format:
 170
 171 ~~~~
 172 Simcall -> Name HasAnswer Res Args
 173 Name -> [a-z0-9_]+
 174 Has_Answer -> "True" | "False"
 175 Res -> "(" Type MaybeCast ")"
 176 Args -> Args Arg | Arg
 177 Arg -> "(" Name "," Type MaybeCast ")"
 178 Type -> "char" | "const char*" | "int" | "long" | "unsigned char" | "unsigned short" | "unsigned int" | "unsigned long" | "float" | "double" | "void*" | "FPtr" | "const void*" | "size_t" | "sg_size_t" | "void" | "void*"
 179 MaybeCast -> "," Cast | ""
 180 Cast -> [a-z0-9_* ]+
 181 ~~~~
 182
 183 \section simgrid_dev_guide_tag What is How to add a new tag for xml files?
 184 Search for expression \"TUTORIAL: New TAG\".
 185 \verbatim
 186 user@caraja:~/workspace/simgrid/src$ cg "TUTORIAL: New TAG"
 187 0 surf/sg_platf.c                    43 /* TUTORIAL: New TAG*/
 188 1 surf/sg_platf.c                    89 /* TUTORIAL: New TAG*/
 189 2 surf/sg_platf.c                   124 /* TUTORIAL: New TAG*/
 190 3 surf/sg_platf.c                   337 /* TUTORIAL: New TAG*/
 191 4 surf/surfxml_parse.c              769 /* TUTORIAL: New TAG*/
 192 5 surf/surf_private.h               205 /* TUTORIAL: New TAG*/
 193 6 surf/surfxml_parseplatf.c          64 /* TUTORIAL: New TAG*/
 194 7 surf/surfxml_parseplatf.c          85 /* TUTORIAL: New TAG*/
 195 8 include/simgrid/platf_interface.h  42 /* TUTORIAL: New TAG*/
 196 \endverbatim
 197 */