Using Propeller with the Linux kernel | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

propeller.rst:1-162

Propeller는 Clang과 perf hardware sampling을 사용해 linking 직전 function 내부와 사이의 block layout을 최적화합니다. AutoFDO 또는 ThinLTO와 함께 사용하며 LLVM 19 이상과 create_llvm_prof가 필요합니다.

Workflow는 AutoFDO profile을 적용한 metadata build, representative workload sampling, compile/link profile pair 생성, 세 profile을 적용한 rebuild와 deployment 순서입니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 .. SPDX-License-Identifier: GPL-2.0

3 =====================================

4 Using Propeller with the Linux kernel

5 =====================================

7 This enables Propeller build support for the kernel when using Clang

8 compiler. Propeller is a profile-guided optimization (PGO) method used

9 to optimize binary executables. Like AutoFDO, it utilizes hardware

10 sampling to gather information about the frequency of execution of

11 different code paths within a binary. Unlike AutoFDO, this information

12 is then used right before linking phase to optimize (among others)

13 block layout within and across functions.

15 A few important notes about adopting Propeller optimization:

17 #. Although it can be used as a standalone optimization step, it is

18 strongly recommended to apply Propeller on top of AutoFDO,

19 AutoFDO+ThinLTO or Instrument FDO. The rest of this document

20 assumes this paradigm.

22 #. Propeller uses another round of profiling on top of

23 AutoFDO/AutoFDO+ThinLTO/iFDO. The whole build process involves

24 "build-afdo - train-afdo - build-propeller - train-propeller -

25 build-optimized".

27 #. Propeller requires LLVM 19 release or later for Clang/Clang++

28 and the linker(ld.lld).

30 #. In addition to LLVM toolchain, Propeller requires a profiling

31 conversion tool: https://github.com/google/autofdo with a release

32 after v0.30.1: https://github.com/google/autofdo/releases/tag/v0.30.1.

34 The Propeller optimization process involves the following steps:

36 #. Initial building: Build the AutoFDO or AutoFDO+ThinLTO binary as

37 you would normally do, but with a set of compile-time / link-time

38 flags, so that a special metadata section is created within the

39 kernel binary. The special section is only intend to be used by the

40 profiling tool, it is not part of the runtime image, nor does it

41 change kernel run time text sections.

43 #. Profiling: The above kernel is then run with a representative

44 workload to gather execution frequency data. This data is collected

45 using hardware sampling, via perf. Propeller is most effective on

46 platforms supporting advanced PMU features like LBR on Intel

47 machines. This step is the same as profiling the kernel for AutoFDO

48 (the exact perf parameters can be different).

50 #. Propeller profile generation: Perf output file is converted to a

51 pair of Propeller profiles via an offline tool.

53 #. Optimized build: Build the AutoFDO or AutoFDO+ThinLTO optimized

54 binary as you would normally do, but with a compile-time /

55 link-time flag to pick up the Propeller compile time and link time

56 profiles. This build step uses 3 profiles - the AutoFDO profile,

57 the Propeller compile-time profile and the Propeller link-time

58 profile.

60 #. Deployment: The optimized kernel binary is deployed and used

61 in production environments, providing improved performance

62 and reduced latency.

64 Preparation

65 ===========

67 Configure the kernel with::

69 CONFIG_AUTOFDO_CLANG=y

70 CONFIG_PROPELLER_CLANG=y

72 Customization

73 =============

75 The default CONFIG_PROPELLER_CLANG setting covers kernel space objects

76 for Propeller builds. One can, however, enable or disable Propeller build

77 for individual files and directories by adding a line similar to the

78 following to the respective kernel Makefile:

80 - For enabling a single file (e.g. foo.o)::

82 PROPELLER_PROFILE_foo.o := y

84 - For enabling all files in one directory::

86 PROPELLER_PROFILE := y

88 - For disabling one file::

90 PROPELLER_PROFILE_foo.o := n

92 - For disabling all files in one directory::

94 PROPELLER__PROFILE := n

97 Workflow

98 ========

100 Here is an example workflow for building an AutoFDO+Propeller kernel:

101

102 1) Assuming an AutoFDO profile is already collected following

103 instructions in the AutoFDO document, build the kernel on the host

104 machine, with AutoFDO and Propeller build configs ::

105

106 CONFIG_AUTOFDO_CLANG=y

107 CONFIG_PROPELLER_CLANG=y

108

109 and ::

110

111 $ make LLVM=1 CLANG_AUTOFDO_PROFILE=<autofdo-profile-name>

112

113 2) Install the kernel on the test machine.

114

115 3) Run the load tests. The '-c' option in perf specifies the sample

116 event period. We suggest using a suitable prime number, like 500009,

117 for this purpose.

