doc/guides/rawdevs/ifpga.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018-2022 Intel Corporation.
   3
   4 IFPGA Rawdev Driver
   5 ======================
   6
   7 FPGA is used more and more widely in Cloud and NFV, one primary reason is
   8 that FPGA not only provides ASIC performance but also it's more flexible
   9 than ASIC.
  10
  11 FPGA uses Partial Reconfigure (PR) Parts of Bit Stream to achieve its
  12 flexibility. That means one FPGA Device Bit Stream is divided into many Parts
  13 of Bit Stream(each Part of Bit Stream is defined as AFU-Accelerated Function
  14 Unit), and each AFU is a hardware acceleration unit which can be dynamically
  15 reloaded respectively.
  16
  17 By PR (Partial Reconfiguration) AFUs, one FPGA resources can be time-shared by
  18 different users. FPGA hot upgrade and fault tolerance can be provided easily.
  19
  20 The SW IFPGA Rawdev Driver (**ifpga_rawdev**) provides a Rawdev driver
  21 that utilizes Intel FPGA Software Stack OPAE(Open Programmable Acceleration
  22 Engine) for FPGA management.
  23
  24 Implementation details
  25 ----------------------
  26
  27 Each instance of IFPGA Rawdev Driver is probed by Intel FpgaDev. In coordination
  28 with OPAE share code IFPGA Rawdev Driver provides common FPGA management ops
  29 for FPGA operation, OPAE provides all following operations:
  30 - FPGA PR (Partial Reconfiguration) management
  31 - FPGA AFUs Identifying
  32 - FPGA Thermal Management
  33 - FPGA Power Management
  34 - FPGA Performance reporting
  35 - FPGA Remote Debug
  36
  37 All configuration parameters are taken by vdev_ifpga_cfg driver. Besides
  38 configuration, vdev_ifpga_cfg driver also hot plugs in IFPGA Bus.
  39
  40 All of the AFUs of one FPGA may share same PCI BDF and AFUs scan depend on
  41 IFPGA Rawdev Driver so IFPGA Bus takes AFU device scan and AFU drivers probe.
  42 All AFU device driver bind to AFU device by its UUID (Universally Unique
  43 Identifier).
  44
  45 To avoid unnecessary code duplication and ensure maximum performance,
  46 handling of AFU devices is left to different PMDs; all the design as
  47 summarized by the following block diagram::
  48
  49      +---------------------------------------------------------------+
  50      |                       Application(s)                          |
  51      +----------------------------.----------------------------------+
  52                                   |
  53                                   |
  54      +----------------------------'----------------------------------+
  55      |                    DPDK Framework (APIs)                      |
  56      +----------|------------|--------.---------------------|--------+
  57                /              \                             |
  58               /                \                            |
  59      +-------'-------+  +-------'-------+          +--------'--------+
  60      |    Eth PMD    |  |   Crypto PMD  |          |                 |
  61      +-------.-------+  +-------.-------+          |                 |
  62              |                  |                  |                 |
  63              |                  |                  |                 |
  64      +-------'-------+  +-------'-------+          |      IFPGA      |
  65      |  Eth AFU Dev  |  |Crypto AFU Dev |          |  Rawdev Driver  |
  66      +-------.-------+  +-------.-------+          |(OPAE Share Code)|
  67              |                  |                  |                 |
  68              |                  |          Rawdev  |                 |
  69      +-------'------------------'-------+    Ops   |                 |
  70      |              IFPGA Bus           | -------->|                 |
  71      +-----------------.----------------+          +--------.--------+
  72                        |                                    |
  73          Hot-plugin -->|                                    |
  74                        |                                    |
  75      +-----------------'------------------+        +--------'--------+
  76      |        vdev_ifpga_cfg driver       |        |  Intel FpgaDev  |
  77      +------------------------------------+        +-----------------+
  78
  79
  80 Run-time parameters
  81 -------------------
  82
  83 This driver is invoked automatically in systems added with Intel FPGA,
  84 but PR and IFPGA Bus scan is triggered by command line using
  85 ``--vdev 'ifpga_rawdev_cfg`` EAL option.
  86
  87 The following device parameters are supported:
  88
  89 - ``ifpga`` [string]
  90
  91   Provide a specific Intel FPGA device PCI BDF. Can be provided multiple
  92   times for additional instances.
  93
  94 - ``port`` [int]
  95
  96   Each FPGA can provide many channels to PR AFU by software, each channels
  97   is identified by this parameter.
  98
  99 - ``afu_bts`` [string]
 100
 101   If null, the AFU Bit Stream has been PR in FPGA, if not forces PR and
 102   identifies AFU Bit Stream file.
 103
 104
 105 Open FPGA Stack
 106 =====================
 107
 108 Open FPGA Stack (OFS) is a collection of RTL and open source software providing
 109 interfaces to access the instantiated RTL easily in an FPGA. OFS leverages the
 110 DFL for the implementation of the FPGA RTL design.
 111
 112 OFS designs allow for the arrangement of software interfaces across multiple
 113 PCIe endpoints. Some of these interfaces may be PFs defined in the static region
 114 that connect to interfaces in an IP that is loaded via Partial Reconfiguration (PR).
 115 And some of these interfaces may be VFs defined in the PR region that can be
 116 reconfigured by the end-user. Furthermore, these PFs/VFs may use DFLs such that
 117 features may be discovered and accessed in user space with the aid of a generic
 118 kernel driver like vfio-pci. The diagram below depicts an example design with one
 119 PF and two VFs. In this example, it will export the management functions via PF0
 120 and acceleration functions via VF0 and VF1, leverage VFIO to export the MMIO space
 121 to an application.::
 122
 123      +-----------------+  +-------------+  +------------+
 124      | FPGA Management |  |  DPDK App   |  |  User App  |
 125      |      App        |  |             |  |            |
 126      +--------+--------+  +------+------+  +-----+------+
 127               |                  |               |
 128      +--------+--------+  +------+------+        |
 129      |    IFPGA PMD    |  |   AFU PMD   |        |
 130      +--------+--------+  +------+------+        |
 131               |                  |               |
 132      +--------+------------------+---------------+------+
 133      |                VFIO-PCI                          |
 134      +--------+------------------+---------------+------+
 135               |                  |               |
 136      +--------+--------+  +------+------+  +-----+------+
 137      |       PF0       |  |   PF0_VF0   |  |  PF0_VF1   |
 138      +-----------------+  +-------------+  +------------+
 139
 140 As accelerators are specialized hardware, they are typically limited in the
 141 number installed in a given system. Many use cases require them to be shared
 142 across multiple software contexts or threads of software execution, either
 143 through partitioning of individual dedicated resources, or virtualization of
 144 shared resources. OFS provides several models to share the AFU resources via
 145 PR mechanism and hardware-based virtualization schemes.
 146
 147 1. Legacy model.
 148    With legacy model FPGA cards like Intel PAC N3000 or N5000, there is
 149    a notion that the boundary between the AFU and the shell is also the unit of
 150    PR for those FPGA platforms. This model is only able to handle a
 151    single context, because it only has one PR engine, and one PR region which
 152    has an associated Port device.
 153 2. Multiple VFs per PR slot.
 154    In this model, available AFU resources may allow instantiation of many VFs
 155    which have a dedicated PCIe function with their own dedicated MMIO space, or
 156    partition a region of MMIO space on a single PCIe function. Intel PAC N6000
 157    card has implemented this model.
 158    In this model, the AFU/PR slot was not connected to port device. For DFL's view,
 159    the Next_AFU pointer in FIU feature header of port device points to NULL in this
 160    model. On the other hand, each VF can start with an AFU feature header without
 161    being connected to a FIU Port feature header.
 162
 163 The VFs are created through the Linux kernel driver before we use them in DPDK.
 164
 165 OFS provides the diversity for accessing the AFU resource to RTL developer.
 166 An IP designer may choose to add more than one PF for interfacing with IP
 167 on the FPGA and choose different model to access the AFU resource.
 168
 169 There is one reference architecture design using the "Multiple VFs per PR slot"
 170 model for OFS as illustrated below. In this reference design, it exports the
 171 FPGA management functions via PF0. PF1 will bind with DPDK virtio driver
 172 presenting itself as a network interface to the application. PF2 will bind to the
 173 vfio-pci driver allowing the user space software to discover and interface
 174 with the specific workload like diagnostic test. It leverages AFU PMD driver to
 175 access the AFU resources in DPDK.::
 176
 177                               +----------------------+
 178                               |   PF/VF mux/demux    |
 179                               +--+--+-----+------+-+-+
 180                                  |  |     |      | |
 181         +------------------------+  |     |      | |
 182   PF0   |                 +---------+   +-+      | |
 183     +---+---+             |         +---+----+   | |
 184     |  DFH  |             |         |   DFH  |   | |
 185     +-------+       +-----+----+    +--------+   | |
 186     |  FME  |       |  VirtIO  |    |  Test  |   | |
 187     +---+---+       +----------+    +--------+   | |
 188         |                PF1            PF2      | |
 189         |                                        | |
 190         |                             +----------+ |
 191         |                             |           ++
 192         |                             |           |
 193         |                             | PF0_VF0   | PF0_VF1
 194         |           +-----------------+-----------+------------+
 195         |           |           +-----+-----------+--------+   |
 196         |           |           |     |           |        |   |
 197         |           | +------+  |  +--+ -+     +--+---+    |   |
 198         |           | | Port |  |  | DFH |     |  DFH |    |   |
 199         +-----------+ +------+  |  +-----+     +------+    |   |
 200                     |           |  | DEV |     |  DEV |    |   |
 201                     |           |  +-----+     +------+    |   |
 202                     |           |            PR Slot       |   |
 203                     |           +--------------------------+   |
 204                     | Port Gasket                              |
 205                     +------------------------------------------+