Overview

The Linux Model Extractor (LiME) is a tool designed to observe and describe the timing behavior of real-time threads on Linux systems. It uses eBPF to monitor process execution and can extract various metrics including periodic behaviors, execution times, and resource usage patterns.

Prerequisites

• Linux kernel version 5.15 or later
• Rust toolchain (1.75.0 or later)
• LLVM and Clang

Installation

Installing Dependencies

On Ubuntu/Debian:

# Install required dependencies
sudo apt-get update
sudo apt-get install -y libbpf-dev libelf-dev zlib1g-dev pkg-config clang protobuf-compiler

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Building from Source

# Clone the repository
git clone https://github.com/LiME-org/lime-rtw.git
cd lime-rtw

# Build the project
cargo build --release

# Note: Root privileges are required to load eBPF programs
sudo target/release/lime-rtw

Usage

LiME provides three main commands:

1. Trace Command

Records and dumps a trace in JSON format:

sudo lime-rtw trace [OPTIONS] [COMMAND]

Example of tracing a real-time program:

# Trace htop running with SCHED_FIFO policy
sudo lime-rtw trace -- chrt -f 99 htop

Options:

• -o, --output <DIR>: Specify output directory
• --all: Do not filter by child TGID
• --cfs: Trace events emitted by CFS tasks
• --irq: Trace IRQ events
• --user-job <PATH>: Path to JSON format user job
• --rate-limiter-period <DURATION>: Set rate limiter period
• --rate-limiter-budget <NUMBER>: Set rate limiter budget
• --allow-task-affinity-change: Do not update task ID on affinity change
• --allow-task-priority-change: Do not update task ID on priority change

2. Extract Command

Observes the system and extracts a workload model:

sudo lime-rtw extract [OPTIONS] [COMMAND]

Examples:

# Extract from live execution
sudo lime-rtw extract -- /path/to/rt-application

# Extract from recorded trace
sudo lime-rtw extract --from /path/to/trace

Options:

• -o, --output <DIR>: Specify output directory
• -f, --from <PATH>: Path to a trace folder for offline analysis
• --inplace: Save extraction in the trace folder
• --max-jitter <MS>: Max jitter for periodic extraction (default: 1000ms)
• --wcet-n-max-len <N>: Max window length for WCET(n) (default: 32)
• --enable-rbf: Enable Request Bound Function extraction
• --rbf-horizon <DURATION>: Set RBF horizon (default: 10s)
• --all-threads: Report all threads, including short-lived ones

3. Extract Jobs Command

Extracts job information from a recorded trace:

sudo lime-rtw extract-jobs -f <trace_folder> [OPTIONS]

Options:

• -o, --output <DIR>: Specify output directory
• -f, --from <PATH>: Path to trace folder (required)
• --inplace: Save extraction in the trace folder

Output Format

Successfully extracted models are recorded as:

• <pid>.models.json for the first extraction
• <pid>.models.<version>.json for subsequent extractions (version: 1-255)

Project Structure

LiME consists of two main components:

Tracing Component

• Located in src/bpf/
• Uses eBPF for kernel-level tracing
• Defines callbacks for tracepoints and shared memory buffers
• Event formats defined in src/bpf/lime_tracer.h

Extraction Component

• Implements the model extraction logic
• Uses observer pattern for event handling
• Supports various metrics including:
  • Periodic behavior
  • Execution times
  • Resource usage patterns
  • Request Bound Functions (RBF)

Profiling

For profiling on OSX, use cargo-instruments:

cargo instruments -t time --release -- <lime_arguments>

Contributing

Contributions are welcome! Please feel free to submit pull requests to the LiME repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and feature requests, please use the GitHub issue tracker.