Userspace

📋 Overview

Userspace is a Rust implementation of a standard library for userspace applications, designed to work without depending on the Rust standard library (no_std). It provides safe abstractions for low-level operations, architecture-specific functionality, memory management, and executable file format handling.

Key Features

• 🔒 Memory Safety: Leverage Rust's ownership model for secure systems programming
• 🧩 Modular Architecture: Well-defined components with clear interfaces
• 🔄 Cross-Platform: Architecture abstractions for portability (currently x86_64)
• 📦 No Standard Library: Works in no_std environments
• 📄 ELF Support: Parse and work with Executable and Linkable Format files
• 🧠 Memory Management: Stack manipulation and memory allocation utilities

🔍 Project Structure

userspace/
├── src/
│   ├── file/         # File format handling (ELF)
│   ├── macros/       # Utility macros
│   ├── memory/       # Memory management
│   │   ├── alloc/    # Allocation functionality
│   │   ├── page/     # Page management
│   │   └── stack/    # Stack handling
│   ├── target/       # Architecture abstractions
│   │   ├── architecture/   # CPU architecture specifics
│   │   └── operating_system/  # OS abstractions
│   ├── traits/       # Common interfaces
│   ├── types/        # Library-specific types
│   ├── entry.rs      # Binary entry point
│   ├── library.rs    # Main library definition
│   ├── panic.rs      # Panic handler
│   └── result.rs     # Error handling
├── Cargo.toml        # Project configuration
└── build.rs         # Build script

🚀 Getting Started

Prerequisites

• Rust 2024 Edition or newer
• Cargo and Rustup

Installation

Add this to your Cargo.toml:

[dependencies]
userspace = { git = "https://github.com/ze-gois/rust_userspace" }

Usage Example

// Create a no_std binary
#![no_std]
#![no_main]

use userspace;

#[unsafe(no_mangle)]
pub extern "C" fn entry(stack_pointer: userspace::target::arch::PointerType) -> ! {
    // Convert raw stack pointer to a safe abstraction
    let stack = userspace::memory::Stack::from_pointer(
        userspace::target::arch::Pointer(stack_pointer)
    );
    
    // Access command-line arguments
    if let Some(arg) = stack.arguments.get(0) {
        userspace::info!("Program name: {:?}", arg);
    }
    
    // Work with the ELF format
    if let Some(arg0) = stack.arguments.get(0) {
        if !arg0.pointer.0.is_null() {
            unsafe {
                let cstr = core::ffi::CStr::from_ptr(arg0.pointer.0 as *mut i8);
                let path = cstr.to_str().unwrap();
                let elf = userspace::file::format::elf::header::Identifier::from_path(path);
                userspace::info!("ELF identifier: {:?}", elf);
            }
        }
    }
    
    loop {}
}

🛠️ Architecture

Userspace is designed with a layered architecture:

1. Core Layer: Basic types, traits and utilities
2. Target Layer: Architecture and OS abstractions
3. Memory Layer: Stack, pages, and allocation
4. File Layer: File format parsing and manipulation

Each layer builds upon the previous ones, providing increasingly higher-level abstractions while maintaining safety and performance.

Memory Management

The memory subsystem provides:

• Safe stack traversal and argument extraction
• Page allocation primitives
• Basic heap allocation in no_std environments

Architecture Abstraction

The target subsystem abstracts architecture details:

• Pointer types and operations
• Register access patterns
• CPU-specific features
• OS-specific functionality

Currently focused on x86_64, but designed to be extensible to other architectures.

🧪 Experimental Features

Userspace uses several experimental Rust features:

#![feature(generic_const_exprs)]
#![feature(generic_const_items)]

These enable advanced type-level programming required for zero-cost abstractions across architectures.

📚 Documentation

For more detailed documentation:

cargo doc --open

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -am 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📜 License

This project is licensed under the terms found in the LICENSE file.

🔮 Future Work

• Support for additional architectures (ARM, RISC-V)
• Enhanced file system abstractions
• Networking capabilities
• Threading and concurrency primitives
• Comprehensive test suite