Re: [PATCH v4 6/6] Add Propeller configuration for kernel build.

[Masahiro Yamada <masahiroy@kernel.org>]

Please remove the period at the end of the commit subject.



On Tue, Oct 15, 2024 at 6:34 AM Rong Xu <xur@google.com> wrote:
>
> Add the build support for using Clang's Propeller optimizer. Like
> AutoFDO, Propeller uses hardware sampling to gather information
> about the frequency of execution of different code paths within a
> binary. This information is then used to guide the compiler's
> optimization decisions, resulting in a more efficient binary.
>
> The support requires a Clang compiler LLVM 19 or later, and the
> create_llvm_prof tool
> (https://github.com/google/autofdo/releases/tag/v0.30.1). This
> submission is limited to x86 platforms that support PMU features


"This submission" -> "This commit"



> like LBR on Intel machines and AMD Zen3 BRS.
>
> For Arm, we plan to send patches for SPE-based Propeller when
> AutoFDO for Arm is ready.


"we plan to send ..." is not a good description once it is committed.

This sentence should be moved to the cover letter, or reworked.






>
> Here is an example workflow for building an AutoFDO+Propeller
> optimized kernel:
>
> 1) Build the kernel on the HOST machine, with AutoFDO and Propeller


Why is the "HOST" capitalized?



>    build config
>       CONFIG_AUTOFDO_CLANG=y
>       CONFIG_PROPELLER_CLANG=y
>    then
>       $ make LLVM=1 CLANG_AUTOFDO_PROFILE=<autofdo_profile>
>
> “<autofdo_profile>” is the profile collected when doing a non-Propeller
> AutoFDO build. This step builds a kernel that has the same optimization
> level as AutoFDO, plus a metadata section that records basic block
> information. This kernel image runs as fast as an AutoFDO optimized
> kernel.
>
> 2) Install the kernel on test/production machines.
>
> 3) Run the load tests. The '-c' option in perf specifies the sample
>    event period. We suggest using a suitable prime number,
>    like 500009, for this purpose.
>    For Intel platforms:
>       $ perf record -e BR_INST_RETIRED.NEAR_TAKEN:k -a -N -b -c <count> \
>         -o <perf_file> -- <loadtest>
>    For AMD platforms:
>       The supported system are: Zen3 with BRS, or Zen4 with amd_lbr_v2
>       # To see if Zen3 support LBR:
>       $ cat proc/cpuinfo | grep " brs"
>       # To see if Zen4 support LBR:
>       $ cat proc/cpuinfo | grep amd_lbr_v2
>       # If the result is yes, then collect the profile using:
>       $ perf record --pfm-events RETIRED_TAKEN_BRANCH_INSTRUCTIONS:k -a \
>         -N -b -c <count> -o <perf_file> -- <loadtest>
>
> 4) (Optional) Download the raw perf file to the HOST machine.


Same question as above.


>
> 5) Generate Propeller profile:
>    $ create_llvm_prof --binary=<vmlinux> --profile=<perf_file> \
>      --format=propeller --propeller_output_module_name \
>      --out=<propeller_profile_prefix>_cc_profile.txt \
>      --propeller_symorder=<propeller_profile_prefix>_ld_profile.txt
>
>    “create_llvm_prof” is the profile conversion tool, and a prebuilt
>    binary for linux can be found on
>    https://github.com/google/autofdo/releases/tag/v0.30.1 (can also build
>    from source).
>
>    "<propeller_profile_prefix>" can be something like
>    "/home/user/dir/any_string".
>
>    This command generates a pair of Propeller profiles:
>    "<propeller_profile_prefix>_cc_profile.txt" and
>    "<propeller_profile_prefix>_ld_profile.txt".
>
> 6) Rebuild the kernel using the AutoFDO and Propeller profile files.
>       CONFIG_AUTOFDO_CLANG=y
>       CONFIG_PROPELLER_CLANG=y
>    and
>       $ make LLVM=1 CLANG_AUTOFDO_PROFILE=<autofdo_profile> \
>         CLANG_PROPELLER_PROFILE_PREFIX=<propeller_profile_prefix>
>
> Co-developed-by: Han Shen <shenhan@google.com>
> Signed-off-by: Han Shen <shenhan@google.com>
> Signed-off-by: Rong Xu <xur@google.com>
> Suggested-by: Sriraman Tallam <tmsriram@google.com>
> Suggested-by: Krzysztof Pszeniczny <kpszeniczny@google.com>
> Suggested-by: Nick Desaulniers <ndesaulniers@google.com>
> Suggested-by: Stephane Eranian <eranian@google.com>



