From 0b352edd68eb877208dd56d8919e350c3a4100d4 Mon Sep 17 00:00:00 2001 From: Nikita Popov Date: Mon, 15 Sep 2025 11:40:04 +0200 Subject: [PATCH 1/5] [DeveloperPolicy] Add guidelins for adding/enabling passes --- llvm/docs/DeveloperPolicy.rst | 44 +++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/llvm/docs/DeveloperPolicy.rst b/llvm/docs/DeveloperPolicy.rst index b54f111ed0916..ecb38e82206a1 100644 --- a/llvm/docs/DeveloperPolicy.rst +++ b/llvm/docs/DeveloperPolicy.rst @@ -1185,6 +1185,50 @@ Suggested disclaimer for the project README and the main project web page: necessarily a reflection of the completeness or stability of the code, it does indicate that the project is not yet endorsed as a component of LLVM. +Adding or enabling a new LLVM pass +---------------------------------- + +The guidelines here are primarily targeted at the enablement of new major +passes in the target-independent optimization pipeline. Small additions, or +backend-specific passes, require a lesser degree of care. + +When adding a new pass, the goal should be to enable it as part of the default +optimization pipeline as early as possible and then continue development +incrementally. The recommended workflow is: + +1. Implement a basic version of the pass and add it to the pass pipeline behind + a flag that is disabled by default. +2. Enable the pass by default. Separating this step allows easily disabling the + pass if issues are encountered, without having to revert the entire + implementation. +3. Incrementally extend the pass with new functionality. As the pass is already + enabled, it becomes easier to identify the specific change that has caused a + regression in correctness, optimization quality or compile-time. + +When enabling a pass, regardless of whether it is old or new, certain +requirements must be met (in no particular order): + + * **Maintenance:** The pass (and any analyses it depends on) must have at + least one maintainer. + * **Usefulness:** There should be evidence that the pass improves performance + (or whatever metric it optimizes for) on real-world workloads. Improvements + seen only on synthetic benchmarks may be insufficient. + * **Compile-Time:** The pass should not have a large impact on compile-time, + where the evaluation of what "large" means is up to reviewer discretion, and + may differ based on the value the pass provides. In any case, it is expected + that a concerted effort has been made to mitigate the compile-time impact, + both for the average case, and for pathological cases. + * **Correctness:** The pass should have no known correctness issues (except + global correctness issues that affect all of LLVM). If an old pass is being + enabled (rather than implementing a new one incrementally), additional due + diligence is required. The pass should be fully reviewed to ensure that it + still complies with current quality standards. Fuzzing with disabled + profitability checks may help gain additional confidence in the + implementation. + +If non-trivial issues are found in a newly enabled pass, it may be temporarily +disabled again, until the issues have been resolved. + .. _copyright-license-patents: Copyright, License, and Patents From 5c8b52215202da0077a46b964e10b9064c02430c Mon Sep 17 00:00:00 2001 From: Nikita Popov Date: Mon, 22 Sep 2025 14:47:53 +0200 Subject: [PATCH 2/5] Suggest adding to an existing pass --- llvm/docs/DeveloperPolicy.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/llvm/docs/DeveloperPolicy.rst b/llvm/docs/DeveloperPolicy.rst index ecb38e82206a1..3e5f0a77375e0 100644 --- a/llvm/docs/DeveloperPolicy.rst +++ b/llvm/docs/DeveloperPolicy.rst @@ -1190,7 +1190,9 @@ Adding or enabling a new LLVM pass The guidelines here are primarily targeted at the enablement of new major passes in the target-independent optimization pipeline. Small additions, or -backend-specific passes, require a lesser degree of care. +backend-specific passes, require a lesser degree of care. Before creating a new +pass, consider whether the functionality can be integrated into an existing +pass first. This is often both faster and more powerful. When adding a new pass, the goal should be to enable it as part of the default optimization pipeline as early as possible and then continue development From b5ea3c79b859539d1fbdd48e8e9a08027aa8ccf3 Mon Sep 17 00:00:00 2001 From: Nikita Popov Date: Mon, 22 Sep 2025 14:57:38 +0200 Subject: [PATCH 3/5] Drop old/new distinction in one place --- llvm/docs/DeveloperPolicy.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/llvm/docs/DeveloperPolicy.rst b/llvm/docs/DeveloperPolicy.rst index 3e5f0a77375e0..286a6ef609ee3 100644 --- a/llvm/docs/DeveloperPolicy.rst +++ b/llvm/docs/DeveloperPolicy.rst @@ -1207,8 +1207,7 @@ incrementally. The recommended workflow is: enabled, it becomes easier to identify the specific change that has caused a regression in correctness, optimization quality or compile-time. -When enabling a pass, regardless of whether it is old or new, certain -requirements must be met (in no particular order): +When enabling a pass, certain requirements must be met (in no particular order): * **Maintenance:** The pass (and any analyses it depends on) must have at least one maintainer. From 14595d4eaa058e3727ec436a0e64750b12a15aa5 Mon Sep 17 00:00:00 2001 From: Nikita Popov Date: Mon, 22 Sep 2025 14:59:56 +0200 Subject: [PATCH 4/5] Clarify what basic version means --- llvm/docs/DeveloperPolicy.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/llvm/docs/DeveloperPolicy.rst b/llvm/docs/DeveloperPolicy.rst index 286a6ef609ee3..bfeb2295f368d 100644 --- a/llvm/docs/DeveloperPolicy.rst +++ b/llvm/docs/DeveloperPolicy.rst @@ -1199,7 +1199,8 @@ optimization pipeline as early as possible and then continue development incrementally. The recommended workflow is: 1. Implement a basic version of the pass and add it to the pass pipeline behind - a flag that is disabled by default. + a flag that is disabled by default. The initial version should focus on + handling simple cases correctly and efficiently. 2. Enable the pass by default. Separating this step allows easily disabling the pass if issues are encountered, without having to revert the entire implementation. From 750a5bfa21899aea76360549e0fa15d045e5fbc3 Mon Sep 17 00:00:00 2001 From: Nikita Popov Date: Mon, 22 Sep 2025 15:48:33 +0200 Subject: [PATCH 5/5] Exclude passes which shouldn't be in the default pipeline --- llvm/docs/DeveloperPolicy.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/llvm/docs/DeveloperPolicy.rst b/llvm/docs/DeveloperPolicy.rst index bfeb2295f368d..ea19ad292946d 100644 --- a/llvm/docs/DeveloperPolicy.rst +++ b/llvm/docs/DeveloperPolicy.rst @@ -1196,7 +1196,10 @@ pass first. This is often both faster and more powerful. When adding a new pass, the goal should be to enable it as part of the default optimization pipeline as early as possible and then continue development -incrementally. The recommended workflow is: +incrementally. (This does not apply to passes that are only relevant for +specific uses of LLVM, such as GC support passes.) + +The recommended workflow is: 1. Implement a basic version of the pass and add it to the pass pipeline behind a flag that is disabled by default. The initial version should focus on