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 show the architecture of the SURF layer. This layer is composed
   8 of different kind of models representing the differents systems we want to
   9 modelize (i.e.cpu, network, storage, workstation, virtual machine).
  10
  11 A model in simgrid is composed of three classes: Model, Resource and Action
  12 (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.: cpu_interface.hpp) and some implementations (e.g.: cpu_cas01.hpp,
  20 cpu_ti.hpp).
  21
  22 init function:
  23 void surf_cpu_model_init_Cas01()
  24 s_surf_model_description_t surf_network_model_description[] = {
  25
  26 \subsection simgrid_dev_guide_model_implem How to add a new model implementation in surf?
  27
  28 If you want to create a new implementation of a kind of model you must extend
  29 the classes of the corresponding interfaces.
  30
  31 For instance, if you want to add a new cup model called `Plop`, create two files
  32 cpu_plop.hpp and cpu_plop_cpp which contains classes CpuPlopModel, CpuPlop and
  33 CpuPlopAction implementating respectively the interfaces CpuModel, Cpu and
  34 CpuAction. You also need to define a initializing function like this:
  35
  36 ~~~~
  37 void surf_cpu_model_init_plop()
  38 {
  39   xbt_assert(!surf_cpu_model_pm);
  40
  41   surf_cpu_model_pm = new CpuPlopModel();
  42
  43   sg_platf_host_add_cb(cpu_parse_init);
  44   sg_platf_postparse_add_cb(cpu_add_traces);
  45
  46   xbt_dynar_push(model_list, &surf_cpu_model_pm);
  47 }
  48 ~~~~
  49
  50 and add an entry in the corresponding array in surf_interface.cpp
  51
  52 ~~~~
  53 s_surf_model_description_t surf_cpu_model_description[] = {
  54   {"Cas01",
  55    "Simplistic CPU model (time=size/power).",
  56    surf_cpu_model_init_Cas01},
  57   {"Plop",
  58    "The new plop CPU model.",
  59    surf_cpu_model_init_plop},
  60   {NULL, NULL, NULL}      // this array must be NULL terminated
  61 };
  62 ~~~~
  63
  64 \subsection simgrid_dev_guide_model_kind How to add a new kind of model in surf?
  65
  66 If you want to create a new kind of model, you must create a new interface
  67 where you extend the classes Model, Resource and Action, and then create an
  68 implementation of this interface.
  69
  70
  71 \section simgrid_dev_guide_surf_callbacks How to use surf callbacks?
  72
  73 Adding features to surf could also be handle by using surf callbacks (instead
  74 of adding new implementation model). The list of available callbacks is
  75 accessible there \ref SURF_callbacks. An example of using surf callbacks is the
  76 energy plugin. If you want to add a plugin you need to define callback function
  77 and to connect them to callbacks handler in an initialization function.
  78
  79 ~~~~
  80 static void MyNetworkLinkCreatedCallback(NetworkLinkPtr cpu){
  81   // your code
  82 }
  83
  84 static void MyNetworkLinkDestructedCallback(NetworkLinkPtr cpu){
  85   // your code
  86 }
  87
  88 static void MyNetworkCommunicationCallback(NetworkActionPtr cpu,
  89                                            RoutingEdgePtr src,
  90                                            RoutingEdgePtr dst){
  91   // your code
  92 }
  93
  94 void sg_my_network_plugin_init() {
  95   surf_callback_connect(networkLinkCreatedCallbacks,
  96                         MyNetworkLinkCreatedCallback);
  97   surf_callback_connect(networkLinkDestructedCallbacks,
  98                         MyNetworkLinkDestructedCallback);
  99   surf_callback_connect(networkCommunicationCallbacks,
 100                         MyNetworkCommunicationCallback);
 101 }
 102 ~~~~
 103
 104 Then you need to add an entry in surf_interface.cpp refering to your
 105 initialization function.
 106
 107 ~~~~
 108 s_surf_model_description_t surf_plugin_description[] = {
 109                   {"Energy",
 110                    "Cpu energy consumption.",
 111                    sg_energy_plugin_init},
 112                   {"MyNetworkPlugin",
 113                    "My network plugin.",
 114                    sg_my_network_plugin_init},
 115                   {NULL, NULL, NULL}      // this array must be NULL terminated
 116 };
 117 ~~~~
 118
 119 \section simgrid_dev_guide_simcall How to add a new simcall?
 120 A simcall is used to go from user mode to kernel mode. The workflow of
 121 a simcall is the following:
 122
 123 - `<ret> simcall_<name>(<args>)`
 124  - `simcall_BODY_<name>(<args>)`
 125   - create the simcall
 126   - `SIMIX_process_yield` if not maestro
 127   - ========== KERNEL MODE ==========
 128   - `SIMIX_simcall_pre`
 129    - `SIMIX_pre_<name>(simcall, <args>)`
 130    - `SIMIX_simcall_answer(simcall)`
 131
 132 To simplify the simcall creation, we have made a python script that
 133 generate most of the code and give helpers for the remaining stuff.
 134 The script generating the simcalls (src/simix/simcalls.in) take in input
 135 the src/simix/simcalls.in file where the simcalls are defined and generate
 136 the following files:
 137
 138 - simcall_generated_args_getter_setter.h:
 139   functions to get and set simcall arguments
 140 - simcall_generated_res_getter_setter.h:
 141   functions to get and set simcall result
 142 - simcall_generated_body.c:
 143   the BODY function of the simcall
 144 - simcall_generated_case.c:
 145   the case of the SIMIX_simcall_pre function
 146 - simcall_generated_enum.h:
 147   the enum of simcalls
 148 - simcall_generated_string.c:
 149   string corresponding to the enum to debug
 150
 151 Furthermode if the simcall_<name> or the SIMIX_pre_<name> function are missing,
 152 a warning will show up with a prototype of the corresponding fonction to fill.
 153
 154 The simcall.in file list all the simcalls in sections. A line starting by "##"
 155 define a new section which will be replace by a "ifdef" in the generated code.
 156 There is a simcall by line which follow this format:
 157
 158 ~~~~
 159 Simcall -> Name HasAnswer Res Args
 160 Name -> [a-z0-9_]+
 161 Has_Answer -> "True" | "False"
 162 Res -> "(" Type MaybeCast ")"
 163 Args -> Args Arg | Arg
 164 Arg -> "(" Name "," Type MaybeCast ")"
 165 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*"
 166 MaybeCast -> "," Cast | ""
 167 Cast -> [a-z0-9_* ]+
 168 ~~~~
 169
 170 \section simgrid_dev_guide_tag What is How to add a new tag for xml files?
 171 Search for expression \"TUTORIAL: New TAG\".
 172 \verbatim
 173 user@caraja:~/workspace/simgrid/src$ cg "TUTORIAL: New TAG"
 174 0 surf/sg_platf.c                    43 /* TUTORIAL: New TAG*/
 175 1 surf/sg_platf.c                    89 /* TUTORIAL: New TAG*/
 176 2 surf/sg_platf.c                   124 /* TUTORIAL: New TAG*/
 177 3 surf/sg_platf.c                   337 /* TUTORIAL: New TAG*/
 178 4 surf/surfxml_parse.c              769 /* TUTORIAL: New TAG*/
 179 5 surf/surf_private.h               205 /* TUTORIAL: New TAG*/
 180 6 surf/surfxml_parseplatf.c          64 /* TUTORIAL: New TAG*/
 181 7 surf/surfxml_parseplatf.c          85 /* TUTORIAL: New TAG*/
 182 8 include/simgrid/platf_interface.h  42 /* TUTORIAL: New TAG*/
 183 \endverbatim
 184 */