-
Notifications
You must be signed in to change notification settings - Fork 1
/
mainpage.dox
58 lines (33 loc) · 3.58 KB
/
mainpage.dox
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
/*!
\mainpage LibDVFS
\section sec_intro 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 \c libdvfs/libdvfs.h.
\section sec_supsys Supported systems
The library currently supports Linux operating systems with \c cpufreq installed and running.
\section sec_gov 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 \c ondemand and \c userspace.
The \c ondemand governor ask Linux to automatically control frequencies. This is the default governor on Linux.
The \c 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 \c dvfs_start() is restored when \c dvfs_stop() is called.
\section sec_errors Errors handling
Every function returns an error code. You can check it against \c DVFS_SUCCESS to determine if the function failed or not. \c dvfs_strerror() can be used to get a human readable error string.
\section sec_install Compilation and installation
The library has no external dependcy, you can compile it using the \c make command. You will need a standard C compilation tool-chain (make and GCC for instance).
You can install the library using \c make \c install. Moreover, you can set the following environment variables \c PREFIX, \c INCLUDE_DIR and \c 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 (\c scaling_setspeed, \c scaling_governor) in \c /sys/devices/system/cpu/cpu*\htmlonly\endhtmlonly/cpufreq/ and to read in most of the other files within the same directory.
\section sec_ex Example
The library provides a few tests that can be used to better understand how to use the library.
\subsection ssec_core Controlling a single core
In order to control a single core, you need to perform the following operations:
\li Start the library using \c dvfs_start()
\li Get the DVFS unit in charge of the core you want to control (\c dvfs_get_unit_by_id() or \c dvfs_get_unit_by_core())
\li Sets the \c userspace governor on it (\c dvfs_unit_set_gov())
\li Sets the core frequency (\c 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 \c dvfs_unit_set_freq().
\subsection ssec_cpu Controlling the whole system
A similar procedure can be used to control all the cores at the same time. The functions \c dvfs_set_gov() and \c dvfs_set_freq() can be used for that purpose.
Have a look to \c test_cpu and \c test_core to see how to use the library.
*/