| 1 |
|
| 2 |
|
| 3 |
======================================================================== |
| 4 |
README for PQoS/Intel(R) RDT utility |
| 5 |
|
| 6 |
January 2019 |
| 7 |
|
| 8 |
======================================================================== |
| 9 |
|
| 10 |
|
| 11 |
Contents |
| 12 |
======== |
| 13 |
|
| 14 |
- Overview |
| 15 |
- Requirements and Installation |
| 16 |
- Usage |
| 17 |
- Legal Disclaimer |
| 18 |
|
| 19 |
|
| 20 |
Overview |
| 21 |
======== |
| 22 |
|
| 23 |
This software package provides basic support for |
| 24 |
Cache Monitoring Technology (CMT), Memory Bandwidth Monitoring (MBM), |
| 25 |
Cache Allocation Technology (CAT) and Memory Bandwidth Allocation (MBA). |
| 26 |
This release supports last level cache occupancy monitoring and |
| 27 |
memory bandwidth monitoring on a per core or logical thread basis. |
| 28 |
MBM supports two types of events reporting local and remote |
| 29 |
memory bandwidth. |
| 30 |
Both events are reported on a per core or logical thread basis. |
| 31 |
Local memory bandwidth reports the bandwidth of a thread accessing |
| 32 |
memory associated with the local socket. |
| 33 |
In a dual socket system, the remote memory bandwidth reports the |
| 34 |
bandwidth of a thread accessing the remote socket. |
| 35 |
The monitoring utility does not track application migration across |
| 36 |
cores as this would require scheduler integration. |
| 37 |
Instead, applications should be pinned to cores to track |
| 38 |
last level cache occupancy and memory bandwidth. |
| 39 |
Scheduler-integrated alternatives such as cgroups and perf are being |
| 40 |
researched to track the application PID (and all associated TIDs) |
| 41 |
rather than static assignment. The monitoring utility currently associates |
| 42 |
a Resource Monitoring ID (RMID) per hardware thread or group of hardware |
| 43 |
threads when monitoring is started. By default, PID tracking is not enabled. |
| 44 |
Details on enabling this feature can be found in INSTALL and lib/README. |
| 45 |
|
| 46 |
The command line utility provides the necessary functionality to set |
| 47 |
up the CAT capabilities. The software provides flags to configure the |
| 48 |
class of service (CLOS) and associate cores / logical threads with a |
| 49 |
class of service. |
| 50 |
|
| 51 |
MBA controller allows to specify memory bandwidth in MBps instead of percentage. |
| 52 |
It is supported only on OS interface and requires Linux kernel |
| 53 |
4.18 or above. |
| 54 |
|
| 55 |
Use of concurrent monitoring instances is possible as long as each |
| 56 |
instance monitors exclusive set of cores. Library APIs are also thread safe. |
| 57 |
|
| 58 |
For additional CMT, MBM, CAT and MBA details please refer to the Intel(R) |
| 59 |
Architecture Software Development Manuals available at: |
| 60 |
http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html |
| 61 |
Specific information with regard to CMT, MBM, CAT and MBA can be found in |
| 62 |
Chapter 17.18 and 17.19 (SDM volume 3, version 065). |
| 63 |
|
| 64 |
|
| 65 |
Requirements and Installation |
| 66 |
============================= |
| 67 |
|
| 68 |
For installation of the Intel(R) RDT utility, ensure the library is |
| 69 |
installed and follow below instructions to create pqos executable. |
| 70 |
|
| 71 |
To compile Intel(R) RDT utility: |
| 72 |
"make" or "make all" for building utility. |
| 73 |
"make all DEBUG=y" for building utility for debugging. |
| 74 |
"make clean" for clearing even more files than "make rinse". |
| 75 |
Note: Having both local and installed copies of the library |
| 76 |
may cause undefined behaviour when building the utility. |
| 77 |
|
| 78 |
To install the Intel(R) RDT utility (optional), first compile, then: |
| 79 |
"sudo make install" to install below /usr/local. |
| 80 |
"sudo make install PREFIX=/some/where" to install below /some/where. |
| 81 |
|
| 82 |
|
| 83 |
Note: For installation of the PQoS utility on FreeBSD, simply follow the steps |
| 84 |
above for Linux installation replacing "make" with "gmake". |
| 85 |
|
| 86 |
Currently verified configuration is: |
| 87 |
- FreeBSD 9.1 |
| 88 |
- GNU Compiler Collection 5 (gcc 5.3.1) |
| 89 |
- GNU Make 4.1 |
| 90 |
|
| 91 |
|
| 92 |
Usage |
| 93 |
===== |
| 94 |
|
| 95 |
After compilation the PQoS executable can be used to configure the |
| 96 |
last level cache allocation feature and monitor the last level cache |
| 97 |
occupancy as well as memory bandwidth. |
| 98 |
|
| 99 |
Usage: For pqos utility: |
| 100 |
"./pqos -h" This option will display extensive help page. |
| 101 |
Please refer to "-h" option for usage details. |
| 102 |
"./pqos -s" Shows current Intel(R) RDT configuration. |
| 103 |
"./pqos -d" Shows detected Intel(R) RDT capabilities (-D for verbose mode). |
| 104 |
"./pqos -T" Starts CMT and MBM monitoring on all detected |
| 105 |
cores (depends of hardware feature availability). |
| 106 |
Note: It may be necessary to set "LD_LIBRARY_PATH=path/to/libpqos.so" |
| 107 |
when running the utility with local shared library. |
| 108 |
|
| 109 |
Legal Disclaimer |
| 110 |
================ |
| 111 |
|
| 112 |
THIS SOFTWARE IS PROVIDED BY INTEL"AS IS". NO LICENSE, EXPRESS OR |
| 113 |
IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS |
| 114 |
ARE GRANTED THROUGH USE. EXCEPT AS PROVIDED IN INTEL'S TERMS AND |
| 115 |
CONDITIONS OF SALE, INTEL ASSUMES NO LIABILITY WHATSOEVER AND INTEL |
| 116 |
DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR |
| 117 |
USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO |
| 118 |
FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT |
| 119 |
OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. |