[PATCH v7 5/5] iFPGA: add document for iFPGA driver

["Xu, Rosen" <rosen.xu@intel.com>]

From: Figo Zhang <tianfei.zhang@intel.com>

add some introduction, motivation and usage for iFPGA driver.

Signed-off-by: Rosen Xu <rosen.xu@intel.com>
Signed-off-by: Figo Zhang <tianfei.zhang@intel.com>
---
 doc/guides/index.rst                   |   1 +
 doc/guides/rawdevs/ifpga_rawdev.rst    | 112 +++++++++++++++++++++++++++++++++
 doc/guides/rawdevs/index.rst           |  11 ++++
 doc/guides/rel_notes/release_18_05.rst |  13 ++++
 4 files changed, 137 insertions(+)
 create mode 100644 doc/guides/rawdevs/ifpga_rawdev.rst
 create mode 100644 doc/guides/rawdevs/index.rst

diff --git a/doc/guides/index.rst b/doc/guides/index.rst
index d60529d..a93baac 100644
--- a/doc/guides/index.rst
+++ b/doc/guides/index.rst
@@ -20,6 +20,7 @@ DPDK documentation
    eventdevs/index
    mempool/index
    platform/index
+   rawdevs/index
    contributing/index
    rel_notes/index
    faq/index
diff --git a/doc/guides/rawdevs/ifpga_rawdev.rst b/doc/guides/rawdevs/ifpga_rawdev.rst
new file mode 100644
index 0000000..3311586
--- /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 upgraded 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. Cooperated
+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 is taken by vdev_ifpga_cfg driver. Besides
+configuration, vdev_ifpga_cfg driver also hot plugin AFUs 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 Intel FPGA system,
+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.
\ No newline at end of file
diff --git a/doc/guides/rawdevs/index.rst b/doc/guides/rawdevs/index.rst
new file mode 100644
index 0000000..cdee371
--- /dev/null
+++ b/doc/guides/rawdevs/index.rst
@@ -0,0 +1,11 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Intel Corporation
+
+Raw Device Drivers
+=======================
+
+.. toctree::
+    :maxdepth: 2
+    :numbered:
+
+    ifpga_rawdev
\ No newline at end of file
diff --git a/doc/guides/rel_notes/release_18_05.rst b/doc/guides/rel_notes/release_18_05.rst
index 0ae61e8..77b96e2 100644
--- a/doc/guides/rel_notes/release_18_05.rst
+++ b/doc/guides/rel_notes/release_18_05.rst
@@ -164,6 +164,19 @@ New Features
   stats/xstats on shared memory from secondary process, and also pdump packets on
   those virtual devices.
 
+* **Added Ifpga Bus, a generic Intel FPGA Bus library.**
+
+  The Ifpga Bus library provides support for integrating any Intel FPGA device with
+  the DPDK framework. It provides Intel FPGA Partial Bit Stream AFU(Accelerated
+  Function Unit) scan and drivers prove.
+
+* **Added IFPGA(Intel FPGA) Rawdev Driver.**
+
+  Added a new Rawdev driver called IFPGA(Intel FPGA) Rawdev Driver, which cooperates
+  with OPAE(Open Programmable Acceleration Engine) share code provides common FPGA
+  management ops for FPGA operation.
+
+  See the :doc:`../rawdevs/ifpga_rawdev` programmer's guide for more details.
 
 API Changes
 -----------
-- 
1.8.3.1