1PQOS(8) System Manager's Manual PQOS(8)
2
6 pqos - Intel(R) Resource Director Technology monitoring and control
7 tool
8
10 pqos [OPTIONS]...
11
13 Intel(R) Resource Director Technology is designed to monitor and manage
14 cpu resources and improve performance of applications and virtual
15 machines.
16 Intel(R) Resource Director Technology includes monitoring and control
18 technologies. Monitoring technologies include CMT (Cache Monitoring
19 Technology), which monitors occupancy of last level cache, and MBM
20 (Memory Bandwidth Monitoring). Control technologies include CAT (Cache
21 Allocation Technology) and CDP (Code Data Prioritization).
22 pqos supports CMT and MBM on a per core or hardware thread basis. MBM
24 supports two types of events reporting local and remote memory band‐
25 width.
26 For hardware information please refer to the README located on:
28 https://github.com/01org/intel-cmt-cat/blob/master/README
29
31 pqos options are as follow:
32 -h, --help
34 show help
35 -v, --verbose
37 verbose mode
38 -V, --super-verbose
40 super-verbose mode
41 -l FILE, --log-file=FILE
43 log messages into selected log FILE
44 -s, --show
46 show the current allocation and monitoring configuration
47 -f FILE, --config-file=FILE
49 load commands from selected configuration FILE
50 -e CLASSDEF, --alloc-class=CLASSDEF
52 define the allocation classes on all CPU sockets. CLASSDEF for‐
53 mat is "TYPE:ID=DEFINITION;...".
54 define classes for selected CPU resources. CLASSDEF format is
55 "TYPE[@RESOURCE_ID]:ID=DEFINITION;...".
56 For CAT, TYPE is "llc" for the last level cache (aka l3) and
57 "l2" for level 2 cache, ID is a CLOS number and DEFINITION is a
58 bitmask.
59 For MBA, TYPE is "mba", ID is a CLOS number and DEFINITION is a
60 value between 1 and 100 representing the percentage of available
61 memory bandwidth.
62 RESOURCE_ID is a unique number that can represent a socket or
63 l2/l3 cache identifier. The RESOURCE_ID for each logical CPU can
64 be found using "pqos -s"
65 Note: When CDP is on, ID can be postfixed with 'D' for data or
66 'C' for code. CDP is not available for l2.
67 Some examples:
68 "-e
69 llc:0=0xffff;llc:1=0x00ff;llc@0-1:2=0xff00;l2:2=0x3f;l2@2:1=0xf"
70 "-e llc:0d=0xfff;llc:0c=0xfff00"
71 "-e mba:1=30;mba@1:3=80"
72 Note:
73 "-e l2:2=0x3f" means that COS2 for all L2 cache clusters
74 is changed to 0x3f.
75 "-e l2@2:1=0xf" means that COS1 for L2 cache cluster 2 is
76 changed to 0xf.
77 "-e mba:1=30" means that COS1, on all sockets, can uti‐
78 lize up to 30% of available memory bandwidth.
79 -a CLASS2CORE, --alloc-assoc=CLASS2CORE
81 associate allocation classes with cores. CLASS2CORE format is
82 "TYPE:ID=CORE_LIST;...".
83 For CAT, TYPE is "llc" and ID is a class number. CORE_LIST is
84 comma or dash separated list of cores.
85 For example "-a llc:0=0,2,4,6-10;llc:1=1;" associates cores 0,
86 2, 4, 6, 7, 8, 9, 10 with CAT class 0 and core 1 with class 1.
87 -R [CONFIG], --alloc-reset[=CONFIG]
89 reset allocation setting (L3 CAT, L2 CAT) and reconfigure L3
90 CDP. CONFIG is one of the following options:
91 l3cdp-on sets L3 CDP on
92 l3cdp-off sets L3 CDP off
93 l3cdp-any keep current L3 CDP setting (default)
94 -m EVTCORES, --mon-core=EVTCORES
96 select the cores and events for monitoring, EVTCORES format is
97 "EVENT:CORE_LIST". Valid EVENT settings are:
98 - "llc" for CMT (LLC occupancy)
99 - "mbr" for MBR (remote memory bandwidth)
100 - "mbl" for MBL (local memory bandwidth)
101 - "all" or "" for all detected event types
102 CORE_LIST is comma or dash separated list of cores.
103 Example "-m all:0,2,4-10;llc:1,3;mbr:11-12".
104 Core statistics can be grouped by enclosing the core list in
105 square brackets.
106 Example "-m llc:[0-3];all:[4,5,6];mbr:[0-3],7,8".
107 -p EVTPIDS, --mon-pid=EVTPIDS
109 select the process ids and events to monitor, EVTPIDS format is
110 "EVENT:PID_LIST". See -m option for valid EVENT settings.
111 PID_LIST is comma separated list of process ids.
112 Examples "-p llc:22,25673" or "-p all:892,4588-4592".
113 Note: it is not possible to track both processes and cores at
114 the same time.
115 Note: Process tracking depends on the library to be built with
116 PID API.
117 -T, --mon-top
119 enable top like monitoring output sorted by highest LLC occu‐
120 pancy
121 -o FILE, --mon-file FILE
123 select output FILE to store monitored data in, the default is
124 'stdout'
125 -u TYPE, --mon-file-type=TYPE
127 select the output format TYPE for monitored data. Supported TYPE
128 settings are: "text" (default), "xml" and "csv".
129 -i INTERVAL, --mon-interval=INTERVAL
131 define monitoring sampling INTERVAL in 100ms units, 1=100ms,
132 default 10=10x100ms=1s
133 -t SECONDS, --mon-time=SECONDS
135 define monitoring time in seconds, use 'inf' or 'infinite' for
136 infinite monitoring. Use CTRL+C to stop monitoring at any time.
137 -r, --mon-reset
139 reset monitoring and use all RMID's and cores in the system
140 -H, --profile-list
142 list supported allocation profiles
143 -c PROFILE, --profile-set=PROFILE
145 select a PROFILE from predefined allocation classes, use -H to
146 list available profiles
147
149 CMT, MBM and CAT are configured using Model Specific Registers (MSRs).
150 The pqos software executes in user space, and access to the MSRs is
151 obtained through a standard Linux* interface. The msr file interface is
152 protected and requires root privileges. The msr driver might not be
153 auto-loaded and on some modular kernels the driver may need to be
154 loaded manually:
155 For Linux:
157 sudo modprobe msr
158 For FreeBSD:
160 sudo kldload cpuctl
161
163 msr(4)
164
166 pqos was written by Tomasz Kantecki <tomasz.kantecki@intel.com>, Marcel
167 Cornu <marcel.d.cornu@intel.com>
168 This is free software; see the source for copying conditions. There is
170 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
171 PURPOSE.
172 January 5, 2017 PQOS(8)