LiME - Documentation.
Last updated on

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

Kernel Requirements

LiME has been tested and is supported on Linux kernel versions from 5.15 to 6.12. Using LiME with kernel versions outside this range may result in unexpected behavior.

The tool requires a Linux kernel with eBPF features enabled. Additionally, the kernel must be compiled with CONFIG_DEBUG_INFO_BTF=y as LiME utilizes eBPF's CO-RE (Compile Once - Run Everywhere) feature. Without this configuration, the eBPF programs will fail to load.

For Raspberry Pi 4 and 5 users, we provide specific instructions for compiling a kernel with BTF support.

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
  • --best-effort: Trace events emitted by best-effort 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

4. View Command (TUI-viewer)

View traced results and extracted models in a TUI:

lime-rtw view <FOLDER>

Arguments:

  • <FOLDER>: Path to the folder containing trace results and extracted models

Options:

  • -h, --help: Print help

The TUI-viewer supports the following navigation controls: up/down arrows for vertical navigation, left/right arrows for horizontal scrolling, enter key to go into details, escape key to return to the previous view, and q to exit the application.

Output Format

Successfully extracted models are recorded as:

  • $(taskID).models.json

A taskID is composed of a process ID (pid) and a unique identifier, formatted as $(pid)-$(identifier). The identifier increments when task properties change, such as when the scheduling policy is modified. The identifier ranges from 0 to 255.

Additional output files include:

  • $(taskID).jobs.json: Contains extracted jobs information for a task (only generated when executing the extract-jobs command)
  • $(taskID).events.json: Contains all raw events captured for a task when using offline mode
  • $(taskID).infos.json: Contains task information such as scheduling policy, PPID, comm and other task-specific details

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)

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.