..
 # Copyright (c) 2025, Arm Limited.
 #
 # SPDX-License-Identifier: MIT

############
Introduction
############

********************
Overview of Fastpath
********************

Fastpath is a command-line tool specifically designed for monitoring the
performance of the Linux kernel by executing structured performance benchmarks
on a diverse range of hardware platforms. It automates the collection, storage,
and analysis of performance data to assess how Linux kernel modifications impact
various workloads. By structuring execution plans in YAML and providing flexible
result management, Fastpath enables developers and performance engineers to
detect regressions, validate optimizations, and track long-term performance
trends effectively.

***************************
Key Features & Capabilities
***************************

- **Benchmark Execution Automation**: Define and execute benchmark runs using
  structured plans.
- **Flexible Result Management**: Store results in CSV, SQLite, or MySQL formats
  for analysis.
- **Statistical Performance Analysis**: Compare multiple benchmark runs to
  detect performance regressions or improvements.
- **Command-Line Driven**: Lightweight and scriptable for CI/CD integration.
- **Multi-Architecture Support**: Native support for arm64 and x86_64.
- **Extensibility**: New benchmarks can be integrated without needing to modify
  the tool.
- **Containerized Benchmarks**: Benchmarks are deployed as containers so that
  all user-space code remains identical across different SUTs.
- **Interactive Dashboard**: Visualize results in web browser.
- **Performance Regression Bisection (Coming Soon!)**: Identifies the specific
  Git commit responsible for performance regressions.

*******************************
Supported Workflows & Use Cases
*******************************

Fastpath is used in various scenarios, including:

- **Kernel Performance Tracking**: Monitoring Linux kernel updates and their
  impact on workloads.
- **Hardware Comparison**: Comparing different systems under test (SUTs) to
  evaluate performance.
- **Automated CI/CD Benchmarking**: Running benchmarks as part of a continuous
  integration process.

*****
Links
*****

- Documentation is available at: https://fastpath.docs.arm.com
- Source Code is available at: https://gitlab.arm.com/tooling/fastpath
- Container Images are available at: https://gitlab.arm.com/tooling/fastpath/container_registry

********************
Repository Structure
********************

Key directories within the repository:

=================== ====
Directory           Description
=================== ====
./benchmarks        Standard benhmark library. Includes all benchmark description yamls.
./containers        Definitions for all container images containing benchmarks.
./documentation     Source for this documentation.
./fastpath          CLI tool implementation.
=================== ====

******************
Repository License
******************

The software is provided under an MIT license (more details in
:ref:`license:License`).

Contributions to the project should follow the same license.

*****************************
Contributions and Bug Reports
*****************************

Contributions are accepted under the MIT license. Only submit contributions
where you have authored all of the code.

If you're hitting an error/bug and need help, it's best to raise an issue in
GitLab.

*************
Maintainer(s)
*************

- Ryan Roberts <ryan.roberts@arm.com>
- Aishwarya TCV <Aishwarya.TCV@arm.com>
- Aishwarya Rambhadran <Aishwarya.Rambhadran@arm.com>