Portable Bitwise Manipulation Intrinsics

0b0000_0010_1001_1010

The intrinsics are named after their CPU instruction and organized in modules named after their architecture/instruction set: bitintr::{arch}::{instruction_set}::{intrinsic_name}.

They are implemented for all integer types except u128/i128. Whether a fallback software implementation is used depends on the integer types involved and the instruction sets supported by the target.

The following instruction sets are implemented:

x86 (bitintr::x86):
- ABM: Advanced Bit Manipulation instructions (bitintr::x86::abm).
- TBM: Trailing Bit Manipulation instructions (bitintr::x86::tbm).
- BMI: Bit Manipulation Instruction Set 1.0 (bitintr::x86::bmi).
- BMI2: Bit Manipulation Instruction Set 2.0 (bitintr::x86::bmi2).
ARM (bitintr::arm):
- ARMv5: bitintr::arm::v5.
- ARMv6: bitintr::arm::v6.
- ARMv7: bitintr::arm::v7.
- ARMv8: bitintr::arm::v8.

Note: This library is low-level by purpose (and works with #![no_std]). For a portable higher-level bitwise manipulation algorithms library you might want to check out the bitwise crate.

Example

extern crate bitintr;
use bitintr::x86::bmi2::*;

fn main() {
    // Intrinsics are provided as trait methods:
    let method_call = 1.pdep(0);
    // And as free functions:
    let free_call = pdep(1, 0);
    assert_eq!(method_call, free_call);
}

Supported compilers

The minimum required rustc version is >= 1.13.0.

When compiled with a rust stable compiler the intrinsics are implemented using the software fallback. In release builds LLVM often generates the corresponding CPU instruction.

When compiled with a rust nightly compiler the following unstable features are used to generate the corresponding CPU instruction in all cases:

cfg_target_feature for target-dependent behavior,
platform_intrinsics for using the bitwise manipulation compiler intrinsics,
link_llvm_intrinsics for using the llvm intrinsics not yet available in rustc, and
i128_type support for efficient 64-bit multiplication (using u128).

Verify the generated assembly

A small script (check_asm.py) is used for verifying the generated assembly of the intrinsics. It compiles the asm/arch_feature_*.rs for the appropriate architectures and target features and compares the assembly generated by rustc with that included in the corresponding asm/arch_feature_*.asm files.

License

Licensed under the MIT license.

Contribution