# Intel Platform Shared Resource Monitoring/Control in xl

This document introduces Intel Platform Shared Resource Monitoring/Control technologies, their basic concepts and the xl interfaces.

## Cache Monitoring Technology (CMT)

Cache Monitoring Technology (CMT) is a new feature available on Intel Haswell and later server platforms that allows an OS or Hypervisor/VMM to determine the usage of cache (currently only L3 cache supported) by applications running on the platform. A Resource Monitoring ID (RMID) is the abstraction of the application(s) that will be monitored for its cache usage. The CMT hardware tracks cache utilization of memory accesses according to the RMID and reports monitored data via a counter register.

For more detailed information please refer to Intel SDM chapter "Platform Shared Resource Monitoring: Cache Monitoring Technology".

In Xen's implementation, each domain in the system can be assigned a RMID independently, while RMID=0 is reserved for monitoring domains that don't have CMT service attached. RMID is opaque for xl/libxl and is only used in hypervisor.

### xl interfaces

A domain is assigned a RMID implicitly by attaching it to CMT service:

`xl psr-cmt-attach <domid>`

After that, cache usage for the domain can be shown by:

`xl psr-cmt-show cache-occupancy <domid>`

Once monitoring is not needed any more, the domain can be detached from the CMT service by:

`xl psr-cmt-detach <domid>`

An attach may fail because of no free RMID available. In such case unused RMID(s) can be freed by detaching corresponding domains from CMT service.

Maximum RMID and supported monitor types in the system can be obtained by:

`xl psr-hwinfo --cmt`

## Memory Bandwidth Monitoring (MBM)

Memory Bandwidth Monitoring(MBM) is a new hardware feature available on Intel Broadwell and later server platforms which builds on the CMT infrastructure to allow monitoring of system memory bandwidth. It introduces two new monitoring event type to monitor system total/local memory bandwidth. The same RMID can be used to monitor both cache usage and memory bandwidth at the same time.

For more detailed information please refer to Intel SDM chapter "Overview of Cache Monitoring Technology and Memory Bandwidth Monitoring".

In Xen's implementation, MBM shares the same set of underlying monitoring service with CMT and can be used to monitor memory bandwidth on a per domain basis.

The xl interfaces are the same with that of CMT. The difference is the monitor type is corresponding memory monitoring type (local-mem-bandwidth/ total-mem-bandwidth instead of cache-occupancy). E.g. after a `xl psr-cmt-attach`:

`xl psr-cmt-show local-mem-bandwidth <domid>`

`xl psr-cmt-show total-mem-bandwidth <domid>`

## Cache Allocation Technology (CAT)

Cache Allocation Technology (CAT) is a new feature available on Intel Broadwell and later server platforms that allows an OS or Hypervisor/VMM to partition cache allocation (i.e. L3 cache) based on application priority or Class of Service (COS). Each COS is configured using capacity bitmasks (CBM) which represent cache capacity and indicate the degree of overlap and isolation between classes. System cache resource is divided into numbers of minimum portions which is then made up into subset for cache partition. Each portion corresponds to a bit in CBM and the set bit represents the corresponding cache portion is available.

For example, assuming a system with 8 portions and 3 domains:

- A CBM of 0xff for every domain means each domain can access the whole cache. This is the default.

- Giving one domain a CBM of 0x0f and the other two domain's 0xf0 means that the first domain gets exclusive access to half of the cache (half of the portions) and the other two will share the other half.

- Giving one domain a CBM of 0x0f, one 0x30 and the last 0xc0 would give the first domain exclusive access to half the cache, and the other two exclusive access to one quarter each.

For more detailed information please refer to Intel SDM chapter "Platform Shared Resource Control: Cache Allocation Technology".

In Xen's implementation, CBM can be configured with libxl/xl interfaces but COS is maintained in hypervisor only. The cache partition granularity is per domain, each domain has COS=0 assigned by default, the corresponding CBM is all-ones, which means all the cache resource can be used by default.

### xl interfaces

System CAT information such as maximum COS and CBM length can be obtained by:

`xl psr-hwinfo --cat`

The simplest way to change a domain's CBM from its default is running:

`xl psr-cat-cbm-set [OPTIONS] <domid> <cbm>`

where cbm is a number to represent the corresponding cache subset can be used. A cbm is valid only when:

- Set bits only exist in the range of [0, cbm_len), where cbm_len can be obtained with `xl psr-hwinfo --cat`.
- All the set bits are contiguous.

In a multi-socket system, the same cbm will be set on each socket by default. Per socket cbm can be specified with the `--socket SOCKET` option.

Setting the CBM may not be successful if insufficient COS is available. In such case unused COS(es) may be freed by setting CBM of all related domains to its default value(all-ones).

Per domain CBM settings can be shown by:

`xl psr-cat-show`

## Code and Data Prioritization (CDP)

Code and Data Prioritization (CDP) Technology is an extension of CAT, which is available on Intel Broadwell and later server platforms. CDP enables isolation and separate prioritization of code and data fetches to the L3 cache in a software configurable manner, which can enable workload prioritization and tuning of cache capacity to the characteristics of the workload. CDP extends Cache Allocation Technology (CAT) by providing separate code and data masks per Class of Service (COS).

CDP can be enabled by adding `psr=cdp` to Xen command line.

When CDP is enabled,

- the CAT masks are re-mapped into interleaved pairs of masks for data or code fetches.

- the range of COS for CAT is re-indexed, with the lower-half of the COS range available for CDP.

CDP allows the OS or Hypervisor to partition cache allocation in a more fine-grained manner. Code cache and data cache can be specified independently. With CDP enabled, one COS corresponds to two CBMs (code CBM & data CBM), since the sum of CBMs is fixed, that means the number of available COSes will reduce by half when CDP is on.

For more detailed information please refer to Intel SDM chapter "Platform Shared Resource Control: Cache Allocation Technology".

The xl interfaces are the same with that of CAT. The difference is that CBM type can be passed as option to set code CBM or data CBM.

When CDP is enabled, `-c` or `--code` option is available to set code CBM for the domain.

When CDP is enabled, `-d` or `--data` option is available to set data CBM for the domain.

If neither `-c` nor `-d` option is specified when CDP is on, the same code CBM and data CBM will be set for the domain. Passing both `-c` and `-d` options is invalid.

Example:

Setting code CBM for a domain: `xl psr-cat-cbm-set -c <domid> <cbm>`

Setting data CBM for a domain: `xl psr-cat-cbm-set -d <domid> <cbm>`

Setting the same code and data CBM for a domain: `xl psr-cat-cbm-set <domid> <cbm>`

## Reference

[1] Intel SDM (http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html).