[dpdk-dev] [PATCH v8 5/5] iFPGA: add document for iFPGA driver

[Shreyansh Jain]

Hi Rosen,

> -----Original Message-----
> From: Xu, Rosen [mailto:rosen.xu at intel.com]
> Sent: Sunday, May 6, 2018 2:11 PM
> To: dev at dpdk.org
> Cc: rosen.xu at intel.com; declan.doherty at intel.com;
> bruce.richardson at intel.com; Shreyansh Jain <shreyansh.jain at nxp.com>;
> ferruh.yigit at intel.com; konstantin.ananyev at intel.com;
> tianfei.zhang at intel.com; song.liu at intel.com; hao.wu at intel.com;
> gaetan.rivet at 6wind.com
> Subject: [PATCH v8 5/5] iFPGA: add document for iFPGA driver
> 
> From: Figo Zhang <tianfei.zhang at intel.com>
> 
> add some introduction, motivation and usage for iFPGA driver.
> 
> Signed-off-by: Rosen Xu <rosen.xu at intel.com>
> Signed-off-by: Figo Zhang <tianfei.zhang at intel.com>
> ---
>  doc/guides/rawdevs/ifpga_rawdev.rst    | 112
> +++++++++++++++++++++++++++++++++
>  doc/guides/rel_notes/release_18_05.rst |  13 ++++
>  2 files changed, 125 insertions(+)
>  create mode 100644 doc/guides/rawdevs/ifpga_rawdev.rst
> 
> diff --git a/doc/guides/rawdevs/ifpga_rawdev.rst
> b/doc/guides/rawdevs/ifpga_rawdev.rst
> new file mode 100644
> index 0000000..37ae4cc
> --- /dev/null
> +++ b/doc/guides/rawdevs/ifpga_rawdev.rst
> @@ -0,0 +1,112 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2018 Intel Corporation.
> +
> +IFPGA Rawdev Driver
> +======================
> +
> +FPGA is used more and more widely in Cloud and NFV, one primary reason
> is
> +that FPGA not only provides ASIC performance but also it's more
> flexible
> +than ASIC.
> +
> +FPGA uses Partial Reconfigure (PR) Parts of Bit Stream to achieve its
> +flexibility. That means one FPGA Device Bit Stream is divided into
> many Parts
> +of Bit Stream(each Part of Bit Stream is defined as AFU-Accelerated
> Function
> +Unit), and each AFU is a hardware acceleration unit which can be
> dynamically
> +reloaded respectively.
> +
> +By PR (Partial Reconfiguration) AFUs, one FPGA resources can be time-
> shared by
> +different users. FPGA hot upgrade and fault tolerance can be provided
> easily.
> +
> +The SW IFPGA Rawdev Driver (**ifpga_rawdev**) provides a Rawdev driver
> +that utilizes Intel FPGA Software Stack OPAE(Open Programmable
> Acceleration
> +Engine) for FPGA management.
> +
> +Implementation details
> +----------------------
> +
> +Each instance of IFPGA Rawdev Driver is probed by Intel FpgaDev. In
> coordination
> +with OPAE share code IFPGA Rawdev Driver provides common FPGA
> management ops
> +for FPGA operation, OPAE provides all following operations:
> +- FPGA PR (Partial Reconfiguration) management
> +- FPGA AFUs Identifying
> +- FPGA Thermal Management
> +- FPGA Power Management
> +- FPGA Performance reporting
> +- FPGA Remote Debug
> +
> +All configuration parameters are taken by vdev_ifpga_cfg driver.
> Besides
> +configuration, vdev_ifpga_cfg driver also hot plugs in IFPGA Bus.
> +
> +All of the AFUs of one FPGA may share same PCI BDF and AFUs scan
> depend on
> +IFPGA Rawdev Driver so IFPGA Bus takes AFU device scan and AFU drivers
> probe.
> +All AFU device driver bind to AFU device by its UUID (Universally
> Unique
> +Identifier).
> +
> +To avoid unnecessary code duplication and ensure maximum performance,
> +handling of AFU devices is left to different PMDs; all the design as
> +summarized by the following block diagram::
> +
> +     +---------------------------------------------------------------+
> +     |                       Application(s)                          |
> +     +----------------------------.----------------------------------+
> +                                  |
> +                                  |
> +     +----------------------------'----------------------------------+
> +     |                    DPDK Framework (APIs)                      |
> +     +----------|------------|--------.---------------------|--------+
> +               /              \                             |
> +              /                \                            |
> +     +-------'-------+  +-------'-------+          +--------'--------+
> +     |    Eth PMD    |  |   Crypto PMD  |          |                 |
> +     +-------.-------+  +-------.-------+          |                 |
> +             |                  |                  |                 |
> +             |                  |                  |                 |
> +     +-------'-------+  +-------'-------+          |      IFPGA      |
> +     |  Eth AFU Dev  |  |Crypto AFU Dev |          |  Rawdev Driver  |
> +     +-------.-------+  +-------.-------+          |(OPAE Share Code)|
> +             |                  |                  |                 |
> +             |                  |          Rawdev  |                 |
> +     +-------'------------------'-------+    Ops   |                 |
> +     |              IFPGA Bus           | -------->|                 |
> +     +-----------------.----------------+          +--------.--------+
> +                       |                                    |
> +         Hot-plugin -->|                                    |
> +                       |                                    |
> +     +-----------------'------------------+        +--------'--------+
> +     |        vdev_ifpga_cfg driver       |        |  Intel FpgaDev  |
> +     +------------------------------------+        +-----------------+
> +
> +Build options
> +-------------
> +
> +- ``CONFIG_RTE_LIBRTE_IFPGA_BUS`` (default ``y``)
> +
> +   Toggle compilation of IFPGA Bus library.
> +
> +- ``CONFIG_RTE_LIBRTE_IFPGA_RAWDEV`` (default ``y``)
> +
> +   Toggle compilation of the ``ifpga_rawdev`` driver.
> +
> +Run-time parameters
> +-------------------
> +
> +This driver is invoked automatically in systems added with Intel FPGA,
> +but PR and IFPGA Bus scan is trigged by command line using
> +``--vdev 'net_ifpga_cfg`` EAL option.
> +
> +The following device parameters are supported:
> +
> +- ``ifpga`` [string]
> +
> +  Provide a specific Intel FPGA device PCI BDF. Can be provided
> multiple
> +  times for additional instances.
> +
> +- ``port`` [int]
> +
> +  Each FPGA can provide many channels to PR AFU by software, each
> channels
> +  is identified by this parameter.
> +
> +- ``afu_bts`` [string]
> +
> +  If null, the AFU Bit Stream has been PR in FPGA, if not forces PR
> and
> +  identifies AFU Bit Stream file.

[...]

If you don't introduce this file into doc/guides/rawdevs/index.rst (like your v7), the doc index won't be generated.
I think you misunderstood my comment in [1] - I meant that you will have to rebase over CMDIF because it has already introduced the doc/guides/rawdevs/index.rst file. Your patch v7 was adding this file. It would have conflicted for Thomas' eventual merge.

[1] http://dpdk.org/ml/archives/dev/2018-May/100313.html

Unfortunately, you might have to send a v9 or maybe Thomas can take care of this while merging.