========================================================================
README for PQoS/Intel(R) RDT utility

February 2018

========================================================================


Contents
========

- Overview
- Requirements and Installation
- Usage
- Legal Disclaimer


Overview
========

This software package provides basic support for
Cache Monitoring Technology (CMT), Memory Bandwidth Monitoring (MBM)
and Cache Allocation Technology (CAT).
This release 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.
Both events are reported on a per core or logical thread basis.
Local memory bandwidth reports the bandwidth of a thread accessing
memory associated with the local socket.
In a dual socket system, the remote memory bandwidth reports the
bandwidth of a thread accessing the remote socket.
The monitoring utility does not track application migration across
cores as this would require scheduler integration.
Instead, applications should be pinned to cores to track
last level cache occupancy and memory bandwidth.
Scheduler-integrated alternatives such as cgroups and perf are being
researched to track the application PID (and all associated TIDs)
rather than static assignment. The monitoring utility currently associates
a Resource Monitoring ID (RMID) per hardware thread or group of hardware
threads when monitoring is started. By default, PID tracking is not enabled.
Details on enabling this feature can be found in INSTALL and lib/README.

The command line utility provides the necessary functionality to set
up the CAT capabilities. The software provides flags to configure the
class of service (CLOS) and associate cores / logical threads with a
class of service.

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.18 and 17.19 (SDM version 065).


Requirements and Installation
=============================

For installation of the Intel(R) RDT utility, ensure the library is
installed and follow below instructions to create pqos executable.

To compile Intel(R) RDT utility:
        "make" or "make all" for building utility.
        "make all DEBUG=y" for building utility for debugging.
        "make clean" for clearing even more files than "make rinse".
        Note: Having both local and installed copies of the library
        may cause undefined behaviour when building the utility.

To install the Intel(R) RDT utility (optional), first compile, then:
        "sudo make install" to install below /usr/local.
        "sudo make install PREFIX=/some/where" to install below /some/where.


Note: For installation of the PQoS utility on FreeBSD, simply follow the steps
      above for Linux installation replacing "make" with "gmake".

Currently verified configuration is:
- FreeBSD 9.1
- GNU Compiler Collection 5 (gcc 5.3.1)
- GNU Make 4.1


Usage
=====

After compilation the PQoS executable can be used to configure the
last level cache allocation feature and monitor the last level cache
occupancy as well as memory bandwidth.

Usage: For pqos utility:
        "./pqos -h"    This option will display extensive help page.
                       Please refer to "-h" option for usage details.
        "./pqos -s"    Shows current Intel(R) RDT configuration.
        "./pqos -d"    Shows detected Intel(R) RDT capabilities (-D for verbose mode).
        "./pqos -T"    Starts CMT and MBM monitoring on all detected
                       cores (depends of hardware feature availability).
        Note: It may be necessary to set "LD_LIBRARY_PATH=path/to/libpqos.so"
              when running the utility with local shared library.

Legal Disclaimer
================

THIS SOFTWARE IS PROVIDED BY INTEL"AS IS". NO LICENSE, EXPRESS OR
IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS
ARE GRANTED THROUGH USE. EXCEPT AS PROVIDED IN INTEL'S TERMS AND
CONDITIONS OF SALE, INTEL ASSUMES NO LIABILITY WHATSOEVER AND INTEL
DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR
USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO
FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT
OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.