Skip to content

QUICKSTART.md

Latest commit

 

History

History
154 lines (115 loc) · 2.86 KB

QUICKSTART.md

File metadata and controls

154 lines (115 loc) · 2.86 KB

Quick Start Guide

Installation (30 seconds)

# On Gentoo
echo "dev-libs/capstone python" >> /etc/portage/package.use/checksysasm
emerge dev-libs/capstone dev-python/pyelftools gentoolkit

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install
pip install -e .

# Verify
checksysasm --version

Common Commands

1. Check entire system

checksysasm -m x86-64-v2 -o violations.txt

2. Check with your CPU

checksysasm -m native

3. Test single binary

checksysasm -m x86-64-v2 --check-binary /usr/bin/python3 -v

4. Get package report (Gentoo)

checksysasm -m x86-64-v2 --package-report packages.txt

5. Fast scan (no kernel modules)

checksysasm -m x86-64-v2 --no-kernel-modules -j 8

Output Formats

# Text (default)
checksysasm -m x86-64-v2 -o report.txt

# JSON
checksysasm -m x86-64-v2 --format json -o report.json

# CSV
checksysasm -m x86-64-v2 --format csv -o report.csv

# Simple list
checksysasm -m x86-64-v2 --format list -o files.list

Architecture Levels

Level Includes Use Case
x86-64 SSE2 Legacy (pre-2010)
x86-64-v2 SSE4.2, POPCNT Modern baseline (2010+)
x86-64-v3 AVX2, BMI, FMA Recent CPUs (2015+)
x86-64-v4 AVX-512 High-end only (2017+)

Common Intel CPUs

checksysasm -m haswell      # 2013-2015
checksysasm -m skylake      # 2015-2017
checksysasm -m cascadelake  # 2019+

Common AMD CPUs

checksysasm -m znver1  # Zen 1 (2017)
checksysasm -m znver2  # Zen 2 (2019)
checksysasm -m znver3  # Zen 3 (2020)
checksysasm -m znver4  # Zen 4 (2022)

Interpreting Results

Exit codes:

  • 0 = All binaries compliant
  • 1 = Violations found

Example output:

[1] /usr/bin/example
    Extensions: avx2
    Instructions:
      [avx2] vperm2i128, vbroadcasti128

Meaning: Binary uses AVX2 instructions, won't run on CPUs without AVX2.

What to do with violations?

  1. Rebuild package (Gentoo):

    emerge -av category/package

  2. Use package report to rebuild many:

    checksysasm -m x86-64-v2 --package-report packages.txt
# Review packages.txt and rebuild as needed

  3. Ignore if upgrading hardware (new CPU supports extensions)

Troubleshooting

"No module named 'elftools'"

source venv/bin/activate
pip install pyelftools

"Permission denied"

sudo checksysasm -m x86-64-v2

Slow scan

# Use more workers
checksysasm -m x86-64-v2 -j 16

# Skip kernel modules
checksysasm -m x86-64-v2 --no-kernel-modules

Get Help

checksysasm --help

Full Documentation

  • README.md - Complete documentation
  • EXAMPLES.md - Detailed examples
  • INSTALL.md - Installation guide
  • PROJECT_SUMMARY.md - Technical details