118

119 - For Intel platforms::

120

121 $ perf record -e BR_INST_RETIRED.NEAR_TAKEN:k -a -N -b -c <count> -o <perf_file> -- <loadtest>

122

123 - For AMD platforms::

124

125 $ perf record --pfm-event RETIRED_TAKEN_BRANCH_INSTRUCTIONS:k -a -N -b -c <count> -o <perf_file> -- <loadtest>

126

127 Note you can repeat the above steps to collect multiple <perf_file>s.

128

129 4) (Optional) Download the raw perf file(s) to the host machine.

130

131 5) Use the create_llvm_prof tool (https://github.com/google/autofdo) to

132 generate Propeller profile. ::

133

134 $ create_llvm_prof --binary=<vmlinux> --profile=<perf_file>

135 --format=propeller --propeller_output_module_name

136 --out=<propeller_profile_prefix>_cc_profile.txt

137 --propeller_symorder=<propeller_profile_prefix>_ld_profile.txt

138

139 "<propeller_profile_prefix>" can be something like "/home/user/dir/any_string".

140

141 This command generates a pair of Propeller profiles:

142 "<propeller_profile_prefix>_cc_profile.txt" and

143 "<propeller_profile_prefix>_ld_profile.txt".

144

145 If there are more than 1 perf_file collected in the previous step,

146 you can create a temp list file "<perf_file_list>" with each line

147 containing one perf file name and run::

148

149 $ create_llvm_prof --binary=<vmlinux> --profile=@<perf_file_list>

150 --format=propeller --propeller_output_module_name

151 --out=<propeller_profile_prefix>_cc_profile.txt

152 --propeller_symorder=<propeller_profile_prefix>_ld_profile.txt

153

154 6) Rebuild the kernel using the AutoFDO and Propeller

155 profiles. ::

156

157 CONFIG_AUTOFDO_CLANG=y

158 CONFIG_PROPELLER_CLANG=y

159

160 and ::

161

162 $ make LLVM=1 CLANG_AUTOFDO_PROFILE=<profile_file> CLANG_PROPELLER_PROFILE_PREFIX=<propeller_profile_prefix>

163

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Propeller 개요와 optimization 단계

1-63

SPDX 라이선스 식별자: GPL-2.0

Linux kernel에서 Propeller 사용

이 기능은 Clang compiler를 사용할 때 kernel의 Propeller build를 지원합니다. Propeller는 binary executable을 최적화하는 profile-guided optimization, 즉 PGO 방식입니다.

AutoFDO와 마찬가지로 hardware sampling으로 binary의 여러 code path가 실행되는 빈도를 수집합니다. AutoFDO와 달리 이 정보는 linking 직전에 사용되어 function 내부와 function 사이의 block layout 등을 최적화합니다.

Propeller 도입 시 중요한 사항은 다음과 같습니다.

1. 독립적인 optimization 단계로 사용할 수도 있지만 AutoFDO, AutoFDO+ThinLTO 또는 Instrument FDO 위에 Propeller를 적용할 것을 강하게 권장합니다. 이 문서의 나머지 부분도 이 방식을 가정합니다.

2. Propeller는 AutoFDO, AutoFDO+ThinLTO 또는 iFDO profiling 위에 별도의 profiling round를 추가합니다. 전체 build 과정은 `build-afdo - train-afdo - build-propeller - train-propeller - build-optimized`입니다.

3. Clang, Clang++와 linker `ld.lld`에는 LLVM 19 이상 release가 필요합니다.

4. LLVM toolchain 외에도 v0.30.1 이후 release의 profiling conversion tool `https://github.com/google/autofdo`가 필요합니다. Release reference는 `https://github.com/google/autofdo/releases/tag/v0.30.1`입니다.

Propeller optimization은 다음 단계로 진행됩니다.

1. Initial build: 평소처럼 AutoFDO 또는 AutoFDO+ThinLTO binary를 build하되 compile-time과 link-time flag를 추가해 kernel binary 안에 special metadata section을 만듭니다. 이 section은 profiling tool만 사용하며 runtime image의 일부가 아니고 kernel runtime text section도 바꾸지 않습니다.

2. Profiling: 위 kernel을 representative workload로 실행해 execution frequency data를 수집합니다. Perf를 통한 hardware sampling을 사용하며 Intel LBR 같은 advanced PMU feature를 지원하는 platform에서 특히 효과적입니다. 정확한 perf parameter는 다를 수 있지만 AutoFDO kernel profiling과 같은 단계입니다.

3. Propeller profile 생성: Offline tool로 perf output file을 Propeller profile pair로 변환합니다.

