DOCSEARCHbyAlgolia
Submit Docs

blktests

repository·master·Indexed 40 days ago

https://github.com/linux-blktests/blktests

A test framework for the Linux kernel block layer and storage stack, inspired by xfstests. It is used to validate block layer features, bug fixes, and overall coverage through a suite of tests executed via the ./check script.

Tokens
1.9K
Snippets
12
Records
15
Agent score
0%

What's inside blktests

  1. Install and build blktests

    master

    Build the blktests framework using make. You can install it to a specific location using make install. By default, it installs to /usr/local/blktests, but you can override this using the DESTDIR and/or prefix variables.

    Prerequisites

    Ensure the following minimal dependencies are installed:

    • bash (>= 4.3)
    • GNU coreutils
    • GNU awk
    • util-linux
    • fio
    • gcc
    • make
    • getconf
    • systemd-udev (udevadm)

    Optional dependencies for specific tests:

    • Filesystem tools: e2fsprogs, xfsprogs, f2fs-tools, btrfs-progs
    • NVMe: nvme-cli
    • Multipath: multipath-tools (Debian, openSUSE, Arch) or device-mapper-multipath (Fedora)
    • NBD: nbd-client and nbd-server (Debian) or nbd (Fedora, openSUSE, Arch)
    • Device Mapper: dmsetup (Debian) or device-mapper (Fedora, openSUSE, Arch)
    • Ublk: rublk (install via cargo install --version=^0.1 rublk)
    • NVMe-TCP zero-copy offload: python3, ethtool, iproute2
    make
# To install to a custom location:
make install DESTDIR=/path/to/dest prefix=/custom/prefix

  3. Create a new test case

    master
    To add a new test case (e.g., to confirm a bug fix or test a new feature), use the ./new script. This script generates a new test from a template that includes detailed documentation. The generated template defines the variables and functions required for the test case and provides coding guidelines.
    ./new

  4. Execute blktests using the ./check script

    master

    The ./check script is the primary entry point for executing tests. It exits with status 0 if all tests pass, and non-zero otherwise. You can run entire test groups (subdirectories of tests/) or specific individual tests.

    Precedence Rules:

    1. Command line options (highest precedence)
    2. Configuration file (config)
    3. Environment variables (lowest precedence)
    # Run all tests in the 'loop' group and the specific test 'block/002'
./check loop block/002

  5. Configure block devices for testing

    master

    Before running tests, you must specify which block devices to target. Create a file named config in the root directory and define the TEST_DEVS array with the paths to your devices.

    WARNING: These tests are potentially destructive. Do not include any devices containing data you wish to keep.

    TEST_DEVS=(/dev/nvme0n1 /dev/sdb)

  6. Configure test devices with TEST_DEVS and TEST_CASE_DEV_ARRAY

    master

    Tests that require physical block devices use specific variables to identify targets. Warning: Tests are destructive and will overwrite data on these devices.

    Global Test Devices (TEST_DEVS)

    Use TEST_DEVS to define an array of block devices that every applicable test will run on.

    Per-Test Device Arrays (TEST_CASE_DEV_ARRAY)

    For tests requiring multiple specific devices (like bcache or md tests), use the TEST_CASE_DEV_ARRAY associative array. Keys can be specific test case names or regular expressions matching test names.

    Note: If TEST_DEVS is undefined, only tests that do not require a device (often using null_blk or scsi_debug) will run.

    # Global devices
TEST_DEVS=(/dev/nvme0n1 /dev/sdb)

# Specific devices for specific tests or patterns
TEST_CASE_DEV_ARRAY[md/003]="/dev/nvme0n1 /dev/nvme1n1 /dev/nvme2n1 /dev/nvme3n1"
TEST_CASE_DEV_ARRAY[meta/02*]="/dev/nvme0n1 /dev/nvme1n1"
TEST_CASE_DEV_ARRAY[bcache/*]="/dev/nvme0n1 /dev/vdb /dev/vdc"

  7. Manage test timeouts and quick runs

    master

    To prevent long-running tests from hanging the suite, use TIMEOUT and QUICK_RUN.

    • TIMEOUT: Sets the maximum runtime in seconds for each test.
    • QUICK_RUN: When set, only tests that are marked as "quick" or those that honor the timeout will be executed.
    # Limit tests to 30 seconds and only run quick tests
QUICK_RUN=1
TIMEOUT=30

  10. Configure Blk-throttle tests

    master

    The throtl tests use THROTL_BLKDEV_TYPES to select the target block device driver. Options are 'nullb' (null_blk) and 'sdebug' (scsi_debug). The default is 'nullb sdebug'.

    # Run with scsi_debug only
THROTL_BLKDEV_TYPES="sdebug" ./check throtl/

# Run with both
THROTL_BLKDEV_TYPES="nullb sdebug" ./check throtl/

  12. Configure NVMe target via NVME_TARGET_CONTROL

    master

    Setting NVME_TARGET_CONTROL allows running tests against a real, external target. Instead of internal setup, blktests will call the script pointed to by this variable. The external script must implement a specific command interface.

    Required Script Commands:

    • config: --show-blkdev-type, --show-trtype, --show-hostnqn, --show-hostid, --show-host-traddr, --show-traddr, --show-trsvid, --show-subsys-uuid, --show-subsysnqn
    • setup: --subsysnqn SUBSYSNQN, --subsys-uuid SUBSYS_UUID, --hostnqn HOSTNQN, --ctrlkey CTRLKEY, --hostkey HOSTKEY
    • cleanup: --subsysnqn SUBSYSNQN