SimGrid Plugins¶

You can extend SimGrid without modifying it, thanks to our plugin mechanism. This page describes how to write your own plugin, and documents some of the plugins distributed with SimGrid:

Host Load: monitors the load of the compute units.

Host Energy: models the energy dissipation of the compute units.

Link Energy: models the energy dissipation of the network.

WiFi Energy: models the energy dissipation of wifi links.

You can activate these plugins with the –cfg=plugin command line option, for example with --cfg=plugin:host_energy. You can get the full list of existing plugins with --cfg=plugin:help.

Defining a Plugin¶

A plugin can get some additional code executed within the SimGrid kernel, and attach the data needed by that code to the SimGrid objects.

The host load plugin in src/plugins/host_load.cpp constitutes a good introductory example. It defines a class HostLoad that is meant to be attached to each host. This class contains a EXTENSION_ID field that is mandatory to our extension mechanism. Then, the function sg_host_load_plugin_init initializes the plugin. It first calls simgrid::s4u::Host::extension_create() to register its extension to the s4u::Host objects, and then attaches some callbacks to signals.

You can attach your own extension to most kinds of s4u object: Actors, Disks, Hosts and Links. If you need to extend another kind of objects, please let us now.

template<class R, class ...P> class simgrid::xbt::signal<R(P...)>¶

A signal/slot mechanism, where you can attach callbacks to a given signal, and then fire the signal.

The template parameter is the function signature of the signal (the return value currently ignored).

template<class R, class ...P> simgrid::xbt::signal<R(P...)>::operator()(P... args)¶: Fire that signal, invoking all callbacks.

Partial list of existing signals in s4u:

Existing Plugins¶

Only the major plugins are described here. Please check in src/plugins to explore the other ones.

Host Energy¶

group plugin_host_energy

This is the energy plugin, enabling to account not only for computation time, but also for the dissipated energy in the simulated platform. To activate this plugin, first call sg_host_energy_plugin_init() before your loading your platform, and then use sg_host_get_consumed_energy() to retrieve the consumption of a given host.

When the host is on, this energy consumption naturally depends on both the current CPU load and the host energy profile. According to our measurements, the consumption is somehow linear in the amount of cores at full speed, with an abnormality when all the cores are idle. The full details are in our scientific paper on that topic.

As a result, our energy model takes 4 parameters:

Idle wattage (i.e., instantaneous consumption in Watt) when your host is up and running, but without anything to do.

Epsilon wattage when all cores are at 0 or epsilon%, but not in Idle state.

AllCores wattage when all cores of the host are at 100%.

Off wattage when the host is turned off.

Here is an example of XML declaration:

<host id="HostA" speed="100.0Mf" core="4">
    <prop id="wattage_per_state" value="100.0:120.0:200.0" />
    <prop id="wattage_off" value="10" />
</host>

If only two values are given, Idle is used for the missing Epsilon value.

This example gives the following parameters: Off is 10 Watts; Idle is 100 Watts; Epsilon is 120 Watts and AllCores is 200 Watts. This is enough to compute the wattage as a function of the amount of loaded cores:

#Cores loaded	Wattage	Explanation
0 (idle)	100 Watts	Idle value
0 (not idle)	120 Watts	Epsilon value
1	140 Watts	Linear extrapolation between Epsilon and AllCores
2	160 Watts	Linear extrapolation between Epsilon and AllCores
3	180 Watts	Linear extrapolation between Epsilon and AllCores
4	200 Watts	AllCores value

How does DVFS interact with the host energy model?

If your host has several DVFS levels (several pstates), then you should give the energetic profile of each pstate level:

<host id="HostC" speed="100.0Mf,50.0Mf,20.0Mf" core="4">
    <prop id="wattage_per_state"
          value="95.0:120.0:200.0, 93.0:115.0:170.0, 90.0:110.0:150.0" />
    <prop id="wattage_off" value="10" />
</host>

This encodes the following values:

pstate	Performance	Idle	Epsilon	AllCores
0	100 Mflop/s	95 Watts	120 Watts	200 Watts
1	50 Mflop/s	93 Watts	115 Watts	170 Watts
2	20 Mflop/s	90 Watts	110 Watts	150 Watts

To change the pstate of a given CPU, use the following functions: MSG_host_get_nb_pstates(), simgrid::s4u::Host::set_pstate(), MSG_host_get_power_peak_at().

How accurate are these models?

This model cannot be more accurate than your instantiation: with the default values, your result will not be accurate at all. You can still get accurate energy prediction, provided that you carefully instantiate the model. The first step is to ensure that your timing prediction match perfectly. But this is only the first step of the path, and you really want to read this paper to see all what you need to do before you can get accurate energy predictions.

Functions

void sg_host_energy_plugin_init()¶

Enable host energy plugin.

Enable energy plugin to get joules consumption of each cpu. Call this function before loading your platform.

void sg_host_energy_update_all()¶

updates the consumption of all hosts

After this call, sg_host_get_consumed_energy() will not interrupt your process (until after the next clock update).

double sg_host_get_consumed_energy(const_sg_host_t host)¶

Returns the total energy consumed by the host so far (in Joules)

Please note that since the consumption is lazily updated, it may require a simcall to update it. The result is that the actor requesting this value will be interrupted, the value will be updated in kernel mode before returning the control to the requesting actor.

double sg_host_get_idle_consumption(const_sg_host_t host)¶: Get the amount of watt dissipated when the host is idling.

double sg_host_get_idle_consumption_at(const_sg_host_t host, int pstate)¶: Get the amount of watt dissipated at the given pstate when the host is idling.

double sg_host_get_wattmin_at(const_sg_host_t host, int pstate)¶: Get the amount of watt dissipated at the given pstate when the host is at 0 or epsilon% CPU usage.

double sg_host_get_wattmax_at(const_sg_host_t host, int pstate)¶: Returns the amount of watt dissipated at the given pstate when the host burns CPU at 100%.

double sg_host_get_power_range_slope_at(const_sg_host_t host, int pstate)¶: Returns the power slope at the given pstate.

double sg_host_get_current_consumption(const_sg_host_t host)¶: Returns the current consumption of the host.

Link Energy¶

group plugin_link_energy

This is the link energy plugin, accounting for the dissipated energy in the simulated platform.

The energy consumption of a link depends directly on its current traffic load. Specify that consumption in your platform file as follows:

<link id="SWITCH1" bandwidth="125Mbps" latency="5us" sharing_policy="SHARED" >
<prop id="wattage_range" value="100.0:200.0" />
<prop id="wattage_off" value="10" />
</link>

The first property means that when your link is switched on, but without anything to do, it will dissipate 100 Watts. If it’s fully loaded, it will dissipate 200 Watts. If its load is at 50%, then it will dissipate 150 Watts. The second property means that when your host is turned off, it will dissipate only 10 Watts (please note that these values are arbitrary).

To simulate the energy-related elements, first call the sg_link_energy_plugin_init() before loading the platform and then use the following function to retrieve the consumption of a given link: sg_link_get_consumed_energy().

Functions

void sg_link_energy_plugin_init()¶

Enable energy plugin.

Enable energy plugin to get joules consumption of each cpu. You should call this function before loading your platform.

double sg_link_get_consumed_energy(const_sg_link_t link)¶

Returns the total energy consumed by the link so far (in Joules)

Please note that since the consumption is lazily updated, it may require a simcall to update it. The result is that the actor requesting this value will be interrupted, the value will be updated in kernel mode before returning the control to the requesting actor.

WiFi Energy¶

group plugin_link_energy_wifi

This is the WiFi energy plugin, accounting for the dissipated energy of WiFi links.

Functions

void sg_wifi_energy_plugin_init()¶: Initialize the wifi energy plugin.

Host Load¶

group plugin_host_load