>
>  .. only::  subproject and html
> diff --git a/Documentation/dev-tools/propeller.rst b/Documentation/dev-tools/propeller.rst
> new file mode 100644
> index 000000000000..a217354e0f95
> --- /dev/null
> +++ b/Documentation/dev-tools/propeller.rst
> @@ -0,0 +1,161 @@
> +.. 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.

This is a hard requirement instead of a recommendation
because PROPERLLER_CLANG has "depends on AUTOFDO_CLANG".




> +
> +#. 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/autofdo with a release
> +   after v0.30.1: https://github.com/google/autofdo/releases/tag/v0.30.1.
> +
> +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::
> +
> +   CONFIG_AUTOFDO_CLANG=y


This is automatically met due to "depends on AUTOFDO_CLANG".



> +   CONFIG_PROPELLER_CLANG=y
> +
> +Customization
> +=============
> +
> +You can enable or disable Propeller build for individual file and
> +directories by adding a line similar to the following to the
> +respective kernel Makefile:

The same comment as in 1/6.



> +- For enabling a single file (e.g. foo.o)::
> +
> +   PROPELLER_PROFILE_foo.o := y
> +
> +- For enabling all files in one directory::
> +
> +   PROPELLER_PROFILE := y
> +
> +- For disabling one file::
> +
> +   PROPELLER_PROFILE_foo.o := n
> +
> +- For disabling all files in one directory::
> +
> +   PROPELLER__PROFILE := n
> +
> +
> +Workflow
> +========
> +
> +Here is an example workflow for building an AutoFDO+Propeller kernel:
> +
> +1) Assuming an AutoFDO profile is already collected following
> +   instructions in the AutoFDO document, build the kernel on the HOST
> +   machine, with AutoFDO and Propeller build configs ::
> +
> +      CONFIG_AUTOFDO_CLANG=y
> +      CONFIG_PROPELLER_CLANG=y
> +
> +   and ::
> +
> +      $ make LLVM=1 CLANG_AUTOFDO_PROFILE=<autofdo-profile-name>
> +
> +2) Install the kernel on the TEST machine.


I am repeatedly encountered with capitalized "HOST" and "TEST".

Does this term have a special meaning instead of a test machine in general?







> +
> +3) Run the load tests. The '-c' option in perf specifies the sample
> +   event period. We suggest using a suitable prime number, like 500009,
> +   for this purpose.
> +
> +   - For Intel platforms::
> +
> +      $ perf record -e BR_INST_RETIRED.NEAR_TAKEN:k -a -N -b -c <count> -o <perf_file> -- <loadtest>
> +
> +   - For AMD platforms::
> +
> +      $ perf record --pfm-event RETIRED_TAKEN_BRANCH_INSTRUCTIONS:k -a -N -b -c <count> -o <perf_file> -- <loadtest>
> +
> +   Note you can repeat the above steps to collect multiple <perf_file>s.
> +
> +4) (Optional) Download the raw perf file(s) to the HOST machine.
> +
> +5) Use the create_llvm_prof tool (https://github.com/google/autofdo) to
> +   generate Propeller profile. ::
> +
> +      $ create_llvm_prof --binary=<vmlinux> --profile=<perf_file>
> +                         --format=propeller --propeller_output_module_name
> +                         --out=<propeller_profile_prefix>_cc_profile.txt
> +                         --propeller_symorder=<propeller_profile_prefix>_ld_profile.txt
> +
> +   "<propeller_profile_prefix>" can be something like "/home/user/dir/any_string".
> +
> +   This command generates a pair of Propeller profiles:
> +   "<propeller_profile_prefix>_cc_profile.txt" and
> +   "<propeller_profile_prefix>_ld_profile.txt".
> +
> +   If there are more than 1 perf_file collected in the previous step,
> +   you can create a temp list file "<perf_file_list>" with each line
> +   containing one perf file name and run::
> +
> +      $ create_llvm_prof --binary=<vmlinux> --profile=@<perf_file_list>
> +                         --format=propeller --propeller_output_module_name
> +                         --out=<propeller_profile_prefix>_cc_profile.txt
> +                         --propeller_symorder=<propeller_profile_prefix>_ld_profile.txt
> +
> +6) Rebuild the kernel using the AutoFDO and Propeller
> +   profiles. ::


