DragonOS/docs/locales/en/kernel/device/loop_device.md

:::{note} AI Translation Notice

This document was automatically translated by hunyuan-turbos-latest model, for reference only.

• Source document: kernel/device/loop_device.md

• Translation time: 2025-12-24 06:30:50

• Translation model: hunyuan-turbos-latest

Please report issues via Community Channel

:::

Loop Device Architecture Design

This document outlines the architectural design rationale of the loop device subsystem in DragonOS, serving as guidance for development and future evolution.

Problem Background

In operating system development, we frequently encounter these requirements:

• How to use an image file as a block device?
• How to dynamically create/delete virtual block devices without system reboot?

The loop device is the key component addressing these needs.

System Architecture Positioning

The loop device plays the role of a "virtualization bridge" in DragonOS architecture:

用户态应用
     ↓
loop-control 接口 (字符设备)
     ↓
LoopManager (设备生命周期管理)
     ↓
LoopDevice[] (虚拟块设备数组)
     ↓
块设备层 ←→ 后端文件系统

The core concept of this layered design is: separating control plane from data plane.

Core Design Philosophy

1. State-driven Device Management

We adopt a state machine approach for device lifecycle management, similar to Linux design:

Unbound → Bound → Rundown → Deleting
    ↓       ↓         ↓
Deleting  Unbound  Deleting

Design Considerations:

• Prevent illegal state transitions (e.g., deleting a device directly in Bound state)
• Provide clear device lifecycle semantics
• Lay foundation for future extensions (e.g., hot-plugging)

2. Dual Interface Strategy

Our design deliberately distinguishes between two interfaces:

Character Control Interface (/dev/loop-control):

• Manages device lifecycle
• Provides user-friendly device allocation/recycling mechanisms
• Maintains compatibility with Linux standard interfaces

Block Device Interface (/dev/loopX):

• Focuses on data read/write functionality
• Provides standard block device semantics
• Supports advanced features like offset and size limits

Design Value: This separation ensures control logic and data paths don't interfere, improving system maintainability.

3. Security First

When interacting with user space, we implement multiple security checks:

• Parameter Boundary Checks: All offsets and sizes must be LBA-aligned
• Memory Safety: Uses UserBufferReader/Writer for user-space data copying
• Permission Validation: Read-only devices reject write operations
• State Validation: Each operation checks if current device state permits it

Module Collaboration Architecture

Role of LoopManager

LoopManager isn't just a device array manager, but the subsystem's "dispatch center":

• Device Allocation Policy: Adopts "nearest allocation" principle, prioritizing reuse of idle devices
• Resource Pool Management: Pre-registers 8 devices to avoid runtime allocation overhead
• Concurrency Safety: All device operations are protected by locks

Abstraction Design of LoopDevice

The core abstraction of LoopDevice is "block device view of backend files":

用户视角          内部实现
/dev/loop0  ←→   文件偏移 + 大小限制
  块0-100           文件偏移0-51200
  块101-200         文件偏移51200-102400

This design allows mapping any part of a file as a block device, providing great flexibility for applications like containers.

Key Designs

Why Choose 256 as Device Limit?

• Sufficient for most application scenarios
• Avoids resource exhaustion from unlimited growth
• Maintains compatibility with Linux's default limit

Why Pre-register 8 Devices?

• Covers common testing scenarios (typically ≤4-5 devices)
• Reduces wait time for first-time usage
• Provides a reasonable initial working set

Why Use SpinLock Instead of Other Locks?

• Loop device operations are mostly short-lived
• Avoids complex lock hierarchies and deadlocks
• Simplifies implementation and improves performance

Compatibility Considerations

Our design heavily references Linux loop driver interfaces by intentional choice:

1. User-space Software Compatibility: Existing loop tools work without modification
2. API Contract Consistency: Avoids potential issues from interface differences
3. Community Knowledge Reuse: Developers can leverage existing loop device knowledge

Summary

DragonOS's loop device design follows these core principles:

1. Clear Architecture: Separation of control and data planes
2. State Safety: State-machine-based device lifecycle management
3. Interface Compatibility: Alignment with Linux standard interfaces
4. Extension Friendly: Architectural space reserved for future features
5. Comprehensive Testing: Quality ensured through multi-level testing