From c9fe41c4e2631d4d19817147b0295c07acb2a034 Mon Sep 17 00:00:00 2001 From: Adarsh Rawat Date: Mon, 19 Aug 2024 22:04:33 +0530 Subject: [PATCH] Docs : Content Organization and Documentation Updates (#4850) * Create Subsections of related topics Signed-off-by: Adarsh * Remove Revision History Signed-off-by: Adarsh * Exclude Subsections from generated Documentation Signed-off-by: Adarsh * Remove: deprecated Section from generated docs Signed-off-by: Adarsh * Disable Todo list Signed-off-by: Adarsh * Docs : Hide Namespace and Classes section from output Signed-off-by: Adarsh * Merge P4C Overview with P4C root README Signed-off-by: Adarsh * Minor Fix : missing "`" in directory structure Signed-off-by: Adarsh * Remove Revision History Signed-off-by: Adarsh * Merge P4C Overview with P4C root README Signed-off-by: Adarsh * Disable Auto Link support for classes/namespaces Signed-off-by: Adarsh * Merge "Common P4C Utility Functions" as a subsection of "P4C" Page Signed-off-by: Adarsh * Convert file descriptions to Markdown table format in BMv2 "pna_nic" Backend Signed-off-by: Adarsh * Remove Revision History Signed-off-by: Adarsh * Merge P4C Overview with P4C root README Signed-off-by: Adarsh * Remove Revision History Signed-off-by: Adarsh * Merge P4C Overview with P4C root README Signed-off-by: Adarsh * Content for P4test Backend Signed-off-by: Adarsh * Refactor : Organize `portable_common` directory file descriptions Organize `portable_common` directory file descriptions into a table format Signed-off-by: Adarsh * Hide Doxygen Commands from GitHub Markdown render Using the New Doxygen comment style in v1.12.0 i.e. `` For details - https://github.com/p4lang/p4c/pull/4861 Signed-off-by: Adarsh * Create Subsections of related topics Signed-off-by: Adarsh * Docs : Hide Namespace and Classes section from output Signed-off-by: Adarsh * Merge P4C Overview with P4C root README Signed-off-by: Adarsh * Remove Revision History Signed-off-by: Adarsh * Merge P4C Overview with P4C root README Signed-off-by: Adarsh * Content for P4test Backend Signed-off-by: Adarsh * Fix : removed extra Command Signed-off-by: Adarsh * Organize `IR` Classes descriptions into a table format Signed-off-by: Adarsh * chore: Add TOC to content-rich pages Signed-off-by: Adarsh * Remove TOC from Changelogs Signed-off-by: Adarsh * Exclude GitHub markdown TOC from Doxygen output Signed-off-by: Adarsh * Highlight sample backends in P4C with a dedicated heading Signed-off-by: Adarsh * Merged: BMv2 "pna_nic" Backend into Behavioral Model Backend Signed-off-by: Adarsh * Merge P4C IR Classes into IR Page Signed-off-by: Adarsh * Change the top of tree view from "P4C" -> "P4 Compiler Documentation (P4C)" Signed-off-by: Adarsh * Change root page heading "P4C" -> "Getting Started" Signed-off-by: Adarsh * Move changelogs to the end of Side bar Signed-off-by: Adarsh * Improve Getting started page heading Signed-off-by: Adarsh * Merge "portable_common" section under "bmv2" Signed-off-by: Adarsh * Minor formatting Fixes Signed-off-by: Adarsh * Minor command fix Signed-off-by: Adarsh * Fix: Broken Table structure in Doxygen output Signed-off-by: Adarsh * Refactor : Page headings Signed-off-by: Adarsh * Refactor : Ordering of backends Signed-off-by: Adarsh * Enable Nice URL for generated docs Current default doxygen URL config Output- https://p4lang.github.io/p4c/md__2home_2runner_2work_2p4c_2p4c_2backends_2dpdk_2_r_e_a_d_m_e.html Updated - https://p4lang.github.io/p4c/dpdk_backend.html Signed-off-by: Adarsh * Doc: Add inclusion notes to Documented Markdown files - Added comments to indicate whether each README is included as a standalone page, a subsection, or not included in the P4 compiler documentation. - Provided specific links to relevant sections or pages within the documentation. Signed-off-by: Adarsh * Docs: Add remaining documentation inclusion notes Signed-off-by: Adarsh * Add GitHub profile links for Core developers of p4tools Compatible with GitHub and Doxygen Signed-off-by: Adarsh * Fix: formatting of inclusion note Signed-off-by: Adarsh * Docs: Side bar grouping of backends Signed-off-by: Adarsh * Add Introduction for Frontend and Midend Signed-off-by: Adarsh * Update lib/README.md Signed-off-by: Adarsh Co-authored-by: Fabian Ruffy <5960321+fruffy@users.noreply.github.com> Signed-off-by: Adarsh Rawat * Revert: Changes that are migrated to PR #4876 Signed-off-by: Adarsh --------- Signed-off-by: Adarsh Signed-off-by: Adarsh Rawat Co-authored-by: Fabian Ruffy <5960321+fruffy@users.noreply.github.com> --- CHANGELOG.md | 18 ++++- CONTRIBUTING.md | 23 +++++- README.md | 29 ++++++- backends/bmv2/README.md | 26 ++++++ backends/bmv2/pna_nic/README.md | 11 ++- backends/bmv2/portable_common/README.md | 8 +- backends/dpdk/README.md | 21 ++++- backends/ebpf/README.md | 22 +++++ backends/ebpf/psa/README.md | 9 ++- backends/graphs/README.md | 19 ++++- backends/p4fmt/README.md | 19 ++++- backends/p4test/README.md | 20 ++++- backends/p4tools/CONTRIBUTORS.md | 7 ++ backends/p4tools/README.md | 37 +++++++-- backends/p4tools/modules/smith/README.md | 24 ++++++ backends/p4tools/modules/testgen/README.md | 31 +++++++ .../modules/testgen/benchmarks/README.md | 8 +- .../testgen/targets/bmv2/test/README.md | 6 ++ backends/tc/README.md | 22 ++++- backends/ubpf/README.md | 33 ++++++-- backends/ubpf/docs/EXAMPLES.md | 17 +++- backends/ubpf/tests/README.md | 12 ++- docs/CodingStandardPhilosophy.md | 7 ++ docs/IR.md | 26 +++++- docs/README.md | 21 ++++- docs/doxygen/01_overview.md | 7 ++ docs/doxygen/Doxymain.md | 15 +++- docs/doxygen/doxygen.cfg | 81 ++++++++++--------- docs/doxygen/p4c_header.html | 2 +- docs/doxygen/p4c_layout.xml | 24 +++++- frontends/README.md | 16 ++++ ir/README.md | 8 +- lib/README.md | 12 ++- midend/README.md | 18 +++++ 34 files changed, 571 insertions(+), 88 deletions(-) create mode 100644 frontends/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 8fbc9b43a8a..b9c893c177b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,20 @@ -# Changelog + + + +# Releases + + ## Semantic Versioning We follow a monthly release cadence. Our versioning scheme is as follows: - **Major.Minor.Patch** versions align with the P4 specification. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ad2e70bceeb..1db8ce7dd35 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,22 @@ + + + # Contribute to the P4 Compiler Project - + + Thank you for considering contributing to the P4 Compiler Project (P4C)! Your contributions are valuable and help improve the project for everyone. Before getting started, please take a moment to review the following guidelines. ## Contributing License @@ -37,3 +54,7 @@ If you encounter any issues or have suggestions for improvement, please [open an We welcome feature requests! Please open an issue and provide as much detail as possible about the requested feature and its use case. Happy coding! + + diff --git a/README.md b/README.md index 7e322b46789..6f62c275aa0 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,16 @@ + + # P4C + + [![Main Build](https://github.com/p4lang/p4c/actions/workflows/ci-test-debian.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-test-debian.yml) [![Main Build](https://github.com/p4lang/p4c/actions/workflows/ci-test-fedora.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-test-fedora.yml) [![Main Build](https://github.com/p4lang/p4c/actions/workflows/ci-test-mac.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-test-mac.yml) @@ -6,6 +18,10 @@ [![Validation](https://github.com/p4lang/p4c/actions/workflows/ci-validation-nightly.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-validation-nightly.yml) [![Docker Container](https://github.com/p4lang/p4c/actions/workflows/ci-container-image.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-container-image.yml) + +* [Sample Backends in P4C](#sample-backends-in-p4c) * [Getting started](#getting-started) * [Installing packaged versions of P4C](#installing-packaged-versions-of-p4c) * [Installing P4C from source](#installing-p4c-from-source) @@ -27,7 +43,9 @@ * [How to Contribute](#how-to-contribute) * [P4 Compiler Onboarding](#p4-compiler-onboarding) * [Contact](#contact) - + P4C is a reference compiler for the P4 programming language. It supports both P4-14 and P4-16; you can find more information about P4 [here](http://p4.org) and the specifications for both versions of the language @@ -41,7 +59,11 @@ P4C is modular; it provides a standard frontend and midend which can be combined with a target-specific backend to create a complete P4 compiler. The goal is to make adding new backends easy. -The code contains seven sample backends: + +## Sample Backends in P4C +P4C includes seven sample backends, catering to different target architectures and use cases: * p4c-bm2-ss: can be used to target the P4 `simple_switch` written using the [BMv2 behavioral model](https://github.com/p4lang/behavioral-model), * p4c-dpdk: can be used to target the [DPDK software switch (SWX) pipeline](https://doc.dpdk.org/guides/rel_notes/release_20_11.html), @@ -652,6 +674,9 @@ install (FILES ${CMAKE_CURRENT_SOURCE_DIR}/driver/p4c.mybackend.cfg DESTINATION ${P4C_ARTIFACTS_OUTPUT_DIRECTORY}/p4c_src) ``` + ## Known issues Issues with the compiler are tracked on diff --git a/backends/bmv2/README.md b/backends/bmv2/README.md index cff45c46b1b..5a0e0322013 100644 --- a/backends/bmv2/README.md +++ b/backends/bmv2/README.md @@ -1,5 +1,23 @@ + + + # Behavioral Model Backend + + This is a back-end which generates code for the [Behavioral Model version 2 (BMv2)](https://github.com/p4lang/behavioral-model.git). It can accept either P4_14 programs, or P4_16 programs written for the @@ -41,3 +59,11 @@ controlc c() { - user-defined extern types / methods which are not defined in `v1model.p4` - stacks of header unions + + + + diff --git a/backends/bmv2/pna_nic/README.md b/backends/bmv2/pna_nic/README.md index c27a39ca856..8d6001ed543 100644 --- a/backends/bmv2/pna_nic/README.md +++ b/backends/bmv2/pna_nic/README.md @@ -1,6 +1,13 @@ + + # BMv2 "pna_nic" Backend -This directory contains components specific to the BMv2's PNA NIC (Portable NIC Architecture) backend in the P4C compiler. The files in this folder depend on each other, on the files in the `bmv2/common` and `portable_common` directories. Most of the classes are inherited from the classes in the `portable_common` directory. +The [`backends/bmv2/pna_nic` directory](https://github.com/p4lang/p4c/tree/main/backends/bmv2/pna_nic) contains components specific to the BMv2's PNA NIC (Portable NIC Architecture) backend in the P4C compiler. The files in this folder depend on each other, on the files in the `bmv2/common` and `portable_common` directories. Most of the classes are inherited from the classes in the `portable_common` directory. Output Binary: `p4c-bm2-pna` @@ -26,4 +33,4 @@ Sets up compilation environment, integrates various components, and executes the ##### version.h.cmake -Defines macros containing version information for the PNA NIC compiler. \ No newline at end of file +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 index 4a0f22cfafe..91779137197 100644 --- a/backends/bmv2/portable_common/README.md +++ b/backends/bmv2/portable_common/README.md @@ -1,3 +1,9 @@ + # portable_common This directory contains reusable components common to both the `psa_switch` and `pna_nic` backends. @@ -18,4 +24,4 @@ The files `portableProgramStructure.h` and `portableProgramStructure.cpp` are in ### portableProgramStructure.h, portableProgramStructure.cpp -Defines and implements the common program structure of both the `psa_switch` and `pna_nic` backends. \ No newline at end of file +Defines and implements the common program structure of both the `psa_switch` and `pna_nic` backends. diff --git a/backends/dpdk/README.md b/backends/dpdk/README.md index dcb1352ba98..26a7858f4f2 100644 --- a/backends/dpdk/README.md +++ b/backends/dpdk/README.md @@ -1,5 +1,22 @@ -# DPDK backend - + + + +# DPDK Backend + + The **p4c-dpdk** backend translates the P4-16 programs to DPDK API to configure the DPDK software switch (SWX) pipeline. DPDK introduced the SWX pipeline in the DPDK 20.11 LTS release. For more information, please refer to the [release note](https://doc.dpdk.org/guides/rel_notes/release_20_11.html). diff --git a/backends/ebpf/README.md b/backends/ebpf/README.md index ba95dcee530..0ee14ed370a 100644 --- a/backends/ebpf/README.md +++ b/backends/ebpf/README.md @@ -1,5 +1,23 @@ + + + # eBPF Backend + + The back-end accepts only P4_16 code written for the `ebpf_model.p4` or `xdp_model.p4` filter models. It generates C code that can be afterwards compiled into [eBPF (extended Berkeley Packet Filters)](https://en.wikipedia.org/wiki/Berkeley_Packet_Filter) using clang/llvm or @@ -414,3 +432,7 @@ clang -O2 -include C-EXTERN-FILE.c -target bpf -c OUTPUT.c -o OUTPUT.o ``` * The C extern function must not access BPF maps that are used to implement P4 tables and defined in the main C program generated from the P4 language. + + diff --git a/backends/ebpf/psa/README.md b/backends/ebpf/psa/README.md index d6c5541b6a7..d45fa482bb1 100644 --- a/backends/ebpf/psa/README.md +++ b/backends/ebpf/psa/README.md @@ -1,6 +1,13 @@ + + # PSA implementation for eBPF backend -This directory implements PSA (Portable Switch Architecture) for the eBPF backend. +The [`backends/ebpf/psa` directory](https://github.com/p4lang/p4c/tree/main/backends/ebpf/psa) implements PSA (Portable Switch Architecture) for the eBPF backend. # Prerequisites diff --git a/backends/graphs/README.md b/backends/graphs/README.md index 2658ac486a1..0bb45cc03fd 100644 --- a/backends/graphs/README.md +++ b/backends/graphs/README.md @@ -1,5 +1,22 @@ + + + # Graphs Backend - + + This backend produces visual representations of a P4 program as dot files. For now it supports the generation of graphs for top-level control and parser blocks, generation of fullGraph, which merges graphs for top-level program blocks and diff --git a/backends/p4fmt/README.md b/backends/p4fmt/README.md index 8e2aeb1e08a..57e9c1da181 100644 --- a/backends/p4fmt/README.md +++ b/backends/p4fmt/README.md @@ -1,5 +1,22 @@ + + + # p4fmt (P4 Formatter) - + + p4fmt is a WIP formatter for P4. It's in a highly experimental phase and, not yet stable/reliable for general use. Contributions and feedbacks from the community diff --git a/backends/p4test/README.md b/backends/p4test/README.md index b8870300b89..985af680667 100644 --- a/backends/p4test/README.md +++ b/backends/p4test/README.md @@ -1,3 +1,21 @@ + + + # P4test Backend + -This is a "fake" backend, whose sole purpose is to test the P4-16 front-end. + +This is a "fake" backend, whose sole purpose is to test the P4-16 front-end. \ No newline at end of file diff --git a/backends/p4tools/CONTRIBUTORS.md b/backends/p4tools/CONTRIBUTORS.md index a58f5218e8f..00ac66ab64a 100644 --- a/backends/p4tools/CONTRIBUTORS.md +++ b/backends/p4tools/CONTRIBUTORS.md @@ -1,3 +1,10 @@ + # P4Tools Contributors P4Testgen is a test oracle for the P4 language. Given a P4_16 program and a specification of the underlying architecture, it automatically generates a comprehensive set of input/output tests that can be executed to validate a target device. diff --git a/backends/p4tools/README.md b/backends/p4tools/README.md index dc5a5a3f155..89c6348c5dd 100644 --- a/backends/p4tools/README.md +++ b/backends/p4tools/README.md @@ -1,4 +1,29 @@ -# P4Tools - Testing Tools For P4 Targets + + + +# P4Tools + + + +P4Tools is a collection of tools that make testing P4 targets and programs a little easier. So far the platform supports the following tools and projects: + +- [P4Testgen](https://github.com/p4lang/p4c/tree/main/backends/p4tools/modules/testgen): An input-output test case generator for P4. + +- [P4Smith](https://github.com/p4lang/p4c/tree/main/backends/p4tools/modules/smith): A random P4 program generator in the spirit of Csmith. + ## Directory Structure @@ -15,13 +40,6 @@ p4tools └─ testgen ── P4Testgen: a test-case generator for P4 programs. ``` -## P4Tools -P4Tools is a collection of tools that make testing P4 targets and programs a little easier. So far the platform supports the following tools and projects: - -- [P4Testgen](https://github.com/p4lang/p4c/tree/main/backends/p4tools/modules/testgen): An input-output test case generator for P4. - -- [P4Smith](https://github.com/p4lang/p4c/tree/main/backends/p4tools/modules/smith): A random P4 program generator in the spirit of Csmith. - ## Building Please see the general installation instructions [here](https://github.com/p4lang/p4c#installing-p4c-from-source). P4Tools can be built using the following CMAKE configuration in the P4C repository. @@ -69,3 +87,6 @@ P4Tools in general follows the [P4C coding style](https://github.com/p4lang/p4c/ library of related classes. Multiple classes may be declared in a `.cpp` file. + diff --git a/backends/p4tools/modules/smith/README.md b/backends/p4tools/modules/smith/README.md index 41a74847c79..871e5a37fc5 100644 --- a/backends/p4tools/modules/smith/README.md +++ b/backends/p4tools/modules/smith/README.md @@ -1,7 +1,28 @@ + + + # P4Smith + + [![Status](https://github.com/p4lang/p4c/actions/workflows/ci-p4tools.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-p4tools.yml) + ## Table of Contents - [Installation](#installation) @@ -12,6 +33,9 @@ - [Contributing](#contributing) - [License](#license) + P4Smith is an extensible random P4 program generator in the spirit of [CSmith](https://en.wikipedia.org/wiki/Csmith). P4Smith generates random, but valid P4 programs for various P4 targets, for example the [v1model.p4](https://github.com/p4lang/behavioral-model/blob/main/docs/simple_switch.md) architecture on [BMv2](https://github.com/p4lang/behavioral-model) or `tna.p4` running on Tofino 1. P4Smiths generates programs that are valid according to the latest version of the (P4 specification)[https://p4.org/p4-spec/docs/P4-16-working-spec.html] or the restrictions of the specific target. ## Installation diff --git a/backends/p4tools/modules/testgen/README.md b/backends/p4tools/modules/testgen/README.md index d2c7fa30eb3..2c7390abb5c 100644 --- a/backends/p4tools/modules/testgen/README.md +++ b/backends/p4tools/modules/testgen/README.md @@ -1,7 +1,28 @@ + + + # P4Testgen + + [![Status](https://github.com/p4lang/p4c/actions/workflows/ci-p4tools.yml/badge.svg)](https://github.com/p4lang/p4c/actions/workflows/ci-p4tools.yml) + ## Table of Contents - [Installation](#installation) @@ -16,6 +37,9 @@ - [Contributing](#contributing) - [License](#license) + P4Testgen is an extensible [test oracle](https://en.wikipedia.org/wiki/Test_oracle) that uses symbolic execution to automatically generate input-output tests for P4 programs. P4Testgen is part of the P4Tools and P4C ecosystem. ## Features @@ -156,6 +180,12 @@ If you would like to cite this work please use this citation format: } ``` + + ## Contributing Contributions to P4Testgen in any form are welcome! Please follow the guidelines listed [here](https://github.com/p4lang/p4c/blob/main/CONTRIBUTING.md) to contribute. @@ -163,3 +193,4 @@ Contributions to P4Testgen in any form are welcome! Please follow the guidelines ## License This project is licensed under the Apache License 2.0. See the [LICENSE](https://github.com/p4lang/p4c/blob/main/backends/p4tools/LICENSE) file for details. + diff --git a/backends/p4tools/modules/testgen/benchmarks/README.md b/backends/p4tools/modules/testgen/benchmarks/README.md index f56e48c3a89..83bee7796f0 100644 --- a/backends/p4tools/modules/testgen/benchmarks/README.md +++ b/backends/p4tools/modules/testgen/benchmarks/README.md @@ -1,2 +1,8 @@ + # P4Testgen Benchmarks -This folder contains utility scripts to benchmark P4Testgen. `test_coverage.py` measures coverage of various path selection strategies. `plot.py` creates plots of the results. +The [`backends\p4tools\modules\testgen\benchmarks` folder](https://github.com/p4lang/p4c/tree/main/backends/p4tools/modules/testgen/benchmarks) contains utility scripts to benchmark P4Testgen. `test_coverage.py` measures coverage of various path selection strategies. `plot.py` creates plots of the results. diff --git a/backends/p4tools/modules/testgen/targets/bmv2/test/README.md b/backends/p4tools/modules/testgen/targets/bmv2/test/README.md index 2392c88dfc5..48dfaa49d74 100644 --- a/backends/p4tools/modules/testgen/targets/bmv2/test/README.md +++ b/backends/p4tools/modules/testgen/targets/bmv2/test/README.md @@ -1,3 +1,9 @@ + # P4Testgen BMv2 target tests ## CMake Files diff --git a/backends/tc/README.md b/backends/tc/README.md index 91fd465d421..e2be58a431c 100644 --- a/backends/tc/README.md +++ b/backends/tc/README.md @@ -1,5 +1,23 @@ -# TC backend - + + + +# TC Backend + + + TC backend aims to generate files for the P4TC implementation in Linux kernel (from 6.3.x version). P4TC is an implementation of the Programming Protocol-independent Packet Processors (P4) that is kernel based, building on top of Linux TC. For more info on P4TC, Please refer: diff --git a/backends/ubpf/README.md b/backends/ubpf/README.md index ef2a7fafd0e..309c8167274 100644 --- a/backends/ubpf/README.md +++ b/backends/ubpf/README.md @@ -1,5 +1,24 @@ -# Introduction to uBPF Backend - + + + + +# uBPF Backend + + + The **p4c-ubpf** compiler allows to translate P4 programs into the uBPF programs. We use the uBPF implementation provided by [the P4rt-OVS switch](https://github.com/Orange-OpenSource/p4rt-ovs). The uBPF VM is based on the open-source implementation provided by [IOVisor](https://github.com/iovisor/ubpf). @@ -70,6 +89,11 @@ Once the C program is generated it can be compiled using: The output file (`out.o`) can be injected to the uBPF VM. + + #### Custom C extern functions The P4 to uBPF compiler allows to define custom C extern functions and call them from P4 program as P4 action. @@ -86,8 +110,3 @@ to learn how to use this feature. Note that the C extern function written for `p Tomasz Osiński <tomasz.osinski2@orange.com> Mateusz Kossakowski <mateusz.kossakowski@orange.com> - - - - - diff --git a/backends/ubpf/docs/EXAMPLES.md b/backends/ubpf/docs/EXAMPLES.md index a6e4e6907ad..fd7bd732d3a 100644 --- a/backends/ubpf/docs/EXAMPLES.md +++ b/backends/ubpf/docs/EXAMPLES.md @@ -1,8 +1,23 @@ + # uBPF Backend test programs -This file contains description of the basic P4 programs, which were used to test the functionality of the P4-to-uBPF compiler. +This Section contains description of the basic P4 programs, which were used to test the functionality of the P4-to-uBPF compiler. All tests have been run on the [P4rt-OVS](https://github.com/Orange-OpenSource/p4rt-ovs) switch. + You can use [Vagrantfile](../tests/environment/Vagrantfile) to set up a test environment. + + Before any experiment the following commands need to be invoked: diff --git a/backends/ubpf/tests/README.md b/backends/ubpf/tests/README.md index 43f1cfd84f5..383512c5306 100644 --- a/backends/ubpf/tests/README.md +++ b/backends/ubpf/tests/README.md @@ -1,6 +1,10 @@ -# uBPF Backend testing + -# Steps to run tests +# uBPF Backend testing Tests use two VMs: - `switch` - on this VM we run PTF tests @@ -8,7 +12,9 @@ Tests use two VMs: **Note.** As P4rt-OVS (the test uBPF target) is built on top of DPDK the tests require to be run in virtual environment with two VMs (`generator` + `switch`). - + +## Steps to Run Tests: + 0. Install `Virtualbox` and `Vagrant` on you machine: `sudo apt install -y virtualbox vagrant` diff --git a/docs/CodingStandardPhilosophy.md b/docs/CodingStandardPhilosophy.md index cb6075345ba..4c2562a0f24 100644 --- a/docs/CodingStandardPhilosophy.md +++ b/docs/CodingStandardPhilosophy.md @@ -1,3 +1,10 @@ + + # Coding Standard When writing code in any language the most important consideration is diff --git a/docs/IR.md b/docs/IR.md index 09df06a7d0b..0a285766a12 100644 --- a/docs/IR.md +++ b/docs/IR.md @@ -1,5 +1,23 @@ -# P4 Compiler Intermediate representation - + + + +# P4C Intermediate Representation (IR) + + + ## Introduction This document outlines the design of the P4_16 compiler. @@ -265,3 +283,7 @@ in this information should be considered equal, and not require cloning or the I This template class holds a vector of (`const`) pointers to nodes of a particular `IR::Node` subclass. + + diff --git a/docs/README.md b/docs/README.md index 9463c901630..11a92a6d829 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,22 @@ -# Repository - + + + +# P4C Repository Organization + + This folder contains documentation for the P4_16 prototype compiler. The code and documentation are hosted in the [p4c repository](https://github.com/p4lang/p4c). diff --git a/docs/doxygen/01_overview.md b/docs/doxygen/01_overview.md index a590ac93f00..ff730a8a7f7 100644 --- a/docs/doxygen/01_overview.md +++ b/docs/doxygen/01_overview.md @@ -1,3 +1,10 @@ + + # Overview The P4C compiler is a compiler infrastructure for the P4 compiler designed with the following goals: diff --git a/docs/doxygen/Doxymain.md b/docs/doxygen/Doxymain.md index 05f65f24d4c..545081f4a33 100644 --- a/docs/doxygen/Doxymain.md +++ b/docs/doxygen/Doxymain.md @@ -1,4 +1,11 @@ -# %P4 Compiler Documentation + @htmlonly
@@ -47,7 +54,7 @@ P4C is the official open-source reference compiler for the [P4](https://p4.org/)
- +
@@ -59,7 +66,7 @@ P4C is the official open-source reference compiler for the [P4](https://p4.org/)
- +
@@ -72,7 +79,7 @@ P4C is the official open-source reference compiler for the [P4](https://p4.org/)
- +

Contribute

diff --git a/docs/doxygen/doxygen.cfg b/docs/doxygen/doxygen.cfg index 204dd4b7e58..f8496bcb197 100644 --- a/docs/doxygen/doxygen.cfg +++ b/docs/doxygen/doxygen.cfg @@ -42,7 +42,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = P4C +PROJECT_NAME = P4 Compiler Documentation (P4C) # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -376,7 +376,7 @@ MARKDOWN_ID_STYLE = GITHUB # globally by setting AUTOLINK_SUPPORT to NO. # The default value is: YES. -AUTOLINK_SUPPORT = YES +AUTOLINK_SUPPORT = NO # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want # to include (a tag file for) the STL sources as input, then you should set this @@ -730,7 +730,7 @@ STRICT_PROTO_MATCHING = NO # list. This list is created by putting \todo commands in the documentation. # The default value is: YES. -GENERATE_TODOLIST = YES +GENERATE_TODOLIST = NO # The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test # list. This list is created by putting \test commands in the documentation. @@ -749,7 +749,7 @@ GENERATE_BUGLIST = YES # the documentation. # The default value is: YES. -GENERATE_DEPRECATEDLIST= YES +GENERATE_DEPRECATEDLIST= NO # The ENABLED_SECTIONS tag can be used to enable conditional documentation # sections, marked by \if ... \endif and \cond @@ -955,40 +955,30 @@ WARN_LOGFILE = p4c-doxygen-warn.log # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../../docs/README.md \ - ../../README.md \ - ../../docs/doxygen/00_revision_history.md \ - ../../docs/doxygen/01_overview.md \ - ../../docs/doxygen \ - ../../frontends \ - ../../midend \ - ../../lib/README.md \ - ../../lib \ - ../../docs/IR.md \ - ../../ir/README.md \ - ../../ir \ - ../../CHANGELOG.md \ - ../../backends/bmv2/README.md \ - ../../backends/dpdk/README.md \ - ../../backends/ebpf/README.md \ - ../../backends/ebpf/psa/README.md \ - ../../backends/graphs/README.md \ - ../../backends/p4fmt/README.md \ - ../../backends/p4test/README.md \ - ../../backends/p4tools/README.md \ - ../../backends/p4tools/CONTRIBUTORS.md \ - ../../backends/p4tools/modules/smith/README.md \ - ../../backends/p4tools/modules/testgen/README.md \ - ../../backends/p4tools/modules/testgen/benchmarks/README.md \ - ../../backends/p4tools/modules/testgen/targets/bmv2/test/README.md \ - ../../backends/tc/README.md \ - ../../backends/ubpf/README.md \ - ../../backends/ubpf/docs/EXAMPLES.md \ - ../../backends/ubpf/tests/README.md \ - ../../backends \ - ../../control-plane \ - ../../CONTRIBUTING.md \ - ../../docs/CodingStandardPhilosophy.md +INPUT = ../../docs/README.md \ + ../../frontends/README.md \ + ../../README.md \ + ../../docs/doxygen \ + ../../frontends \ + ../../midend \ + ../../lib \ + ../../docs/IR.md \ + ../../ir \ + ../../backends/bmv2/README.md \ + ../../backends/dpdk/README.md \ + ../../backends/ebpf/README.md \ + ../../backends/tc/README.md \ + ../../backends/ubpf/README.md \ + ../../backends/p4test/README.md \ + ../../backends/graphs/README.md \ + ../../backends/p4fmt/README.md \ + ../../backends/p4tools/README.md \ + ../../backends/p4tools/modules/smith/README.md \ + ../../backends/p4tools/modules/testgen/README.md \ + ../../backends \ + ../../control-plane \ + ../../CONTRIBUTING.md \ + ../../CHANGELOG.md \ # This tag can be used to specify the character encoding of the source files # that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses @@ -1052,7 +1042,20 @@ EXCLUDE = ../../frontends/p4/README.md \ ../../backends/p4tools/cmake/README.md \ ../../backends/p4tools/common/lib/README.md \ ../../backends/p4tools/common/README.md \ - ../../backends/p4tools/modules/testgen/lib/README.md + ../../backends/p4tools/modules/testgen/lib/README.md \ + ../../docs/doxygen/00_revision_history.md \ + ../../backends/ebpf/psa/README.md \ + ../../backends/p4tools/CONTRIBUTORS.md \ + ../../backends/p4tools/modules/testgen/benchmarks/README.md \ + ../../backends/p4tools/modules/testgen/targets/bmv2/test/README.md \ + ../../backends/ubpf/docs/EXAMPLES.md \ + ../../backends/ubpf/tests/README.md \ + ../../docs/doxygen/01_overview.md \ + ../../docs/doxygen/00_revision_history.md \ + ../../lib/README.md \ + ../../backends/bmv2/pna_nic/README.md \ + ../../ir/README.md \ + ../../backends/bmv2/portable_common/README.md \ # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded diff --git a/docs/doxygen/p4c_header.html b/docs/doxygen/p4c_header.html index ef9296224fa..d451e3a058c 100644 --- a/docs/doxygen/p4c_header.html +++ b/docs/doxygen/p4c_header.html @@ -67,7 +67,7 @@ -
$projectname $projectnumber +
P4C $projectnumber
$projectbrief
diff --git a/docs/doxygen/p4c_layout.xml b/docs/doxygen/p4c_layout.xml index f0bbba651bd..51e825dc5cd 100644 --- a/docs/doxygen/p4c_layout.xml +++ b/docs/doxygen/p4c_layout.xml @@ -4,8 +4,28 @@ - - + + + + + + + + + + + + + + + + + + + + + + diff --git a/frontends/README.md b/frontends/README.md new file mode 100644 index 00000000000..1fad4e4b140 --- /dev/null +++ b/frontends/README.md @@ -0,0 +1,16 @@ + + + +# Frontend + diff --git a/ir/README.md b/ir/README.md index 2b88d3b099f..08ceeedb4ca 100644 --- a/ir/README.md +++ b/ir/README.md @@ -1,3 +1,9 @@ + # P4C Intermediate Representation (IR) Classes {#irdefs} The IR classes are automatically generated by tools/ir-generator @@ -89,4 +95,4 @@ boilerplate removed, which the ir-generator generates. ##### pass\_manager.h pass\_manager.cpp `PassManager` subclass (of `Visitor`) which manages an arbitrary sequence of - `Visitor`s, and handles backtracking between passes. + `Visitor`s, and handles backtracking between passes. \ No newline at end of file diff --git a/lib/README.md b/lib/README.md index b1835a02f72..295fbbd7a9b 100644 --- a/lib/README.md +++ b/lib/README.md @@ -1,8 +1,15 @@ + + # Common P4C utility functions -This directory contains miscellaneous utilities that are generally useful +The [`lib` directory](https://github.com/p4lang/p4c/tree/main/lib) contains miscellaneous utilities that are generally useful and not specific to any part of the compiler. Most are not even compiler -specific. The files in this folder should only depend on each other; they +specific. The files in the `lib` folder should only depend on each other; they cannot depend on any other compiler files. ##### algorithm.h @@ -87,3 +94,4 @@ Conversion of various types to strings. ##### sourceCodeBuilder.h Support for emitting programs in source (works for P4 and C). + diff --git a/midend/README.md b/midend/README.md index ae716fc0929..bc7705643ec 100644 --- a/midend/README.md +++ b/midend/README.md @@ -1,3 +1,21 @@ + + + +# Midend + This folder contains passes which may be useful for implementing various mid-ends. These are linked as part of the front-end library. These passes are not used in the front-end, but are still largely architecture-independent. + +