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)