qemu-affinity is a tool to easily pin certain QEMU threads to select CPU cores.
Getting Started
Installing
This will install the qemu-affinity command to /usr/local/bin.
From pip
pip install qemu-affinity
From source
Clone the repo and run:
python setup.py install
Requirements
qemu-affinity requires Python 3.
Usage
qemu-affinity qemu-system-pid
[-h] [--dry-run] [-v] [-p [AFFINITY]]
[-q AFFINITY [AFFINITY ...]]
[-k THREAD_AFFINITY [THREAD_AFFINITY ...]]
[-i THREAD_AFFINITY [THREAD_AFFINITY ...]]
[-w THREAD_AFFINITY [THREAD_AFFINITY ...]]
[-t THREAD_AFFINITY [THREAD_AFFINITY ...]]
Positional arguments
- qemu-system-pid
PID of the qemu-system process
Optional arguments
- -h, --help
show this help message and exit
- --dry-run
don’t modify thread affinity values (useful with -v)
- -v, --verbose
be verbose
- -p AFFINITY, --process-affinity AFFINITY
set qemu-system process affinity (and default for new threads)
- -q AFFINITY [AFFINITY ...], --qemu-affinity AFFINITY [AFFINITY ...]
set qemu-system thread affinity (partial name selectors not allowed)
- -k THREAD_AFFINITY [THREAD_AFFINITY ...], --kvm-affinity THREAD_AFFINITY [THREAD_AFFINITY ...]
set KVM (CPU <n>/KVM) thread affinity
- -i THREAD_AFFINITY [THREAD_AFFINITY ...], --io-affinity THREAD_AFFINITY [THREAD_AFFINITY ...]
set IO object (IO <name>) thread affinity
- -w THREAD_AFFINITY [THREAD_AFFINITY ...], --worker-affinity THREAD_AFFINITY [THREAD_AFFINITY ...]
set qemu worker (worker) thread affinity (partial name selectors not allowed, only positional)
- -t THREAD_AFFINITY [THREAD_AFFINITY ...], --thread-affinity THREAD_AFFINITY [THREAD_AFFINITY ...]
set arbitary (<name>) thread affinity
AFFINITY is an affinity-spec
and
THREAD_AFFINITY can be one of:
affinity-spec
selector:affinity-spec
Where affinity-spec is a CPU number, a range (inclusive) of CPU numbers separated by a dash (-), or a comma-delimited (,) list of CPU numbers or ranges.
For example:
- 0
specifies CPU 0
- 0,1,2,3
specifies CPU 0, 1, 2 and 3
- 0-3
same as above
- 0,2-4,6
specifies CPU 0, 2, 3, 4 and 6
and, where selector is one of:
*, meaning all threads
partial-name for -k (CPU <partial-name>/KVM) and -i (IO <partial-name>)
name for -t
The first variant, affinity-spec, selects threads based on argument position.
e.g., -k 0,4 1,5 2,6 3,7 pins the first KVM thread to CPUs 0 and 4, the second KVM thread to CPUs 1 and 5, and so on.
The second variant, selector:affinity-spec, selects threads by selector, which is a partial name or wildcard. KVM threads have numeric names (0, 1, 2, etc.). IO threads have user-supplied names (-object iothread,id=name).
e.g., -k 2:2,6 -i myiothread:7 *:0 pins KVM thread 2 (aka CPU 2/KVM) to CPUs 2 and 6, IO thread myiothread (aka IO myiothread) to CPU 7, and all remaining IO threads to CPU 0.
The two variants can be combined.
- e.g., -k 0,4 *:2,6 pins the first KVM thread to CPUs 0 and 4,
and all remaining KVM threads to CPUs 2 and 6.
Known Limitations
the built-in help (qemu-affinity -h) lists the qemu-system-pid argument last in the list which may conflict with multi-argument parameters such as -q, -k, -i, -w, and -t.
Either specify qemu-system-pid at the beginning of the argument list or use -- to separate the multi-argument parameters from the positional parameters.
-t/--thread-affinity only applies to the first of multiple threads that share an identical name (such as the QEMU worker threads).
-t is unable to specify different affinities for threads with duplicate names, nor is it able to apply the same affinity value to multiple threads with the same name (* applies to all threads, not just a sub-set).
e.g. -t abc:1 abc:2 results in an error, and there is no way to set all threads with the name “abc” to the same affinity value.
Additionally, there is no way to select the nth thread with the same name.
e.g. -t abc:1 will always select the 1st thread with the name “abc”.
Sample Usage
The following systemd.service(5) starts QEMU as a daemon and then pins the 4 KVM threads (one for each emulated CPU core) to host CPUs 2, 3, 4 and 5. IO threads and other QEMU worker threads are pinned to host CPUs 0 and 1.
In this example the host kernel has been configured to isolate cores 2, 3, 4 & 5 so they can be solely utilised by QEMU.
[Unit] Description=QEMU virtual machine After=network.target netctl@br0.service [Service] CPUSchedulingPolicy=rr Type=forking PIDFile=/run/qemu_ex.pid Environment=QEMU_AUDIO_DRV=pa ExecStart=/usr/bin/qemu-system-x86_64 -name example-qemu-machine,debug-threads=on -daemonize -pidfile /run/qemu_ex.pid -monitor unix:/tmp/qemu_ex.sock,server,nowait -smp cores=4,threads=1,sockets=1 ... ExecStartPost=/bin/sh -c 'exec /usr/bin/qemu-affinity $MAINPID -p 0-1 -i *:0-1 -q 0-1 -w *:0-1 -k 2 3 4 5' ExecStop=/bin/sh -c 'while test -d /proc/$MAINPID; do /usr/bin/echo system_powerdown | /usr/bin/socat - UNIX-CONNECT:/tmp/qemu_ex.sock; sleep 60; done' TimeoutStopSec=1m [Install] WantedBy=multi-user.target
1 maintainer
Metadata
1 maintainer
Release files for qemu-affinity 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| qemu-affinity-1.0.0.tar.gz | 7.2 kB | Without provenance | Details for qemu-affinity-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| qemu_affinity-1.0.0-py2.py3-none-any.whl | Python 2, Python 3 | none | any | Details for qemu_affinity-1.0.0-py2.py3-none-any.whl |
Total release size: 18.0 kB
Release files / qemu-affinity-1.0.0.tar.gz
| Download URL | qemu-affinity-1.0.0.tar.gz |
|---|---|
| Size | 7.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c9cbecc36a2714bd3caaf772909e70e467aa063e8b229a87d976e65f9cde0470
|
|
BLAKE2b-256 checksum How to use checksums |
d8c28081a0a037b4325a47849a61e36889bcd6221cb099ec206d512f175a0413
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
Release files / qemu_affinity-1.0.0-py2.py3-none-any.whl
| Download URL | qemu_affinity-1.0.0-py2.py3-none-any.whl |
|---|---|
| Size | 10.8 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
042315d0a2b291253a5efbc0fb001e550317b55f470f0c09cfc1abd9c4f62449
|
|
BLAKE2b-256 checksum How to use checksums |
61a0466df76d9b26fbd2cc2b919e62073f3ac12749653f1b4a1ad235a1e83ca2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
Security for qemu-affinity 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
