Documentation/dev-tools/autofdo.rst

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

File Facts

System
Linux kernel
Corpus path
Documentation/dev-tools/autofdo.rst
Extension
.rst
Size
7736 bytes
Lines
210
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 AutoFDO with the Linux kernel
===================================

This enables AutoFDO build support for the kernel when using
the Clang compiler. AutoFDO (Auto-Feedback-Directed Optimization)
is a type of profile-guided optimization (PGO) used to enhance the
performance of binary executables. It gathers information about the
frequency of execution of various code paths within a binary using
hardware sampling. This data is then used to guide the compiler's
optimization decisions, resulting in a more efficient binary. AutoFDO
is a powerful optimization technique, and data indicates that it can
significantly improve kernel performance. It's especially beneficial
for workloads affected by front-end stalls.

For AutoFDO builds, unlike non-FDO builds, the user must supply a
profile. Acquiring an AutoFDO profile can be done in several ways.
AutoFDO profiles are created by converting hardware sampling using
the "perf" tool. It is crucial that the workload used to create these
perf files is representative; they must exhibit runtime
characteristics similar to the workloads that are intended to be
optimized. Failure to do so will result in the compiler optimizing
for the wrong objective.

The AutoFDO profile often encapsulates the program's behavior. If the
performance-critical codes are architecture-independent, the profile
can be applied across platforms to achieve performance gains. For
instance, using the profile generated on Intel architecture to build
a kernel for AMD architecture can also yield performance improvements.

There are two methods for acquiring a representative profile:
(1) Sample real workloads using a production environment.
(2) Generate the profile using a representative load test.
When enabling the AutoFDO build configuration without providing an
AutoFDO profile, the compiler only modifies the dwarf information in
the kernel without impacting runtime performance. It's advisable to
use a kernel binary built with the same AutoFDO configuration to
collect the perf profile. While it's possible to use a kernel built
with different options, it may result in inferior performance.

One can collect profiles using AutoFDO build for the previous kernel.
AutoFDO employs relative line numbers to match the profiles, offering
some tolerance for source changes. This mode is commonly used in a
production environment for profile collection.

In a profile collection based on a load test, the AutoFDO collection
process consists of the following steps:

#. Initial build: The kernel is built with AutoFDO options
   without a profile.

#. 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. AutoFDO is most
   effective on platforms supporting advanced PMU features like
   LBR on Intel machines.

#. AutoFDO profile generation: Perf output file is converted to
   the AutoFDO profile via offline tools.

The support requires a Clang compiler LLVM 17 or later.
Current supported architectures include x86/x86_64 (via LBR) and
arm64 (via SPE or ETM).


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

Annotation

Implementation Notes