Introduction

LibDVFS is intended to provide simple functions and structures to manipulate the CPU frequency.

Currently, the library allows controlling three different levels: the whole system, a DVFS unit, or a single core.

System and core levels exactly represent what you think they do. A DVFS unit is however a little bit more subbtle. In fact, on many processors, it is not possible to effectively set a different frequency on all the cores and some cores must run at the same frequency. All the cores that must run at the same frequency form a so-called DVFS unit. The frequency actually set to all the cores of a single DVFS unit is usually the maximal one among the frequencies requested by every cores in the unit.

In order to use the library, you only need to include libdvfs/libdvfs.h.

Supported systems

The library currently supports Linux operating systems with cpufreq installed and running.

Governors

Linux uses governors to specify how it must control frequencies. Several options exist but the two options one has to be aware of is ondemand and userspace.

The ondemand governor ask Linux to automatically control frequencies. This is the default governor on Linux. The userspace governor ask Linux to let us control the frequencies. You must set this governor on the whole DVFS unit before changing the frequency of one of its core.

The governor used prior calling dvfs_start() is restored when dvfs_stop() is called.

Errors handling

Every function returns an error code. You can check it against DVFS_SUCCESS to determine if the function failed or not. dvfs_strerror() can be used to get a human readable error string.

Compilation and installation

The library has no external dependcy, you can compile it using the make command. You will need a standard C compilation tool-chain (make and GCC for instance).

You can install the library using make install. Moreover, you can set the following environment variables PREFIX, INCLUDE_DIR and LIB_DIR to modify where the library will be installed.

Warning: In order to be able to control the frequencies, you need to be able to write to various files (scaling_setspeed, scaling_governor) in /sys/devices/system/cpu/cpu*/cpufreq/ and to read in most of the other files within the same directory.

Example

The library provides a few tests that can be used to better understand how to use the library.

Controlling a single core

In order to control a single core, you need to perform the following operations:

Start the library using dvfs_start()
Get the DVFS unit in charge of the core you want to control (dvfs_get_unit_by_id() or dvfs_get_unit_by_core())
Sets the userspace governor on it (dvfs_unit_set_gov())
Sets the core frequency (dvfs_core_set_freq()).

Warning: This only sets the core frequency but, if any core on the same DVFS unit requests an higher frequency, it will overwrite our request. If you want to make sure that the desired frequency is applied to your core, you should apply it to the whole DVFS unit using dvfs_unit_set_freq().

Controlling the whole system

A similar procedure can be used to control all the cores at the same time. The functions dvfs_set_gov() and dvfs_set_freq() can be used for that purpose. Have a look to test_cpu and test_core to see how to use the library.