Appendix F: Environment Setup Guide

"A good setup is half the battle." — Engineering Proverb

Platform Overview

The examples and exercises in this book support multiple platforms.

Supported Platforms

Platform          Architecture  Notes
─────────────────────────────────────────────────────
Linux x86-64      x86-64        Most complete tool support
macOS             aarch64       Apple Silicon (M1/M2/M3)
Windows           x86-64        Recommend WSL2
RISC-V hardware   riscv64       SiFive, StarFive, Milk-V
RISC-V emulator   riscv64       QEMU, Spike
ARM dev boards    aarch64       Raspberry Pi, Jetson

Linux x86-64 Setup

Basic Tools

# Update system
sudo apt update && sudo apt upgrade -y

# Compilation tools
sudo apt install -y build-essential cmake ninja-build

# Performance tools
sudo apt install -y linux-tools-common linux-tools-generic
sudo apt install -y perf

# Other tools
sudo apt install -y git wget curl htop

Performance Analysis Tools

# perf
sudo apt install -y linux-tools-$(uname -r)

# Valgrind
sudo apt install -y valgrind

# FlameGraph
git clone https://github.com/brendangregg/FlameGraph.git

# sysstat (iostat, mpstat)
sudo apt install -y sysstat

Benchmark Tools

# fio
sudo apt install -y fio

# iperf3
sudo apt install -y iperf3

# stress-ng
sudo apt install -y stress-ng

# sysbench
sudo apt install -y sysbench

Permission Settings

# Allow non-root to use perf
echo 0 | sudo tee /proc/sys/kernel/perf_event_paranoid

# Permanent setting
echo 'kernel.perf_event_paranoid = 0' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Linux Baseline (Benchmarking)

# 1. Stop unnecessary services
sudo systemctl stop cron snapd unattended-upgrades

# 2. Set CPU frequency (disable scaling)
sudo cpupower frequency-set -g performance

# 3. Disable Turbo Boost
# Intel:
echo 1 | sudo tee /sys/devices/system/cpu/intel_pstate/no_turbo
# AMD:
echo 0 | sudo tee /sys/devices/system/cpu/cpufreq/boost

# 4. Disable ASLR
echo 0 | sudo tee /proc/sys/kernel/randomize_va_space

# 5. Run with CPU pinning
sudo nice -n -20 taskset -c 2 ./benchmark

Memory Configuration

# Enable huge pages
echo 1024 | sudo tee /proc/sys/vm/nr_hugepages

# NUMA binding
numactl --membind=0 --cpunodebind=0 ./benchmark

Restore System Settings

sudo cpupower frequency-set -g ondemand
echo 0 | sudo tee /sys/devices/system/cpu/intel_pstate/no_turbo
echo 2 | sudo tee /proc/sys/kernel/randomize_va_space
sudo systemctl start cron

macOS Setup

Homebrew Installation

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Basic tools
brew install cmake ninja git wget

# Benchmark tools
brew install fio iperf3 stress-ng

Xcode Command Line Tools

xcode-select --install

Performance Analysis

# Instruments (installed with Xcode)
# Use GUI or command line

# Using sample
sudo sample <pid> 10 -file output.txt

# Using dtrace (requires disabling SIP)
sudo dtrace -n 'profile-997 { @[ustack()] = count(); }'

Notes

macOS limitations:

1. No perf
   - Use Instruments instead
   - Or use dtrace

2. SIP (System Integrity Protection)
   - Some tools require disabling
   - Not recommended for production

3. Apple Silicon
   - Some tools not yet supported
   - Use Rosetta 2 for x86 tools

Windows Setup

WSL2 Installation

# Run PowerShell as Administrator
wsl --install

# Install Ubuntu
wsl --install -d Ubuntu-22.04

# Enter WSL
wsl

Inside WSL2

# Same as Linux
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential cmake git

# Note: Some kernel features are limited
# perf requires special configuration

Native Windows Tools

Windows Performance Tools:

1. Windows Performance Toolkit
   - xperf
   - Windows Performance Analyzer

2. Visual Studio Profiler
   - CPU usage
   - Memory analysis

3. Intel VTune
   - Windows support
   - Detailed CPU analysis

Cross-Platform Tool Mapping

Linux → Windows

Linux → macOS

RISC-V Environment Setup

QEMU Emulator

# Install QEMU
sudo apt install -y qemu-system-riscv64 qemu-user

# Test
qemu-system-riscv64 --version
qemu-riscv64 --version

Toolchain

# Pre-built toolchain
sudo apt install -y gcc-riscv64-linux-gnu

# Or build from source
git clone https://github.com/riscv-collab/riscv-gnu-toolchain.git
cd riscv-gnu-toolchain
./configure --prefix=/opt/riscv
make linux -j$(nproc)

Spike Simulator

# Install dependencies
sudo apt install -y device-tree-compiler

