Documentation/fpga/dfl.rst

   1 =================================================
   2 FPGA Device Feature List (DFL) Framework Overview
   3 =================================================
   4
   5 Authors:
   6
   7 - Enno Luebbers <enno.luebbers@intel.com>
   8 - Xiao Guangrong <guangrong.xiao@linux.intel.com>
   9 - Wu Hao <hao.wu@intel.com>
  10
  11 The Device Feature List (DFL) FPGA framework (and drivers according to
  12 this framework) hides the very details of low layer hardwares and provides
  13 unified interfaces to userspace. Applications could use these interfaces to
  14 configure, enumerate, open and access FPGA accelerators on platforms which
  15 implement the DFL in the device memory. Besides this, the DFL framework
  16 enables system level management functions such as FPGA reconfiguration.
  17
  18
  19 Device Feature List (DFL) Overview
  20 ==================================
  21 Device Feature List (DFL) defines a linked list of feature headers within the
  22 device MMIO space to provide an extensible way of adding features. Software can
  23 walk through these predefined data structures to enumerate FPGA features:
  24 FPGA Interface Unit (FIU), Accelerated Function Unit (AFU) and Private Features,
  25 as illustrated below::
  26
  27     Header            Header            Header            Header
  28  +----------+  +-->+----------+  +-->+----------+  +-->+----------+
  29  |   Type   |  |   |  Type    |  |   |  Type    |  |   |  Type    |
  30  |   FIU    |  |   | Private  |  |   | Private  |  |   | Private  |
  31  +----------+  |   | Feature  |  |   | Feature  |  |   | Feature  |
  32  | Next_DFH |--+   +----------+  |   +----------+  |   +----------+
  33  +----------+      | Next_DFH |--+   | Next_DFH |--+   | Next_DFH |--> NULL
  34  |    ID    |      +----------+      +----------+      +----------+
  35  +----------+      |    ID    |      |    ID    |      |    ID    |
  36  | Next_AFU |--+   +----------+      +----------+      +----------+
  37  +----------+  |   | Feature  |      | Feature  |      | Feature  |
  38  |  Header  |  |   | Register |      | Register |      | Register |
  39  | Register |  |   |   Set    |      |   Set    |      |   Set    |
  40  |   Set    |  |   +----------+      +----------+      +----------+
  41  +----------+  |      Header
  42                +-->+----------+
  43                    |   Type   |
  44                    |   AFU    |
  45                    +----------+
  46                    | Next_DFH |--> NULL
  47                    +----------+
  48                    |   GUID   |
  49                    +----------+
  50                    |  Header  |
  51                    | Register |
  52                    |   Set    |
  53                    +----------+
  54
  55 FPGA Interface Unit (FIU) represents a standalone functional unit for the
  56 interface to FPGA, e.g. the FPGA Management Engine (FME) and Port (more
  57 descriptions on FME and Port in later sections).
  58
  59 Accelerated Function Unit (AFU) represents a FPGA programmable region and
  60 always connects to a FIU (e.g. a Port) as its child as illustrated above.
  61
  62 Private Features represent sub features of the FIU and AFU. They could be
  63 various function blocks with different IDs, but all private features which
  64 belong to the same FIU or AFU, must be linked to one list via the Next Device
  65 Feature Header (Next_DFH) pointer.
  66
  67 Each FIU, AFU and Private Feature could implement its own functional registers.
  68 The functional register set for FIU and AFU, is named as Header Register Set,
  69 e.g. FME Header Register Set, and the one for Private Feature, is named as
  70 Feature Register Set, e.g. FME Partial Reconfiguration Feature Register Set.
  71
  72 This Device Feature List provides a way of linking features together, it's
  73 convenient for software to locate each feature by walking through this list,
  74 and can be implemented in register regions of any FPGA device.
  75
  76
  77 FIU - FME (FPGA Management Engine)
  78 ==================================
  79 The FPGA Management Engine performs reconfiguration and other infrastructure
  80 functions. Each FPGA device only has one FME.
  81
  82 User-space applications can acquire exclusive access to the FME using open(),
  83 and release it using close().
  84
  85 The following functions are exposed through ioctls:
  86
  87 - Get driver API version (DFL_FPGA_GET_API_VERSION)
  88 - Check for extensions (DFL_FPGA_CHECK_EXTENSION)
  89 - Program bitstream (DFL_FPGA_FME_PORT_PR)
  90 - Assign port to PF (DFL_FPGA_FME_PORT_ASSIGN)
  91 - Release port from PF (DFL_FPGA_FME_PORT_RELEASE)
  92 - Get number of irqs of FME global error (DFL_FPGA_FME_ERR_GET_IRQ_NUM)
  93 - Set interrupt trigger for FME error (DFL_FPGA_FME_ERR_SET_IRQ)
  94
  95 More functions are exposed through sysfs
  96 (/sys/class/fpga_region/regionX/dfl-fme.n/):
  97
  98  Read bitstream ID (bitstream_id)
  99      bitstream_id indicates version of the static FPGA region.
 100
 101  Read bitstream metadata (bitstream_metadata)
 102      bitstream_metadata includes detailed information of static FPGA region,
 103      e.g. synthesis date and seed.
 104
 105  Read number of ports (ports_num)
 106      one FPGA device may have more than one port, this sysfs interface indicates
 107      how many ports the FPGA device has.
 108
 109  Global error reporting management (errors/)
 110      error reporting sysfs interfaces allow user to read errors detected by the
 111      hardware, and clear the logged errors.
 112
 113  Power management (dfl_fme_power hwmon)
 114      power management hwmon sysfs interfaces allow user to read power management
 115      information (power consumption, thresholds, threshold status, limits, etc.)
 116      and configure power thresholds for different throttling levels.
 117
 118  Thermal management (dfl_fme_thermal hwmon)
 119      thermal management hwmon sysfs interfaces allow user to read thermal
 120      management information (current temperature, thresholds, threshold status,
 121      etc.).
 122
 123  Performance reporting
 124      performance counters are exposed through perf PMU APIs. Standard perf tool
 125      can be used to monitor all available perf events. Please see performance
 126      counter section below for more detailed information.
 127
 128
 129 FIU - PORT
 130 ==========
 131 A port represents the interface between the static FPGA fabric and a partially
 132 reconfigurable region containing an AFU. It controls the communication from SW
 133 to the accelerator and exposes features such as reset and debug. Each FPGA
 134 device may have more than one port, but always one AFU per port.
 135
 136
 137 AFU
 138 ===
 139 An AFU is attached to a port FIU and exposes a fixed length MMIO region to be
 140 used for accelerator-specific control registers.
 141
 142 User-space applications can acquire exclusive access to an AFU attached to a
 143 port by using open() on the port device node and release it using close().
 144
 145 The following functions are exposed through ioctls:
 146
 147 - Get driver API version (DFL_FPGA_GET_API_VERSION)
 148 - Check for extensions (DFL_FPGA_CHECK_EXTENSION)
 149 - Get port info (DFL_FPGA_PORT_GET_INFO)
 150 - Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO)
 151 - Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
 152 - Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
 153 - Reset AFU (DFL_FPGA_PORT_RESET)
 154 - Get number of irqs of port error (DFL_FPGA_PORT_ERR_GET_IRQ_NUM)
 155 - Set interrupt trigger for port error (DFL_FPGA_PORT_ERR_SET_IRQ)
 156 - Get number of irqs of UINT (DFL_FPGA_PORT_UINT_GET_IRQ_NUM)
 157 - Set interrupt trigger for UINT (DFL_FPGA_PORT_UINT_SET_IRQ)
 158
 159 DFL_FPGA_PORT_RESET:
 160   reset the FPGA Port and its AFU. Userspace can do Port
 161   reset at any time, e.g. during DMA or Partial Reconfiguration. But it should
 162   never cause any system level issue, only functional failure (e.g. DMA or PR
 163   operation failure) and be recoverable from the failure.
 164
 165 User-space applications can also mmap() accelerator MMIO regions.
 166
 167 More functions are exposed through sysfs:
 168 (/sys/class/fpga_region/<regionX>/<dfl-port.m>/):
 169
 170  Read Accelerator GUID (afu_id)
 171      afu_id indicates which PR bitstream is programmed to this AFU.
 172
 173  Error reporting (errors/)
 174      error reporting sysfs interfaces allow user to read port/afu errors
 175      detected by the hardware, and clear the logged errors.
 176
 177
 178 DFL Framework Overview
 179 ======================
 180
 181 ::
 182
 183          +----------+    +--------+ +--------+ +--------+
 184          |   FME    |    |  AFU   | |  AFU   | |  AFU   |
 185          |  Module  |    | Module | | Module | | Module |
 186          +----------+    +--------+ +--------+ +--------+
 187                  +-----------------------+
 188                  | FPGA Container Device |    Device Feature List
 189                  |  (FPGA Base Region)   |         Framework
 190                  +-----------------------+
 191   ------------------------------------------------------------------
 192                +----------------------------+
 193                |   FPGA DFL Device Module   |
 194                | (e.g. PCIE/Platform Device)|
 195                +----------------------------+
 196                  +------------------------+
 197                  |  FPGA Hardware Device  |
 198                  +------------------------+
 199
 200 DFL framework in kernel provides common interfaces to create container device
 201 (FPGA base region), discover feature devices and their private features from the
 202 given Device Feature Lists and create platform devices for feature devices
 203 (e.g. FME, Port and AFU) with related resources under the container device. It
 204 also abstracts operations for the private features and exposes common ops to
 205 feature device drivers.
 206
 207 The FPGA DFL Device could be different hardwares, e.g. PCIe device, platform
 208 device and etc. Its driver module is always loaded first once the device is
 209 created by the system. This driver plays an infrastructural role in the
 210 driver architecture. It locates the DFLs in the device memory, handles them
 211 and related resources to common interfaces from DFL framework for enumeration.
 212 (Please refer to drivers/fpga/dfl.c for detailed enumeration APIs).
 213
 214 The FPGA Management Engine (FME) driver is a platform driver which is loaded
 215 automatically after FME platform device creation from the DFL device module. It
 216 provides the key features for FPGA management, including:
 217
 218         a) Expose static FPGA region information, e.g. version and metadata.
 219            Users can read related information via sysfs interfaces exposed
 220            by FME driver.
 221
 222         b) Partial Reconfiguration. The FME driver creates FPGA manager, FPGA
 223            bridges and FPGA regions during PR sub feature initialization. Once
 224            it receives a DFL_FPGA_FME_PORT_PR ioctl from user, it invokes the
 225            common interface function from FPGA Region to complete the partial
 226            reconfiguration of the PR bitstream to the given port.
 227
 228 Similar to the FME driver, the FPGA Accelerated Function Unit (AFU) driver is
 229 probed once the AFU platform device is created. The main function of this module
 230 is to provide an interface for userspace applications to access the individual
 231 accelerators, including basic reset control on port, AFU MMIO region export, dma
 232 buffer mapping service functions.
 233
 234 After feature platform devices creation, matched platform drivers will be loaded
 235 automatically to handle different functionalities. Please refer to next sections
 236 for detailed information on functional units which have been already implemented
 237 under this DFL framework.
 238
 239
 240 Partial Reconfiguration
 241 =======================
 242 As mentioned above, accelerators can be reconfigured through partial
 243 reconfiguration of a PR bitstream file. The PR bitstream file must have been
 244 generated for the exact static FPGA region and targeted reconfigurable region
 245 (port) of the FPGA, otherwise, the reconfiguration operation will fail and
 246 possibly cause system instability. This compatibility can be checked by
 247 comparing the compatibility ID noted in the header of PR bitstream file against
 248 the compat_id exposed by the target FPGA region. This check is usually done by
 249 userspace before calling the reconfiguration IOCTL.
 250
 251
 252 FPGA virtualization - PCIe SRIOV
 253 ================================
 254 This section describes the virtualization support on DFL based FPGA device to
 255 enable accessing an accelerator from applications running in a virtual machine
 256 (VM). This section only describes the PCIe based FPGA device with SRIOV support.
 257
 258 Features supported by the particular FPGA device are exposed through Device
 259 Feature Lists, as illustrated below:
 260
 261 ::
 262
 263     +-------------------------------+  +-------------+
 264     |              PF               |  |     VF      |
 265     +-------------------------------+  +-------------+
 266         ^            ^         ^              ^
 267         |            |         |              |
 268   +-----|------------|---------|--------------|-------+
 269   |     |            |         |              |       |
 270   |  +-----+     +-------+ +-------+      +-------+   |
 271   |  | FME |     | Port0 | | Port1 |      | Port2 |   |
 272   |  +-----+     +-------+ +-------+      +-------+   |
 273   |                  ^         ^              ^       |
 274   |                  |         |              |       |
 275   |              +-------+ +------+       +-------+   |
 276   |              |  AFU  | |  AFU |       |  AFU  |   |
 277   |              +-------+ +------+       +-------+   |
 278   |                                                   |
 279   |            DFL based FPGA PCIe Device             |
 280   +---------------------------------------------------+
 281
 282 FME is always accessed through the physical function (PF).
 283
 284 Ports (and related AFUs) are accessed via PF by default, but could be exposed
 285 through virtual function (VF) devices via PCIe SRIOV. Each VF only contains
 286 1 Port and 1 AFU for isolation. Users could assign individual VFs (accelerators)
 287 created via PCIe SRIOV interface, to virtual machines.
 288
 289 The driver organization in virtualization case is illustrated below:
 290 ::
 291
 292     +-------++------++------+             |
 293     | FME   || FME  || FME  |             |
 294     | FPGA  || FPGA || FPGA |             |
 295     |Manager||Bridge||Region|             |
 296     +-------++------++------+             |
 297     +-----------------------+  +--------+ |             +--------+
 298     |          FME          |  |  AFU   | |             |  AFU   |
 299     |         Module        |  | Module | |             | Module |
 300     +-----------------------+  +--------+ |             +--------+
 301           +-----------------------+       |       +-----------------------+
 302           | FPGA Container Device |       |       | FPGA Container Device |
 303           |  (FPGA Base Region)   |       |       |  (FPGA Base Region)   |
 304           +-----------------------+       |       +-----------------------+
 305             +------------------+          |         +------------------+
 306             | FPGA PCIE Module |          | Virtual | FPGA PCIE Module |
 307             +------------------+   Host   | Machine +------------------+
 308    -------------------------------------- | ------------------------------
 309              +---------------+            |          +---------------+
 310              | PCI PF Device |            |          | PCI VF Device |
 311              +---------------+            |          +---------------+
 312
 313 FPGA PCIe device driver is always loaded first once a FPGA PCIe PF or VF device
 314 is detected. It:
 315
 316 * Finishes enumeration on both FPGA PCIe PF and VF device using common
 317   interfaces from DFL framework.
 318 * Supports SRIOV.
 319
 320 The FME device driver plays a management role in this driver architecture, it
 321 provides ioctls to release Port from PF and assign Port to PF. After release
 322 a port from PF, then it's safe to expose this port through a VF via PCIe SRIOV
 323 sysfs interface.
 324
 325 To enable accessing an accelerator from applications running in a VM, the
 326 respective AFU's port needs to be assigned to a VF using the following steps:
 327
 328 #. The PF owns all AFU ports by default. Any port that needs to be
 329    reassigned to a VF must first be released through the
 330    DFL_FPGA_FME_PORT_RELEASE ioctl on the FME device.
 331
 332 #. Once N ports are released from PF, then user can use command below
 333    to enable SRIOV and VFs. Each VF owns only one Port with AFU.
 334
 335    ::
 336
 337       echo N > $PCI_DEVICE_PATH/sriov_numvfs
 338
 339 #. Pass through the VFs to VMs
 340
 341 #. The AFU under VF is accessible from applications in VM (using the
 342    same driver inside the VF).
 343
 344 Note that an FME can't be assigned to a VF, thus PR and other management
 345 functions are only available via the PF.
 346
 347 Device enumeration
 348 ==================
 349 This section introduces how applications enumerate the fpga device from
 350 the sysfs hierarchy under /sys/class/fpga_region.
 351
 352 In the example below, two DFL based FPGA devices are installed in the host. Each
 353 fpga device has one FME and two ports (AFUs).
 354
 355 FPGA regions are created under /sys/class/fpga_region/::
 356
 357         /sys/class/fpga_region/region0
 358         /sys/class/fpga_region/region1
 359         /sys/class/fpga_region/region2
 360         ...
 361
 362 Application needs to search each regionX folder, if feature device is found,
 363 (e.g. "dfl-port.n" or "dfl-fme.m" is found), then it's the base
 364 fpga region which represents the FPGA device.
 365
 366 Each base region has one FME and two ports (AFUs) as child devices::
 367
 368         /sys/class/fpga_region/region0/dfl-fme.0
 369         /sys/class/fpga_region/region0/dfl-port.0
 370         /sys/class/fpga_region/region0/dfl-port.1
 371         ...
 372
 373         /sys/class/fpga_region/region3/dfl-fme.1
 374         /sys/class/fpga_region/region3/dfl-port.2
 375         /sys/class/fpga_region/region3/dfl-port.3
 376         ...
 377
 378 In general, the FME/AFU sysfs interfaces are named as follows::
 379
 380         /sys/class/fpga_region/<regionX>/<dfl-fme.n>/
 381         /sys/class/fpga_region/<regionX>/<dfl-port.m>/
 382
 383 with 'n' consecutively numbering all FMEs and 'm' consecutively numbering all
 384 ports.
 385
 386 The device nodes used for ioctl() or mmap() can be referenced through::
 387
 388         /sys/class/fpga_region/<regionX>/<dfl-fme.n>/dev
 389         /sys/class/fpga_region/<regionX>/<dfl-port.n>/dev
 390
 391
 392 Performance Counters
 393 ====================
 394 Performance reporting is one private feature implemented in FME. It could
 395 supports several independent, system-wide, device counter sets in hardware to
 396 monitor and count for performance events, including "basic", "cache", "fabric",
 397 "vtd" and "vtd_sip" counters. Users could use standard perf tool to monitor
 398 FPGA cache hit/miss rate, transaction number, interface clock counter of AFU
 399 and other FPGA performance events.
 400
 401 Different FPGA devices may have different counter sets, depending on hardware
 402 implementation. E.g., some discrete FPGA cards don't have any cache. User could
 403 use "perf list" to check which perf events are supported by target hardware.
 404
 405 In order to allow user to use standard perf API to access these performance
 406 counters, driver creates a perf PMU, and related sysfs interfaces in
 407 /sys/bus/event_source/devices/dfl_fme* to describe available perf events and
 408 configuration options.
 409
 410 The "format" directory describes the format of the config field of struct
 411 perf_event_attr. There are 3 bitfields for config: "evtype" defines which type
 412 the perf event belongs to; "event" is the identity of the event within its
 413 category; "portid" is introduced to decide counters set to monitor on FPGA
 414 overall data or a specific port.
 415
 416 The "events" directory describes the configuration templates for all available
 417 events which can be used with perf tool directly. For example, fab_mmio_read
 418 has the configuration "event=0x06,evtype=0x02,portid=0xff", which shows this
 419 event belongs to fabric type (0x02), the local event id is 0x06 and it is for
 420 overall monitoring (portid=0xff).
 421
 422 Example usage of perf::
 423
 424   $# perf list |grep dfl_fme
 425
 426   dfl_fme0/fab_mmio_read/                              [Kernel PMU event]
 427   <...>
 428   dfl_fme0/fab_port_mmio_read,portid=?/                [Kernel PMU event]
 429   <...>
 430
 431   $# perf stat -a -e dfl_fme0/fab_mmio_read/ <command>
 432   or
 433   $# perf stat -a -e dfl_fme0/event=0x06,evtype=0x02,portid=0xff/ <command>
 434   or
 435   $# perf stat -a -e dfl_fme0/config=0xff2006/ <command>
 436
 437 Another example, fab_port_mmio_read monitors mmio read of a specific port. So
 438 its configuration template is "event=0x06,evtype=0x01,portid=?". The portid
 439 should be explicitly set.
 440
 441 Its usage of perf::
 442
 443   $# perf stat -a -e dfl_fme0/fab_port_mmio_read,portid=0x0/ <command>
 444   or
 445   $# perf stat -a -e dfl_fme0/event=0x06,evtype=0x02,portid=0x0/ <command>
 446   or
 447   $# perf stat -a -e dfl_fme0/config=0x2006/ <command>
 448
 449 Please note for fabric counters, overall perf events (fab_*) and port perf
 450 events (fab_port_*) actually share one set of counters in hardware, so it can't
 451 monitor both at the same time. If this set of counters is configured to monitor
 452 overall data, then per port perf data is not supported. See below example::
 453
 454   $# perf stat -e dfl_fme0/fab_mmio_read/,dfl_fme0/fab_port_mmio_write,\
 455                                                     portid=0/ sleep 1
 456
 457   Performance counter stats for 'system wide':
 458
 459                  3      dfl_fme0/fab_mmio_read/
 460    <not supported>      dfl_fme0/fab_port_mmio_write,portid=0x0/
 461
 462        1.001750904 seconds time elapsed
 463
 464 The driver also provides a "cpumask" sysfs attribute, which contains only one
 465 CPU id used to access these perf events. Counting on multiple CPU is not allowed
 466 since they are system-wide counters on FPGA device.
 467
 468 The current driver does not support sampling. So "perf record" is unsupported.
 469
 470
 471 Interrupt support
 472 =================
 473 Some FME and AFU private features are able to generate interrupts. As mentioned
 474 above, users could call ioctl (DFL_FPGA_*_GET_IRQ_NUM) to know whether or how
 475 many interrupts are supported for this private feature. Drivers also implement
 476 an eventfd based interrupt handling mechanism for users to get notified when
 477 interrupt happens. Users could set eventfds to driver via
 478 ioctl (DFL_FPGA_*_SET_IRQ), and then poll/select on these eventfds waiting for
 479 notification.
 480 In Current DFL, 3 sub features (Port error, FME global error and AFU interrupt)
 481 support interrupts.
 482
 483
 484 Add new FIUs support
 485 ====================
 486 It's possible that developers made some new function blocks (FIUs) under this
 487 DFL framework, then new platform device driver needs to be developed for the
 488 new feature dev (FIU) following the same way as existing feature dev drivers
 489 (e.g. FME and Port/AFU platform device driver). Besides that, it requires
 490 modification on DFL framework enumeration code too, for new FIU type detection
 491 and related platform devices creation.
 492
 493
 494 Add new private features support
 495 ================================
 496 In some cases, we may need to add some new private features to existing FIUs
 497 (e.g. FME or Port). Developers don't need to touch enumeration code in DFL
 498 framework, as each private feature will be parsed automatically and related
 499 mmio resources can be found under FIU platform device created by DFL framework.
 500 Developer only needs to provide a sub feature driver with matched feature id.
 501 FME Partial Reconfiguration Sub Feature driver (see drivers/fpga/dfl-fme-pr.c)
 502 could be a reference.
 503
 504
 505 Open discussion
 506 ===============
 507 FME driver exports one ioctl (DFL_FPGA_FME_PORT_PR) for partial reconfiguration
 508 to user now. In the future, if unified user interfaces for reconfiguration are
 509 added, FME driver should switch to them from ioctl interface.