[dpdk-dev,v7,5/5] iFPGA: add document for iFPGA driver
Checks
Commit Message
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
Comments
Some trivial comments inlined which can be fixed in v8 easily:
> -----Original Message-----
> From: Xu, Rosen [mailto:rosen.xu@intel.com]
> Sent: Friday, May 4, 2018 7:41 PM
> To: dev@dpdk.org
> Cc: rosen.xu@intel.com; declan.doherty@intel.com;
> bruce.richardson@intel.com; Shreyansh Jain <shreyansh.jain@nxp.com>;
> ferruh.yigit@intel.com; konstantin.ananyev@intel.com;
> tianfei.zhang@intel.com; song.liu@intel.com; hao.wu@intel.com;
> gaetan.rivet@6wind.com
> Subject: [PATCH v7 5/5] iFPGA: add document for iFPGA driver
>
> 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
^^^^^^
Stream<space>(each ...
Same at couple of places in below text as well.
> 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
^^^^^^^^^^^^
Hot upgrade?
> 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
Or, maybe you can use 'In coordination with...' in pace of '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.
^^^^
are
> Besides
> +configuration, vdev_ifpga_cfg driver also hot plugin AFUs in IFPGA
^^^^^^^^^^^^
also hot plugs
> 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
^^^^^^^^^^^^^^
Maybe you meant "systems added with 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
This patch too would have to be rebased over cmdif patches as that already introduces the rawdevs/index.rst 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
@@ -20,6 +20,7 @@ DPDK documentation
eventdevs/index
mempool/index
platform/index
+ rawdevs/index
contributing/index
rel_notes/index
faq/index
new file mode 100644
@@ -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
new file mode 100644
@@ -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
@@ -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
-----------