# Build Spike
git clone https://github.com/riscv-software-src/riscv-isa-sim.git
cd riscv-isa-sim
mkdir build && cd build
../configure --prefix=/opt/riscv
make -j$(nproc)
sudo make install

Running Examples

# Compile program
riscv64-linux-gnu-gcc -static -o hello hello.c

# Run on QEMU
qemu-riscv64 ./hello

# Run on Spike (requires pk)
spike pk ./hello

ARM Environment Setup

Cross Compilation

# Install toolchain
sudo apt install -y gcc-aarch64-linux-gnu
sudo apt install -y gcc-arm-none-eabi  # Bare metal

# Install QEMU
sudo apt install -y qemu-system-arm qemu-user

Raspberry Pi Setup

# On Raspberry Pi
sudo apt update && sudo apt upgrade -y

# Performance tools
sudo apt install -y linux-tools-generic
sudo apt install -y perf

# Note: Some tools may need to be built from source

Docker Environment

Using Docker for Isolated Environment

# Dockerfile
FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    build-essential \
    cmake \
    git \
    linux-tools-generic \
    perf \
    fio \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /workspace

Running

# Build image
docker build -t benchmark-env .

# Run (requires privileged mode for perf)
docker run --privileged -it benchmark-env

Environment Verification

Verification Script

#!/bin/bash
# verify_environment.sh

echo "=== Environment Verification ==="

# Compiler
echo -n "GCC: "
gcc --version | head -1

# perf
echo -n "perf: "
perf --version 2>/dev/null || echo "Not available"

# fio
echo -n "fio: "
fio --version 2>/dev/null || echo "Not available"

# Python
echo -n "Python: "
python3 --version

# Kernel version
echo -n "Kernel: "
uname -r

# CPU info
echo "CPU:"
lscpu | grep "Model name"
lscpu | grep "CPU(s):"

echo "=== Verification Complete ==="

Common Issues

perf Permission Issues

# Problem: perf requires root permission
# Solution:
echo 0 | sudo tee /proc/sys/kernel/perf_event_paranoid

# Or use sudo
sudo perf stat ./benchmark

Frequency Instability

# Problem: CPU frequency changes affect results
# Solution: Fix frequency
sudo cpupower frequency-set -g performance

# Or disable turbo boost
echo 1 | sudo tee /sys/devices/system/cpu/intel_pstate/no_turbo

Insufficient Memory

# Problem: Large benchmark runs out of memory
# Solution: Add swap
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Summary

Environment setup key points:

Platform Selection

• Linux x86-64: Most complete support
• macOS: Need alternative tools
• Windows: Recommend WSL2
• RISC-V/ARM: Use emulator or physical hardware

Required Tools

• Compiler (GCC/Clang)
• Performance analysis (perf/Instruments)
• Benchmark tools (fio, iperf3)

Environment Preparation

• Fix CPU frequency
• Set appropriate permissions
• Verify tool availability

Isolation

• Docker containers
• Virtual machines
• Dedicated benchmark machine

Cross-Platform Timer

// cross_platform_timer.h
#ifndef CROSS_PLATFORM_TIMER_H
#define CROSS_PLATFORM_TIMER_H

#include <stdint.h>

#if defined(_WIN32)
    #include <windows.h>
#elif defined(__APPLE__)
    #include <mach/mach_time.h>
#else
    #include <time.h>
#endif

static inline uint64_t get_time_ns(void) {
#if defined(_WIN32)
    static LARGE_INTEGER freq = {0};
    if (freq.QuadPart == 0) QueryPerformanceFrequency(&freq);
    LARGE_INTEGER counter;
    QueryPerformanceCounter(&counter);
    return (uint64_t)(counter.QuadPart * 1000000000ULL / freq.QuadPart);
#elif defined(__APPLE__)
    static mach_timebase_info_data_t timebase = {0};
    if (timebase.denom == 0) mach_timebase_info(&timebase);
    return mach_absolute_time() * timebase.numer / timebase.denom;
#else
    struct timespec ts;
    clock_gettime(CLOCK_MONOTONIC, &ts);
    return (uint64_t)ts.tv_sec * 1000000000ULL + ts.tv_nsec;
#endif
}

#endif // CROSS_PLATFORM_TIMER_H

Benchmark Environment Checklist

Required

• Record hardware specs (CPU, RAM, storage)
• Record OS and kernel version
• Record compiler version and flags
• Close unnecessary background programs
• Ensure sufficient available memory
• Ensure power supply (laptop plugged in)

Recommended (Linux)

• Fix CPU frequency
• Disable Turbo Boost
• Disable ASLR
• Use CPU isolation
• Set real-time priority

Recommended (Windows/macOS)

• Disable antivirus real-time scanning
• Disable Windows Update / macOS auto-updates
• Disable Spotlight indexing (macOS)
• Use "High Performance" power plan (Windows)

At Runtime

• Run sufficient warm-up iterations
• Run enough iterations for statistics
• Record all raw data
• Monitor system state (CPU temp, frequency)