# CPUMap - view and edit CPU affinities

## About 

**CPUMap** is a graphical (TUI and GUI) tool to view and edit CPU affinity
of processes on a Linux system.

## Screenshots

![Video: (0.1.0) Browse and view CPU affinity of processes](https://codeberg.org/Kiith/cpumap/raw/branch/master/view.webm)

![Video: (0.1.0) Specify cores for a process to use, or how its threads should be assigned to cores](https://codeberg.org/Kiith/cpumap/raw/branch/master/edit.webm)

![Video: (0.1.0) Run a process only on specified cores](https://codeberg.org/Kiith/cpumap/raw/branch/master/run.webm)

| GUI                                                                      | TUI                                                                   |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| ![](https://codeberg.org/Kiith/cpumap/raw/branch/master/cpumap-view.png) | ![](https://codeberg.org/Kiith/cpumap/raw/branch/master/tui-view.png) |
| ![](https://codeberg.org/Kiith/cpumap/raw/branch/master/cpumap-edit.png) | ![](https://codeberg.org/Kiith/cpumap/raw/branch/master/tui-edit.png) |
| ![](https://codeberg.org/Kiith/cpumap/raw/branch/master/cpumap-run.png)  | ![](https://codeberg.org/Kiith/cpumap/raw/branch/master/tui-run.png)  |

## Use cases

* Benchmarking:
  - Set one thread per core to limit contention 
  - Set many threads per core to maximize contention
  - Force a program to use specified cores to simulate performance on different CPUs
* Gaming: 
  - Force a game to only use P-cores on an Intel Alder Lake or newer CPU
  - Force a game to only use cores with 3D V-cache on Ryzen 7950x
  - Force a game to use a single CCD on an AMD Zen 3 or newer CPU
* Profiling:
  - Force a program to only run on one type of CPU (P-cores or E-cores) 
    to get consistent values from CPU performance counters.
* Workstation:
  - Prevent resource-intensive program from hogging all cores to ensure
    system responsiveness.
* High-performance applications:
  - Run threads of an IDS to cores where packets are received from a NIC.
  - Maximize cache-per-thread by running only one thread per CCD of an AMD Epyc CPU.

Note that tweaking CPU affinity is unlikely to improve performance if you don't
know what you are doing - usually, it's best to let the OS scheduler
do its work.

## Features 

* OS support: 
  - Linux
  - May work on other Unix-like OS's (based on the `hwloc` library) but only Linux has been tested so far.
* GUI and TUI frontends (with identical features)
* Visualize CPU topology hierarchy with caches and logical cores ('hyperthreads')
* View affinities for all running processes
* Fuzzy search running processes
* Set cores a process *and each individual thread* of that process can use
  - Manually
  - 'Thread order', e.g. one core, L3, etc. per thread
* Run programs with specified affinity 
  - Run programs and control affinity of subprocesses launched by those programs

## Install

* TUI build: ``cargo install cpumap``
* GUI build: ``cargo install --no-default-features --features gui cpumap``

Or get the [linux x64 binaries](https://codeberg.org/Kiith/cpumap/releases)
            
You may need to install the `hwloc` library; Names
or its Linux packages usually start with `libhwloc`.

## Run 

``cpumap``

## License

Licensed under the [MIT](http://opensource.org/licenses/MIT) license, see file `LICENSE`.