Debian Codegraph @

pqos/README

raw
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.