# Energy Benchmarking Tool

The energy benchmarking Rust crate can be added to your project with `cargo add energy-bench`.
The tool is continuously being updated, so please make sure you are using the most recent version.

Tool for benchmarking the energy consumption of programs.
Idle energy consumption, as well as energy consumed by data generation and cleanup, are subtracted from the results.

Check out the `example` folder for a few examples, and check the `.gitlab-ci.yml` for an example of how to run the _Software Energy Lab_ pipeline.

Some programs are too short-running to provide accurate energy measurements.
To avoid this, the benchmark can be repeated until a given amount of time has passed: `set_min_measurement_duration`.
By default, benchmarks are run for at least 100ms.

## RAPL permissions (Debian)

If you want to run this locally, you will likely need elevated permissions for reading RAPL energy data.

I suggest adding a new `rapl` group.

```bash
sudo addgroup rapl
sudo usermod -aG rapl $(whoami)
```

And then adding entries to `/etc/sysfs.conf` for your RAPL domains and subdomains.
Check your folder hierarchy in `/sys/class/powercap/` to determine which domains
you have available to your CPU.

Then for each domain, add the following lines to `/etc/sysfs.conf`.
(Requires `sysfsutils` to be installed.)

For example, for package 0:

```bash
mode class/powercap/intel-rapl:0/energy_uj = 0440
owner class/powercap/intel-rapl:0/energy_uj = root:rapl
```

And for its first subdomain:

```bash
mode class/powercap/intel-rapl:0:0/energy_uj = 0440
owner class/powercap/intel-rapl:0:0/energy_uj = root:rapl
```

Finally, restart the `sysfsutils` service.

```bash
sudo systemctl restart sysfsutils
```

## RAPL permissions (Arch)

These instructions should be distribution-invariant and even work on Debian-based distributions, I think.

1. Create and edit the following file: `sudo nano /etc/udev/rules.d/99-powercap.rules`
2. Put the following into the file: `ACTION=="add", SUBSYSTEM=="powercap", KERNEL=="intel-rapl:0", RUN+="/bin/chmod 644 /sys/class/powercap/%k/energy_uj"`
3. Reload udev rules: `sudo udevadm control --reload-rules`
4. Trigger the rule: `sudo udevadm trigger --verbose --subsystem-match=powercap --action=add`
5. Check if the rule worked (you should have read permissions for the file): `ls -la /sys/class/powercap/intel-rapl:0/energy_uj`

The reason we're doing it this way is because permission changes applied to /sys/ get reset on reboot, so this is a way to make the permission change persistent.

