SimGrid  3.11
Versatile Simulation of Distributed Systems
Extending SimGrid

We start to put TAGS in simgrid source code for having tutorials to see where is the important parts ans steps to create:

How to add a new MSG function?

Search for expression "TUTORIAL: New API".

user@caraja:~/workspace/simgrid/src$ cg "TUTORIAL: New API"
 0 msg/msg_new_api.c             15 /* TUTORIAL: New API*/
 1 simix/smx_smurf.c            582 /* TUTORIAL: New API*/
 2 simix/smx_smurf.c            616 /* TUTORIAL: New API*/
 3 simix/smx_smurf_private.h    102 /* TUTORIAL: New API*/
 4 simix/smx_smurf_private.h    629 /* TUTORIAL: New API*/
 5 simix/smx_private.h           28 /* TUTORIAL: New API*/
 6 simix/smx_private.h          101 /* TUTORIAL: New API*/
 7 simix/smx_private.h          182 /* TUTORIAL: New API*/
 8 simix/smx_global.c           454 /* TUTORIAL: New API*/
 9 simix/smx_new_api.c            8 /* TUTORIAL: New API*/
10 simix/smx_user.c            1684 /* TUTORIAL: New API*/
11 simix/smx_new_api_private.h    8 /* TUTORIAL: New API*/
12 simix/smx_process.c          338 /* TUTORIAL: New API*/

How to add a new model in surf?

The figure below show the architecture of the SURF layer. This layer is composed of different kind of models representing the differents systems we want to modelize (i.e.cpu, network, storage, workstation, virtual machine).

A model in simgrid is composed of three classes: Model, Resource and Action (surf_interface.hpp).

surf++.png

Actually there are five kind of models: CpuModel, NetworkModel, WorkstationModel, WorkstationVMModel and StorageModel. For each kind of model, there is an interface (e.g.: cpu_interface.hpp) and some implementations (e.g.: cpu_cas01.hpp, cpu_ti.hpp).

init function: void surf_cpu_model_init_Cas01() s_surf_model_description_t surf_network_model_description[] = {

How to add a new model implementation in surf?

If you want to create a new implementation of a kind of model you must extend the classes of the corresponding interfaces.

For instance, if you want to add a new cup model called Plop, create two files cpu_plop.hpp and cpu_plop_cpp which contains classes CpuPlopModel, CpuPlop and CpuPlopAction implementating respectively the interfaces CpuModel, Cpu and CpuAction. You also need to define a initializing function like this:

void surf_cpu_model_init_plop()
{
xbt_assert(!surf_cpu_model_pm);
surf_cpu_model_pm = new CpuPlopModel();
sg_platf_host_add_cb(cpu_parse_init);
sg_platf_postparse_add_cb(cpu_add_traces);
xbt_dynar_push(model_list, &surf_cpu_model_pm);
}

and add an entry in the corresponding array in surf_interface.cpp

s_surf_model_description_t surf_cpu_model_description[] = {
{"Cas01",
"Simplistic CPU model (time=size/power).",
surf_cpu_model_init_Cas01},
{"Plop",
"The new plop CPU model.",
surf_cpu_model_init_plop},
{NULL, NULL, NULL} // this array must be NULL terminated
};

How to add a new kind of model in surf?

If you want to create a new kind of model, you must create a new interface where you extend the classes Model, Resource and Action, and then create an implementation of this interface.

How to use surf callbacks?

Adding features to surf could also be handle by using surf callbacks (instead of adding new implementation model). The list of available callbacks is accessible there SURF callbacks. An example of using surf callbacks is the energy plugin. If you want to add a plugin you need to define callback function and to connect them to callbacks handler in an initialization function.

static void MyNetworkLinkCreatedCallback(NetworkLinkPtr cpu){
// your code
}
static void MyNetworkLinkDestructedCallback(NetworkLinkPtr cpu){
// your code
}
static void MyNetworkCommunicationCallback(NetworkActionPtr cpu,
// your code
}
void sg_my_network_plugin_init() {
surf_callback_connect(networkLinkCreatedCallbacks,
MyNetworkLinkCreatedCallback);
surf_callback_connect(networkLinkDestructedCallbacks,
MyNetworkLinkDestructedCallback);
surf_callback_connect(networkCommunicationCallbacks,
MyNetworkCommunicationCallback);
}

Then you need to add an entry in surf_interface.cpp refering to your initialization function.

s_surf_model_description_t surf_plugin_description[] = {
{"Energy",
"Cpu energy consumption.",
{"MyNetworkPlugin",
"My network plugin.",
sg_my_network_plugin_init},
{NULL, NULL, NULL} // this array must be NULL terminated
};

How to add a new simcall?

A simcall is used to go from user mode to kernel mode. The workflow of a simcall is the following:

  • <ret> simcall_<name>(<args>)
    • simcall_BODY_<name>(<args>)
      • create the simcall
      • SIMIX_process_yield if not maestro
      • ========== KERNEL MODE ==========
      • SIMIX_simcall_pre
        • SIMIX_pre_<name>(simcall, <args>)
        • SIMIX_simcall_answer(simcall)

To simplify the simcall creation, we have made a python script that generate most of the code and give helpers for the remaining stuff. The script generating the simcalls (src/simix/simcalls.in) take in input the src/simix/simcalls.in file where the simcalls are defined and generate the following files:

  • simcall_generated_args_getter_setter.h: functions to get and set simcall arguments
  • simcall_generated_res_getter_setter.h: functions to get and set simcall result
  • simcall_generated_body.c: the BODY function of the simcall
  • simcall_generated_case.c: the case of the SIMIX_simcall_pre function
  • simcall_generated_enum.h: the enum of simcalls
  • simcall_generated_string.c: string corresponding to the enum to debug

Furthermode if the simcall_<name> or the SIMIX_pre_<name> function are missing, a warning will show up with a prototype of the corresponding fonction to fill.

The simcall.in file list all the simcalls in sections. A line starting by "##" define a new section which will be replace by a "ifdef" in the generated code. There is a simcall by line which follow this format:

Simcall -> Name HasAnswer Res Args
Name -> [a-z0-9_]+
Has_Answer -> "True" | "False"
Res -> "(" Type MaybeCast ")"
Args -> Args Arg | Arg
Arg -> "(" Name "," Type MaybeCast ")"
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*"
MaybeCast -> "," Cast | ""
Cast -> [a-z0-9_* ]+

What is How to add a new tag for xml files?

Search for expression "TUTORIAL: New TAG".

user@caraja:~/workspace/simgrid/src$ cg "TUTORIAL: New TAG"
0 surf/sg_platf.c                    43 /* TUTORIAL: New TAG*/
1 surf/sg_platf.c                    89 /* TUTORIAL: New TAG*/
2 surf/sg_platf.c                   124 /* TUTORIAL: New TAG*/
3 surf/sg_platf.c                   337 /* TUTORIAL: New TAG*/
4 surf/surfxml_parse.c              769 /* TUTORIAL: New TAG*/
5 surf/surf_private.h               205 /* TUTORIAL: New TAG*/
6 surf/surfxml_parseplatf.c          64 /* TUTORIAL: New TAG*/
7 surf/surfxml_parseplatf.c          85 /* TUTORIAL: New TAG*/
8 include/simgrid/platf_interface.h  42 /* TUTORIAL: New TAG*/