doc/doxygen/inside_extending.doc

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