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

AUTHOR

pqos was written by Tomasz Kantecki <[email protected]>

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.