Awesome

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");

    // loop all supported features
    const char* const* supported = ruapu_rua();
    while (*supported)
    {
        fprintf(stderr, "%s\n", *supported);
        supported++;
    }

    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

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 ... :)

Let's ruapu

ruapu with C

Compile ruapu test program

# GCC / MinGW
gcc main.c -o ruapu

# Clang
clang main.c -o ruapu

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

Run ruapu in command line

./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

Compile and install ruapu library

# from pypi
pip3 install ruapu

# from source code
pip3 install ./python

Use ruapu in python

import ruapu

ruapu.supports("avx2")
# True

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

ruapu.rua()
#(mmx', 'sse', 'sse2', 'sse3', 'ssse3', 'sse41', 'sse42', 'avx', 'f16c', 'fma', 'avx2')

ruapu with Rust

Compile ruapu library

# from source code
cd rust
cargo build --release

Use ruapu in Rust

extern crate ruapu;

fn main() {
    println!("supports neon: {}", ruapu::supports("neon").unwrap());
    println!("supports avx2: {}", ruapu::supports("avx2").unwrap());
    println!("rua: {:?}", ruapu::rua());
}

ruapu with Lua

Compile ruapu library

# from source code
cd lua
# lua binding has been tested on Lua 5.2~5.4
luarocks make

Use ruapu in Lua

ruapu = require "ruapu";
print(ruapu.supports("mmx"));
for _, ext in ipairs(ruapu.rua()) do
    print(ext);
end

ruapu with Erlang

Compile ruapu library

% add this to deps list 
% in your rebar.config
{ruapu, "0.1.0"}

Use ruapu in Erlang rebar3 shell

ruapu:rua().
{ok,["neon","vfpv4","asimdrdm","asimdhp","asimddp",
     "asimdfhm","bf16","i8mm","pmull","crc32","aes","sha1",
     "sha2","sha3","sha512","amx"]}
> ruapu:supports("neon").
true
> ruapu:supports(neon).
true
> ruapu:supports(<<"neon">>).
true
> ruapu:supports("avx2").
false
> ruapu:supports(avx2).
false
> ruapu:supports(<<"avx2">>).
false

ruapu with Fortran

Compile ruapu library

# from source code
cd fortran
cmake -B build
cmake --build build

Use ruapu in Fortran

program main
    use ruapu, only: ruapu_init, ruapu_supports, ruapu_rua
    implicit none

    character(len=:), allocatable :: isa_supported(:)
    integer :: i

    call ruapu_init()

    print *, "supports sse: ", ruapu_supports("sse")
    print *, "supports neon: ", ruapu_supports("neon")

    isa_supported = ruapu_rua()
    do i = 1, size(isa_supported)
        print *, trim(isa_supported(i))
    end do
end program main

ruapu with Golang

Compile ruapu library

cd go
go build -o ruapu-go

Use ruapu in Golang

package main

import (
	"fmt"
	"ruapu-go/ruapu"
	"strconv"
)

func main() {
	ruapu.Init()
	avx2Status := ruapu.Supports("avx2")
	fmt.Println("avx2:" + strconv.Itoa(avx2Status))
	rua := ruapu.Rua()
	fmt.Println(rua)
}

ruapu with Haskell

Add ruapu library to your project

haskell/Ruapu.hs, haskell/ruapu.c and ruapu.h should be copied in your project.

Use ruapu in Haskell

import Ruapu
-- Ruapu.rua :: IO [String]
-- Ruapu.supports :: String -> IO Bool
main = do
    Ruapu.init
    Ruapu.supports "mmx" >>= putStrLn . show
    Ruapu.rua >>= sequence_ . map putStrLn

ruapu with Vlang

Compile ruapu library

cd vlang
v .

Use ruapu in Vlang

module main

import ruapu

fn main() {
    ruapu.ruapu_init()
    mut avx2_status := ruapu.ruapu_supports('avx2')
    if avx2_status {
        println('avx2: ' + avx2_status.str())
    }

    println(ruapu.ruapu_rua())
}

ruapu with Pascal

Compile ruapu library

cd pascal
sudo apt install fpc
cmake .
make
fpc ruapu.lpr

Use ruapu in Pascal

program ruapu;

uses ruapu_pascal;

var
  has_avx2: integer;
  supported: PPAnsiChar;
begin
  // initialize ruapu once
  ruapu_init();

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

  // loop all supported features
  supported := ruapu_rua();
  while supported^ <> nil do
  begin
      writeln(supported^);
      inc(supported);
  end;

  readln();
end.
      

ruapu with Java

Compile ruapu library and example

./gradlew build

Run example

java -cp \
    ./build/libs/ruapu-1.0-SNAPSHOT.jar \
    ./Example.java

Use ruapu in Java

import ruapu.Ruapu;
import java.util.*;

class Example {
    public static void main(String args[]) {
        Ruapu ruapu = new Ruapu();
        
        System.out.println("avx: " + ruapu.supports("avx")); 
        // avx: 1
        System.out.println(Arrays.toString(ruapu.rua())); 
        // [mmx, sse, sse2, sse3, ssse3, sse41, sse42, avx, f16c, fma, avx2]
    }
}
      

ruapu with cangjie

Compile ruapu library

cd cangjie
cd c-src
cmake .
make

run example

cd cangjie
cjpm run

or compile example

cd cangjie
cjpm build
./target/release/bin/main

import ruapu.*
main(): Int64 {
    ruapu_init()
    let neon_supported = ruapu_supports("neon")
    println("supports neon: ${neon_supported}") 
    let d = ruapu_rua()
    for (i in d) {
        println(i)
    }
    return 0
}

ruapu with Dart

Compile ruapu library

cd dart
bash build.sh

void main() {
  var libraryPath =
  path.join(Directory.current.path, 'build', 'libruapu.so');

  if (Platform.isMacOS) {
    libraryPath =
        path.join(Directory.current.path, 'build', 'libruapu.dylib');
  }

  if (Platform.isWindows) {
    libraryPath = path.join(
        Directory.current.path, 'build', 'Debug', 'ruapu.dll');
  }

  Ruapu ruapu = Ruapu(libraryPath);

  ruapu.init();

  List<String> isas = ruapu.rua();
  print("This CPU Support:");
  for (String isa in isas) {
    print(isa);
  }
  print("=================");

  String isaToCheck = 'aes';
  bool isSupported = ruapu.supports(isaToCheck);
  print('Does the system support $isaToCheck? $isSupported');
}

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
avx512er = 0
avx5124fmaps = 0
avx5124vnniw = 0
avxvnni = 0
avxvnniint8 = 0
avxifma = 0
amxfp16 = 0
amxbf16 = 0
amxint8 = 0
amxtile = 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
avx512er = 0
avx5124fmaps = 0
avx5124vnniw = 0
avxvnni = 0
avxvnniint8 = 0
avxifma = 0
amxfp16 = 0
amxbf16 = 0
amxint8 = 0
amxtile = 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
avx512er = 0
avx5124fmaps = 0
avx5124vnniw = 0
avxvnni = 0
avxvnniint8 = 0
avxifma = 0
amxfp16 = 0
amxbf16 = 0
amxint8 = 0
amxtile = 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
avx512er = 0
avx5124fmaps = 0
avx5124vnniw = 0
avxvnni = 0
avxvnniint8 = 0
avxifma = 0
amxfp16 = 0
amxbf16 = 0
amxint8 = 0
amxtile = 0

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

Contribution behavior

• @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
• @whyb  Detect more x86 AMX*, SHA*, AVX512*, SM*

License

MIT License