intel-cmt-cat programs Intel RDT caches and memory bandwidth from user space

What the package programs on the hardware

This software package provides basic support for Intel(R) Resource Director Technology (Intel(R) RDT) and Intel(R) I/O Resource Director Technology (Intel(R) I/O RDT), covering Cache Monitoring Technology (CMT), Memory Bandwidth Monitoring (MBM), Cache Allocation Technology (CAT), Code and Data Prioritization (CDP) and Memory Bandwidth Allocation (MBA).

The mechanism is direct. In principle, the software programs the technologies via Model Specific Registers (MSR) on a hardware thread basis. The MSR access is arranged via a standard operating system driver: msr on Linux and cpuctl on FreeBSD.

That gives a clear picture of what the package is for. These are hardware features that a processor exposes through architectural MSRs, and the package is the user space software that writes those registers and reads back the counters. It is not a scheduler, not a hypervisor component and not a monitoring agent that ships telemetry to a backend. It is a control and observation layer.

Detection follows the same layering. In the most common architectural implementations, presence of the technologies is detected via the CPUID instruction. In a limited number of special cases where CAT is not architecturally supported on a particular SKU, but a non-architectural, model-specific, implementation exists, it can be detected via brand string. The brand string is read from CPUID and compared to a table of known-supported SKUs. If needed, a final check is to probe the specific MSRs to discover hardware capabilities, though the README recommends that CPUID enumeration be used wherever possible.

That three-stage detection, CPUID first, brand string as a fallback, MSR probing as a last resort, is a good indicator of how the package is built around a real hardware reality where feature availability is not uniform across SKUs.

The homepage for the technology is Intel's Resource Director Technology page, and the repository itself is under the intel organisation. The primary language is C, the default branch is master, and the last push was on 2026-10-20.

Two interfaces, and the OS one became the default

The library and utilities offer two interfaces to program Intel RDT technologies, and the difference between them decides what granularity you get.

The MSR interface configures the platform by programming the hardware MSRs directly. The README calls it the legacy interface, and it requires no kernel support for Intel RDT but is limited to monitoring and managing resources on a per core basis.

The OS interface was added later and, when selected, uses Linux kernel extensions to program the technologies. This allows monitoring and managing resources on a per core and per process basis, and the README says it should be used when available.

The history of the kernel side explains why there are two. Linux kernel support for Intel RDT was originally introduced with Linux perf system call extensions for CMT and MBM, and more recently the Resctrl interface added support for CAT, CDP and MBA. On modern kernels the README advises using the kernel and OS interface when it is available, with details in resctrl_ui.txt.

The library detects which interfaces are present and lets you select the preferred one through a configuration option. From software version v1.0.0 that option exists, and as of release v4.3.0 the OS interface became the default. The practical effect for existing users is a behaviour change that happened silently between releases: an installation that used to write MSRs may now go through resctrl.

Two utility wrappers were added to help with the interface selection: pqos-os and pqos-msr, for OS and MSR interface operations respectively. That is the answer to the question a new user will ask first, which is how to force one path or the other for a specific run.

One API change is also worth knowing. The PID API compile time option has been removed and the APIs are always available, and the README notes that proper operation of those APIs depends on the availability and selection of the OS interface.

What is in the package: library, pqos, examples, membw

The top level of the repository maps onto the roles a user has.

The lib directory includes software library files providing APIs for technology detection, monitoring and allocation, and the library has its own README at lib/README. The pqos directory includes source files for a utility that provides command line access to Intel RDT. It links against the library and programs the technologies via its APIs, and there is a README in pqos/README plus a manual page.

That manual page is the first place to look for the command line surface:

$ man pqos

The examples directory includes C and Perl examples of Intel RDT usage via the library APIs, with a README at examples/README and a C example under examples/c. The tools directory includes a membw tool for stressing memory bandwidth with different operations, which is a genuinely useful companion because it gives you a workload to watch while you change allocation.

The rest is packaging and housekeeping. The srpm directory holds *.src, *.rpm and *.spec files for the software package, and there is an rpm directory at the top level as well. The ChangeLog file gives a brief description of changes between releases, the INSTALL file holds installation instructions, the LICENSE file holds the licence of the package, and the unit-test directory holds unit tests. The tests directory covers broader testing, and there is a .clang-format file, a .checkpatch.types file and a .dockerignore, which suggests the code is held to kernel-style formatting and review conventions.

The library is also usable from more than C. The Perl examples, together with the swig topic and the presence of a lib/python licence badge in the README, point at a Python binding path in the tree. That matters for scripting a monitoring loop without writing a C program.

Installing: the INSTALL file, and the srpm route

The README does not put the installation steps in the README itself. It points at the INSTALL file for package installation instructions, and separately at the wiki, which provides FAQ, usage examples and useful links.

For distributions that want a native package, the srpm directory is the reference implementation of that path, holding the source RPM, the RPM and the spec file. The presence of a top level rpm directory and the spec file in srpm means the packaging is versioned in the repository rather than being maintained separately, which is what you want when you are tracking a specific upstream release.

Building from source follows the conventional make path. The Makefile carries the BSD licence text at the top with the copyright line for Intel Corporation, and the build targets are for the sample application, which the header describes as the PQoS sample application. There is also a pre-build.mk file at the top level, and the.dockerignore suggests the project also expects to be built inside a container.