In addition, this constitutes a good introductory example on how to write a plugin. It attaches an extension to each host to store some data, and places callbacks in the following signals:

simgrid::s4u::Host::on_creation: Attach a new extension to the newly created host.

simgrid::s4u::Exec::on_start: Make note that a new execution started, increasing the load.

simgrid::s4u::Exec::on_completion: Make note that an execution completed, decreasing the load.

simgrid::s4u::Host::on_state_change: Do what is appropriate when the host gets suspended, turned off or similar.

simgrid::s4u::Host::on_speed_change: Do what is appropriate when the DVFS is modified.

Note that extensions are automatically destroyed when the host gets destroyed.

Functions

void sg_host_load_plugin_init()¶: Initializes the HostLoad plugin.

double sg_host_get_current_load(const_sg_host_t host)¶: Returns the current load of that host, as a ratio = achieved_flops / (core_current_speed * core_amount)

double sg_host_get_avg_load(const_sg_host_t host)¶: Returns the current load of that host.

double sg_host_get_idle_time(const_sg_host_t host)¶: Returns the time this host was idle since the last reset.

double sg_host_get_total_idle_time(const_sg_host_t host)¶: Returns the time this host was idle since the beginning of the simulation.

double sg_host_get_computed_flops(const_sg_host_t host)¶: Returns the amount of flops computed by that host since the last reset.

void sg_host_load_reset(const_sg_host_t host)¶: Resets the idle time and flops amount of that host.

File System¶

group plugin_filesystem

This adds the notion of Files on top of the storage notion that provided by the core of SimGrid. Activate this plugin at will.

Typedefs

typedef s4u_File *sg_file_t¶: Pointer to a SimGrid file object

typedef const s4u_File *const_sg_file_t¶: Constant pointer to a SimGrid file object

Functions

void sg_storage_file_system_init()¶

Initialize the file system plugin.

See the examples in I/O on Disks and Files.

const char *sg_file_get_name(const_sg_file_t fd)¶: Retrieves the path to the file

sg_size_t sg_file_get_size(const_sg_file_t fd)¶: Retrieves the size of the file

void *sg_file_get_data(const_sg_file_t fd)¶: Retrieves the user data associated with the file

void sg_file_set_data(sg_file_t fd, void *data)¶: Changes the user data associated with the file

void sg_file_seek(sg_file_t fd, sg_offset_t offset, int origin)¶

Set the file position indicator in the sg_file_t by adding offset bytes to the position specified by origin (either SEEK_SET, SEEK_CUR, or SEEK_END).

Parameters

fd: : file object that identifies the stream
offset: : number of bytes to offset from origin
origin: : Position used as reference for the offset. It is specified by one of the following constants defined in <stdio.h> exclusively to be used as arguments for this function (SEEK_SET = beginning of file, SEEK_CUR = current position of the file pointer, SEEK_END = end of file)

int sg_file_rcopy(sg_file_t file, sg_host_t host, const char *fullpath)¶

Copy a file to another location on a remote host.

Return

If successful, the function returns 0. Otherwise, it returns -1.

Parameters

file: : the file to move
host: : the remote host where the file has to be copied
fullpath: : the complete path destination on the remote host

int sg_file_rmove(sg_file_t file, sg_host_t host, const char *fullpath)¶

Move a file to another location on a remote host.

Return

If successful, the function returns 0. Otherwise, it returns -1.

Parameters

file: : the file to move
host: : the remote host where the file has to be moved
fullpath: : the complete path destination on the remote host

sg_size_t write(sg_size_t size, bool write_inside = false)¶

Write into a file (local or remote)

Simulates a write action. Returns the size of data actually written.

Return

the number of bytes successfully write or -1 if an error occurred

Parameters

size: of the file to write
write_inside:

class File : public xbt::Extendable<File>¶

#include <file_system.h>

A simulated file.

Used to simulate the time it takes to access to a file, but does not really store any information.

They are located on simgrid::s4u::Disk that are accessed from a given simgrid::s4u::Host