TAIL OS

get_started

Posted by:

cs253086

|

On:

|

Getting Started with TAIL OS

Welcome to TAIL OS! This guide will help you download, build, run, and develop applications for TAIL OS.

Table of Contents

  1. Prerequisites
  2. Download and Setup
  3. Building TAIL OS
  4. Running TAIL OS
  5. Developing Applications
  6. Troubleshooting

Prerequisites

System Requirements

  • Operating System: Linux (Ubuntu/Debian recommended)
  • Architecture: x86_64 host system
  • Memory: At least 4GB RAM
  • Storage: At least 10GB free space

Required Software

Before starting, ensure you have the following installed:

# Essential build tools
sudo apt update
sudo apt install build-essential curl git

# Cross-compilation dependencies
sudo apt install bison flex libgmp3-dev libmpc-dev libmpfr-dev texinfo

# QEMU for emulation
sudo apt install qemu-system-arm qemu-efi

# Development tools
sudo apt install gdb-multiarch libelf-dev

Download and Setup

1. Download

wget https://tail-os.com/wp-content/uploads/2025/09/install_tail_os_for_qemu.sh
wget https://tail-os.com/wp-content/uploads/2025/09/run_tail_os_on_qemu.sh

2. Install

chmod +x ./install_tail_os_for_qemu.sh
./install_tail_os_for_qemu.sh
# Follow the instructions

3. Run

# Set up TAIL OS environment
source ~/.bashrc
chmod +x ./run_tail_os_on_qemu.sh

# Run TAIL OS
./run_tail_os_on_qemu.sh

4. Build Cross-Compiler Toolchain

# Run the setup script
./utility/host/set_up_tail/set_up_tail_dev_env.sh

This script will:

  • Build AArch64 cross-compiler (GCC + Binutils)
  • Set up Rust target for AArch64
  • Configure build environment

Building TAIL OS

Build Options

TAIL OS supports both debug and release builds:

# Debug build (recommended for development)
make build-debug

# Release build (optimized for performance)
make build-release

What Gets Built

The build process creates:

  • Startup: Bootloader and early initialization
  • Kernel: Core operating system
  • Drivers: Hardware drivers (UART, SD card)
  • Servers: System services (file system server)
  • Utilities: Basic user programs (shell, ls)
  • OS Image: Complete bootable image (tail.rfs)

Build Output

After successful build, you’ll find:

  • OS image: ${TAIL_ROOT}/os_image/tail.rfs
  • Individual binaries: ${TAIL_ROOT}/target/bin/
  • Disk image: tail_disk.img

Running TAIL OS

Using QEMU (Recommended)

# Run debug build
make run-debug

# Run release build
make run-release

QEMU Options

# Run with GDB debugging
make run-gdb

# In another terminal, connect GDB
gdb-multiarch
(gdb) target remote localhost:1234
(gdb) file ${TAIL_ROOT}/target/bin/aarch64-kernel
(gdb) continue

Expected Output

When TAIL OS boots successfully, you should see:

[START] kernel
[SUCCESS] KERNEL_MEMORY_ALLOCATOR is initialized
[SUCCESS] exception manager is initialized
[SUCCESS] system clock is initialized
#  Type 'exit' to terminate TSH    #

tsh>

Developing Applications

Application Structure

TAIL OS applications are Rust programs that use the tail_core library for system services.

1. Creating Your Own Application

Step 1: Create Project Structure

mkdir -p utility/target/myapp/src
cd utility/target/myapp

Step 2: Create Cargo.toml

[package]
name = "myapp"
version = "0.1.0"
edition = "2021"

[dependencies]
tail_core = { path = "../../../library/tail_core" }

Step 3: Create main.rs

use tail_core::kprint;

fn main() {
    kprint!("Hello from my TAIL OS application!n");

    // Your application logic here
    loop {
        // Application main loop
    }
}

2. Compiling Your Application

