ruapu

Detect CPU ISA features with single-file

#define RUAPU_IMPLEMENTATION
#include "ruapu.h"

int main()
{
    // initialize ruapu once
    ruapu_init();

    // now, tell me if this cpu has avx2
    int has_avx2 = ruapu_supports("avx2");

    return 0;
}

Best practice for using ruapu.h in multiple compilation units

1. Create one ruapu.c for your project
2. ruapu.c is ONLY #define RUAPU_IMPLEMENTATION and #include "ruapu.h"
3. Other sources #include "ruapu.h" but NO #define RUAPU_IMPLEMENTATION

Let's ruapu

ruapu with C

# GCC / MinGW
gcc main.c -o ruapu

# Clang
clang main.c -o ruapu

# MSVC
cl.exe /Fe: ruapu.exe main.c

./ruapu 
mmx = 1
sse = 1
sse2 = 1
sse3 = 1
ssse3 = 1
sse41 = 1
sse42 = 1
sse4a = 1
xop = 0
... more lines omitted ...

ruapu with Python

# from source code
pip3 install .

import ruapu

ruapu.supports("avx2")
# True

ruapu.supports(isa="avx2")
# True

mmx = 1
sse = 1
sse2 = 1
sse3 = 1
ssse3 = 1
sse41 = 1
sse42 = 1
sse4a = 1
xop = 0
avx = 1
f16c = 1
fma = 1
avx2 = 1
avx512f = 0
avx512bw = 0
avx512cd = 0
avx512dq = 0
avx512vl = 0
avx512vnni = 0
avx512bf16 = 0
avx512ifma = 0
avx512vbmi = 0
avx512vbmi2 = 0
avx512fp16 = 0
avxvnni = 0
avxvnniint8 = 0
avxifma = 0

mmx = 1
sse = 1
sse2 = 1
sse3 = 1
ssse3 = 1
sse41 = 1
sse42 = 1
sse4a = 0
xop = 0
avx = 1
f16c = 1
fma = 1
avx2 = 1
avx512f = 0
avx512bw = 0
avx512cd = 0
avx512dq = 0
avx512vl = 0
avx512vnni = 0
avx512bf16 = 0
avx512ifma = 0
avx512vbmi = 0
avx512vbmi2 = 0
avx512fp16 = 0
avxvnni = 0
avxvnniint8 = 0
avxifma = 0

neon = 1
vfpv4 = 1
cpuid = 0
asimdhp = 1
asimddp = 1
asimdfhm = 1
bf16 = 0
i8mm = 0
sve = 0
sve2 = 0
svebf16 = 0
svei8mm = 0
svef32mm = 0

mmx = 1
sse = 1
sse2 = 1
sse3 = 1
ssse3 = 1
sse41 = 1
sse42 = 1
sse4a = 1
xop = 0
avx = 1
f16c = 1
fma = 1
avx2 = 1
avx512f = 0
avx512bw = 0
avx512cd = 0
avx512dq = 0
avx512vl = 0
avx512vnni = 0
avx512bf16 = 0
avx512ifma = 0
avx512vbmi = 0
avx512vbmi2 = 0
avx512fp16 = 0
avxvnni = 0
avxvnniint8 = 0
avxifma = 0

mmx = 1
sse = 1
sse2 = 1
sse3 = 1
ssse3 = 1
sse41 = 1
sse42 = 1
sse4a = 1
xop = 0
avx = 1
f16c = 1
fma = 1
fma4 = 0
avx2 = 1
avx512f = 0
avx512bw = 0
avx512cd = 0
avx512dq = 0
avx512vl = 0
avx512vnni = 0
avx512bf16 = 0
avx512ifma = 0
avx512vbmi = 0
avx512vbmi2 = 0
avx512fp16 = 0
avxvnni = 0
avxvnniint8 = 0
avxifma = 0

Features

• Detect CPU ISA with single-file    sse2, avx, avx512f, neon, etc.
• Detect vendor extended ISA     apple amx, risc-v vendor ISA, etc.
• Detect richer ISA on Windows ARM   IsProcessorFeaturePresent() returns little ISA information
• Detect x86-avx512 on macOS correctly  macOS hides it in cpuid
• Detect new CPU's ISA on old systems  they are usually not exposed in auxv or MISA
• Detect CPU hidden ISA        fma4 on zen1, ISA in hypervisor, etc.

Supported ISA  (more is comming ... :)

Techniques inside ruapu

ruapu is implemented in C language to ensure the widest possible portability.

ruapu determines whether the CPU supports certain instruction sets by trying to execute instructions and detecting whether an Illegal Instruction exception occurs. ruapu does not rely on the cpuid instructions and registers related to the CPU architecture, nor does it rely on the MISA information and system calls of the operating system. This can help us get more detailed CPU ISA information.

FAQ

Why is the project named ruapu

 ruapu is the abbreviation of rua-cpu, which means using various extended instructions to harass and amuse the CPU (rua!). Based on whether the CPU reacts violently (throws an illegal instruction exception), it is inferred whether the CPU supports a certain extended instruction set.

Why is ruapu API designed like this

 We consider gcc builtin functions to be good practice, saying __builtin_cpu_init() and __builtin_cpu_supports(). ruapu refers to this design, which can be a 1:1 replacement for gcc functions, and supports more operating systems and compilers, giving it better portability.

Why does SIGILL occur when executing in debugger or simulator, such as gdb, lldb, qemu-user, sde etc.

 Because debuggers and simulators capture the signal and stop the ruapu signal handler function by default, we can continue execution at this time, or configure it specifically, such as handle SIGILL nostop in gdb. ruapu technically cannot prevent programs from stopping in debuggers and emulators

How to add detection capabilities for new instructions to ruapu

 Assume that the new extended instruction set is named rua

1. Add RUAPU_INSTCODE(rua, rua-inst-hex) // rua r0,r0 and RUAPU_ISAENTRY(rua) in ruapu.h
2. Add PRINT_ISA_SUPPORT(rua) in main.c to print the detection result
3. Add entries about rua in README.md
4. Create a pull request!

 https://godbolt.org/ is a good helper to view the compiled binary code of instructions.

Repos that use ruapu

• ncnn  High-performance neural network inference framework
• libllm  Efficient inference of large language models

Credits

• @nihui  Write the initial POC code and ruapu maintainer
• @kernelbin  Implement exception handling for Windows
• @zchrissirhcz  Detect x86 FMA4
• @MollySophia  Fix C++ export symbol
• @strongtz  Detect more aarch64 ISA
• @monkeyking  Detect apple arm64 AMX
• @junchao-loongson  Add loongarch support
• @ziyao233  Detect more risc-v ISA
• @dreamcmi  Detect more risc-v ISA
• @cocoa-xu  Add FreeBSD support, python support
• @YuzukiTsuru  Add OpenRISC support

License

MIT License