Jean Perier db77b18887 [flang] Adding a guideline for flang design documentation

The goal of this document is to:
- Allow the community to contribute to flang design by defining the
  expectations.
- Ensure there is a minimum of consistency between future design docs.

Differential Revision: https://reviews.llvm.org/D130166

2022-08-26 16:18:16 +02:00

5.4 KiB

Raw Blame History

Design Guideline

.. contents::
   :local:

Documenting the design

Designing support for a new feature

When working on a new feature in flang, some design document should be produced before submitting patches to the code. Note that new features that need support in flang are listed in llvm github project Flang features to be implemented.

The preferred organization of such documents is:

Problem description
Proposed solution
Implementation details overview
Testing plan

If several solutions can be considered, it is best to briefly describe the alternate solutions in 2) and why they were not retained.

The design document should be added to the docs folder as a markdown document, ideally using the name of the feature as the document name. Its approval on Phabricator is the pre-requisite to submitting patches implementing new features.

An RFC on flang https://discourse.llvm.org can first be made as one sees fit, but this document should still be produced to summarize, organize, and formalize the discussions. If a related discourse RFC was made it is a good idea to give a link to it in the document for future reference. If no RFC was made before sending the design document for review, it is highly encouraged to make a small announcement on https://discourse.llvm.org with a link to the Phabricator design document review.

The Testing Plan should briefly describe what aspects will be tested with LLVM unit test tools (see LLVM Testing Guide), and if some existing end-to-end test suite or application can be used to validate the feature implementation.

Features impacting projects outside of flang (like work OpenMP or OpenACC that may require touching parts outside of flang tree) should follow the general LLVM process, or the related subproject process. There should still be a related flang design document if part of the solution impacts flang in significant ways (e.g. if the changes in the code that lowers the parse-tree to OpenMP and FIR dialects are not straightforwardly mapping parse-tree nodes to dialect operations).

Updating the implementation solution of a feature

When doing a significant change to the implementation solution for a feature, the related design document should be updated so that it will justify the new solution.

Design tips

Design document style

The document does not have to be long. It is highly encouraged to:

Stick to well-defined Fortran terms when talking about Fortran (definitions of these terms can be found in Section 3 of Fortran 2018 standard).
Be precise (e.g., pointing to the standard reference or constraint numbers). References should currently be given against the Fortran 2018 standard version.
Illustrate with a few small Fortran code snippets if applicable
When dealing with lowering, illustrate lowering output with a few FIR and LLVM IR code snippets.
Illustrations do not have to be fully functional programs, it is better to keep them small and focused on the feature. More detailed expectations can be added in a second time or in parallel as LIT tests for example.

Thinking through the design of a Fortran feature

Below is a set of suggested steps that one can take to fully apprehend a Fortran feature before writing a design for its implementation in flang.

Identify the relevant sections and constraints in the standard.
Write Fortran programs using the feature and, if possible, verify your expectations with existing compilers.
Check if the related constraints (Cxxx numbers in the standard) are enforced by semantic checks in the compiler. If not, it is a good idea to start by adding the related checks (this does not require writing a design document).
Identify if the feature affects compatibility with programs compiled by other Fortran compilers, or if a given solution for flang could not be changed in the future without breaking compatibility with programs previously compiled with flang. It is not a goal to be 100% binary compatible with other compilers outside of Fortran 77, but sources of incompatibility should be known and justified. By binary compatibility, it is meant that F77 libraries compiled with other Fortran compilers (at least gfortran) should link with flang compiled code and vice-versa.
Identify related features, or contexts that matter for the feature (e.g, does being in an internal procedure, a module, a block… affect what should happen?).
Not everything has to be inlined code, delegating part of the work to the Fortran runtime may be a solution. Identify the relevant Fortran runtime API if any.
For inlined code, consider what should happen when generating the FIR, what should happen in the FIR transformation passes (FIR to FIR), and what should happen when lowering the FIR to LLVM IR.
For inlined ops, look at how the existing dialects can be reused. If new FIR operations are required, justify their purpose.
Look at the related representation in Semantics (e.g., is some information from the parse tree, the Symbol or evaluate::Expr required? Are there tools to query this information easily?).

5.4 KiB Raw Blame History