From 158731258126651f2ca4d20e1e603c917352057f Mon Sep 17 00:00:00 2001
From: Yaman Umuroglu <maltanar@gmail.com>
Date: Thu, 10 Sep 2020 21:28:41 +0200
Subject: [PATCH] [Docs] update docs to reflect new hw build system
---
docs/finn/end_to_end_flow.rst | 3 +-
docs/finn/hw_build.rst | 100 ++++++++++++++++++++++++++++++++++
docs/finn/pynq_deploy.rst | 41 --------------
3 files changed, 101 insertions(+), 43 deletions(-)
create mode 100644 docs/finn/hw_build.rst
delete mode 100644 docs/finn/pynq_deploy.rst
diff --git a/docs/finn/end_to_end_flow.rst b/docs/finn/end_to_end_flow.rst
index fd6960a2f..529df57a5 100644
--- a/docs/finn/end_to_end_flow.rst
+++ b/docs/finn/end_to_end_flow.rst
@@ -20,6 +20,5 @@ For a more detailed overview about the different flow sections, please have a lo
brevitas_export
nw_prep
- vivado_synth
- pynq_deploy
+ hw_build
verification
diff --git a/docs/finn/hw_build.rst b/docs/finn/hw_build.rst
new file mode 100644
index 000000000..9f292a91c
--- /dev/null
+++ b/docs/finn/hw_build.rst
@@ -0,0 +1,100 @@
+.. _hw_build:
+
+*****************************
+Hardware Build and Deployment
+*****************************
+
+.. image:: /img/finn-hw-build.png
+ :scale: 70%
+ :align: center
+
+A model where all layers have been converted to HLS layers can be processed by
+FINN to build a bitfile targeting either a Zynq or Alveo system.
+
+Hardware Build
+==============
+
+Internally, the hardware build consists of the following steps:
+
+1. Driver generation
+2. DMA and DWC node insertion
+3. Partitioning for floorplanning
+4. FIFO insertion and IP generation
+5. Vivado/Vitis project generation and synthesis
+
+.. note:: **In previous FINN releases it was necessary to step through the
+individual sub-steps for hardware build manually by calling each transformation.
+The hardware build transformations `ZynqBuild` and `VitisBuild` now execute all
+necessary sub-transformations. For more control over the build process, the
+transformations listed below can still be called individually.
+**
+
+Driver Generation
+------------------
+
+To rapidly test the generated design on PYNQ platforms, FINN is capable of
+generating a Python driver for the given design. This driver packs/unpacks the
+input/output tensors in the expected format, then uses PYNQ APIs to initiate
+data movement and transfer back the results to the host CPU. The generation of
+the driver is done by transformation pass :py:mod:`finn.transformation.fpgadataflow.make_pynq_driver.MakePYNQDriver`.
+
+DMA and DWC Node Insertion
+---------------------------
+
+At this step, FINN will insert custom hardware-oriented ONNX nodes into the graph.
+These are DMA engines for moving data into and out of the accelerator (from DRAM),
+and data width converters between consecutive nodes where required.
+These steps are accomplished by calling the :py:mod:`finn.transformation.fpgadataflow.insert_iodma.InsertIODMA`
+and :py:mod:`finn.transformation.fpgadataflow.insert_dwc.InsertDWC` transformations,
+respectively.
+
+Partitioning for Floorplanning
+-------------------------------
+
+FINN will now partition the graph into several StreamingDataflowPartitions.
+This capability is most to facilitate floorplanning for future FINN releases
+and does not alter the functioning of the model itself. Each DMA node will be
+placed into its own partition. If no partition number attributes are specified,
+all the regular network nodes will become a single partition.
+This is accomplished by the :py:mod:`finn.transformation.fpgadataflow.floorplan.Floorplan`
+and :py:mod:`finn.transformation.fpgadataflow.create_dataflow_partition.CreateDataflowPartition`
+transformations.
+
+.. note:: **For Vitis, each partition will be compiled as a separate kernel,
+and linked together afterwards. For Zynq, each partition will become an IP
+block. **
+
+
+FIFO Insertion and IP Generation
+-------------------------------
+
+FINN will descend into each partition and insert FIFO nodes between streaming nodes,
+where FIFO depths dictated by the node attributes, using the :py:mod:`finn.transformation.fpgadataflow.insert_fifo.InsertFIFO`
+transformation.
+Afterwards, IP blocks will be created for each partition, which in turn contain the
+IP blocks for each layer stitched together. The layer-level IP blocks
+are generated by Vivado HLS, using a sequence of :py:mod:`finn.transformation.fpgadataflow.prepare_ip.PrepareIP`
+and :py:mod:`finn.transformation.fpgadataflow.hlssynth_ip.HLSSynthIP` transformations.
+The top-level IP blocks are generated in Vivado IPI, using the :py:mod:`finn.transformation.fpgadataflow.create_stitched_ip.CreateStitchedIP` transformation.
+
+Vivado/Vitis Project Generation and Synthesis
+---------------------------------------------
+
+The final step in the hardware build flow is to generate a Vivado (for Zynq) or Vitis (for Alveo)
+project, and run synthesis to generate a bitfile. This is done using the `MakeZYNQProject`
+transformation for Zynq, and the `VitisLink` transformation for Alveo.
+
+
+Deployment
+==========
+
+
+Deployment and Remote Execution
+-------------------------------
+
+The bitfile and the driver file(s) are copied to the PYNQ board and can be executed there using the *onnx_exec* function with the right *exec_mode* settings. For details please have a look at transformation :py:mod:`finn.transformation.fpgadataflow.make_deployment.DeployToPYNQ` and the execution function :py:mod:`finn.core.onnx_exec`.
+
+Throughput Test
+---------------
+
+FINN also offers the possibility to measure the network performance directly on the PYNQ board. This can be done by using :py:mod:`finn.core.throughput_test`. When running this function the metrics of the network are returned as dictionary.
diff --git a/docs/finn/pynq_deploy.rst b/docs/finn/pynq_deploy.rst
deleted file mode 100644
index ef36da9e7..000000000
--- a/docs/finn/pynq_deploy.rst
+++ /dev/null
@@ -1,41 +0,0 @@
-.. _pynq_deploy:
-
-***************
-PYNQ Deployment
-***************
-
-.. note:: **This website is currently under construction.**
-
-.. image:: /img/pynq-deploy.png
- :scale: 70%
- :align: center
-
-This chapter is about the hardware generation and deployment on PYNQ. If you need more information about PYNQ, please have a look at the `PYNQ website <https://pynq.readthedocs.io/en/v2.5.1/>`_.
-
-Create PYNQ Shell Project
-=========================
-
-To deploy the network on A PYNQ platform, it needs to be put inside an appropriate *shell*. This *shell* bridges the network with the interfaces the underlying system exposes. This can be done using the transformation MakePYNQProject, see :py:mod:`finn.transformation.fpgadataflow.make_pynq_proj.MakePYNQProject`.
-
-Test on Hardware
-================
-
-Synthesis, Place and Route
---------------------------
-
-After integrating the model into the PYNQ shell, Vivado *Synthesis, Place and Route* can be launched. The result is a bitfile which can be used for the PYNQ board. In FINN this can be done using a transformation pass. For details, please have a look at :py:mod:`finn.transformation.fpgadataflow.synth_pynq_proj.SynthPYNQProject`.
-
-Generate PYNQ runtime code
---------------------------
-
-Additionally, a Python code is necessary to execute the model on the board. This is done by transformation pass :py:mod:`finn.transformation.fpgadataflow.make_pynq_driver.MakePYNQDriver`.
-
-Deployment and Remote Execution
--------------------------------
-
-The bitfile and the driver file(s) are copied to the PYNQ board and can be executed there using the *onnx_exec* function with the right *exec_mode* settings. For details please have a look at transformation :py:mod:`finn.transformation.fpgadataflow.make_deployment.DeployToPYNQ` and the execution function :py:mod:`finn.core.onnx_exec`.
-
-Throughput Test
----------------
-
-Finn also offers the possibility to measure the network performance directly on the PYNQ board. This can be done by using :py:mod:`finn.core.throughput_test`. When running this function the metrics of the network are returned as dictionary.
--
GitLab