Docs:Content Organization & Add 'Frontend' and 'Midend' Sections (#4876)

* Migrate Content Updates from PR #4850 Signed-off-by: Adarsh <[email protected]> * Fix: Formatting of IR Description tables Signed-off-by: Adarsh <[email protected]> * Refactor: Shorter description for Pass library Signed-off-by: Adarsh <[email protected]> * Remove Optimization Passes Section from Midend Signed-off-by: Adarsh <[email protected]> * Improve front end description Co-authored-by: Fabian Ruffy <[email protected]> Signed-off-by: Adarsh Rawat <[email protected]> * Formatting Changes P4_14 -> P4-14 P4_16 -> P4-16 Signed-off-by: Adarsh <[email protected]> * Removed Pass library section from Midend Signed-off-by: Adarsh <[email protected]> * Fix: Midend ref Link in doxygen Signed-off-by: Adarsh <[email protected]> * Removed Extra lines from Midend Description Signed-off-by: Adarsh <[email protected]> * Minor fix : Spacing Co-authored-by: Fabian Ruffy <[email protected]> Signed-off-by: Adarsh Rawat <[email protected]> * Minor Refactor : IR Classes heading Signed-off-by: Adarsh <[email protected]> Co-authored-by: Fabian Ruffy <[email protected]> Signed-off-by: Adarsh Rawat <[email protected]> * Minor Fix: Spelling of 'Ternary' Signed-off-by: Adarsh <[email protected]> Co-authored-by: Fabian Ruffy <[email protected]> Signed-off-by: Adarsh Rawat <[email protected]> --------- Signed-off-by: Adarsh <[email protected]> Signed-off-by: Adarsh Rawat <[email protected]> Co-authored-by: Fabian Ruffy <[email protected]>
p4lang · Aug 22, 2024 · 54d4b9d · 54d4b9d
1 parent bba10d7
commit 54d4b9d
Show file tree

Hide file tree

Showing 10 changed files with 126 additions and 227 deletions.
diff --git a/backends/bmv2/pna_nic/README.md b/backends/bmv2/pna_nic/README.md
@@ -11,26 +11,11 @@ The [`backends/bmv2/pna_nic` directory](https://github.com/p4lang/p4c/tree/main/
 
 Output Binary: `p4c-bm2-pna`
 
-#### pnaProgramStructure.h, pnaProgramStructure.cpp
-
-Defines and implements the program structure (metadata, parsers, controls, and deparsers) and parsing logic specific to the BMv2's PNA NIC backend.
-
-##### midend.h, midend.cpp
-
-Defines the mid-end processing of the PNA NIC compiler. Performs various transformations and optimizations on the program's Intermediate Representation (IR).
-
-##### options.h, options.cpp
-
-Manages the command-line options for the PNA NIC compiler.
-
-##### pnaNic.h, pnaNic.cpp
-
-Provides backend implementation to the BMv2's PNA NIC compiler.
-
-##### main.cpp
-
-Sets up compilation environment, integrates various components, and executes the PNA NIC compiler.
-
-##### version.h.cmake
-
-Defines macros containing version information for the PNA NIC compiler.
+| File(s)                      | Description |
+|------------------------------|-------------|
+| `pnaProgramStructure.h`, `pnaProgramStructure.cpp` | Defines and implements the program structure (metadata, parsers, controls, and deparsers) and parsing logic specific to the BMv2's PNA NIC backend. |
+| `midend.h`, `midend.cpp`     | Defines the mid-end processing of the PNA NIC compiler. Performs various transformations and optimizations on the program's Intermediate Representation (IR). |
+| `options.h`, `options.cpp`   | Manages the command-line options for the PNA NIC compiler. |
+| `pnaNic.h`, `pnaNic.cpp`     | Provides backend implementation to the BMv2's PNA NIC compiler. |
+| `main.cpp`                   | Sets up compilation environment, integrates various components, and executes the PNA NIC compiler. |
+| `version.h.cmake`            | Defines macros containing version information for the PNA NIC compiler. |
diff --git a/backends/bmv2/portable_common/README.md b/backends/bmv2/portable_common/README.md
@@ -6,22 +6,11 @@ Refer to the specific section here: [portable_common - Subsection](https://p4lan
 -->
 # portable_common
 
-This directory contains reusable components common to both the `psa_switch` and `pna_nic` backends.
-
-### midend.h, midend.cpp
-
-Defines the common mid-end processing of both the `psa_switch` and `pna_nic` backends.
-
-### options.h, options.cpp
-
-Defines the common command-line options of both the `psa_switch` and `pna_nic` backends.
-
-### portable.h, portable.cpp
-
-Defines common functionalities that generate representations of P4 programs.
-
-The files `portableProgramStructure.h` and `portableProgramStructure.cpp` are in the `backends/common` directory.
-
-### portableProgramStructure.h, portableProgramStructure.cpp
-
-Defines and implements the common program structure of both the `psa_switch` and `pna_nic` backends.
+The [`portable_common` directory](https://github.com/p4lang/p4c/tree/main/backends/bmv2/portable_common) contains reusable components common to both the `psa_switch` and `pna_nic` backends.
+
+|      **File Name**          |      **Description**     |
+|-----------------------------|--------------------------|
+| **midend.h, midend.cpp**    | Defines the common mid-end processing of both the `psa_switch` and `pna_nic` backends.    |
+| **options.h, options.cpp**  | Defines the common command-line options of both the `psa_switch` and `pna_nic` backends.   |
+| **portable.h, portable.cpp**| Defines common functionalities that generate representations of P4 programs.   |
+| **portableProgramStructure.h, portableProgramStructure.cpp** | Defines and implements the common program structure of both the `psa_switch` and `pna_nic` backends. _These files are located in the `backends/common` directory. |
diff --git a/backends/p4test/README.md b/backends/p4test/README.md
@@ -18,4 +18,37 @@ Refer to the full page here: [P4test Backend](https://p4lang.github.io/p4c/p4tes
 <!--!
 [TOC]
 -->
-This is a "fake" backend, whose sole purpose is to test the P4-16 front-end.
+The P4Test Backend is a tool designed for testing and debugging P4
+programs. It supports both the P4-14 and P4-16 standards and can
+translate P4 code from one version to another. Additionally, it
+provides a syntax checker for P4 code, enabling the verification of 
+the correctness of your P4 programs.
+
+## Auto-translate P4-14 source to P4-16 source:
+You can automatically translate a P4-14 program to a P4-16 program
+using the following command:
+```bash
+p4test --std p4-14 my-p4-14-prog.p4 --pp auto-translated-p4-16-prog.p4
+```
+
+This command takes the P4-14 program (my-p4-14-prog.p4) and generates
+a corresponding P4-16 program (auto-translated-p4-16-prog.p4).
+
+
+## Check syntax of P4-16 or P4-14 source code
+The P4test Backend can check the syntax of P4 programs without being
+restricted by any specific compiler back end. This is useful for
+ensuring that your P4 code is syntactically correct.
+
+For P4-16 code: 
+```bash
+p4test my-p4-16-prog.p4
+```
+
+For P4-14 code: 
+```bash
+p4test --std p4-14 my-p4-14-prog.p4
+```
+
+These commands will output error and/or warning messages if there 
+are any issues with the syntax of your P4 code.
diff --git a/backends/p4tools/CONTRIBUTORS.md b/backends/p4tools/CONTRIBUTORS.md
@@ -11,14 +11,13 @@ P4Testgen is a test oracle for the P4 language. Given a P4_16 program and a spec
 
 # Core Developers
 
-* @fruffy (NYU)
-* @liujed (Akita Software)
-* @pkotikal (Intel)
-* @vhavel (Intel)
-* @hannelita (Intel)
-* @vladyslav-dubina (Litsoft)
-* @VolodymyrPeschanenko (Litsoft)
-* @jnfoster (Cornell and Intel)
+* [@fruffy (NYU)](https://github.com/fruffy)
+* [@liujed (Akita Software)](https://github.com/liujed)
+* [@vhavel (Intel)](https://github.com/vhavel)
+* [@hannelita (Intel)](https://github.com/hannelita)
+* [@vladyslav-dubina (Litsoft)](https://github.com/vladyslav-dubina)
+* [@VolodymyrPeschanenko (Litsoft)](https://github.com/VolodymyrPeschanenko)
+* [@jnfoster (Cornell and Intel)](https://github.com/jnfoster)
 
 # History
 

diff --git a/docs/IR.md b/docs/IR.md
@@ -272,17 +272,11 @@ method is not declared in the .def file, a standard definition (based on the fie
 declared in the class) will be created.  In this way, *most* classes can avoid including
 this boilerplate code in the .def file.
 
-#### `IR::Node`
-
-This is the ultimate abstract base class of all IR nodes and contains only a small amount of
-data for error reporting and debugging.  In general, this info is NEVER compared for
-equality (so subclasses should never call Node::operator==`) as Nodes that differ only
-in this information should be considered equal, and not require cloning or the IR tree.
-
-#### `IR::Vector<T>`
-
-This template class holds a vector of (`const`) pointers to nodes of a particular `IR::Node`
-subclass.
+## Classes
+| **Class**      | **Description**  |
+|----------------|------------------|
+| `IR::Node`     | This is the ultimate abstract base class of all IR nodes and contains only a small amount of data for error reporting and debugging.  In general, this info is NEVER compared for equality (so subclasses should never call `Node::operator==`) as Nodes that differ only in this information should be considered equal, and not require cloning or the IR tree.   |
+| `IR::Vector<T>`| This template class holds a vector of (`const`) pointers to nodes of a particular `IR::Node` subclass. |
 
 <!--!
 \include{doc} "../ir/README.md" 

diff --git a/docs/doxygen/doxygen.cfg b/docs/doxygen/doxygen.cfg
@@ -1036,7 +1036,6 @@ RECURSIVE              = YES
 # run.
 
 EXCLUDE                = ../../frontends/p4/README.md \
-                         ../../midend/README.md \
                          ./awesome_css \
                          ./build \
                          ../../backends/p4tools/cmake/README.md \

diff --git a/frontends/README.md b/frontends/README.md
@@ -14,3 +14,18 @@ Refer to the full page here: [Frontend](https://p4lang.github.io/p4c/frontend.ht
 <!--!
 \endinternal
 -->
+The front end of the P4 compiler translates P4 source code into the P4 Intermediate Representation (P4C-IR), performs type-checking, and ensures that the P4 program complies with the P4 specification. The front end also applies architecture-independent optimizations such as Strength Reduction, Constant Folding, Inlining, or Dead-Code Elimination. This is a non-exhaustive list of passes:
+
+- **Program Parsing:** Converts the P4 source code into an Abstract Syntax Tree (AST).
+- **Validation:** Checks the program against P4 language rules and constraints to ensure it is valid.
+- **Name Resolution:** Resolves all identifiers, such as variables and functions, to their declarations.
+- **Type Checking/Inference:** Uses the Hindley-Milner type inference algorithm to ensure that all types are correctly assigned and compatible.
+- **Making Semantics Explicit:** Ensures the program's semantics, such as the order of side effects, are clearly defined and explicit.
+## Optimization Tasks
+The front-end also performs some optimization-related tasks, including:
+- **Inlining:** Replaces function calls with the function body to reduce overhead.
+- **Compile-Time Evaluation and Specialization:** Evaluates expressions and specializes code at compile time for efficiency.
+- **Conversion to P4 Source:** Converts the AST back to P4 source code if needed.
+- **Deparser Inference (for P4_14 programs):** Automatically infers deparser logic for P4_14 programs.
+
+After completing these passes, the front-end generates the control-plane API, which is essential for the interaction between the control plane and the data plane.
diff --git a/ir/README.md b/ir/README.md
@@ -4,42 +4,20 @@ This README is integrated as a subsection of the "P4C Intermediate Representatio
 
 Refer to the specific section here: [P4C Intermediate Representation (IR) Classes - Subsection](https://p4lang.github.io/p4c/intermediate_representation_ir.html#p4c-intermediate-representation-ir-classes)
 -->
-# P4C Intermediate Representation (IR) Classes {#irdefs}
-
-The IR classes are automatically generated by tools/ir-generator
-from \*.def files.  The .def files contain class definitions with
-boilerplate removed, which the ir-generator generates.
-
-##### ir.h
-  Top level include file that just includes everything else.  Code outside this
-  folder generally just includes this file.
-
-##### ir-inline.h ir-tree-macros.h ir-util.h
-  IR support stuff.  `ir-inline.h` has inline methods for things in header
-  files that can't be defined until after other header files are included.
-  `ir-tree-macros.h` has macros for generating code referring to all IR
-  classes, used by the visitors.
-
-##### node.h node.cpp
-  `IR::Node` base class.
-
-##### id.h
-  Defines the `ID` struct, which is not a standalone IR class, but is used
-  in many places in IR classes, representing an identifier with associated
-  source location (for error reporting).
-
-##### ir.def ir.cpp
-   Miscelaneous front-end IR classes.
-
-##### v1.def, v1.cpp
-   IR classes only needed to process P4 v1.0 / v1.1 programs
-
-##### expression.def expression.cpp
-  IR classes related to expressions.  The `Expression` abstract class is
-  base for all expressions, and contains a `type` field.  Abstract subclasses
-  include `Operation`, `Unary`, `Binary`, and `Trinary`, with concrete
-  subclasses:
 
+# P4C Intermediate Representation (P4C-IR) Classes 
+The IR classes are automatically generated by `tools/ir-generator` from `*.def` files. The `.def` files contain class definitions with boilerplate removed, which the `ir-generator` generates.
+
+| **File**     | **Description**  |
+|--------------|------------------|
+| `ir.h`       | Top-level include file that includes everything else. Code outside this folder generally just includes this file. |
+| `ir-inline.h`, `ir-tree-macros.h`, `ir-util.h` | IR support files. `ir-inline.h` contains inline methods for header files that can't be defined until after other headers are included. `ir-tree-macros.h` has macros for generating code referring to all IR classes, used by the visitors.  |
+| `node.h`, `node.cpp`    | `IR::Node` base class.   |
+| `id.h`      | Defines the `ID` struct, which is not a standalone IR class but is used in many places in IR classes, representing an identifier with associated source location (for error reporting). |
+| `ir.def`, `ir.cpp`| Miscellaneous front-end IR classes.|
+| `v1.def`, `v1.cpp` | IR classes only needed to process P4 v1.0 / v1.1 programs.|
+| `expression.def`, `expression.cpp` | IR classes related to expressions. The `Expression` abstract class is the base for all expressions and contains a `type` field. Subclasses include `Operation`, `Unary`, `Binary`, and `Ternary`. **Concrete subclasses are detailed as follows:** |
+```
         Expression
         +-- Operation
         |   +-- Operation_Unary
@@ -55,44 +33,16 @@ boilerplate removed, which the ir-generator generates.
         |   |   \-- Slice, Mux
         |   \-- Primitive
         \-- Constant, ...
+```
+
+| **File**     | **Description**  |
+|--------------|------------------|
+| `typedecl.def`, `type.cpp`  | IR subclasses related to types and declarations.|
+| `namemap.h`  | `NameMap` template, which holds a set of named IR objects and supports lookups by name. `NameMap` supports transforms that return null or additional `NameMap` objects for IR objects in the `NameMap` to modify the `NameMap`. |
+| `vector.h`| `Vector` template, which holds a vector of IR objects. It is a subclass of `IR::Node` with traversal code and automatically flattens any sub-`Vector` objects and removes nulls when transforms on elements of the vector return them.              |
+| `indexed_vector.h`  | `IndexedVector`: Contains a `Vector` and also an index mapping cstrings to `IDeclarations` for all objects in the vector that are `IDeclarations`. |
+| `dbprint.h`, `dbprint.cpp`, `dbprint-expression.cpp`, `dbprint-p4.cpp` | Debug printing routines. Most IR classes declare a `dbprint` method, defined here. The header contains flags and support that `dbprint` methods use to communicate formatting information (indentation, precedence, and format mode). |
+| `std.h`| Using directives for frequently used `std::` classes. `std::vector` is wrapped with bounds-checking for all indexed accesses. |
+| `visitor.h`, `visitor.cpp` | `Visitor` base class and subclass definitions, including `Inspector`, `Modifier`, `Transform`, `ControlFlowVisitor`, `Backtrack`, and `P4WriteContext` mixin interfaces. |
+| `pass_manager.h`, `pass_manager.cpp` | `PassManager` subclass (of `Visitor`) that manages an arbitrary sequence of `Visitor`s and handles backtracking between passes. |
 
-##### typedecl.def type.cpp
-  IR subclasses related to types and declarations.
-
-##### namemap.h
-  IR subclass template `NameMap`, which holds a set of named IR objects and
-  supports lookups by name.  `NameMap` supports transforms that return null or
-  additional `NameMap` objects for IR objects in the `NameMap` to modify the
-  `NameMap`.
-
-##### vector.h
-  IR subclass template `Vector`, which holds a vector of IR objects.
-  This is largely equivalent to a `vector`, except that it is a subclass
-  of `IR::Node` so it can be included in an IR tree as a first-class
-  member, with its own traversal code (visitor subclass preorder and
-  postorder functions).  Automatically flattens any sub-`Vector` objects
-  and removes null when transforms on elements of the vector return them.
-
-###### indexed_vector.h
-  IndexedVector: contains a Vector and also an index mapping cstrings
-  to IDeclarations for all objects in the vector that are IDeclarations.
-
-##### dbprint.h dbprint.cpp dbprint-expression.cpp dbprint-p4.cpp
-  Debug printing routines.  Most IR classes declared a `dbprint` method,
-  which are defined here.  The header contains flags and support that
-  dbprint methods use to communicate formatting information (indentation,
-  precendence, and format mode).
-
-##### std.h
-  using directives for a bunch of `std::` classes that are heavily used in
-  the code.  `std::vector` is instead wrapped (as `vector`) with a version
-  that automatically uses bounds-checking for *all* indexed accesses.
-
-##### visitor.h visitor.cpp
-  `Visitor` base class, and `Inspector`, `Modifier`, and `Transform` subclass
-  definitions, along with `ControlFlowVisitor`, `Backtrack` and `P4WriteContext`
-  mixin interfaces.
-
-##### pass\_manager.h pass\_manager.cpp
-  `PassManager` subclass (of `Visitor`) which manages an arbitrary sequence of
-  `Visitor`s, and handles backtracking between passes.