RAM File System (axfs_ramfs)

Relevant source files

Cargo.toml

README.md

axfs_devfs/README.md

Purpose and Scope

axfs_ramfs implements a RAM-based file system for the axfs_crates ecosystem. It provides an in-memory storage solution that conforms to the Virtual File System (VFS) interfaces defined in axfs_vfs. This document covers the architecture, components, and usage patterns of the RAM File System.

For information about the VFS interface that axfs_ramfs implements, see Virtual File System Interface (axfs_vfs).

Sources: Cargo.toml(L4 - L8) README.md(L7 - L9)

System Architecture

The RAM File System is one of the concrete implementations in the axfs_crates ecosystem, alongside the Device File System (axfs_devfs).

Integration with axfs_crates

flowchart TD
A["Applications"]
B["axfs_vfs: VfsOps & VfsNodeOps Traits"]
C["axfs_ramfs: RamFileSystem"]
D["axfs_devfs: DeviceFileSystem"]
E["System Memory (RAM)"]
F["Hardware Devices"]

A --> B
B --> C
B --> D
C --> E
D --> F

This diagram illustrates how axfs_ramfs fits within the overall architecture. Applications interact with file systems through the VFS interface, which delegates operations to the appropriate implementation based on mount points.

Sources: Cargo.toml(L4 - L8) README.md(L7 - L9)

Core Components

Based on the VFS interface requirements, the RAM File System likely consists of these core components:

Component Relationships

classDiagram
class VfsOps {
    <<trait>>
    
    +mount(path, mount_point)
    +root_dir()
}

class VfsNodeOps {
    <<trait>>
    
    +get_attr()
    +lookup(path)
    +read_dir(start_idx, dirents)
    +read_at(offset, buf)
    +write_at(offset, buf)
    +create(path, type)
    +remove(path)
    +truncate(size)
}

class RamFileSystem {
    -root
    +new()
    +root_dir()
    +mount(path, mount_point)
}

class RamDirNode {
    -parent
    -children
    +new()
    +lookup(path)
    +create(name, type)
}

class RamFileNode {
    -parent
    -content
    +new()
    +read_at(offset, buf)
    +write_at(offset, buf)
    +truncate(size)
}

VfsOps  ..|>  RamFileSystem : implements
VfsNodeOps  ..|>  RamDirNode : implements
VfsNodeOps  ..|>  RamFileNode : implements
RamFileSystem  -->  RamDirNode : contains
RamDirNode  -->  RamDirNode
RamDirNode  -->  RamDirNode : contains
RamDirNode  -->  RamDirNode
RamDirNode  -->  RamFileNode : contains

The key components likely include:

Component	Purpose	Key Responsibilities
RamFileSystem	Main file system implementation	ImplementsVfsOpstrait, manages mount operations, provides access to root directory
RamDirNode	Directory node implementation	Stores hierarchical structure, manages children (files and subdirectories)
RamFileNode	File node implementation	Stores file content in memory, handles read/write operations

These components work together to provide a complete in-memory file system hierarchy with the same interface as other file systems.

Sources: Based on common Rust patterns and the VFS architecture shown in the high-level diagrams

In-Memory Hierarchy

A typical RAM file system hierarchy structure:

flowchart TD
A["RamDirNode: Root '/'"]
B["RamDirNode: '/tmp'"]
C["RamDirNode: '/home'"]
D["RamFileNode: 'temp.txt'"]
E["RamDirNode: 'cache'"]
F["RamFileNode: 'data.bin'"]
G["RamDirNode: 'user1'"]
H["RamFileNode: 'document.txt'"]
I["RamFileNode: 'image.png'"]

A --> B
A --> C
B --> D
B --> E
C --> G
E --> F
G --> H
G --> I

This structure mirrors traditional file systems but exists entirely in memory. Each node (RamDirNode or RamFileNode) implements the VfsNodeOps trait, providing a consistent interface regardless of node type.

Sources: Based on common file system hierarchy patterns

Operation Patterns

The RAM File System implements file system operations defined by the VFS traits:

