Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
546a6c69efa3d49b6a9b9bfdde7683423f94f9da
[simgrid.git] / 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
121 A simcall is used to go from user mode to kernel mode. There is some
122 sort of popping dance involved, as we want to isolate the user
123 contextes from their environment (so that they can run in parallel).
124
125 The workflow of a simcall is the following:
126
127 - `<ret> simcall_<name>(<args>)`
128  - `simcall_BODY_<name>(<args>)`
129   - Initializes the simcall (store the arguments in position)
130   - If maestro, executes the simcall directly (and return)
131   - If not, call `SIMIX_process_yield` to give back the control to maestro
132   - ========== KERNEL MODE ==========
133   - `SIMIX_simcall_handle` large switch (on simcall) doing for each:
134    - `simcall_HANDLER_<name>(simcall, <args>)`
135    - `SIMIX_simcall_answer(simcall)`
136
137 To simplify the simcall creation, a python script generates most of
138 the code and give helpers for the remaining stuff. That script reads
139 the simcall definitions from src/simix/simcalls.in, checks that both
140 `simcall_<name>()` and `simcall_HANDLER()` are defined somewhere, and
141 generates the following files:
142
143 - smx_popping_accessors.h:
144   Helper functions to get and set simcall arguments and results
145 - smx_popping_bodies.c:
146   The BODY function of each simcall
147 - smx_popping_enum.c:
148   Definition of type `enum e_smx_simcall_t` (one value per existing simcall)
149 - smx_popping_generated.c:
150   Definitions of `simcall_names[]` (debug name of each simcall), and
151   SIMIX_simcall_enter() that deals with the simcall from within the kernel
152
153 The simcall.in file list all the simcalls in sections. A line starting by "##"
154 define a new section which will be replace by a "ifdef" in the generated code.
155 There is a simcall by line which follow this format:
156
157 ~~~~
158 Simcall -> Name HasAnswer Res Args
159 Name -> [a-z0-9_]+
160 Has_Answer -> "True" | "False"
161 Res -> "(" Type MaybeCast ")"
162 Args -> Args Arg | Arg
163 Arg -> "(" Name "," Type MaybeCast ")"
164 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*"
165 MaybeCast -> "," Cast | ""
166 Cast -> [a-z0-9_* ]+
167 ~~~~
168
169 \section simgrid_dev_guide_tag What is How to add a new tag for xml files?
170 Search for expression \"TUTORIAL: New TAG\".
171 \verbatim
172 user@caraja:~/workspace/simgrid/src$ cg "TUTORIAL: New TAG"
173 0 surf/sg_platf.c                    43 /* TUTORIAL: New TAG*/
174 1 surf/sg_platf.c                    89 /* TUTORIAL: New TAG*/
175 2 surf/sg_platf.c                   124 /* TUTORIAL: New TAG*/
176 3 surf/sg_platf.c                   337 /* TUTORIAL: New TAG*/
177 4 surf/surfxml_parse.c              769 /* TUTORIAL: New TAG*/
178 5 surf/surf_private.h               205 /* TUTORIAL: New TAG*/
179 6 surf/surfxml_parseplatf.c          64 /* TUTORIAL: New TAG*/
180 7 surf/surfxml_parseplatf.c          85 /* TUTORIAL: New TAG*/
181 8 include/simgrid/platf_interface.h  42 /* TUTORIAL: New TAG*/
182 \endverbatim
183 */