4. Optimized build: Propeller compile-time과 link-time profile을 읽는 flag를 추가해 AutoFDO 또는 AutoFDO+ThinLTO optimized binary를 build합니다. AutoFDO profile, Propeller compile-time profile, Propeller link-time profile의 세 profile을 사용합니다.

5. Deployment: 최적화한 kernel binary를 production environment에 배포해 performance를 높이고 latency를 줄입니다.

AutoFDO와 Propeller workflow

build-afdoAutoFDO용 kernel build

train-afdo대표 workload로 AutoFDO profile 수집

build-propellerPropeller metadata를 포함한 kernel build

train-propellerPerf sampling과 profile pair 생성

build-optimizedAutoFDO와 Propeller profile 3개를 적용

deployProduction kernel로 배포

두 차례 profiling과 최종 optimized build의 순서를 나타냅니다.

준비와 Makefile customizing

64-96

준비

Kernel에 다음 option을 설정합니다.

CONFIG_AUTOFDO_CLANG=y
CONFIG_PROPELLER_CLANG=y

Customizing

기본 `CONFIG_PROPELLER_CLANG` 설정은 Propeller build의 kernel-space object를 대상으로 합니다. 각 file과 directory의 kernel Makefile에 다음 variable을 추가해 개별 범위를 활성화하거나 비활성화할 수 있습니다.

`foo.o` 하나를 활성화합니다.

PROPELLER_PROFILE_foo.o := y

Directory의 모든 file을 활성화합니다.

PROPELLER_PROFILE := y

File 하나를 비활성화합니다.

PROPELLER_PROFILE_foo.o := n

Directory의 모든 file을 비활성화합니다.

PROPELLER__PROFILE := n

마지막 원문 variable은 underscore가 두 개인 `PROPELLER__PROFILE`로 표기되어 있으므로 그대로 보존했습니다.

Propeller Makefile 범위 제어

범위활성화비활성화

개별 objectPROPELLER_PROFILE_foo.o := yPROPELLER_PROFILE_foo.o := n

Directory 전체PROPELLER_PROFILE := yPROPELLER__PROFILE := n

Global Kconfig 위에서 file과 directory 단위 적용 범위를 조정하는 variable입니다.

Profiling과 profile pair 생성

97-153

Workflow

다음은 AutoFDO+Propeller kernel build의 예입니다.

1. AutoFDO 문서에 따라 AutoFDO profile을 이미 수집했다고 가정하고 host machine에서 AutoFDO와 Propeller config를 설정합니다.

CONFIG_AUTOFDO_CLANG=y
CONFIG_PROPELLER_CLANG=y

AutoFDO profile을 전달해 kernel을 build합니다.

$ make LLVM=1 CLANG_AUTOFDO_PROFILE=<autofdo-profile-name>

2. Kernel을 test machine에 설치합니다.

3. Load test를 실행합니다. Perf의 `-c` option은 sample event period를 지정하며 500009처럼 적절한 prime number 사용을 권장합니다.

Intel platform에서는 다음 event를 기록합니다.

$ perf record -e BR_INST_RETIRED.NEAR_TAKEN:k -a -N -b -c <count> -o <perf_file> -- <loadtest>

AMD platform에서는 다음 PMU event를 기록합니다.

$ perf record --pfm-event RETIRED_TAKEN_BRANCH_INSTRUCTIONS:k -a -N -b -c <count> -o <perf_file> -- <loadtest>

위 단계를 반복해 여러 `<perf_file>`을 수집할 수도 있습니다.

4. 선택적으로 raw perf file을 host machine으로 download합니다.

5. `https://github.com/google/autofdo`의 `create_llvm_prof` tool로 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>`는 `/home/user/dir/any_string` 같은 값일 수 있습니다. Command는 `<prefix>_cc_profile.txt`와 `<prefix>_ld_profile.txt`라는 Propeller profile pair를 생성합니다.

Perf file을 둘 이상 수집했다면 각 line에 perf filename 하나를 넣은 temporary `<perf_file_list>`를 만들고 `@` prefix로 list를 전달합니다.

$ 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

AutoFDO와 Propeller profile로 rebuild

154-162

6. AutoFDO와 Propeller profile을 사용해 kernel을 다시 build합니다.

CONFIG_AUTOFDO_CLANG=y
CONFIG_PROPELLER_CLANG=y

두 profile source를 build command에 전달합니다.

$ make LLVM=1 CLANG_AUTOFDO_PROFILE=<profile_file> CLANG_PROPELLER_PROFILE_PREFIX=<propeller_profile_prefix>

`CLANG_AUTOFDO_PROFILE`은 AutoFDO profile file을, `CLANG_PROPELLER_PROFILE_PREFIX`는 앞 단계에서 만든 compile-time 및 link-time Propeller profile pair의 공통 prefix를 지정합니다.