[PATCH v6 01/29] docs: fpga: add a document for FPGA Device Feature List (DFL) Framework Overview
Add a document for FPGA Device Feature List (DFL) Framework Overview. Signed-off-by: Enno Luebbers Signed-off-by: Xiao Guangrong Signed-off-by: Wu Hao Acked-by: Alan Tull --- v2: added FME fpga-mgr/bridge/region platform driver to driver organization. updated open discussion per current implementation. fixed some typos. v3: use FPGA base region as container device instead of fpga-dev class. split common enumeration code from pcie driver to functions exposed by device feature list framework. update FME performance reporting which supports both integrated (iperf/) and discrete (dperf/) FPGA solutions. v4: rename this doc to Device Feature List (DFL) Framework Overview (dfl.txt) add Device Feature List introduction and re-organize the content. add description for port reset, bitstream_id/metadata and etc. v5: remove introduction of the APIs/features which aren't covered in this patchset. replace "blue/green bitstream" terminology with "static region" and "PR bitstream". add a "DFL_" prefix to IOCTL APIs introduced by DFL framework. s/FPGA Bus Device Module/FPGA DFL Device Module/ fix typos, improve descriptions per comments from Alan Tull against v4. v6: add Acked-by from Alan. --- Documentation/fpga/dfl.txt | 285 + 1 file changed, 285 insertions(+) create mode 100644 Documentation/fpga/dfl.txt diff --git a/Documentation/fpga/dfl.txt b/Documentation/fpga/dfl.txt new file mode 100644 index 000..ba2a1ee --- /dev/null +++ b/Documentation/fpga/dfl.txt @@ -0,0 +1,285 @@ +=== + FPGA Device Feature List (DFL) Framework Overview +--- +Enno Luebbers +Xiao Guangrong +Wu Hao + +The Device Feature List (DFL) FPGA framework (and drivers according to this +this framework) hides the very details of low layer hardwares and provides +unified interfaces to userspace. Applications could use these interfaces to +configure, enumerate, open and access FPGA accelerators on platforms which +implemented the DFL in the device memory. Besides this, the DFL framework +enables system level management functions such as FPGA reconfiguration. + + +Device Feature List (DFL) Overview +== +Device Feature List (DFL) defines a linked list of feature headers within the +device MMIO space to provide an extensible way of adding features. Software can +walk through these predefined data structures to enumerate FPGA features: +FPGA Interface Unit (FIU), Accelerated Function Unit (AFU) and Private Features, +as illustrated below: + +HeaderHeaderHeaderHeader + +--+ +-->+--+ +-->+--+ +-->+--+ + | Type | | | Type| | | Type| | | Type| + | FIU| | | Private | | | Private | | | Private | + +--+ | | Feature | | | Feature | | | Feature | + | Next_DFH |--+ +--+ | +--+ | +--+ + +--+ | Next_DFH |--+ | Next_DFH |--+ | Next_DFH |--> NULL + |ID| +--+ +--+ +--+ + +--+ |ID| |ID| |ID| + | Next_AFU |--+ +--+ +--+ +--+ + +--+ | | Feature | | Feature | | Feature | + | Header | | | Register | | Register | | Register | + | Register | | | Set| | Set| | Set| + | Set| | +--+ +--+ +--+ + +--+ | Header + +-->+--+ + | Type | + | AFU| + +--+ + | Next_DFH |--> NULL + +--+ + | GUID | + +--+ + | Header | + | Register | + | Set| + +--+ + +FPGA Interface Unit (FIU) represents a standalone functional unit for the +interface to FPGA, e.g the FPGA Management Engine (FME) and Port (more +descriptions on FME and Port in later sections). + +Accelerated Function Unit (AFU) represents a FPGA programmable region, and +always connects to a FIU (e.g a Port) as its child as illustrated above. + +Private Features represent sub features of the FIU and AFU. They could be +various function blocks with different IDs, but all private features which +belong to the same FIU or AFU, must be linked to one list via the Next Device +Feature Header (Next_DFH) pointer. + +Each FIU, AFU and Private Feature could implement its own functional registers. +The functional register set for FIU and AFU, is named as Header Register Set, +e.g FME Header Register
[PATCH v6 01/29] docs: fpga: add a document for FPGA Device Feature List (DFL) Framework Overview
Add a document for FPGA Device Feature List (DFL) Framework Overview. Signed-off-by: Enno Luebbers Signed-off-by: Xiao Guangrong Signed-off-by: Wu Hao Acked-by: Alan Tull --- v2: added FME fpga-mgr/bridge/region platform driver to driver organization. updated open discussion per current implementation. fixed some typos. v3: use FPGA base region as container device instead of fpga-dev class. split common enumeration code from pcie driver to functions exposed by device feature list framework. update FME performance reporting which supports both integrated (iperf/) and discrete (dperf/) FPGA solutions. v4: rename this doc to Device Feature List (DFL) Framework Overview (dfl.txt) add Device Feature List introduction and re-organize the content. add description for port reset, bitstream_id/metadata and etc. v5: remove introduction of the APIs/features which aren't covered in this patchset. replace "blue/green bitstream" terminology with "static region" and "PR bitstream". add a "DFL_" prefix to IOCTL APIs introduced by DFL framework. s/FPGA Bus Device Module/FPGA DFL Device Module/ fix typos, improve descriptions per comments from Alan Tull against v4. v6: add Acked-by from Alan. --- Documentation/fpga/dfl.txt | 285 + 1 file changed, 285 insertions(+) create mode 100644 Documentation/fpga/dfl.txt diff --git a/Documentation/fpga/dfl.txt b/Documentation/fpga/dfl.txt new file mode 100644 index 000..ba2a1ee --- /dev/null +++ b/Documentation/fpga/dfl.txt @@ -0,0 +1,285 @@ +=== + FPGA Device Feature List (DFL) Framework Overview +--- +Enno Luebbers +Xiao Guangrong +Wu Hao + +The Device Feature List (DFL) FPGA framework (and drivers according to this +this framework) hides the very details of low layer hardwares and provides +unified interfaces to userspace. Applications could use these interfaces to +configure, enumerate, open and access FPGA accelerators on platforms which +implemented the DFL in the device memory. Besides this, the DFL framework +enables system level management functions such as FPGA reconfiguration. + + +Device Feature List (DFL) Overview +== +Device Feature List (DFL) defines a linked list of feature headers within the +device MMIO space to provide an extensible way of adding features. Software can +walk through these predefined data structures to enumerate FPGA features: +FPGA Interface Unit (FIU), Accelerated Function Unit (AFU) and Private Features, +as illustrated below: + +HeaderHeaderHeaderHeader + +--+ +-->+--+ +-->+--+ +-->+--+ + | Type | | | Type| | | Type| | | Type| + | FIU| | | Private | | | Private | | | Private | + +--+ | | Feature | | | Feature | | | Feature | + | Next_DFH |--+ +--+ | +--+ | +--+ + +--+ | Next_DFH |--+ | Next_DFH |--+ | Next_DFH |--> NULL + |ID| +--+ +--+ +--+ + +--+ |ID| |ID| |ID| + | Next_AFU |--+ +--+ +--+ +--+ + +--+ | | Feature | | Feature | | Feature | + | Header | | | Register | | Register | | Register | + | Register | | | Set| | Set| | Set| + | Set| | +--+ +--+ +--+ + +--+ | Header + +-->+--+ + | Type | + | AFU| + +--+ + | Next_DFH |--> NULL + +--+ + | GUID | + +--+ + | Header | + | Register | + | Set| + +--+ + +FPGA Interface Unit (FIU) represents a standalone functional unit for the +interface to FPGA, e.g the FPGA Management Engine (FME) and Port (more +descriptions on FME and Port in later sections). + +Accelerated Function Unit (AFU) represents a FPGA programmable region, and +always connects to a FIU (e.g a Port) as its child as illustrated above. + +Private Features represent sub features of the FIU and AFU. They could be +various function blocks with different IDs, but all private features which +belong to the same FIU or AFU, must be linked to one list via the Next Device +Feature Header (Next_DFH) pointer. + +Each FIU, AFU and Private Feature could implement its own functional registers. +The functional register set for FIU and AFU, is named as Header Register Set, +e.g FME Header Register
