[flang-commits] [flang] [flang][docs] Removed HighLevelFIR transition plan section (PR #196227)

[Eugene Epshteyn via flang-commits]

https://github.com/eugeneepshteyn updated https://github.com/llvm/llvm-project/pull/196227

>From d6eac83845d23c8fd3103a3382aa34e0b54e6ca8 Mon Sep 17 00:00:00 2001
From: Eugene Epshteyn <eepshteyn at nvidia.com>
Date: Wed, 6 May 2026 23:28:03 -0400
Subject: [PATCH 1/3] [flang][docs] Mark HighLevelFIR transition plan as
 historical

Rewrite the "Transition Plan" section in flang/docs/HighLevelFIR.md as
"Transition (Historical)". HLFIR is now the only lowering path, and the
opt-in driver flag plus the legacy FIR-only expression lowering have
been removed, so the section no longer describes pending work. Convert
the steps to past tense, drop the "current lowering" framing, and add a
short note explaining how the transition concluded.
---
 flang/docs/HighLevelFIR.md | 87 +++++++++++++++++---------------------
 1 file changed, 38 insertions(+), 49 deletions(-)

diff --git a/flang/docs/HighLevelFIR.md b/flang/docs/HighLevelFIR.md
index 2399efcdeacd3..28fbc9bb531ab 100644
--- a/flang/docs/HighLevelFIR.md
+++ b/flang/docs/HighLevelFIR.md
@@ -960,55 +960,44 @@ LLVM.
 These high level optimization passes can be run any number of times in any
 order.
 
-## Transition Plan
-
-The new higher-level steps proposed in this document will require significant
-refactoring of lowering. Codegen should not be impacted since the current FIR
-will remain untouched.
-
-A lot of the code in lowering generating Fortran features (like an intrinsic or
-how to do assignments) is based on the fir::ExtendedValue concept. This
-currently is a collection of mlir::Value that allows describing a Fortran object
-(either a variable or an evaluated expression result). The variable and
-expression concepts described above should allow to keep an interface very
-similar to the fir::ExtendedValue, but having the fir::ExtendedValue wrap a
-single value or mlir::Operation* from which all of the object entity
-information can be inferred.
-
-That way, all the helpers currently generating FIR from fir::ExtendedValue could
-be kept and used with the new variable and expression concepts with as little
-modification as possible.
-
-The proposed plan is to:
-- 1. Introduce the new HLFIR operations.
-- 2. Refactor fir::ExtendedValue so that it can work with the new variable and
-     expression concepts (requires part of 1.).
-- 3. Introduce the new translation passes, using the fir::ExtendedValue helpers
-     (requires 1.).
-- 3.b Introduce the new optimization passes (requires 1.).
-- 4. Introduce the fir.declare and hlfir.finalize usage in lowering (requires 1.
-     and 2. and part of 3.).
-
-The following steps might have to be done in parallel of the current lowering,
-to avoid disturbing the work on performance until the new lowering is complete
-and on par.
-
-- 5. Introduce hlfir.designate and hlfir.associate usage in lowering.
-- 6. Introduce lowering to hlfir.assign (with RHS that is not a hlfir.expr),
-     hlfir.ptr_assign.
-- 7. Introduce lowering to hlfir.expr and related operations.
-- 8. Introduce lowering to hlfir.forall.
-
-At that point, lowering using the high-level FIR should be in place, allowing
-extensive testing.
-- 9. Debugging correctness.
-- 10. Debugging execution performance.
-
-The plan is to do these steps incrementally upstream, but for lowering this will
-most likely be safer to do have the new expression lowering implemented in
-parallel upstream, and to add an option to use the new lowering rather than to
-directly modify the current expression lowering and have it step by step
-equivalent functionally and performance wise.
+## Transition (Historical)
+
+HLFIR is now the only lowering path; the legacy FIR-only expression lowering
+and the options that selected it have been removed. This section is kept for
+historical reference.
+
+The introduction of HLFIR required significant refactoring of lowering, but
+codegen was unaffected because the underlying FIR pipeline was preserved.
+
+Most lowering helpers were built around the `fir::ExtendedValue` concept --
+a collection of `mlir::Value`s describing a Fortran object (variable or
+evaluated expression result). The variable and expression concepts above
+allowed keeping a similar interface, with `fir::ExtendedValue` wrapping a
+single value or `mlir::Operation *` from which all object information could
+be inferred, so existing helpers carried over with minimal modification.
+
+The transition proceeded in roughly the following order:
+
+1. Introduce the new HLFIR operations.
+2. Refactor `fir::ExtendedValue` to work with the new variable and expression
+   concepts (requires part of 1).
+3. Introduce the new translation passes, using the `fir::ExtendedValue`
+   helpers (requires 1).
+   - 3.b Introduce the new optimization passes (requires 1).
+4. Introduce `fir.declare` and `hlfir.finalize` usage in lowering (requires
+   1, 2, and part of 3).
+5. Introduce `hlfir.designate` and `hlfir.associate` usage in lowering.
+6. Introduce lowering to `hlfir.assign` (with RHS that is not an `hlfir.expr`)
+   and `hlfir.ptr_assign`.
+7. Introduce lowering to `hlfir.expr` and related operations.
+8. Introduce lowering to `hlfir.forall`.
+9. Debug correctness.
+10. Debug execution performance.
+
+Steps 5-10 were done with the new lowering implemented alongside the old one
+behind an opt-in driver flag, so performance work on the legacy path was not
+disturbed until the new lowering reached parity. Once HLFIR was on by
+default, the opt-in flag and the legacy expression lowering were removed.
 
 ## Examples
 

>From 5cdf9e6b8bb92470d8955d9023572dbfe6c63ab7 Mon Sep 17 00:00:00 2001
From: Eugene Epshteyn <eepshteyn at nvidia.com>
Date: Thu, 7 May 2026 06:24:56 -0400
Subject: [PATCH 2/3] Based on review feedback, removed the transition section

---
 flang/docs/HighLevelFIR.md | 39 --------------------------------------
 1 file changed, 39 deletions(-)

diff --git a/flang/docs/HighLevelFIR.md b/flang/docs/HighLevelFIR.md
index 28fbc9bb531ab..99a05c48b1e4e 100644
--- a/flang/docs/HighLevelFIR.md
+++ b/flang/docs/HighLevelFIR.md
@@ -960,45 +960,6 @@ LLVM.
 These high level optimization passes can be run any number of times in any
 order.
 
-## Transition (Historical)
-
-HLFIR is now the only lowering path; the legacy FIR-only expression lowering
-and the options that selected it have been removed. This section is kept for
-historical reference.
-
-The introduction of HLFIR required significant refactoring of lowering, but
-codegen was unaffected because the underlying FIR pipeline was preserved.
-
-Most lowering helpers were built around the `fir::ExtendedValue` concept --
-a collection of `mlir::Value`s describing a Fortran object (variable or
-evaluated expression result). The variable and expression concepts above
-allowed keeping a similar interface, with `fir::ExtendedValue` wrapping a
-single value or `mlir::Operation *` from which all object information could
-be inferred, so existing helpers carried over with minimal modification.
-
-The transition proceeded in roughly the following order:
-
-1. Introduce the new HLFIR operations.
-2. Refactor `fir::ExtendedValue` to work with the new variable and expression
-   concepts (requires part of 1).
-3. Introduce the new translation passes, using the `fir::ExtendedValue`
-   helpers (requires 1).
-   - 3.b Introduce the new optimization passes (requires 1).
-4. Introduce `fir.declare` and `hlfir.finalize` usage in lowering (requires
-   1, 2, and part of 3).
-5. Introduce `hlfir.designate` and `hlfir.associate` usage in lowering.
-6. Introduce lowering to `hlfir.assign` (with RHS that is not an `hlfir.expr`)
-   and `hlfir.ptr_assign`.
-7. Introduce lowering to `hlfir.expr` and related operations.
-8. Introduce lowering to `hlfir.forall`.
-9. Debug correctness.
-10. Debug execution performance.
-
-Steps 5-10 were done with the new lowering implemented alongside the old one
-behind an opt-in driver flag, so performance work on the legacy path was not
-disturbed until the new lowering reached parity. Once HLFIR was on by
-default, the opt-in flag and the legacy expression lowering were removed.
-
 ## Examples
 
 ### Example 1: simple array assignment

>From c1b1cdfaa72e4b5b8864671b70747b44fb768208 Mon Sep 17 00:00:00 2001
From: Eugene Epshteyn <eepshteyn at nvidia.com>
Date: Thu, 7 May 2026 23:31:56 -0400
Subject: [PATCH 3/3] As requested, moved transition section to a new document

---
 flang/docs/HLFIRTransition.md | 53 +++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 flang/docs/HLFIRTransition.md

diff --git a/flang/docs/HLFIRTransition.md b/flang/docs/HLFIRTransition.md
new file mode 100644
index 0000000000000..14d4471bae091
--- /dev/null
+++ b/flang/docs/HLFIRTransition.md
@@ -0,0 +1,53 @@
+# Transition of Lowering to HLFIR
+
+(This section was extracted from [HighLevelFIR.md‎](High-Level Fortran IR (HLFIR)) document: this information is no longer relevant to the current state of HLFIR lowering, but it could be useful as a historical reference.)
+
+## Transition Plan
+
+The new higher-level steps proposed in this document will require significant
+refactoring of lowering. Codegen should not be impacted since the current FIR
+will remain untouched.
+
+A lot of the code in lowering generating Fortran features (like an intrinsic or
+how to do assignments) is based on the fir::ExtendedValue concept. This
+currently is a collection of mlir::Value that allows describing a Fortran object
+(either a variable or an evaluated expression result). The variable and
+expression concepts described above should allow to keep an interface very
+similar to the fir::ExtendedValue, but having the fir::ExtendedValue wrap a
+single value or mlir::Operation* from which all of the object entity
+information can be inferred.
+
+That way, all the helpers currently generating FIR from fir::ExtendedValue could
+be kept and used with the new variable and expression concepts with as little
+modification as possible.
+
+The proposed plan is to:
+- 1. Introduce the new HLFIR operations.
+- 2. Refactor fir::ExtendedValue so that it can work with the new variable and
+     expression concepts (requires part of 1.).
+- 3. Introduce the new translation passes, using the fir::ExtendedValue helpers
+     (requires 1.).
+- 3.b Introduce the new optimization passes (requires 1.).
+- 4. Introduce the fir.declare and hlfir.finalize usage in lowering (requires 1.
+     and 2. and part of 3.).
+
+The following steps might have to be done in parallel of the current lowering,
+to avoid disturbing the work on performance until the new lowering is complete
+and on par.
+
+- 5. Introduce hlfir.designate and hlfir.associate usage in lowering.
+- 6. Introduce lowering to hlfir.assign (with RHS that is not a hlfir.expr),
+     hlfir.ptr_assign.
+- 7. Introduce lowering to hlfir.expr and related operations.
+- 8. Introduce lowering to hlfir.forall.
+
+At that point, lowering using the high-level FIR should be in place, allowing
+extensive testing.
+- 9. Debugging correctness.
+- 10. Debugging execution performance.
+
+The plan is to do these steps incrementally upstream, but for lowering this will
+most likely be safer to do have the new expression lowering implemented in
+parallel upstream, and to add an option to use the new lowering rather than to
+directly modify the current expression lowering and have it step by step
+equivalent functionally and performance wise.