.TH "rapl-info" "1" "2017-09-20" "powercap" "rapl-info"
.SH "NAME"
.LP
rapl\-info \- get RAPL configurations
.SH "SYNPOSIS"
.LP
\fBrapl\-info\fP [\fIOPTION\fP]...
.SH "DESCRIPTION"
.LP
Prints out Intel Running Average Power Limit (RAPL) configurations.
.LP
Since RAPL does not implement all capabilities defined in the powercap
interface, only a subset of the options from powercap-info(1) are
available.
Additionally, the \-p and \-z options are different.
.LP
This software requires an Intel processor (Sandy Bridge or newer), Linux
kernel 3.13 or newer compiled with \fBCONFIG_POWERCAP\fR and
\fBCONFIG_INTEL_RAPL\fR enabled, and the \fBintel_rapl\fR kernel module to
be loaded.
.SH "OPTIONS"
.LP
.TP
\fB\-h,\fR \fB\-\-help\fR
Prints out the help screen
.TP
\fB\-v,\fR \fB\-\-verbose\fR
Print errors when files are not available
.TP
\fB\-p,\fR \fB\-\-package\fR=\fIPACKAGE\fP
The package number (none by default; 0 by default if using \-z/\-\-subzone
and/or \-c/\-\-constraint).
Ending with a colon prevents output for subzones.
E.g., for package 0, but not subzones:
.br
\fB\-p 0:\fP
.TP
\fB\-z,\fR \fB\-\-subzone=\fR\fISUBZONE\fP
The package subzone number (none by default)
.TP
\fB\-c,\fR \fB\-\-constraint\fR=\fICONSTRAINT\fP
The constraint number (none by default)
.TP
All remaining options below are mutually exclusive:
.TP
\fB\-n,\fR \fB\-\-nzones\fR
Print the number of packages found, or the number of subzones found if
\-p/\-\-package is set
.LP
The following are zone-level arguments (\-z/\-\-subzone is optional):
.TP
\fB\-j,\fR \fB\-\-z\-energy\fR
Print zone energy counter
.TP
\fB\-J,\fR \fB\-\-z\-max\-energy\-range\fR
Print zone maximum energy counter range
.TP
\fB\-e,\fR \fB\-\-z\-enabled\fR
Print zone enable/disabled status
.TP
\fB\-x,\fR \fB\-\-z\-name\fR
Print zone name
.LP
The following are constraint-level arguments and require
\-c/\-\-constraint (\-z/\-\-subzone is optional):
.TP
\fB\-l,\fR \fB\-\-c\-power\-limit\fR
Print constraint power limit
.TP
\fB\-s,\fR \fB\-\-c\-time\-window\fR
Print constraint time window
.TP
\fB\-U,\fR \fB\-\-c\-max\-power\fR
Print constraint maximum allowed power
.TP
\fB\-y,\fR \fB\-\-c\-name\fR
Print constraint name
.SH "EXAMPLES"
.LP
Note that \-p/\-\-package=0 is used by default when also specifying
\-z/\-\-subzone and/or \-c/\-\-constraint, allowing for simpler commands
on single-socket systems.
.TP
\fBrapl\-info\fP
Print all RAPL zones.
.TP
\fBrapl\-info \-p 0\fP
Print only package 0, which is usually named \fBpackage\-0\fR.
.TP
\fBrapl\-info \-p 0 \-z 1\fP
Print package 0, subzone 1, which is usually the \fBuncore\fR or
\fBdram\fR subzone of \fBpackage\-0\fR, depending on the system.
.TP
\fBrapl\-info \-p 0 \-c 1\fP
Print package 0, constraint 1, which is usually the \fBshort_term\fR
constraint for \fBpackage\-0\fR.
.TP
\fBrapl\-info \-p 0 \-j\fP
Print the energy counter for package 0, which is usually named
\fBpackage\-0\fR.
.TP
\fBrapl\-info \-p 1 \-z 0 \-c 0 \-l\fP
Print the power limit for package 1, subzone 0, constraint 0, which is
usually the \fBlong_term\fR constraint for the \fBcore\fR subzone of
\fBpackage\-1\fR (a multi-socket system).
.SH "REMARKS"
.LP
A package is a zone with constraints.
Subzones are a package's child domains, including power planes.
.LP
If no subzone/constraint-specific outputs are requested, all available
zones and constraints will be shown.
.LP
Energy units: microjoules (uJ)
.br
Power units: microwatts (uW)
.br
Time units: microseconds (us)
.SH "BUGS"
.LP
The following are behavioral quirks due to the kernel interface or
abnormalities in some hardware.
They are not bugs in \fBrapl\-info\fR and should not be reported as such.
.LP
Values returned by the kernel sometimes lose accuracy from the actual
values stored in Model-Specific Registers due to integer rounding.
For example, the kernel may return a time window value of 7812 us, when in
fact the actual stored value is 7812.5 us.
Writing back a value returned by the kernel, e.g., using rapl\-set(1), may
cause unexpected changes to its value due to these rounding problems.
.LP
On some systems, the constraint max_power_uw file, e.g.,
constraint_0_max_power_uw, is known to receive an ENODATA (No data
available) error from the kernel for subzones.
So even though the file exists, a value may not be printed for it.
.LP
It is possible for packages on multi-socket systems to be indexed out of
order by the kernel.
For example, the package at index 0 (\fB\-p 0\fR) could actually be named
\fBpackage\-1\fR while the package at index 1 (\fB\-p 1\fR) is named
\fBpackage\-0\fR.
.LP
Report bugs upstream at <https://github.com/powercap/powercap>
.SH "FILES"
.nf
\fI/sys/devices/virtual/powercap/intel\-rapl/*\fP
.nf
\fI/sys/class/powercap/intel\-rapl/*\fP
.fi
.SH "AUTHORS"
.nf
Connor Imes <connor.k.imes@gmail.com>
.fi
.SH "SEE ALSO"
.LP
rapl\-set(1), powercap-info(1), powercap-set(1)