"." and "::" are an odd combination.




> +
> +      CONFIG_AUTOFDO_CLANG=y
> +      CONFIG_PROPELLER_CLANG=y
> +
> +   and ::
> +
> +      $ make LLVM=1 CLANG_AUTOFDO_PROFILE=<profile_file> CLANG_PROPELLER_PROFILE_PREFIX=<propeller_profile_prefix>



> diff --git a/Makefile b/Makefile
> index bbb6ec68f5dc..2d2f688c21c6 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -1019,6 +1019,7 @@ include-$(CONFIG_UBSAN)           += scripts/Makefile.ubsan
>  include-$(CONFIG_KCOV)         += scripts/Makefile.kcov
>  include-$(CONFIG_RANDSTRUCT)   += scripts/Makefile.randstruct
>  include-$(CONFIG_AUTOFDO_CLANG)        += scripts/Makefile.autofdo
> +include-$(CONFIG_PROPELLER_CLANG)      += scripts/Makefile.propeller
>  include-$(CONFIG_GCC_PLUGINS)  += scripts/Makefile.gcc-plugins
>
>  include $(addprefix $(srctree)/, $(include-y))
> diff --git a/arch/Kconfig b/arch/Kconfig
> index 5e9604960cbb..fdeb5f173a10 100644
> --- a/arch/Kconfig
> +++ b/arch/Kconfig
> @@ -831,6 +831,28 @@ config AUTOFDO_CLANG
>
>           If unsure, say N.
>
> +config ARCH_SUPPORTS_PROPELLER_CLANG
> +       bool
> +
> +config PROPELLER_CLANG
> +       bool "Enable Clang's Propeller build"
> +       depends on ARCH_SUPPORTS_PROPELLER_CLANG
> +       depends on AUTOFDO_CLANG
> +       depends on CC_IS_CLANG && CLANG_VERSION >= 190000


CC_IS_CLANG is redundant, but I am fine if you want to have it explicitly.



> +       help
> +         This option enables Clang’s Propeller build which
> +         is on top of AutoFDO build. When the Propeller profiles
> +         is specified in variable CLANG_PROPELLER_PROFILE_PREFIX
> +         during the build process, Clang uses the profiles to
> +         optimize the kernel.
> +
> +         If no profile is specified, Proepller options are


"Proepller" is a typo.




> +         still passed to Clang to facilitate the collection
> +         of perf data for creating the Propeller profiles in
> +         subsequent builds.
> +
> +         If unsure, say N.
> +
>  config ARCH_SUPPORTS_CFI_CLANG
>         bool
>         help
> diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig
> index 503a0268155a..da47164bfddc 100644
> --- a/arch/x86/Kconfig
> +++ b/arch/x86/Kconfig
> @@ -127,6 +127,7 @@ config X86
>         select ARCH_SUPPORTS_LTO_CLANG_THIN
>         select ARCH_SUPPORTS_RT
>         select ARCH_SUPPORTS_AUTOFDO_CLANG
> +       select ARCH_SUPPORTS_PROPELLER_CLANG    if X86_64
>         select ARCH_USE_BUILTIN_BSWAP
>         select ARCH_USE_CMPXCHG_LOCKREF         if X86_CMPXCHG64
>         select ARCH_USE_MEMTEST
> diff --git a/arch/x86/kernel/vmlinux.lds.S b/arch/x86/kernel/vmlinux.lds.S
> index 6726be89b7a6..7ecc21c569be 100644
> --- a/arch/x86/kernel/vmlinux.lds.S
> +++ b/arch/x86/kernel/vmlinux.lds.S
> @@ -442,6 +442,10 @@ SECTIONS
>
>         STABS_DEBUG
>         DWARF_DEBUG
> +#ifdef CONFIG_PROPELLER_CLANG
> +       .llvm_bb_addr_map : { *(.llvm_bb_addr_map) }
> +#endif
> +
>         ELF_DETAILS
>
>         DISCARDS
> diff --git a/include/asm-generic/vmlinux.lds.h b/include/asm-generic/vmlinux.lds.h
> index 20e46c0917db..5986dd4cfb14 100644
> --- a/include/asm-generic/vmlinux.lds.h
> +++ b/include/asm-generic/vmlinux.lds.h
> @@ -95,14 +95,14 @@
>   * With LTO_CLANG, the linker also splits sections by default, so we need
>   * these macros to combine the sections during the final link.
>   *
> - * With LTO_CLANG, the linker also splits sections by default, so we need
> - * these macros to combine the sections during the final link.
> + * CONFIG_AUTOFD_CLANG and CONFIG_PROPELLER_CLANG will also split text sections
> + * and cluster them in the linking time.
>   *
>   * RODATA_MAIN is not used because existing code already defines .rodata.x
>   * sections to be brought in with rodata.
>   */
>  #if defined(CONFIG_LD_DEAD_CODE_DATA_ELIMINATION) || defined(CONFIG_LTO_CLANG) || \
> -defined(CONFIG_AUTOFDO_CLANG)
> +defined(CONFIG_AUTOFDO_CLANG) || defined(CONFIG_PROPELLER_CLANG)


