[flang][nfc] Clarify the frontend/backend distinction

[awarzynski]

Summary

This addition was requested in #1262. It probably makes more sense to add to the driver documentation rather than somewhere inside the code.

Does this make sense? Thank you!

[Meinersbur]

IMHO, MLIR is part of the mid-end/optimizer. From a conceptual point, drawing the line between LLVM-IR and MLIR is arbitrary, and optimizations are done on the MLIR/FIR-level as well. Eg. Open64 has six different intermediate representations. "all the stages implemented in the Flang sub-project" is also blurry since MLIR other than the FIR dialect is not part of the flang project. Consistency with Clang can also not claimed since Clang has no MLIR or language-specific IR stage.

Generally, I'd prefer to introduce different meanings for front-end/mid-end/back-end for different parts. IMHO renaming EmitObjAction to BackendAction is still fine since emitting assembly and object code both go through the actual LLVM backends.

flang/docs/FlangDriver.md

340

I think the doc uses American English

[PeteSteinfeld]

Aside from a couple of nits, looks good to me. Thanks for doing this.

flang/docs/FlangDriver.md

360

I think you mean "may refer" rather than "my refer".

361

In American English, at least, the usual phrase is "distinction between" rather than "distinction into".

[schweitz]

I agree with the comment that calling MLIR and/or FIR a "front end" is arbitrary and, I suspect, mostly based on a directory structure.

In the flang project/directory, there is a pretty clear and obvious distinction between the front end of parsing and semantics checking and the high-level semantic representation of FIR and optimizations. Indeed the distinction between these in the vernacular of the Flang project is "front end" vs. "lowering" or "optimizer". Flang has an Optimizer directory, mostly upstreamed, of its own, so the definitions given here seem confusing. In short, LLVM target independent optimizations won't be the only optimizations and do not define the entirety of "the optimizer" for Flang. (For completeness, the LLVM target independent optimizations and code generation parts are often referred to as "the backend" in Flang.)

flang/docs/FlangDriver.md

350

optimizer. You'll want to search and replace as both the British 's' and the American 'z' are used here.

361

backaned / backend

[PeteSteinfeld]

In D115529#3186543, @schweitz wrote:

I agree with the comment that calling MLIR and/or FIR a "front end" is arbitrary and, I suspect, mostly based on a directory structure.

In the flang project/directory, there is a pretty clear and obvious distinction between the front end of parsing and semantics checking and the high-level semantic representation of FIR and optimizations. Indeed the distinction between these in the vernacular of the Flang project is "front end" vs. "lowering" or "optimizer". Flang has an Optimizer directory, mostly upstreamed, of its own, so the definitions given here seem confusing. In short, LLVM target independent optimizations won't be the only optimizations and do not define the entirety of "the optimizer" for Flang. (For completeness, the LLVM target independent optimizations and code generation parts are often referred to as "the backend" in Flang.)

Eric hints at the fact that it would be good for the high-level description of the compiler to mimic the structure of the code.

flang/docs/FlangDriver.md

 cases (e.g. compiling C files, linking existing object files). `gfortran` is
 the default host compiler used by `flang`. You can change it by setting the
 `FLANG_FC` environment variable.
 
 Our intention is to replace `flang` with `flang-new`. Please consider `flang`
 as a temporary substitute for Flang's compiler driver while the actual driver
 is in development.
 
-## Adding new Compiler Options
+# Adding new Compiler Options
 Adding a new compiler option in Flang consists of two steps:
 * define the new option in a dedicated TableGen file,
 * parse and implement the option in the relevant drivers that support it.
 
-### Option Definition
+## Option Definition
 All of Flang's compiler and frontend driver options are defined in
 `clang/include/clang/Driver/Options.td` in Clang. When adding a new option to
 Flang, you will either:
   * extend the existing definition for an option that is already available
     in one of Clang's drivers (e.g.  `clang`), but not yet available in Flang, or
   * add a completely new definition if the option that you are adding has not
     been defined yet.
 

 categories:
   * `Action_Group` - options that define an action to run (e.g.
     `-fsyntax-only`, `-E`)
   * `f_Group` - target independent compiler flags (e.g. `-ffixed-form`,
     `-fopenmp`)
 There are also other groups and occasionally you will use them instead of the
 groups listed above.
 
