Provided by: intel-cmt-cat_0.1.4-1_amd64 
NAME
pqos - Intel Platform Quality of Service
SYNOPSIS
pqos [OPTIONS]...
DESCRIPTION
Intel Platform QoS technologies (also known as Intel Platform Shared Resource Monitoring/Control
technologies) are designed to help improve performance and manageability for virtual machines.
The pqos tool provides support to set up the Intel CAT (Cache Allocation Technology) capabilities, and
monitor last level cache occupancy via CMT (Cache Monitoring Technology) and monitor memory bandwidth via
MBM (Memory Bandwidth Monitoring).
pqos supports last level cache occupancy monitoring and memory bandwidth monitoring on a per core or
logical thread basis. MBM supports two types of events reporting local and remote memory bandwidth.
The software provides flags to configure the class of service (CLOS) and associate cores / logical
threads with a class of service. The Intel(R) Xeon(R) processor E5 v3 generation supports four classes of
service and a set of pre-defined classes of service that should not be changed at run time. Intel(R)
Xeon(R) processor D generation supports sixteen classes of service. There are no pre-defined classes of
service and they can be changed at run time. Intel(R) Xeon(R) processor E5 v3 and Intel(R) Xeon(R)
processor D generations supports Core/Logical thread association with a class of service can be changed
dynamically.
CMT is supported on all Intel(R) Xeon(R) processor E5 v3 and Intel(R) Xeon(R) processor D SKUs.
CAT is supported on the following: 6 SKUs for Intel(R) Xeon(R) processor E5 v3 family: E5-2658 v3,
E5-2648L v3, E5-2628L v3, E5-2618L v3, E5-2608L v3 and E5-2658A v3 2 SKUs for Intel(R) Xeon(R) processor
E3 v4 family: E3-1258L v4 and E3-1278L v4 and all Intel(R) Xeon(R) processor D SKUs.
Use of concurrent monitoring instances is possible as long as each instance monitors exclusive set of
cores. Library APIs are also thread safe.
For additional CMT, MBM and CAT details please see refer to the Intel(R) Architecture Software
Development Manuals available at: http://www.intel.com/content/www/us/en/processors/architectures-
software-developer-manuals.html Specific information with regard to CMT, MBM and CAT can be found in
Chapter 17.14 and 17.15.
OPTIONS
pqos options are as follow:
-h, --help
show help
-v, --verbose
verbose mode
-V, --super-verbose
super-verbose mode
-l FILE, --log-file=FILE
log messages into selected log FILE
-s, --show
show the current allocation and monitoring configuration
-S cdp-on|cdp-off|cdp-any, --set cdp-on|cdp-off|cdp-any
cdp-on sets CDP on
cdp-off sets CDP off
cdp-any keep current CDP setting (default)
-f FILE, --config-file=FILE
load commands from selected configuration FILE
-e CLASSDEF, --alloc-class=CLASSDEF
define the allocation classes. CLASSDEF format is "TYPE:ID=DEFINITION;...".
For CAT, TYPE is "llc", ID is a CLOS number and DEFINITION is a bitmask.
For example: "-e llc:0=0xffff;llc:1=0x00ff;".
-a CLASS2CORE, --alloc-assoc=CLASS2CORE
associate allocation classes with cores. CLASS2CORE format is "TYPE:ID=CORE_LIST;...".
For CAT, TYPE is "llc" and ID is a class number. CORE_LIST is comma or dash separated list of
cores.
For example "-a llc:0=0,2,4,6-10;llc:1=1;" associates cores 0, 2, 4, 6, 7, 8, 9, 10 with CAT class
0 and core 1 with class 1.
-R, --alloc-reset
reset the CAT configuration
-m EVTCORES, --mon-core=EVTCORES
select the cores and events for monitoring, EVTCORES format is "EVENT:CORE_LIST". Valid EVENT
settings are:
- "llc" for CMT (LLC occupancy)
- "mbr" for MBR (remote memory bandwidth)
- "mbl" for MBL (local memory bandwidth)
- "all" or "" for all detected event types
CORE_LIST is comma or dash separated list of cores.
Example "-m all:0,2,4-10;llc:1,3;mbr:11-12".
Core statistics can be grouped by enclosing the core list in square brackets.
Example "-m llc:[0-3];all:[4,5,6];mbr:[0-3],7,8".
-p EVTPIDS, --mon-pid=EVTPIDS
select the process ids and events to monitor, EVTPIDS format is "EVENT:PID_LIST". See -m option
for valid EVENT settings. PID_LIST is comma separated list of process ids.
Examples "-p llc:22,25673" or "-p all:892,4588-4592".
Note: it is not possible to track both processes and cores at the same time.
-T, --mon-top
enable top like monitoring output sorted by highest LLC occupancy
-o FILE, --mon-file FILE
select output FILE to store monitored data in, the default is 'stdout'
-u TYPE, --mon-file-type=TYPE
select the output format TYPE for monitored data. Supported TYPE settings are: "text" (default),
"xml" and "csv".
-i INTERVAL, --mon-interval=INTERVAL
define monitoring sampling INTERVAL in 100ms units, 1=100ms, default 10=10x100ms=1s
-t SECONDS, --mon-time=SECONDS
define monitoring time in seconds, use 'inf' or 'infinite' for infinite monitoring. Use CTRL+C to
stop monitoring at any time.
-r, --mon-reset
reset monitoring and use all RMID's and cores in the system
-H, --profile-list
list supported allocation profiles
-c PROFILE, --profile-set=PROFILE
select a PROFILE from predefined allocation classes, use -H to list available profiles
NOTES
CMT, MBM and CAT are configured using Model Specific Registers (MSRs) to measure occupancy, set up the
class of service masks and manage the association of the cores/logical threads to a class of service.
The pqos software executes in user space, and access to the MSRs is obtained through a standard Linux*
interface. The virtual file system structure /dev/cpu/CPUNUM/msr provides an interface to read and write
the MSRs. The msr file interface is protected and requires root privileges. The msr driver might not be
auto-loaded and on some modular kernels the driver may need to be loaded manually:
sudo modprobe msr
SEE ALSO
msr(4)
AUTHOR
pqos was written by Tomasz Kantecki <tomasz.kantecki@intel.com> This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. January 5, 2016 PQOS(8)