Method 1: Using Cargo (Recommended)

cd utility/target/myapp

# Compile for TAIL OS target
cargo build --target aarch64-unknown-tail --release

# The binary will be in target/aarch64-unknown-tail/release/myapp

Method 2: Using Makefile

Add your application to the main Makefile:

# Add to build-release and build-debug targets
cd utility/target/myapp && 
cargo install --path ./ --root ${TAIL_ROOT}/target --target aarch64-unknown-tail --verbose

3. Loading Your Program

Add to Build Configuration

Edit tail.build file:

# Add your application name to the list
aarch64-startup
kernel
uart_pl011
sd_rpi3
fat_file_system_server
tsh
myapp  # Add this line

Rebuild OS Image

# Rebuild with your application included
make build-debug

4. Executing Your Program

Method 1: Automatic Loading

If added to tail.build, your program will be automatically loaded at boot and available as a process.

Method 2: Manual Execution

From the TAIL OS shell:

tsh> myapp
Hello from my TAIL OS application!

5. Advanced Application Development

Using System Calls

use tail_core::syscall::*;

fn main() {
    // Create a topic for IPC
    let topic_id = create_topic("my_topic").unwrap();

    // Publish data to topic
    let data = b"Hello, World!";
    publish_to_topic(topic_id, data).unwrap();

    // Subscribe to topic
    subscribe_topic(topic_id).unwrap();
}

Memory Management

use tail_core::syscall::*;

fn main() {
    // Allocate memory
    let size = 4096; // 4KB
    let addr = mmap(0, size, PROT_READ | PROT_WRITE).unwrap();

    // Use the memory
    unsafe {
        let slice = std::slice::from_raw_parts_mut(addr as *mut u8, size);
        slice[0] = 42;
    }

    // Free memory
    munmap(addr, size).unwrap();
}

Inter-Process Communication

use tail_core::syscall::*;

fn main() {
    // Create a server
    let server_id = create_server("my_service").unwrap();

    // Handle requests
    loop {
        if let Ok(request) = receive_service_request(server_id) {
            // Process request
            let response = b"Response data";
            reply_to_service_request(request.id, response).unwrap();
        }
    }
}

6. Debugging Applications

Using GDB

# Build with debug symbols
cargo build --target aarch64-unknown-tail

# Run with GDB
make run-gdb

# In GDB
(gdb) target remote localhost:1234
(gdb) file target/aarch64-unknown-tail/debug/myapp
(gdb) break main
(gdb) continue

Using Kernel Print

use tail_core::kprint;

fn main() {
    kprint!("Debug: Application startedn");
    kprint!("Debug: Variable value = {}n", 42);
}

Troubleshooting

Common Issues

Build Failures

# Clean and rebuild
make clean
make build-debug

QEMU Issues

# Check QEMU installation
qemu-system-aarch64 --version

# Try different QEMU options
qemu-system-aarch64 -M raspi3b -kernel ${TAIL_ROOT}/os_image/tail.rfs -serial stdio

Rust Toolchain Issues

# Update Rust
rustup update

# Reinstall target
rustup target remove aarch64-unknown-tail
rustup target add aarch64-unknown-tail

Cross-Compiler Issues

# Rebuild toolchain
cd toolchain/aarch64-elf-gcc
./build_target_toolchain.sh

Getting Help

  • Documentation: Check doc/ directory for detailed documentation
  • Issues: Report bugs and ask questions on the project repository
  • Community: Join discussions in project forums

Development Tips

  1. Start Simple: Begin with basic applications before complex ones
  2. Use Debug Builds: Debug builds include more error checking
  3. Test Frequently: Test your applications regularly during development
  4. Read Documentation: Familiarize yourself with tail_core API
  5. Use GDB: Debugging is essential for complex applications

This guide provides the foundation for TAIL OS development. For advanced topics, refer to the detailed documentation in the doc/ directory.

Posted by

cs253086

in