If you have "depends on PROPELLER_CLANG" in Kconfig,
you do not need to touch this line.

When CONFIG_PROPELLER_CLANG is enabled, CONFIG_AUTOFDO_CLANG is already defined.




>  #define TEXT_MAIN .text .text.[0-9a-zA-Z_]*
>  #else
>  #define TEXT_MAIN .text
> @@ -556,7 +556,7 @@ defined(CONFIG_AUTOFDO_CLANG)
>                 __cpuidle_text_end = .;                                 \
>                 __noinstr_text_end = .;
>
> -#ifdef CONFIG_AUTOFDO_CLANG
> +#if defined(CONFIG_AUTOFDO_CLANG) || defined(CONFIG_PROPELLER_CLANG)


Ditto.


>  #define TEXT_HOT                                                       \
>                 __hot_text_start = .;                                   \
>                 *(.text.hot .text.hot.*)                                \
> @@ -584,7 +584,7 @@ defined(CONFIG_AUTOFDO_CLANG)
>   * first when in these builds.
>   */
>  #if defined(CONFIG_LD_DEAD_CODE_DATA_ELIMINATION) || defined(CONFIG_LTO_CLANG) || \
> -defined(CONFIG_AUTOFDO_CLANG)
> +defined(CONFIG_AUTOFDO_CLANG) || defined(CONFIG_PROPELLER_CLANG)


Ditto.
Make sense only when CONFIG_AUTOFDO_CLANG and CONFIG_PROPELLER_CLANG
are independent of each other.



>  #define TEXT_TEXT                                                      \
>                 ALIGN_FUNCTION();                                       \
>                 *(.text.asan.* .text.tsan.*)                            \
> diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib
> index e85d6ac31bd9..60354c476956 100644
> --- a/scripts/Makefile.lib
> +++ b/scripts/Makefile.lib
> @@ -201,6 +201,16 @@ _c_flags += $(if $(patsubst n%,, \
>         $(CFLAGS_AUTOFDO_CLANG))
>  endif
>
> +#
> +# Enable Clang's Propeller build flags for a file or directory depending on
> +# variables AUTOFDO_PROPELLER_obj.o and PROPELLER_PROFILE.

The same comment as in 1/6.



> +#
> +ifeq ($(CONFIG_PROPELLER_CLANG),y)



ifdef CONFIG_PROPELLER_CLANG

would be simpler, as you used this style in scripts/Makefile.propeller






> +_c_flags += $(if $(patsubst n%,, \
> +       $(AUTOFDO_PROFILE_$(target-stem).o)$(AUTOFDO_PROFILE)$(PROPELLER_PROFILE))$(is-kernel-object), \
> +       $(CFLAGS_PROPELLER_CLANG))
> +endif
> +
>  # $(src) for including checkin headers from generated source files
>  # $(obj) for including generated headers from checkin source files
>  ifeq ($(KBUILD_EXTMOD),)
> diff --git a/scripts/Makefile.propeller b/scripts/Makefile.propeller
> new file mode 100644
> index 000000000000..344190717e47
> --- /dev/null
> +++ b/scripts/Makefile.propeller


> +# Propeller requires debug information to embed module names in the profiles.
> +# If CONFIG_DEBUG_INFO is not enabled, set -gmlt option. Skip this for AutoFDO,
> +# as the option should already be set.
> +ifndef CONFIG_DEBUG_INFO
> +  ifndef CONFIG_AUTOFDO_CLANG
> +    CFLAGS_PROPELLER_CLANG += -gmlt
> +  endif
> +endif


This block is dead code due to "depends on AUTOFDO_CLANG".

"ifndef CONFIG_AUTOFDO_CLANG" is never met here.







-- 
Best Regards
Masahiro Yamada