Orange Pi5 kernel

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