1PQOS(8)                     System Manager's Manual                    PQOS(8)
2
3
4

NAME

6       pqos,  pqos-msr,  pqos-os - Intel(R) Resource Director Technology moni‐
7       toring and control tool
8

SYNOPSIS

10       pqos [OPTIONS]...
11

DESCRIPTION

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
17       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
23       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       pqos-msr and pqos-os are simple pqos wrapper scripts that automatically
27       select  the MSR or OS/Kernel library interface to program the technolo‐
28       gies.
29       Please see the -I option below for more information.
30
31       For hardware  information  please  refer  to  the  README  located  on:
32       https://github.com/01org/intel-cmt-cat/blob/master/README
33

OPTIONS

35       pqos options are as follow:
36
37       -h, --help
38              show help
39
40       -v, --verbose
41              verbose mode
42
43       -V, --super-verbose
44              super-verbose mode
45
46       -l FILE, --log-file=FILE
47              log messages into selected log FILE
48
49       -s, --show
50              show the current allocation and monitoring configuration
51
52       -d, --display
53              display supported Intel(R) Resource Director Technology capabil‐
54              ities
55
56       -D, --display-verbose
57              display supported Intel(R) Resource Director Technology capabil‐
58              ities in verbose mode
59
60       -f FILE, --config-file=FILE
61              load commands from selected configuration FILE
62
63       -e CLASSDEF, --alloc-class=CLASSDEF
64              define  the allocation classes on all CPU sockets. CLASSDEF for‐
65              mat is "TYPE:ID=DEFINITION;...".
66              define classes for selected CPU resources.  CLASSDEF  format  is
67              "TYPE[@RESOURCE_ID]:ID=DEFINITION;...".
68              For  CAT,  TYPE  is  "llc" for the last level cache (aka l3) and
69              "l2" for level 2 cache, ID is a CLOS number and DEFINITION is  a
70              bitmask.
71              For  MBA, TYPE is "mba", ID is a CLOS number and DEFINITION is a
72              value between 1 and 100 representing the percentage of available
73              memory bandwidth.
74              RESOURCE_ID  is  a  unique number that can represent a socket or
75              l2/l3 cache identifier. The RESOURCE_ID for each logical CPU can
76              be found using "pqos -s"
77              Note:  When  L2/L3  CDP  is on, ID can be postfixed with 'D' for
78              data or 'C' for code.
79              Note: L2/L3 CDP is available on selected CPUs only.
80              Some examples:
81                     "-e
82                     llc:0=0xffff;llc:1=0x00ff;llc@0-1:2=0xff00;l2:2=0x3f;l2@2:1=0xf"
83                     "-e llc:0d=0xfff;llc:0c=0xfff00"
84                     "-e l2:0d=0xf;l2:0c=0xc"
85                     "-e mba:1=30;mba@1:3=80"
86              Note:
87                     "-e l2:2=0x3f" means that COS2 for all L2 cache  clusters
88                     is changed to 0x3f.
89                     "-e l2@2:1=0xf" means that COS1 for L2 cache cluster 2 is
90                     changed to 0xf.
91                     "-e mba:1=30" means that COS1, on all sockets,  can  uti‐
92                     lize up to 30% of available memory bandwidth.
93
94       -a CLASS2ID, --alloc-assoc=CLASS2ID
95              associate  allocation  classes  with  cores.  CLASS2ID format is
96              "TYPE:ID=CORE_LIST;..." or "TYPE:ID=TASK_LIST;...".
97              For CAT, TYPE is "llc", "core" or "pid" and ID is a  class  num‐
98              ber.  CORE_LIST  is  comma  or  dash  separated  list  of cores.
99              TASK_LIST is comma or dash separated list of process/task ID's.
100              For example:
101                     "-a llc:0=0,2,4,6-10;llc:1=1;" associates cores 0, 2,  4,
102                     6, 7, 8, 9, 10 with CAT class 0 and core 1 with class 1.
103                     "-a  core:0=0,2,4,6-10;core:1=1;"  associates cores 0, 2,
104                     4, 6, 7, 8, 9, 10 with CAT class 0 and core 1 with  class
105                     1.
106                     "-I   -a   pid:0=3543,7643,4556;pid:1=7644;"   associates
107                     process ID 3543, 7643, 4556 with CAT class 0 and  process
108                     ID 7644 with class 1.
109              Note:
110                     The -I option must be used for PID association.
111
112       -R [CONFIG[,CONFIG]], --alloc-reset[=CONFIG[,CONFIG]]
113              reset  allocation  setting  (L3  CAT, L2 CAT) and reconfigure L3
114              CDP. CONFIG is one of the following options:
115              l3cdp-on  sets L3 CDP on
116              l3cdp-off sets L3 CDP off
117              l3cdp-any keep current L3 CDP setting (default)
118              l2cdp-on  sets L2 CDP on
119              l2cdp-off sets L2 CDP off
120              l2cdp-any keep current L2 CDP setting (default)
121
122       -m EVTCORES, --mon-core=EVTCORES
123              select the cores and events for monitoring, EVTCORES  format  is
124              "EVENT:CORE_LIST". Valid EVENT settings are:
125              - "llc" for CMT (LLC occupancy)
126              - "mbr" for MBR (remote memory bandwidth)
127              - "mbl" for MBL (local memory bandwidth)
128              - "all" or ""  for all detected event types
129              CORE_LIST is comma or dash separated list of cores.
130              Example "-m all:0,2,4-10;llc:1,3;mbr:11-12".
131              Core  statistics  can  be  grouped by enclosing the core list in
132              square brackets.
133              Example "-m llc:[0-3];all:[4,5,6];mbr:[0-3],7,8".
134
135       -p [EVTPIDS], --mon-pid[=EVTPIDS]
136              select top 10 most active (CPU utilizing) process ids to monitor
137              or select the process ids and events to monitor, EVTPIDS  format
138              is "EVENT:PID_LIST".
139              See  -m option for valid EVENT settings. PID_LIST is comma sepa‐
140              rated list of process ids.
141              Examples:
142                     "-p llc:22,25673"
143                     "-p all:892,4588-4592"
144
145              Process' IDs can be grouped by enclosing them in  square  brack‐
146              ets.
147              Examples:
148                     "-p llc:[22,25673]"
149                     "-p all:892,[4588-4592]"
150
151              Note:
152                     Requires Linux and kernel versions 4.10 and newer.
153                     The -I option must be used for PID monitoring.
154                     It  is  not possible to track both processes and cores at
155                     the same time.
156
157       -T, --mon-top
158              enable top like monitoring output sorted by  highest  LLC  occu‐
159              pancy
160
161       -o FILE, --mon-file FILE
162              select  output  FILE  to store monitored data in, the default is
163              'stdout'
164
165       -u TYPE, --mon-file-type=TYPE
166              select the output format TYPE for monitored data. Supported TYPE
167              settings are: "text" (default), "xml" and "csv".
168
169       -i INTERVAL, --mon-interval=INTERVAL
170              define  monitoring  sampling  INTERVAL  in 100ms units, 1=100ms,
171              default 10=10x100ms=1s
172
173       -t SECONDS, --mon-time=SECONDS
174              define monitoring time in seconds, use 'inf' or  'infinite'  for
175              infinite monitoring. Use CTRL+C to stop monitoring at any time.
176
177       -r, --mon-reset
178              reset monitoring and use all RMID's and cores in the system
179
180       -H, --profile-list
181              list supported allocation profiles
182
183       -c PROFILE, --profile-set=PROFILE
184              select  a  PROFILE from predefined allocation classes, use -H to
185              list available profiles
186
187       -I, --iface-os
188              set the library interface to use the kernel  implementation.  If
189              not  set  the  default  implementation  is  to program the MSR's
190              directly.
191

NOTES

193       CMT, MBM and CAT are configured using Model Specific Registers  (MSRs).
194       The  pqos  software  executes  in user space, and access to the MSRs is
195       obtained through a standard Linux* interface. The msr file interface is
196       protected  and  requires  root privileges.  The msr driver might not be
197       auto-loaded and on some modular kernels  the  driver  may  need  to  be
198       loaded manually:
199
200       For Linux:
201       sudo modprobe msr
202
203       For FreeBSD:
204       sudo kldload cpuctl
205
206       Interface enforcement:
207       If  you require system wide interface enforcement you can do so by set‐
208       ting the "RDT_IFACE" environment variable.
209

SEE ALSO

211       msr(4)
212

AUTHOR

214       pqos was written by Tomasz Kantecki <tomasz.kantecki@intel.com>, Marcel
215       Cornu  <marcel.d.cornu@intel.com>, Aaron Hetherington <aaron.hethering‐
216       ton@intel.com>
217
218       This is free software; see the source for copying conditions.  There is
219       NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
220       PURPOSE.
221
222
223
224                               November 16, 2017                       PQOS(8)
Impressum