[dpdk-dev,v8,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/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
Comments
Hi Rosen,
> -----Original Message-----
> From: Xu, Rosen [mailto:rosen.xu@intel.com]
> Sent: Sunday, May 6, 2018 2:11 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 v8 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/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.
> -----Original Message-----
> From: Shreyansh Jain [mailto:shreyansh.jain@nxp.com]
> Sent: Sunday, May 6, 2018 7:54 PM
> To: Xu, Rosen <rosen.xu@intel.com>; dev@dpdk.org;
> thomas@monjalon.net
> Cc: Doherty, Declan <declan.doherty@intel.com>; Richardson, Bruce
> <bruce.richardson@intel.com>; Yigit, Ferruh <ferruh.yigit@intel.com>;
> Ananyev, Konstantin <konstantin.ananyev@intel.com>; Zhang, Tianfei
> <tianfei.zhang@intel.com>; Liu, Song <song.liu@intel.com>; Wu, Hao
> <hao.wu@intel.com>; gaetan.rivet@6wind.com
> Subject: RE: [PATCH v8 5/5] iFPGA: add document for iFPGA driver
>
> Hi Rosen,
>
> > -----Original Message-----
> > From: Xu, Rosen [mailto:rosen.xu@intel.com]
> > Sent: Sunday, May 6, 2018 2:11 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 v8 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/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.
Hi Shreyansh,
Do you mean we donot need this patch on V9.
Reset this patch when the CMDIF patches have merged into mainline, right?
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 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.
@@ -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
-----------