Documentation/dev-tools/propeller.rst

Source file repositories/reference/linux-study-clean/Documentation/dev-tools/propeller.rst

File Facts

System
Linux kernel
Corpus path
Documentation/dev-tools/propeller.rst
Extension
.rst
Size
6852 bytes
Lines
188
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

=====================================
Using Propeller with the Linux kernel
=====================================

This enables Propeller build support for the kernel when using Clang
compiler. Propeller is a profile-guided optimization (PGO) method used
to optimize binary executables. Like AutoFDO, it utilizes hardware
sampling to gather information about the frequency of execution of
different code paths within a binary. Unlike AutoFDO, this information
is then used right before linking phase to optimize (among others)
block layout within and across functions.

A few important notes about adopting Propeller optimization:

#. Although it can be used as a standalone optimization step, it is
   strongly recommended to apply Propeller on top of AutoFDO,
   AutoFDO+ThinLTO or Instrument FDO. The rest of this document
   assumes this paradigm.

#. Propeller uses another round of profiling on top of
   AutoFDO/AutoFDO+ThinLTO/iFDO. The whole build process involves
   "build-afdo - train-afdo - build-propeller - train-propeller -
   build-optimized".

#. Propeller requires LLVM 19 release or later for Clang/Clang++
   and the linker(ld.lld).

#. In addition to LLVM toolchain, Propeller requires a profiling
   conversion tool: https://github.com/google/llvm-propeller.

Current supported architectures include x86/X86_64 (via LBR),
and arm64 (via SPE).

The Propeller optimization process involves the following steps:

#. Initial building: Build the AutoFDO or AutoFDO+ThinLTO binary as
   you would normally do, but with a set of compile-time / link-time
   flags, so that a special metadata section is created within the
   kernel binary. The special section is only intend to be used by the
   profiling tool, it is not part of the runtime image, nor does it
   change kernel run time text sections.

#. Profiling: The above kernel is then run with a representative
   workload to gather execution frequency data. This data is collected
   using hardware sampling, via perf. Propeller is most effective on
   platforms supporting advanced PMU features like LBR on Intel
   machines. This step is the same as profiling the kernel for AutoFDO
   (the exact perf parameters can be different).

#. Propeller profile generation: Perf output file is converted to a
   pair of Propeller profiles via an offline tool.

#. Optimized build: Build the AutoFDO or AutoFDO+ThinLTO optimized
   binary as you would normally do, but with a compile-time /
   link-time flag to pick up the Propeller compile time and link time
   profiles. This build step uses 3 profiles - the AutoFDO profile,
   the Propeller compile-time profile and the Propeller link-time
   profile.

#. Deployment: The optimized kernel binary is deployed and used
   in production environments, providing improved performance
   and reduced latency.

Preparation
===========

Configure the kernel with::

Annotation

Implementation Notes