From 644a313ac35017b1b8604dc70db354ac32dc1525 Mon Sep 17 00:00:00 2001 From: Evawudonger Date: Mon, 9 Jun 2025 20:16:43 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E8=8B=B1=E6=96=87=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/gcc/_toc.yaml | 16 ++ ...ersion_compilation_toolchain_user_guide.md | 139 +++++++++++++ ...sic_performance_optimization_user_guide.md | 185 ++++++++++++++++++ docs/en/gcc/kernel_fdo_user_guide.md | 69 +++++++ docs/en/gcc/lto_user_guide.md | 25 +++ docs/en/gcc/pin_user_guide.md | 134 +++++++++++++ docs/zh/gcc/_toc.yaml | 2 +- docs/zh/gcc/dfot_user_guide.md | 3 +- ...ic_performance_optimization_user_guide.md} | 0 docs/zh/gcc/pin_user_guide.md | 2 +- 10 files changed, 572 insertions(+), 3 deletions(-) create mode 100644 docs/en/gcc/_toc.yaml create mode 100644 docs/en/gcc/gcc_14_secondary_version_compilation_toolchain_user_guide.md create mode 100644 docs/en/gcc/gcc_basic_performance_optimization_user_guide.md create mode 100644 docs/en/gcc/kernel_fdo_user_guide.md create mode 100644 docs/en/gcc/lto_user_guide.md create mode 100644 docs/en/gcc/pin_user_guide.md rename docs/zh/gcc/{gcc_optimization_user_guide.md => gcc_basic_performance_optimization_user_guide.md} (100%) diff --git a/docs/en/gcc/_toc.yaml b/docs/en/gcc/_toc.yaml new file mode 100644 index 0000000..4ceda54 --- /dev/null +++ b/docs/en/gcc/_toc.yaml @@ -0,0 +1,16 @@ +label: GCC User Guide +isManual: true +description: >- + GCC for openEuler builds upon the open source GCC, with a primary focus on + optimizing C, C++, and Fortran languages. +sections: + - label: Kernel FDO User Guide + href: ./kernel_fdo_user_guide.md + - label: LTO User Guide + href: ./lto_user_guide.md + - label: GCC Basic Performance Optimization User Guide + href: ./gcc_basic_performance_optimization_user_guide.md + - label: Alternative GCC 14 User Guide + href: ./gcc_14_secondary_version_compilation_toolchain_user_guide.md + - label: PIN User Guide + href: ./pin_user_guide.md diff --git a/docs/en/gcc/gcc_14_secondary_version_compilation_toolchain_user_guide.md b/docs/en/gcc/gcc_14_secondary_version_compilation_toolchain_user_guide.md new file mode 100644 index 0000000..947bcbc --- /dev/null +++ b/docs/en/gcc/gcc_14_secondary_version_compilation_toolchain_user_guide.md @@ -0,0 +1,139 @@ +# Background + +## Overview + +OSs prioritize robustness by adopting time-tested, stable software versions rather than the latest releases. This strategy minimizes instability risks from version changes and maintains system stability throughout the LTS cycle. Consequently, openEuler has chosen GCC 12.3.1 as its baseline for the entire 24.03 LTS lifecycle. + +This decision, however, introduces challenges. Many hardware features rely on the foundational GCC toolchain, and using an older GCC version delays the activation of new features in OS releases. Additionally, some users prefer the latest compiler versions to unlock new capabilities, which often deliver performance gains over older versions. + +To enable diverse computational features and cater to varying user needs for hardware support, openEuler 24.09 introduces the openEuler GCC Toolset. This multi-version GCC compilation toolchain, tailored for openEuler, provides a secondary GCC version higher than the system primary version, offering users a more flexible and efficient compilation environment. With the openEuler GCC Toolset 14, users can seamlessly switch between GCC versions to leverage new hardware features and benefit from the latest GCC optimizations. + +## Solution Design + +### Compilation Toolchain Features + +The GCC compilation toolchain, developed and maintained by GNU, is a collection of open source tools designed to translate high-level language code into machine language. Beyond GCC itself, it includes a range of auxiliary tools and libraries, collectively forming a comprehensive compilation environment. + +1. GCC compiler (such as `gcc`, `g++`, and `gfortran`): + + - Role: The GCC compiler is the heart of the toolchain, handling preprocessing and compilation to transform source code into assembly or intermediate representation. For C++ code, `g++` acts as the C++ frontend, performing compilation and automatically linking C++ standard libraries. + +2. Binutils toolset: + + - Tools: including the linker (`ld`), assembler (`as`), object file viewer (`readelf`), symbol viewer (`nm`), object file format converter (`objcopy`), disassembler (`objdump`), and size viewer (`size`) + - Role: These tools support the compilation process by converting assembly to machine code, linking object files into executables, and inspecting file details. + +3. glibc library: + + - Role: The GNU C Library (glibc) is the standard C library for GNU and Linux systems, providing essential functions like `printf` and `malloc` required for compiling C programs. + +4. Other auxiliary tools: + + - Debugger (`gdb`): assists developers in debugging executables to identify and fix errors. + - Performance Analysis Tool (`gprof`): helps analyze and optimize program performance. + +### Toolchain Selection + +The software components in the toolchain significantly influence compilation results, with GCC, binutils, and glibc being the core elements. Since glibc, the C standard library, is tightly coupled with the OS kernel version, it remains unchanged. This toolchain includes only GCC and binutils to fulfill the needs of secondary version compilation. + +The latest GCC release, gcc-14.2.0, is selected for the openEuler GCC toolset. For binutils, while openEuler 24.09 defaults to version 2.41, the latest GCC 14 recommends binutils-2.42. Thus, binutils-2.42 is chosen for this toolchain. + +The openEuler GCC toolset incorporates gcc-14.2.0 and binutils-2.42 as the secondary version toolchain to ensure compilation environment stability and efficiency while minimizing complexity. This approach balances compilation quality and user experience. The toolchain GCC version will be updated to gcc-14.3.0 upon its release by the upstream community. + +### Architecture Design + +To differentiate from the default toolchain and prevent conflicts, this toolchain is named gcc-toolset-14. Its package names begin with the prefix `gcc-toolset-14-`, followed by the original toolchain package name. To avoid path overlap with the default **/usr** installation path, gcc-toolset-14 is installed in **/opt/openEuler/gcc-toolset-14/**. Additionally, to distinguish it from open source GCC and enable future integration of openEuler community features, the version of gcc-toolset-14-gcc is set to 14.2.1. + +The applications and libraries in gcc-toolset-14 coexist with the system default GCC version without replacing or overwriting it. They are not set as the default or preferred option. To simplify version switching and management, the scl-utils tool is introduced. Its usage and switching methods are outlined below. + +## Installation and Deployment + +### Software Requirements + +- OS: openEuler 24.09 + +### Hardware Requirements + +- AArch64 or X86_64 + +### Installation Methods + +Install the default GCC compiler, gcc-12.3.1, in **/usr**: + +```shell +yum install -y gcc gcc-c++ +``` + +Install the secondary version compilation toolchain, gcc-toolset-14, in **/opt/openEuler/gcc-toolset-14/root/usr/**: + +```shell +yum install -y gcc-toolset-14-gcc* +yum install -y gcc-toolset-14-binutils* +``` + +## Usage + +This solution uses the SCL (Software Collections) tool to manage different versions of the compilation toolchain. + +### SCL + +SCL is a vital Linux tool that enables users to install and use multiple versions of applications and runtime environments safely and conveniently, preventing system conflicts. + +Key benefits of SCL include: + +1. Multi-version coexistence: allows installing and using multiple versions of software libraries, tools, and runtime environments on the same system to meet diverse needs. +2. Avoiding system conflicts: isolates different software versions to prevent conflicts with the system default version. +3. Enhancing development efficiency: provides developers with the latest toolchains and runtime environments, improving productivity. + +### Version Switching Methods + +**Install SCL:** + +```shell +yum install scl-utils scl-utils-build +``` + +**Register gcc-toolset-14:** + +```shell +## Register gcc-toolset-14. +scl register /opt/openEuler/gcc-toolset-14/ + +## Deregister gcc-toolset-14. +scl deregister gcc-toolset-14 +``` + +Use `scl list-collections` to verify that gcc-toolset-14 is successfully registered. + +**Switch to gcc-toolset-14:** + +```shell +scl enable gcc-toolset-14 bash +``` + +This command launches a new bash shell session with tools from gcc-toolset-14, replacing the system defaults. In this session, there is no need to manually switch compiler versions or paths. To exit the gcc-toolset-14 environment, type `exit` to return to the system default version. + +SCL works by automatically setting environment variables for different tool versions. For details, check the **/opt/openEuler/gcc-toolset-14/enable** file, which contains all environment variable configurations for gcc-toolset-14. If SCL is unavailable, use the following methods to switch toolchain versions: + +```shell +## Option 1: Without SCL, use a script to switch the compilation toolchain. +source /opt/openEuler/gcc-toolset-14/enable + +## Option 2: With SCL, use SCL to switch the toolchain and activate the runtime environment. +scl enable gcc-toolset-14 bash +``` + +## Usage Constraints + +### Compilation Scenarios + +- **Primary version**: Use the system default gcc-12.3.1 for standard compilation and building. +- **Secondary version**: When the advanced features of GCC 14 are needed for application building, use SCL to switch the bash environment to the gcc-toolset-14 compilation environment. + +### GCC 14 Secondary Version Usage Instructions + +1. The openEuler GCC toolset 14 secondary compilation toolchain offers two usage methods: + 1) **Dynamic linking**: By default, the `-lstdc++` option is automatically included for dynamic linking. This links the system dynamic library **/usr/lib64/libstdc++.so.6** and the **libstdc++_nonshared.a** static library provided by the GCC 14 secondary version. This static library contains stable C++ features introduced in GCC 14 compared to GCC 12. + 2) **Static linking**: You can use the `-static` option for static linking, which links the full-feature **libstdc++.a** static library provided by the GCC 14 secondary version. The path to this library is **/opt/openEuler/gcc-toolset-14/root/usr/lib/gcc/aarch64-openEuler-linux/14/libstdc++.a**. + +2. By default, builds use dynamic linking, which links the **libstdc++_nonshared.a** static library. To ensure system compatibility, this library only includes officially standardized C++ features. Experimental features like `-fmodules-ts` and `-fmodule-header`, which are part of C++20 module capabilities, are not included in **libstdc++_nonshared.a**. If you need these features, you should use static linking to fully link the GCC 14 secondary version static library. diff --git a/docs/en/gcc/gcc_basic_performance_optimization_user_guide.md b/docs/en/gcc/gcc_basic_performance_optimization_user_guide.md new file mode 100644 index 0000000..e65f345 --- /dev/null +++ b/docs/en/gcc/gcc_basic_performance_optimization_user_guide.md @@ -0,0 +1,185 @@ +# GCC Basic Performance Optimization User Guide + +## Introduction + +Compiler performance optimization plays a vital role in enhancing application development efficiency, runtime performance, and maintainability. It is a significant research area in computer science and a critical component of the software development process. GCC for openEuler extends its general compilation optimization capabilities by improving backend performance techniques, including instruction optimization, vectorization enhancements, prefetching improvements, and data flow analysis optimizations. + +## Installation and Deployment + +### Software Requirements + +OS: openEuler 24.09 + +### Hardware Requirements + +AArch64 architecture + +### Software Installation + +Install GCC and related components as required. For example, to install GCC: + +```shell +yum install gcc +``` + +## Usage + +### CRC Optimization + +#### Description + +Detects CRC software loop code and generates efficient hardware instructions. + +#### Usage + +Include the `-floop-crc` option during compilation. + +Note: The `-floop-crc` option must be used alongside `-O3 -march=armv8.1-a`. + +### If-Conversion Enhancement + +#### Description + +Improves If-Conversion optimization by leveraging additional registers to minimize conflicts. + +#### Usage + +This optimization is part of the RTL if-conversion process. Enable it using the following compilation options: + +`-fifcvt-allow-complicated-cmps` + +`--param=ifcvt-allow-register-renaming=[0,1,2]` (The value controls the optimization scope.) + +Note: This optimization requires the `-O2` optimization level and should be used with `--param=max-rtl-if-conversion-unpredictable-cost=48` and `--param=max-rtl-if-conversion-predictable-cost=48`. + +### Multiplication Calculation Optimization + +#### Description + +Optimizes Arm-related instruction merging to recognize 32-bit complex combinations of 64-bit integer multiplication logic and produce efficient 64-bit instructions. + +#### Usage + +Enable the optimization using the `-fuaddsub-overflow-match-all` and `-fif-conversion-gimple` options. + +Note: This optimization requires `-O3` or higher optimization levels. + +### cmlt Instruction Generation Optimization + +#### Description + +Generates `cmlt` instructions for specific arithmetic operations, reducing the instruction count. + +#### Usage + +Enable the optimization using the `-mcmlt-arith` option. + +Note: This optimization requires `-O3` or higher optimization levels. + +### Vectorization Optimization Enhancement + +#### Description + +Identifies and simplifies redundant instructions generated during vectorization, enabling shorter loops to undergo vectorization. + +#### Usage + +Enable the optimization using the parameter `--param=vect-alias-flexible-segment-len=1` (default is 0). + +Note: This optimization requires `-O3` or higher optimization levels. + +### Combined Optimization of min max and uzp1/uzp2 Instructions + +#### Description + +Identifies opportunities to optimize `min max` and `uzp1/uzp2` instructions together, reducing the instruction count to enhance performance. + +#### Usage + +Enable `min max` optimization with the `-fconvert-minmax` option. The `uzp1/uzp2` instruction optimization is automatically enabled at `-O3` or higher levels. + +Note: This optimization requires `-O3` or higher optimization levels. + +### ldp/stp Optimization + +#### Description + +Detects poorly performing `ldp/stp` instructions and splits them into two separate `ldr` and `str` instructions. + +#### Usage + +Enable the optimization using the `-fsplit-ldp-stp` option. Control the search range with the parameter `--param=param-ldp-dependency-search-range=[1,32]` (default is 16). + +Note: This optimization requires `-O1` or higher optimization levels. + +### AES Instruction Optimization + +#### Description + +Identifies AES software algorithm instruction sequences and replaces them with hardware instructions for acceleration. + +#### Usage + +Enable the optimization using the `-fcrypto-accel-aes` option. + +Note: This optimization requires `-O3` or higher optimization levels. + +### Indirect Call Optimization + +#### Description + +Analyzes and optimizes indirect calls in the program, converting them into direct calls where possible. + +#### Usage + +Enable the optimization using the `-ficp -ficp-speculatively` options. + +Note: This optimization must be used with `-O2 -flto -flto-partition=one`. + +### IPA-prefetch + +#### Description + +Detects indirect memory accesses in loops and inserts prefetch instructions to minimize latency. + +#### Usage + +Enable the optimization using the `-fipa-prefetch -fipa-ic` options. + +Note: This optimization must be used with `-O3 -flto`. + +### -fipa-struct-reorg + +#### Description + +Optimizes memory layout by reorganizing the arrangement of structure members to improve cache hit rates. + +#### Usage + +Add the options `-O3 -flto -flto-partition=one -fipa-struct-reorg` to enable the optimization. + +Note: The `-fipa-struct-reorg` option requires `-O3 -flto -flto-partition=one` to be enabled globally. + +### -fipa-reorder-fields + +#### Description + +Optimizes memory layout by reordering structure members from largest to smallest, reducing padding and improving cache hit rates. + +#### Usage + +Add the options `-O3 -flto -flto-partition=one -fipa-reorder-fields` to enable the optimization. + +Note: The `-fipa-reorder-fields` option requires `-O3 -flto -flto-partition=one` to be enabled globally. + +### -ftree-slp-transpose-vectorize + +#### Description + +Enhances data flow analysis for loops with consecutive memory reads by inserting temporary arrays during loop splitting. During SLP vectorization, it introduces transposition analysis for `grouped_stores`. + +#### Usage + +Add the options `-O3 -ftree-slp-transpose-vectorize` to enable the optimization. + +Note: The `-ftree-slp-transpose-vectorize` option requires `-O3` to be enabled. diff --git a/docs/en/gcc/kernel_fdo_user_guide.md b/docs/en/gcc/kernel_fdo_user_guide.md new file mode 100644 index 0000000..02c9ec2 --- /dev/null +++ b/docs/en/gcc/kernel_fdo_user_guide.md @@ -0,0 +1,69 @@ +# Kernel FDO User Guide + +## Overview + +The feedback-directed optimization (FDO) of the kernel allows users to build optimized kernels for different applications to improve the application performance in single-application scenarios. In addition, FDO is integrated GCC for openEuler, and A-FOT provides automatic optimization, enabling users to easily enable FDO. + +## Installation and Deployment + +### Software Requirements + +* OS: openEuler 23.09 + +### Hardware Requirements + +* Architecture: AArch64 or x86_64 + +### Software Installation + +#### Downloading the Kernel Source Code + +Download the kernel source code, A-FOT, and dependency packages. + +```shell +yum install -y kernel-source A-FOT make gcc flex bison elfutils-libelf-devel diffutils openssl-devel dwarves +``` + +Copy the kernel source code. + +```shell +cp -r /usr/src/linux-6.4.0-8.0.0.16.oe2309.aarch64 . +``` + +**Note: Change the version number as required.** + +## Usage + +You can use A-FOT to enable kernel FDO and obtain the optimized kernel by specifying **opt_mode** as **Auto_kernel_PGO**. Other configuration items can be specified on the CLI, for example, `./a-fot --pgo_phase 1`. `-s` and `-n` options can be specified on CLI only. Options related to kernel FDO are as follows. + +| No.| Option (Configuration File)| Description | Default Value | +| ---- | -------------------- | ------------------------------------------------------------ | ------------------------ | +| 1 | config_file | Path of the configuration file. User configurations are read from this file. | ${afot_path}/a-fot.ini | +| 2 | opt_mode | Optimization mode to be executed by the tool. The value can be **AutoFDO**, **AutoPrefetch**, **AutoBOLT**, or **Auto_kernel_PGO**.| AutoPrefetch | +| 3 | pgo_mode | Kernel FDO mode, which can be **arc** (GCOV, using only the arc profile) or **all** (full PGO, using the arc and value profiles). | all | +| 4 | pgo_phase | FDO execution phase. The value can be **1** (kernel instrumentation phase) or **2** (data collection and kernel optimization phase). | 1 | +| 5 | kernel_src | Kernel source code directory. If this option is not specified, the tool automatically downloads the source code. | None (optional) | +| 6 | kernel_name | File name of the kernel build. The tool will add the **-pgoing** or **-pgoed** suffix depending on the phase. | kernel | +| 7 | work_path | Script working directory, which is used to store log files, wrappers, and profiles. | **/opt** (**/tmp** cannot be used.)| +| 8 | run_script | Application execution script. The user needs to write the script, which will be used by the tool to execute the target application.| /root/run.sh | +| 9 | gcc_path | GCC path. | /usr | +| 10 | -s | Silent mode. The tool automatically reboots and switches the kernel to execute the second phase. | None | +| 11 | -n | The tool is not used to compile the kernel. This option applies to the scenario where the execution environment and kernel compilation environment are different. | None | + +After configuring the compilation options, run the following command to use A-FOT to automatically optimize the kernel: + +```shell +a-fot --config_file ./a-fot.ini -s +``` + +**Note: The `-s` option instructs A-FOT to automatically reboot into the compiled kernel. If you do not want the tool to automatically perform this sensitive operation, omit this option. However, you need to manually reboot and perform the second phase (`--pgo_phase 2`).** + +**Note: All paths must be absolute paths.** + +**Note: The kernel of openEuler 23.09 does not support full PGO. Change the value of pgo_mode to arc.** + +## Compatibility + +This section describes the compatibility issues in some special scenarios. This project is in continuous iteration and issues will be fixed as soon as possible. Developers are welcome to join this project. + +* The kernel of openEuler 23.09 does not support full PGO. Change the value of pgo_mode to arc. diff --git a/docs/en/gcc/lto_user_guide.md b/docs/en/gcc/lto_user_guide.md new file mode 100644 index 0000000..cd188c1 --- /dev/null +++ b/docs/en/gcc/lto_user_guide.md @@ -0,0 +1,25 @@ +# Introduction to Link-Time Optimization + +In traditional compilation, GCC compiles and optimizes individual source files (compilation units) to generate .o object files containing assembly code. The linker then processes these `.o` files, resolving symbol tables and performing relocations to create the final executable. However, the linker, which has access to cross-file function call information, operates on assembly code and cannot perform compilation optimizations. Conversely, the compilation stage capable of optimizations lacks global cross-file information. While this approach improves efficiency by recompiling only modified units, it misses many cross-file optimization opportunities. + +Link-Time Optimization (LTO) addresses this limitation by enabling optimizations during the linking phase, leveraging cross-compilation-unit call information. To achieve this, LTO preserves the Intermediate Representation (IR) required for optimizations until linking. During linking, the linker invokes the LTO plugin to perform whole-program analysis, make better optimization decisions, and generate more efficient IR. This optimized IR is then converted into object files with assembly code, and the linker completes the standard linking process. + +# Enabling LTO in Version Builds + +## Background + +Many international communities have adopted LTO in their version builds to achieve better performance and smaller binary sizes. LTO is emerging as a key area for exploring compilation optimization opportunities. Starting with version 24.09, openEuler will introduce LTO in its version builds. + +## Solution + +To enable LTO during package builds, we will add `-flto -ffat-lto-objects` to the global compilation options in the macros of **openEuler-rpm-config**. The `-flto` flag enables Link-Time Optimization, while `-ffat-lto-objects` generates fat object files containing both LTO object information and the assembly information required for regular linking. During the build process, LTO object information is used for optimizations. However, since LTO object files are not compatible across GCC versions, we remove the LTO-related fields from `.o/.a` files before packaging them into `.rpm` files, retaining only the assembly code needed for regular linking. This ensures that static libraries remain unaffected. + +## Scope of Enablement + +Due to the significant differences between LTO and traditional compilation workflows, and to minimize the impact on version quality, LTO is currently enabled for only 500+ packages. The list of these packages is available in **/usr/lib/rpm/%{_vendor}/lto_white_list**. These whitelisted applications have been successfully built and passed their test suites with LTO enabled. The LTO compilation options (`-flto -ffat-lto-objects`) are applied only when building whitelisted applications; otherwise, they are omitted. + +In future innovation releases, we will work with application maintainers to expand the scope of LTO enablement. + +## Notes + +The current hot-patching mechanism is incompatible with LTO, causing hot patches to fail when LTO is enabled. We have agreed with the hot-patching team on a solution, which will be implemented in future releases. diff --git a/docs/en/gcc/pin_user_guide.md b/docs/en/gcc/pin_user_guide.md new file mode 100644 index 0000000..750526f --- /dev/null +++ b/docs/en/gcc/pin_user_guide.md @@ -0,0 +1,134 @@ +# Installation and Deployment + +## Software + +* OS: openEuler 23.03 + +## Hardware + +* x86_64 +* Arm + +## Preparing the Environment + +* Install the openEuler operating system. For details, see the [*openEuler Installation Guide*](https://docs.openeuler.openatom.cn/en/docs/24.03_LTS_SP2/server/installation_upgrade/installation/installation_on_servers.html). + +### Install the dependency + +#### Installing the Software on Which the PIN GCC Client Depends + +```shell +yum install -y grpc +yum install -y grpc-devel +yum install -y grpc-plugins +yum install -y protobuf-devel +yum install -y jsoncpp +yum install -y jsoncpp-devel +yum install -y gcc-plugin-devel +yum install -y llvm-mlir +yum install -y llvm-mlir-devel +yum install -y llvm-devel +``` + +#### Installing the Software on Which the PIN Server Depends + +```shell +yum install -y grpc +yum install -y grpc-devel +yum install -y grpc-plugins +yum install -y protobuf-devel +yum install -y jsoncpp +yum install -y jsoncpp-devel +yum install -y llvm-mlir +yum install -y llvm-mlir-devel +yum install -y llvm-devel +``` + +## Installing PIN + +### rpmbuild + +#### Building the PIN GCC Client + +```shell +git clone https://gitee.com/src-openeuler/pin-gcc-client.git +cd pin-gcc-client +mkdir -p ~/rpmbuild/SOURCES +cp *.path pin-gcc-client.tar.gz ~/rpmbuild/SOURCES +rpmbuild -ba pin-gcc-client.spec +cd ~/rpmbuild/RPMS +rpm -ivh pin-gcc-client.rpm +``` + +#### Building the PIN Server + +```shell +git clone https://gitee.com/src-openeuler/pin-server.git +cd pin-server +mkdir -p ~/rpmbuild/SOURCES +cp *.path pin-server.tar.gz ~/rpmbuild/SOURCES +rpmbuild -ba pin-server.spec +cd ~/rpmbuild/RPMS +rpm -ivh pin-server.rpm +``` + +### Build + +#### Building the PIN GCC Client + +```shell +git clone https://gitee.com/openeuler/pin-gcc-client.git +cd pin-gcc-client +mkdir build +cd build +cmake ../ -DMLIR_DIR=${MLIR_PATH} -DLLVM_DIR=${LLVM_PATH} +make +``` + +#### Building the PIN Server + +```shell +git clone https://gitee.com/openeuler/pin-server.git +cd pin-server +mkdir build +cd build +cmake ../ -DMLIR_DIR=${MLIR_PATH} -DLLVM_DIR=${LLVM_PATH} +make +``` + +# Usage + +You can use `-fplugin` and `-fplugin-arg-libpin_xxx` to enable the Plug-IN (PIN) tool. +Command: + +```shell +$(TARGET): $(OBJS) + $(CXX) -fplugin=${CLIENT_PATH}/build/libpin_gcc_client.so \ + -fplugin-arg-libpin_gcc_client-server_path=${SERVER_PATH}/build/pin_server \ + -fplugin-arg-libpin_gcc_client-log_level="1" \ + -fplugin-arg-libpin_gcc_client-arg1="xxx" +``` + +You can use the `${INSTALL_PATH}/bin/pin-gcc-client.json` file to configure PIN. The configuration options are as follows: + +`path`: path of the executable file of the PIN server. + +`sha256file`: path of the PIN verification file `xxx.sha256`. + +`timeout`: timeout interval for cross-process communication, in milliseconds. + +Compile options: + +`-fplugin`: path of the .so file of the PIN client. + +`-fplugin-arg-libpin_gcc_client-server_path`: path of the executable program of the PIN server. + +`-fplugin-arg-libpin_gcc_client-log_level`: default log level. The value ranges from `0` to `3`. The default value is `1`. + +`-fplugin-arg-libpin_gcc_client-argN`: other parameters that can be specified as required. `argN` indicates the argument required by PIN. + +# Compatibility + +This section describes the compatibility issues in some special scenarios. This project is in continuous iteration and will be fixed as soon as possible. Developers are welcome to join this project. + +* When PIN is enabled in the `-flto` phase, multi-process compilation using `make -j` is not supported. You are advised to use `make -j1` for compilation. diff --git a/docs/zh/gcc/_toc.yaml b/docs/zh/gcc/_toc.yaml index 216b1d1..e621a9d 100644 --- a/docs/zh/gcc/_toc.yaml +++ b/docs/zh/gcc/_toc.yaml @@ -7,7 +7,7 @@ sections: - label: 链接时优化特性 href: ./lto_user_guide.md - label: GCC优化特性 - href: ./gcc_optimization_user_guide.md + href: ./gcc_basic_performance_optimization_user_guide.md - label: GCC14副版本编译工具链 href: ./gcc_14_secondary_version_compilation_toolchain_user_guide.md - label: GCC插件框架特性 diff --git a/docs/zh/gcc/dfot_user_guide.md b/docs/zh/gcc/dfot_user_guide.md index 3903e5f..a783602 100644 --- a/docs/zh/gcc/dfot_user_guide.md +++ b/docs/zh/gcc/dfot_user_guide.md @@ -66,7 +66,8 @@ cp configs/dfot.ini /etc/dfot/ | TUNER_CHECK_PERIOD | `[10, max]` | 可用 | 优化插件检查时间间隔，每隔一段时间收集采样插件数据并决定是否进行优化，单位ms | | TUNER_PROFILE_DIR | 按实际需要确定 | 可用 | 采样数据存放位置，profile文件被命名为`[app_name]_[full_path_hash]_[threshold].profile` | | TUNER_OPTIMIZING_STRATEGY | `[0, 1]` | 可用 | 优化策略，0表示只优化一次，1表示只要采样信息在刷新，可以持续多次优化 | -| TUNER_OPTIMIZING_CONDITION | `[0, 2]` | 不可用 | 触发优化的条件，0表示应用退出后即开始优化，1表示低负载时优化，2表示应用退出且低负载时优化，当前仅支持0 | +| TUNER_OPTIMIZING_CONDITION | `[0, 2]` | 不可用 | 触发优化的条件，0表示应用退出后即开始优化，1表示低负载时优化，2表示应用退出且低负载时优化，当前仅支持0 | + 应用配置： [app] | 配置项 | 值范围 | 是否可用 | 说明 | diff --git a/docs/zh/gcc/gcc_optimization_user_guide.md b/docs/zh/gcc/gcc_basic_performance_optimization_user_guide.md similarity index 100% rename from docs/zh/gcc/gcc_optimization_user_guide.md rename to docs/zh/gcc/gcc_basic_performance_optimization_user_guide.md diff --git a/docs/zh/gcc/pin_user_guide.md b/docs/zh/gcc/pin_user_guide.md index 25e243a..0d6fec9 100644 --- a/docs/zh/gcc/pin_user_guide.md +++ b/docs/zh/gcc/pin_user_guide.md @@ -11,7 +11,7 @@ ## 环境准备 -* 安装openEuler系统，安装方法参考 《[安装指南](https://docs.openeuler.openatom.cn/zh/docs/25.03/server/installation_upgrade/installation/installation-preparations.html)》。 +* 安装openEuler系统，安装方法参考 《[安装指南](https://docs.openeuler.openatom.cn/zh/docs/24.03_LTS_SP2/server/installation_upgrade/installation/installation_on_servers.html)》。 ### 安装依赖软件 -- Gitee