Environment Setup

A step-by-step guide to building the USM kernel, module, and userspace components from the provided source.

Setting up the USM environment requires compiling the patched Linux kernel included in this repository. This is a mandatory step to enable the necessary features for USM to function.

Note:

This guide is tested on Ubuntu 22.04 LTS running in a QEMU/KVM virtual machine. We strongly recommend using this environment with at least 8GB of RAM and the maximum available CPU cores to ensure a smooth build process.

Follow these steps carefully to prepare your system.

1

Step 0: Clone the Repository

Before you begin, clone the flusm repository to your home directory or another location of your choice. All subsequent commands will assume you are navigating within this cloned directory.

git clone https://github.com/HTester4/flusm.git
cd flusm
2

Step 1: Install Dependencies & Check dwarves

First, install the build dependencies. The most critical step is ensuring the dwarves package version is correct.

  1. Install Build Tools:

    sudo apt update
sudo apt install build-essential bison flex libncurses-dev libssl-dev libelf-dev dwarves cmake pkg-config clang libdw-dev libbpf-dev liblz4-tool liblz4-dev

  2. Verify dwarves Version:

    Critical: dwarves version must be equal to 1.25:

    The kernel build process will fail with newer versions.

    pahole --version

    If the version is 1.25, proceed to the next step. If it is higher, you must uninstall it and build the provided version from source:

    # Uninstall the system version
sudo apt remove pahole dwarves

# Navigate to the provided source and build
cd Dependencies/dwarves-1.25
mkdir build && cd build
cmake -D__LIB=lib -DBUILD_SHARED_LIBS=OFF ..
sudo make install
3

Step 2: Build the Kernel

Now, navigate to the Kernel/ directory within the repository to configure and compile the provided kernel source. This is the longest step.

  1. Navigate and Create Initial Config:

    # Assuming you are in the root of the cloned 'flusm' repository
cd Kernel/
cp /boot/config-$(uname -r) .config

  2. Enable USM Kernel Options:

    echo -e "CONFIG_CMA=y\nCONFIG_DMA_CMA=y\n" >> .config

  3. Update Config and Disable Key Signing:

    yes "" | make localmodconfig
scripts/config --disable SYSTEM_TRUSTED_KEYS
scripts/config --disable SYSTEM_REVOCATION_KEYS
scripts/config --set-str CONFIG_SYSTEM_TRUSTED_KEYS ""
scripts/config --set-str CONFIG_SYSTEM_REVOCATION_KEYS ""

  4. Compile the Kernel:

    # This will take a long time.
sudo make -j $((`getconf _NPROCESSORS_ONLN`+1))
4

Step 3: Install Kernel and Configure System

With the kernel compiled, install it and configure the bootloader and system environment.

  1. Install the New Kernel:

    sudo make modules_install
sudo make install
sudo make headers_install INSTALL_HDR_PATH=/usr

  2. Configure GRUB for CMA:

    sudo nano /etc/default/grub

    Modify the GRUB_CMDLINE_LINUX or GRUB_CMDLINE_LINUX_DEFAULT line to reserve 2GB of memory for USM. Your file should look similar to this:

    GRUB_DEFAULT=saved
GRUB_SAVEDEFAULT=true
GRUB_TIMEOUT=5
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"
GRUB_CMDLINE_LINUX="transparent_hugepage=never cgroup_disable=memory selinux=0 cma=2G"

    Save the file and update GRUB.

    sudo update-grub

  3. Disable System Swap: USM manages its own swapping, so the OS swapper should be disabled.

    sudo swapoff -a
# Also comment out the swap line in /etc/fstab to make it permanent
sudo nano /etc/fstab

  4. Reboot:

    sudo reboot
5

After rebooting into your new kernel, the final step is to build the USM module and userspace components.

6
Introduction to USM Configuration
7

Step 4: Build Module & Userspace, and Verify

  1. Verify the Environment:

    # Check you are running the new kernel
uname -r 
# The output should contain '6.0.0+'

# Verify the CMA pool was reserved
sudo dmesg | grep cma
# You should see a line like: "cma: Reserved 2048 MiB at..."

  2. Build the Userspace API:

    # Navigate from the repo root
cd Userspace/APIv
make

  3. Build and Load the Kernel Module:

    # Navigate from the repo root
cd ../Kernel/Module
make
sudo insmod usm_lkmRM.ko

  4. Verify Module Load:

    sudo dmesg
# You should see "Yo! #USMRM" near the end of the output.

Your environment is now fully configured. You are ready to run the InstanceUSM (project-2) and manage applications with USM.

Final Verification of USM Installation

Ready to get started? Let's dive into the Test that make USM work.

Edit this page on GitHub