The licence situation has one wrinkle worth flagging. The licence is recorded as Other, a custom licence GitHub cannot classify, and the README badge points at a BSD 3-Clause licence file under lib/python/LICENSE. So the package as a whole is governed by the LICENSE file at the root, while the Python component carries its own BSD 3-Clause file. If you are redistributing or shipping a build, read both files rather than relying on the badge.

For the FreeBSD port, note the qualification later in this article.

Hardware support, and the model-specific probe you have to opt into

Which processors qualify is not decided by this package. Supported products are found in Addendum A of the Intel RDT Architecture Specification, and Addendum B contains a list of processors with model-specific Intel RDT features.

That second addendum is where the caveat lives, and it is a real limitation rather than a detail. Detection of model-specific features requires the RDT_PROBE_MSR environment variable to be set when using the library and utilities, and these features are only available when using the MSR interface.

So there is a three-way dependency in the model-specific path: the CPU has to be on the Addendum B list, the environment variable has to be set for the process, and the interface selection has to be the MSR one. Miss any of the three and the feature is simply absent, with no error telling you why.

The README links a wiki page of usage examples for exactly this case, under the heading for using model-specific, non-architectural, features. That is where the environment variable is documented in context.

For deeper hardware detail the README points to the Intel Architecture Software Development Manuals, with the specific information in volume 3a, chapters 17.18 and 17.19. Chapter-level pointers like that are useful, because the alternative is searching a very large manual for the register definitions the code writes.

The detection order discussed earlier also ties in here. CPUID enumeration is the recommended path because it is the architectural method. The brand string comparison and the MSR probe exist for the SKUs where the architectural path reports nothing useful.

OS support: Linux first, FreeBSD experimental, old kernels tolerated

Linux is the primary supported operating system. There is a FreeBSD port of the software, but the README describes it as rather experimental at this stage due to a limited validation scope.

The most interesting property of the package on the OS side is its age tolerance. Although most modern Linux kernels include support for Intel RDT, the package predates those kernel extensions and can operate with and without kernel support. It detects and leverages the kernel extensions when they are available to add functionality, and it is also compatible with legacy kernels.

That is a deliberate design choice, and it is the difference between a package that runs on the machine in front of you and one that requires a kernel upgrade. For a deployment where you need to instrument an existing fleet, running the OS interface is a bonus rather than a precondition.

The interface table in the README tracks when each RDT feature became available under each interface and what kernel version each requires, which is the document to consult before pinning a kernel version. The change is real: CMT and MBM came through the perf system call extensions, while CAT, CDP and MBA arrived with resctrl.

One inconsistency is worth noting because it can mislead. The OS section of the README says the package remains to work in all Linux kernel versions, while the Interfaces section says the OS interface is the one that should be used when available. Those are compatible statements, but reading only one of them can lead to the wrong expectation: the package still works without kernel support, but without kernel support you are on the MSR path, and the MSR path is per core only.

Where intel-cmt-cat is the wrong tool, and what it costs to keep

The boundaries are clear and mostly follow from what the hardware and the operating system expose.

It needs Intel RDT hardware. On a CPU without the technologies, the detection chain finds nothing and there is nothing to control. The Addendum A list is the authoritative answer to whether a given SKU qualifies.

It is not a general performance monitor. The package programs allocation and reads counters; it does not produce traces, it does not attribute time to source lines, and it does not give you an application-level latency picture. For that, the membw tool in the tools directory is the nearest thing in the package, and it is a stressor rather than a profiler.

On a virtual machine or a container, the situation depends on whether the hypervisor exposes the MSRs and the resctrl filesystem. The README does not discuss virtualisation at all, so that is an area where you are on your own.

For model-specific features you have the three-way dependency described earlier, and the failure is silent.

On maintenance and upgrade cost, the record is good. The recent releases are v25.04 on 2025-04-25, v26.03 on 2026-03-13 and v26.06 on 2026-06-23, so the cadence is roughly quarterly with releases named for their year and month. The last push was on 2026-10-20 and the repository is not archived, which means development continues between tagged releases. The repository also carries a SECURITY.md and a CONTRIBUTING file

The upgrade cost is mostly in behaviour rather than in code. Because the OS interface became the default at v4.3.0, a toolchain that assumed per-core MSR semantics can see different behaviour after an upgrade, and the pqos-os and pqos-msr wrappers exist precisely so you can pin the interface per invocation.

Editorial conclusion

Performance engineers on bare metal Intel servers who need to shape cache and memory bandwidth behaviour for a workload should use intel-cmt-cat, because it covers both the legacy MSR path and the modern resctrl path and ships the pqos utility alongside the library and Perl and C examples. It is the wrong tool on a machine without Intel RDT, on a kernel without perf or resctrl support when you need per-process control, and for model-specific features unless you set RDT_PROBE_MSR and stay on the MSR interface. Before adopting, run pqos and check which interface it selects, read the INSTALL file for the package route your distribution expects, and confirm from Addendum A of the Intel RDT Architecture Specification that your SKU is listed.

Frequently asked questions

Official sources

1. intel/intel-cmt-cat on GitHub
2. Issues
3. Project website
4. README
5. Releases