-### Option Implementation
+## Option Implementation
 First, every option needs to be parsed. Flang compiler options are parsed in
 two different places, depending on which driver they belong to:
 
 * frontend driver: `flang/lib/Frontend/CompilerInvocation.cpp`,
 * compiler driver: `clang/lib/Driver/ToolChains/Flang.cpp`.
 
 The parsing will depend on the semantics encoded in the TableGen definition.
 
 When adding a compiler driver option (i.e. an option that contains
 `FlangOption` among its `Flags`) that you also intend to be understood by the
 frontend, make sure that it is either forwarded to `flang-new -fc1` or translated
 into some other option that is accepted by the frontend driver. In the case of
 options that contain both `FlangOption` and `FC1Option` among its flags, we
 usually just forward from `flang-new` to `flang-new -fc1`. This is then tested in
 `flang/test/Driver/frontend-forward.F90`.
 
 What follows is usually very dependant on the meaning of the corresponding
 option. In general, regular compiler flags (e.g. `-ffree-form`) are mapped to
 some state within the driver. A lot of this state is stored within an instance
 of `FrontendOptions`, but there are other more specialised classes too. Action
 flags (e.g. `-fsyntax-only`) are usually more complex overall, but also more
 structured in terms of the implementation.
 
-### Action Options
+## Action Options
 For options that correspond to an action (i.e. marked as `Action_Group`), you
 will have to define a dedicated instance of `FrontendActions` in
 `flang/include/flang/Frontend/FrontendOptions.h`. For example, for
 `-fsyntax-only` we defined:
 ```cpp
 class ParseSyntaxOnlyAction : public PrescanAndSemaAction {
   void ExecuteAction() override;
 };

 `-fsyntax-only`:
 ```cpp
   case ParseSyntaxOnly:
     return std::make_unique<ParseSyntaxOnlyAction>();
 ```
 At this point you should be able to trigger that frontend action that you have
 just added using your new frontend option.
 
+# Frontend vs Optimiser vs Backend
+Depending on the context, compiler frontend and backend can mean different
+things. From the point of view of the Flang drivers, the **frontend** includes all
+the stages implemented in the Flang sub-project:
+
+* parsing, semantic analysis, lowering from parse tree to MLIR, lowering from
+  MLIR to LLVM IR.
+
+Broadly speaking, the frontend consumes Fortran source files and generates LLVM
+IR output (it can also consume and generate most of the intermediate
+representations). The generated LLVM IR is then passed onto the **optimiser**
+that is implemented within the LLVM sub-project and that transforms the input
+LLVM IR into optimized LLVM IR output. These transformations are mostly
+target-agnostic. The output generated by the optimiser is then passed onto one
+of the many **backends** (e.g. AArch64 or X86), also implemented inside the
+LLVM sub-project. A backend will lower the target agnostic LLVM IR into a
+target specific assembly or machine-code representation. It may also perform
+some target specific micro-optimisations.
+
+This classification is reflected in the naming used for various driver
+components inside Flang. Note that other parts of the Flang frontend my refer
+to LLVM (or LLVM IR) as the backaned without making a distinction into the
+optimiser and one of the LLVM hardware backends.
+
 # Testing
 In LIT, we define two variables that you can use to invoke Flang's drivers:
 * `%flang` is expanded as `flang-new` (i.e. the compiler driver)
 * `%flang_fc1` is expanded as `flang-new -fc1` (i.e. the frontend driver)
 
 For most regression tests for the frontend, you will want to use `%flang_fc1`.
 In some cases, the observable behaviour will be identical regardless of whether
 `%flang` or `%flang_fc1` is used. However, when you are using `%flang` instead