File System Operations (VfsOpsTrait)

mount: Attaches the RAM file system to a mount point
root_dir: Provides access to the root directory

Node Operations (VfsNodeOpsTrait)

Operation	Description	Implementation Considerations
get_attr	Get node attributes (size, type, etc.)	Return cached attributes or calculate on demand
lookup	Find a node by path	Traverse directory hierarchy to locate node
read_dir	List directory contents	Return entries from directory's children map
read_at	Read file data from specified offset	Access in-memory buffer at offset
write_at	Write file data at specified offset	Modify in-memory buffer, potentially resize
create	Create new file or directory	Allocate new node, add to parent's children
remove	Delete file or directory	Remove from parent's children, free memory
truncate	Change file size	Resize in-memory buffer

Sources: Based on VFS interface requirements

Usage Lifecycle

sequenceDiagram
    participant Application as "Application"
    participant VFSInterface as "VFS Interface"
    participant RamFileSystem as "RamFileSystem"
    participant RamDirNode as "RamDirNode"
    participant RamFileNode as "RamFileNode"

    Application ->> RamFileSystem: RamFileSystem::new()
    RamFileSystem ->> RamDirNode: RamDirNode::new()
    RamDirNode ->> RamFileSystem: Arc<RamDirNode>
    RamFileSystem ->> Application: RamFileSystem instance
    Application ->> VFSInterface: mount("/tmp", ramfs.root_dir())
    VFSInterface ->> RamFileSystem: mount operation
    Application ->> VFSInterface: create("/tmp/file.txt", VfsNodeType::File)
    VFSInterface ->> RamFileSystem: create request
    RamFileSystem ->> RamDirNode: lookup("/tmp")
    RamDirNode ->> RamFileSystem: tmp directory node
    RamFileSystem ->> RamDirNode: create("file.txt", VfsNodeType::File)
    RamDirNode ->> RamFileNode: RamFileNode::new()
    RamFileNode ->> RamDirNode: Arc<RamFileNode>
    RamDirNode ->> RamFileSystem: Success
    RamFileSystem ->> VFSInterface: Success
    VFSInterface ->> Application: Success
    Application ->> VFSInterface: lookup("/tmp/file.txt")
    VFSInterface ->> RamFileSystem: lookup request
    RamFileSystem ->> RamDirNode: lookup("/tmp")
    RamDirNode ->> RamFileSystem: tmp directory node
    RamFileSystem ->> RamDirNode: lookup("file.txt")
    RamDirNode ->> RamFileNode: Get file node
    RamFileNode ->> RamDirNode: file node
    RamDirNode ->> RamFileSystem: file node
    RamFileSystem ->> VFSInterface: file node
    VFSInterface ->> Application: file node
    Application ->> VFSInterface: write_at(file, 0, data)
    VFSInterface ->> RamFileNode: write_at(0, data)
    RamFileNode ->> RamFileNode: Store data in memory buffer
    RamFileNode ->> VFSInterface: bytes_written
    VFSInterface ->> Application: bytes_written

This sequence diagram illustrates the typical lifecycle of RAM file system usage, from creation to file operations.

Sources: Based on common file system operation patterns

Implementation Considerations

The RAM File System implementation likely uses these Rust features:

Arc<T> for shared ownership of nodes
Weak<T> references to prevent reference cycles (particularly for parent pointers)
RwLock<T> or Mutex<T> for concurrent access to mutable data
Vec<u8> or similar for storing file contents
BTreeMap<String, VfsNodeRef> for directory entries

Advantages and Limitations

Advantages

Performance: Memory operations are faster than disk I/O
Simplicity: No need for persistent storage management
Portability: Works in environments without storage devices

Limitations

Volatility: All data is lost on system shutdown or restart
Capacity: Limited by available RAM
Concurrent Access: Requires careful synchronization for thread safety

Use Cases

Temporary file storage
Cache for frequently accessed data
Test environments
Embedded systems with limited storage
Performance-critical applications

Sources: README.md(L9)

ArceOS Crates Book