2 @page inside_extending Extending SimGrid
6 @section simgrid_dev_guide_model How to add a new model?
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).
11 A model in SimGrid is composed of three classes: Model, Resource and Action
12 (@ref SURF_interface "surf_interface.hpp").
14 @image html surf++.png
15 @image latex surf++.pdf "surf++" width=\textwidth
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,
22 The CPU model Cas01, for instance, is initialized by the function
23 void surf_cpu_model_init_Cas01()
25 The different network models that are offered by simgrid are stored in the array
26 that is defined as follows:
28 s_surf_model_description_t surf_network_model_description[] = {
30 @subsection simgrid_dev_guide_model_implem How to implement a new model?
32 If you want to create a new implementation of a kind of model you must extend
33 the classes of the corresponding interfaces.
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:
41 void surf_cpu_model_init_plop()
43 xbt_assert(!surf_cpu_model_pm);
45 surf_cpu_model_pm = new CpuPlopModel();
47 simgrid::surf::on_postparse.connect(cpu_add_traces);
49 xbt_dynar_push(model_list, &surf_cpu_model_pm);
53 and add an entry in the corresponding array in surf_interface.cpp
56 s_surf_model_description_t surf_cpu_model_description[] = {
58 "Simplistic CPU model (time=size/speed).",
59 surf_cpu_model_init_Cas01},
61 "The new plop CPU model.",
62 surf_cpu_model_init_plop},
63 {NULL, NULL, NULL} // this array must be NULL terminated
67 @subsection simgrid_dev_guide_model_kind How to add a new kind of model?
69 If you want to create a new kind of model, you must create a new interface
70 where you extend the classes Model, Resource and Action, and then create an
71 implementation of this interface.
74 @section simgrid_dev_guide_surf_callbacks How to use surf callbacks?
76 Adding features to surf could also be handle by using surf callbacks (instead
77 of adding new implementation model). The list of available callbacks is
78 accessible there @ref SURF_callbacks. An example of using surf callbacks is the
79 energy plugin. If you want to add a plugin you need to define callback function
80 and to connect them to callbacks handler in an initialization function.
83 static void MyNetworkLinkCreatedCallback(NetworkLinkPtr cpu){
87 static void MyNetworkLinkDestructedCallback(NetworkLinkPtr cpu){
91 static void MyNetworkCommunicationCallback(NetworkActionPtr cpu,
97 void sg_my_network_plugin_init() {
98 networkLinkCreatedCallbacks.connect(MyNetworkLinkCreatedCallback);
99 networkLinkDestructedCallbacks.connect(MyNetworkLinkDestructedCallback);
100 networkCommunicationCallbacks.connect(MyNetworkCommunicationCallback);
104 Then you need to add an entry in surf_interface.cpp refering to your
105 initialization function.
108 s_surf_model_description_t surf_plugin_description[] = {
110 "Cpu energy consumption.",
111 sg_host_energy_plugin_init},
113 "My network plugin.",
114 sg_my_network_plugin_init},
115 {NULL, NULL, NULL} // this array must be NULL terminated
119 @section simgrid_dev_guide_simcall How to add a new simcall?
121 First of all you might want to avoid defining a new simcall if possible:
122 @ref simgrid_dev_guide_generic_simcall.
124 A simcall is used to go from user mode to kernel mode. There is some
125 sort of popping dance involved, as we want to isolate the user
126 contextes from their environment (so that they can run in parallel and
127 so that we can model-check them).
129 In short, just add a line to src/simix/simcalls.in and run the
130 src/simix/simcalls.py script. It will guide you about how to implement
131 your simcall. Please keep reading this section (only) if you want to
132 understand how it goes.
135 The workflow of a simcall is the following:
137 - `<ret> simcall_<name>(<args>)`
138 - `simcall_BODY_<name>(<args>)`
139 - Initializes the simcall (store the arguments in position)
140 - If maestro, executes the simcall directly (and return)
141 - If not, call `ActorImpl::yield` to give back the control to maestro
142 - ========== KERNEL MODE ==========
143 - `ActorImpl::simcall_handle` large switch (on simcall) doing for each:
144 - `simcall_HANDLER_<name>(simcall, <args>)` (the manual code handling the simcall)
145 - If the simcall is not marked as "blocking" in its definition,
146 call `ActorImpl::simcall_answer()` that adds back the issuer
147 process to the list of processes to run in the next scheduling round.
148 It is thus the responsability of the blocking simcalls to call
149 `ActorImpl::simcall_answer()` themselves in their handler.
151 Note that empty HANDLERs can be omitted. These functions usually do
152 some parameter checking, or retrieve some information about the
153 simcall issuer, but when there no need for such things, the handler
154 can be omited. In that case, we directly call the function
155 `simcall_<name>(<args>)`.
157 To simplify the simcall creation, a python script generates most of
158 the code and give helpers for the remaining stuff. That script reads
159 the simcall definitions from src/simix/simcalls.in, checks that both
160 `simcall_<name>()` and `simcall_HANDLER()` are defined somewhere, and
161 generates the following files:
163 - popping_accessors.hpp:
164 Helper functions to get and set simcall arguments and results
165 - popping_bodies.cpp:
166 The BODY function of each simcall
168 Definition of type `enum e_smx_simcall_t` (one value per existing simcall)
169 - popping_generated.cpp:
170 Definitions of `simcall_names[]` (debug name of each simcall), and
171 SIMIX_simcall_enter() that deals with the simcall from within the kernel
173 The simcall.in file list all the simcalls in sections. A line starting by "##"
174 define a new section which will be replace by a "ifdef" in the generated code.
176 @section simgrid_dev_guide_generic_simcall How to avoid adding a new simcall?
178 We now have some generic simcalls which can be used to interface with the
179 Maestro without creating new simcalls. You might want to use them instead of
180 the defining additional simcalls. The long term goal is to replace most of
181 the simcalls with the generic ones.
183 For simcalls which never block, `kernelImmediate()` can be used. It takes a
184 C++ callback executes it in maestro. Any value returned by the callback is
185 returned by `kernelImmediate()`. Conversely, if the callback throws an
186 exception, this exception is propagated out of `kernelImmediate()`. Executing
187 the code in maestro enforces mutual exclusion (no other user process is running)
188 and enforce a deterministic order which guarantees the reproducibility of the
189 simulation. This call is particularly useful for implementing mutable calls:
192 void Host::setProperty(const char*key, const char *value){
193 simgrid::simix::kernelImmediate([&] {
194 simgrid::surf::HostImpl* surf_host = this->extension<simgrid::surf::HostImpl>();
195 surf_host->setProperty(key,value);
200 If there is no blocking and no mutation involved (getters), you might consider
201 avoiding switching to Maestro and reading directly the data you're interested
204 For simcalls which might block, `kernel_sync()` can be used. It takes a
205 C++ callback and executes it immediately in maestro. This C++ callback is
206 expected to return a `simgrid::kernel::Future<T>` reprensenting the operation
207 in the kernal. When the operations completes, the user process is waken up
212 std::vector<char> result = simgrid::simix::kernel_sync([&] {
213 // Fictional example, simgrid::kernel::readFile does not exist.
214 simgrid::kernel::Future<std::vector<char>> result = simgrid::kernel::readFile(file);
217 XBT_DEBUG("Finished reading file %s: length %zu", file, result.size());
219 // If the operation failed, kernel_sync() throws an exception:
220 catch (std::runtime_error& e) {
221 XBT_ERROR("Could not read file %s", file);
225 Asynchronous blocks can be implemented with `kernel_async()`. It works
226 like `kernel_sync()` but does not block. Instead, it returns a
227 `simgrid::simix::Future` representing the operation in the process:
230 simgrid::simix::Future<std:vector<char>> result = simgrid::simix::kernel_sync([&] {
231 // Fictional example, simgrid::kernel::readFile does not exist.
232 simgrid::kernek::Future<std::vector<char>> result = simgrid::kernel::readFile(file);
236 // Do some work while the operation is pending:
237 while (!result.is_ready() && hasWorkToDo())
240 // We don't have anything to do, wait for the operation to complete and
243 std:vector<char> data = result.get();
244 XBT_DEBUG("Finished reading file %s: length %zu", file, data.size());
246 // If the operation failed, .get() throws an exception:
247 catch (std::runtime_error& e) {
248 XBT_ERROR("Could not read file %s", file);
252 <b>Note:</b> `kernel_sync(f)` could be implemented as `kernel_async(f).get()`.
254 @section simgrid_dev_guide_tag What is How to add a new tag for xml files?
256 You should not do something like that. Please work instead to make XML
257 avoidable, ie to make the C++ interface nice and usable.