Skip to content

EXAMPLES.md

Latest commit

 

History

History
317 lines (222 loc) · 6.58 KB

EXAMPLES.md

File metadata and controls

317 lines (222 loc) · 6.58 KB

Usage Examples

Basic Usage

Check entire system with x86-64-v2

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

Use native CPU detection

checksysasm -m native

Check with specific Intel architecture

# For Haswell CPUs
checksysasm -m haswell -o haswell-violations.txt

# For Skylake
checksysasm -m skylake -o skylake-violations.txt

Check with AMD Zen

# Zen 1/2/3
checksysasm -m znver3 -o zen3-violations.txt

Output Formats

Save as JSON for processing

checksysasm -m x86-64-v2 --format json -o violations.json

Save as CSV for spreadsheets

checksysasm -m x86-64-v2 --format csv -o violations.csv

Get simple file list for scripting

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

# Use with xargs
cat files.list | xargs file

Single Binary Checks

Check Python interpreter

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

Check shared library

checksysasm -m x86-64-v2 --check-binary /usr/lib64/libssl.so -v

Check custom compiled binary

checksysasm -m x86-64-v2 --check-binary ./my-app

Gentoo Package Integration

Generate package report

checksysasm -m x86-64-v2 \
  -o violations.txt \
  --package-report packages.txt

Find packages to rebuild after CFLAGS change

# Old CFLAGS: -march=native (on Zen 4 CPU)
# New CFLAGS: -march=x86-64-v3

checksysasm -m x86-64-v3 --package-report rebuild-list.txt

Custom Scanning

Scan custom directory

checksysasm -m x86-64-v2 --scan-path /opt

Scan multiple custom paths

checksysasm -m x86-64-v2 \
  --scan-path /opt \
  --scan-path /usr/local \
  --scan-path ~/bin

Skip kernel modules (faster)

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

Skip debug files

# Skip *.debug files (separate debug symbols, often very large)
checksysasm -m x86-64-v2 --skip-debug-files

# Combine with other options
checksysasm -m x86-64-v2 --skip-debug-files --no-kernel-modules -j 8

Performance Tuning

Use more workers for faster scanning

# Use 8 parallel workers
checksysasm -m x86-64-v2 -j 8

Large system scan

# For large systems with 10k+ binaries
checksysasm -m x86-64-v2 -j 16 -o violations.txt

Practical Scenarios

Scenario 1: Preparing to move system to older hardware

# Current system: Intel i7-9700K (Coffee Lake, AVX2)
# Target system: Intel Core 2 Duo (SSSE3)

checksysasm -m core2 -o core2-violations.txt --package-report core2-packages.txt

# Review violations and rebuild packages
emerge -av $(cat core2-packages.txt | grep 'Package:' | cut -d' ' -f2)

Scenario 2: Verifying Gentoo @world rebuild

# After rebuilding @world with new CFLAGS
# Verify everything complies

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

Scenario 3: Finding AVX-512 usage

# Check which binaries use AVX-512
checksysasm -m x86-64-v3 --format list | \
  while read binary; do
    objdump -d "$binary" | grep -q "zmm" && echo "$binary uses AVX-512"
  done

Scenario 4: Continuous integration check

#!/bin/bash
# ci-check.sh - Verify build artifacts

checksysasm -m x86-64-v2 --scan-path ./dist --format json -o violations.json

violations=$(jq '.total_violations' violations.json)

if [ "$violations" -gt 0 ]; then
  echo "ERROR: Found $violations non-compliant binaries"
  exit 1
else
  echo "SUCCESS: All binaries compliant with x86-64-v2"
  exit 0
fi

Scenario 5: Pre-migration validation

# Before migrating to AWS/cloud instances
# which may use older CPUs

checksysasm -m x86-64-v2 \
  --package-report aws-migration.txt \
  -o aws-violations.txt \
  -j 8

# Review and rebuild as needed

Scenario 6: Debugging system crashes during scan

# If checksysasm crashes or consumes too much memory,
# use -vv to see which file causes the crash

checksysasm -m x86-64-v2 -vv 2>&1 | tee scan.log

# The last file printed before crash is the problematic one
# Example output:
#   Visiting: /usr/bin/good-binary
#   Visiting: /usr/lib/problematic.so
#   [crash or out of memory]

# Exclude the problematic file and continue
checksysasm -m x86-64-v2 --exclude "*/problematic.so" -vv 2>&1 | tee scan.log

# Or add to exclusion file for permanent exclusion
echo "*/problematic.so" >> excludes.txt
checksysasm -m x86-64-v2 --exclude-file excludes.txt

# Skip debug files if they're causing issues
checksysasm -m x86-64-v2 --skip-debug-files -vv 2>&1 | tee scan.log

Advanced Usage

Combine with other tools

# Find largest violating binaries
checksysasm -m x86-64-v2 --format list | xargs ls -lh | sort -k5 -h

# Check violating binaries' dependencies
checksysasm -m x86-64-v2 --format list | xargs ldd

# Strip debug symbols from violators
checksysasm -m x86-64-v2 --format list | xargs strip

Verbose output for debugging

# Verbose level 1: Show violations as found
checksysasm -m x86-64-v2 -v -o violations.txt

# Verbose level 2: Show ALL visited files (debug crashes/memory issues)
checksysasm -m x86-64-v2 -vv -o violations.txt

Exclude problematic files

# Exclude browser binaries (often highly optimized)
checksysasm -m x86-64-v2 --exclude "*/firefox/*" --exclude "*/chrome/*"

# Use exclusion file for managing many patterns
cat > excludes.txt <<EOF
# Browsers
*/firefox/*
*/chrome/*
*/chromium/*

# CUDA
*/cuda/*
/opt/nvidia/*
EOF

checksysasm -m x86-64-v2 --exclude-file excludes.txt

# Combine file and command-line exclusions
checksysasm -m x86-64-v2 --exclude-file excludes.txt --exclude "*/temp/*"

# Treat excluded files as violations (for compliance reporting)
checksysasm -m x86-64-v2 --exclude-file excludes.txt --exclude-as-violation

Multiple flag combinations

# Check for specific instruction sets
checksysasm -m haswell -f -mavx2 -f -mfma -f -mbmi2 -o violations.txt

Interpretation of Results

Understanding the output

[1] /usr/bin/example-binary
    Extensions: avx2, fma
    Instructions:
      [avx2] vbroadcasti128, vperm2i128
      [fma] vfmadd132ps, vfmadd213pd

This means:

  • Binary uses AVX2 instructions (vbroadcasti128, vperm2i128)
  • Binary uses FMA instructions (vfmadd132ps, vfmadd213pd)
  • Binary is NOT compatible with CPUs lacking AVX2 or FMA support

What to do with violations

  1. Rebuild packages: Use emerge to rebuild with correct CFLAGS
  2. Accept limitation: If upgrading hardware, violations may be acceptable
  3. Use precompiled: Switch to precompiled binaries for those packages
  4. Report upstream: If unexpected, report to package maintainers