Crate test_bd 

A library for creating procedurally generated test block devices using ublk.

test-bd provides a simple API for creating userspace block devices with deterministic, procedurally generated data patterns. This is useful for testing storage systems, compression algorithms, deduplication systems, and other block-level operations.

Features

• Procedural Data Generation: Create block devices with deterministic data patterns using a seed-based random number generator
• Multiple Pattern Types: Support for fill (zeros), duplicate (repeating blocks), and random data patterns
• Configurable Segmentation: Divide devices into multiple segments with different data patterns
• Device Management: High-level API for managing multiple devices with automatic cleanup

Quick Start

The easiest way to create and manage test block devices is using DeviceManager:

use test_bd::{DeviceManager, TestBlockDeviceConfig};

// Create a device manager
let mut manager = DeviceManager::new();

// Configure a 1 GiB device with mixed data patterns
let config = TestBlockDeviceConfig {
    dev_id: -1,              // Auto-assign device ID
    size: 1024 * 1024 * 1024, // 1 GiB
    seed: 42,                // Seed for reproducibility
    fill_percent: 40,        // 40% zeros (compressible)
    duplicate_percent: 30,   // 30% duplicate blocks (deduplicatable)
    random_percent: 30,      // 30% random data
    segments: 100,           // 100 segments
    unprivileged: false,
};

// Create the device (appears as /dev/ublkbN)
let device = manager.create(config).expect("Failed to create device");
println!("Created device: /dev/ublkb{}", device.dev_id);

// Use the device...
// The device will be automatically cleaned up when manager is dropped

Data Patterns

Three types of data patterns are supported via the Bucket enum:

• Fill: All zeros (highly compressible)
• Duplicate: Repeating 512-byte blocks (deduplicatable)
• Random: Deterministic pseudo-random data (incompressible)

The device is divided into segments, and each segment is randomly assigned one of these patterns based on the configured percentages.

Low-Level API

For more control, use the TestBlockDevice API directly:

use test_bd::{TestBlockDevice, TestBlockDeviceConfig};

let config = TestBlockDeviceConfig {
    dev_id: -1,
    size: 100 * 1024 * 1024,  // 100 MiB
    seed: 42,
    fill_percent: 50,
    duplicate_percent: 25,
    random_percent: 25,
    segments: 50,
    unprivileged: false,
};

// This blocks until the device is stopped
TestBlockDevice::run(config).expect("Failed to run device");

Segment Information

You can inspect the segment layout before or after creating a device:

use test_bd::{TestBlockDeviceConfig, Bucket};

let config = TestBlockDeviceConfig {
    dev_id: -1,
    size: 10240,
    seed: 42,
    fill_percent: 50,
    duplicate_percent: 25,
    random_percent: 25,
    segments: 10,
    unprivileged: false,
};

let segments = config.generate_segments();
for (i, segment) in segments.iter().enumerate() {
    println!("Segment {}: {:?} pattern, {} bytes",
             i, segment.pattern, segment.size_bytes());
}

Requirements

• Linux kernel with ublk support (kernel 6.0+)
• Root privileges (unless using unprivileged mode, which requires kernel 6.5+)

See Also

• TestBlockDeviceConfig - Configuration structure
• DeviceManager - High-level device management
• TestBlockDevice - Low-level device API
• SegmentInfo - Segment layout information
• Bucket - Data pattern types

Structs

DeviceManager

Manager for multiple test block devices.

IndexPos

A position index representing an 8-byte aligned offset in a block device.

ManagedDevice

A handle to a managed test block device.

SegmentInfo

Information about a contiguous segment of the block device with a specific data pattern.

TestBlockDevice

Main API for creating and managing test block devices.

TestBlockDeviceConfig

Configuration for creating a test block device.

Enums

Bucket

Represents the type of data pattern used in a block device segment.