systemsoftware
/
CAPI-SNAP-Doc
34
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Add Document enable_capi_snap

Browse Source 
Signed-off-by: Yong Lu <luyong@cn.ibm.com>
master
Yong Lu 6 years ago
parent caf5e08bbc
commit ba3314db9e
23 changed files with 1309 additions and 3 deletions
Show Stats Download Patch File Download Diff File

30
enable_capi_snap/app_template.xml
Unescape Escape View File

@ -0,0 +1,30 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="app_template">
<?dbhtml stop-chunking?>
<title>Appendix template</title>
<para>This is the first paragraph of a new appendix...</para>
<section xml:id="sample-app-section">
<title>Section title</title>
<para>Section text...</para>
</section>
</appendix>

113
enable_capi_snap/bk_main.xml
Unescape Escape View File

@ -0,0 +1,113 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<!-- The following entity variable is used to reflect the version of the
template document master used for building a document. This value
should be set by copy of the of template used to create a new
document and should not be changed. Use of this value is in
in the Abstract section in this file. -->
<!DOCTYPE book [
<!ENTITY template_version "1.0.0">
]>

<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="bk_main">

<!-- TODO: Pick a Title for the new document -->
<title>Enable FPGA for SNAP</title>
<!-- TODO: Either add a subtitle or remove the following line -->
<subtitle>For CAPI2.0 and CAPI1.0</subtitle>

<info>
<author>
<!-- TODO: Set the correct Work Group Name and email id for WG Chair -->
<personname>
Acceleration Workgroup
</personname>
<email>aclwg-chair@openpowerfoundation.org</email>
<affiliation>
<orgname>OpenPower Foundation</orgname>
</affiliation>
</author>
<copyright>
<year>2018</year>
<holder>OpenPOWER Foundation</holder>
</copyright>
<!-- TODO: Set the correct document releaseinfo -->
<releaseinfo>Revision 1.0_pre1</releaseinfo>
<productname>OpenPOWER</productname>
<pubdate/>

<legalnotice role="apache2">
<!--legalnotice role="opfExternal"-->

<annotation>
<remark>Copyright details are filled in by the template.</remark>
</annotation>
</legalnotice>
<!-- TODO: Update the following text with the correct document description (first paragraph),
Work Group name, and Work Product track (both in second paragraph). -->
<abstract>
<!-- TODO: remove "phrase" tags (2) and text below and insert proper information -->
<para>The purpose of this document is to describe how to enable a new customer card on CAPI SNAP framework. SNAP is a open-sourced programming framework for FPGA Acclerations. Its homepage is <link xlink:href="https://github.com/open-power/snap">https://github.com/open-power/snap</link>. With it, you can develop accelerations with Power and CAPI technology easily.</para>
<para>This document describes when you get a PCIe FPGA card not listed in today's "SNAP enabled cards" (On the homepage README of SNAP github website), <emphasis role="bold">how do you get it enabled</emphasis>. Since all of the files are open-sourced, you can create a board support package (bsp) similar to the existing one and walk through the entire working flow with the help of this document. </para>

<para>This document is a Standard Track, Workgroup Specification work product owned by the Acceleration Workgroup and handled in compliance with the requirements outlined in the
<citetitle>OpenPOWER Foundation Work Group (WG) Process</citetitle> document. It was
created using the <citetitle>Master Template Guide</citetitle> version &template_version;.
Comments, questions, etc. can be submitted to the
public mailing list for the parent specification at
<email>tbd@mailinglist.openpowerfoundation.org</email>.</para>
</abstract>

<revhistory>
<revision>
<!-- TODO: Set correct date and remove "phrase" tags (1) and text below and insert proper information -->
<date>2019-03-29</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Start from the original Word document</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
</revhistory>
</info>

<!-- The ch_preface.xml file is required by all documents -->
<xi:include href="../../Docs-Master/common/ch_preface.xml"/>

<!-- TODO: Add your chapter heading files here. Remove both files and insert your own. -->
<!-- See the template document for naming conventions and location of files. -->
<xi:include href="ch_introduction.xml"/>
<xi:include href="ch_enable_snap.xml"/>
<xi:include href="ch_genpsl_capi10.xml"/>

<!-- The app_foundation.xml appendix file is required by all documents. -->
<xi:include href="../../Docs-Master/common/app_foundation.xml"/>

<!-- TODO: The following template document may be modified to create additional appendices as needed. -->
<xi:include href="app_template.xml"/>

</book>

355
enable_capi_snap/ch_enable_snap.xml
Unescape Escape View File

@ -0,0 +1,355 @@
<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<chapter version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chapter_enable_snap">
<!-- Chapter Title goes here. -->
<title>Enable a FPGA card in SNAP</title>
<para>On the FPGA side of SNAP diagram, there are three parts that need to consider when moving to a new FPGA card. They are (a) PSL, (b) PSL/AXI bridge (snap_core), (c) DDR memory controller (mig). And there are also some components in SNAP need to be updated for a new FPGA card. The following sections introduced the the structure of SNAP folders and scripts and the steps. </para>
<section><title>SNAP structure</title>
<para>Firstly, clone the repository:</para>
<screen>
git clone https://github.com/open-power/snap
git submodule init
git submodule update
</screen>

<figure pgwide="1" xml:id="snap-str">
<title>SNAP structure</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/snap-structure_white.png" format="PNG" scalefit="1" width="90%" align="center" />
</imageobject>
</mediaobject>
</figure>
<para>
All of the user-developed accelerators should be put in "<emphasis role="bold">actions</emphasis>" directory. There are already some examples there. Each "action" has its "sw", "hw", "tests", and other sub-directories.</para>
<para>Then back to ${SNAP_ROOT}, "<emphasis role="bold">software</emphasis>" directory includes libsnap, header files and some tools. "<emphasis role="bold">hardware</emphasis>" directory is the main focus. <emphasis role="bold">deconfig</emphasis> has the config files for silent testing purpose, and <emphasis role="bold">scripts</emphasis> has the menu settings and other scripts. </para>
<para>
How does SNAP work and what are the files used in each step?
</para>
<itemizedlist>
<listitem><para><emphasis role="bold">make snap_config</emphasis>: The menu to select cards and other options is controlled by "script/Kconfig"</para></listitem>
<listitem>
<para><emphasis role="bold">make model</emphasis>: This step creates a Vivado project. It firstly calls "hardware/setup/<emphasis role="bold">create_snap_ip.tcl</emphasis>" to generate the IP files in use, then calls "hardware/setup/<emphasis role="bold">create_framework.tcl</emphasis>" to build the project. About create_framework.tcl: </para>
<itemizedlist>
<listitem>
<para>It adds BSP (board support package). In CAPI1.0, it is also called PSL Checkpoint file (b_route_design.dcp) or base_image. It uses the path pointed to b_route_design.dcp and adds it into the design. In CAPI2.0, it will call the make process in capi2-bsp submodule. Submodule "capi2-bsp" reads the encrypted PSL source files, adds PCIe and Flash logic, packs them into capi2_bsp_wrap.xcix (IP container file). Then "create_framework.tcl" adds the capi2_bsp_wrap.xcix into the design.</para>
</listitem>
<listitem>
<para>It adds FPGA top files and snap_core files (in hardware/hdl/core).</para>
</listitem>
<listitem>
<para>It adds constrain files: in hardware/setup/${FPGACARD} or in hardware/capi2-bsp/${FPGACARD}</para>
</listitem>
<listitem>
<para>It adds user files (in actions/${ACTION_NAME}/hw). User's action hardware uses top file named "action_wrapper.vhd"</para>
</listitem>
<listitem>
<para>It adds simulation files (in hardware/sim/core) including simulation top files and simulation models. (If "no_sim" is selected in snap_config menu, this step is skipped.)</para>
</listitem>
</itemizedlist>
<para>After above steps, "<emphasis role="bold">viv_project</emphasis>" is created. You can open it with Vivado GUI, and check the design hierarchy. And it will call the selected simulator to compile the simulation model.</para>
</listitem>
<listitem>
<para><emphasis role="bold">make image</emphasis>: This step runs synthesis, implementation and bitstream generation. It calls "hardware/setup/<emphasis role="bold">snap_build.tcl</emphasis>" and also uses some related tcl scripts to work on "viv_project". In this step, "hardware/build" will be created and the output products like bit images, checkpoints (middle products for debugging) and reports (reports of timing, clock, IO, utilization, etc.) If everything runs well and timing passes, user will get the bitstream files (in "Images" sub directory) to program the FPGA card. </para>
</listitem>
</itemizedlist>
</section>

<section><title>BSP (board support package) module</title>
<figure pgwide="1" xml:id="base_image">
<title>CAPI1.0: base_image (b_route_design.dcp)</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/base_image.png" format="PNG" scalefit="1" width="90%" align="center" />
</imageobject>
</mediaobject>
</figure>
<para>For CAPI1.0, base_image contains surrounding logic and the kernel logic:</para>
<itemizedlist>
<listitem><para>PCIe hard IP core (pcie3_ultrascale_0)</para></listitem>
<listitem><para>Flash Controller (psl_flash)</para></listitem>
<listitem><para>VSEC: Vendor Specific Extended Capability (psl_vsec)</para></listitem>
<listitem><para>Xilinx MultiBoot control logic (psl_xilmltbt)</para></listitem>
<listitem><para>PSL kernel logic (psl)</para></listitem>
</itemizedlist>
<para>The interface between base_image and AFU(psl_accel) has 5 groups of signals, described in PSL spec <link xlink:href="http://openpowerfoundation.org/wp-content/uploads/resources/psl-afu-spec/content/go01.html"> CAPI1.0 PSL/AFU interface Spec</link>.</para>
<para>The interface between base_image and Chip IOs are card specific, and the information need to be provided by Card Vendor. Generally, they include:</para>
<itemizedlist>
<listitem><para>Flash interface (usually DPIx16)</para></listitem>
<listitem><para>PCIe interface: perst, refclk, TX and RX data lanes</para></listitem>
<listitem><para>Peripheral IPs: I2C, LED, DDR, Ethernet, etc. </para></listitem>
</itemizedlist>
<para>Marked in light orange color, you can download the entire base_image (b_route_design.dcp) from <link xlink:href="https://www-355.ibm.com/systems/power/openpower/tgcmDocumentRepository.xhtml?aliasId=CAPI#">OpenPower Portal</link>.</para>

<figure pgwide="1" xml:id="bsp">
<title>CAPI2.0: capi2-bsp (capi_bsp_wrap.xcix)</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/bsp.png" format="PNG" scalefit="1" width="90%" align="center" />
</imageobject>
</mediaobject>
</figure>
<para>For CAPI2.0, the structure is similar, but the PSL9 logic (marked in light orange color) is provided as an encrypted Zip package. It can be downloaded from <link xlink:href="https://www-355.ibm.com/systems/power/openpower/posting.xhtml?postingId=1BED44BCA884D845852582B70076A89A">OpenPower Portal</link> and put in "capi2-bsp/psl" directory. Then it uses the make process in capi2-bsp to generate an IP container file (capi_bsp_wrap.xcix). Please refer to the README file at <link xlink:href="https://github.com/open-power/capi2-bsp">https://github.com/open-power/capi2-bsp</link> for more details.</para>
<para>CAPI2.0 cards are using SPI Flash interface: SPIx4 or dual SPIx4 (also mentioned as SPIx8). For PCIe Gen3, it uses 16 lanes. For PCIe Gen4, it uses 8 lanes. The interface of PSL9 has 6 groups of signals. Please refer to <link xlink:href="http://openpowerfoundation.org/wp-content/uploads/resources/v2-psl-afu-spec/content/ch_preface.html"> CAPI2.0 PSL/AFU interface Spec</link> for the details. </para>
<note><para>The logic in snap_core (CAPI2.0) implements the data path with DMA interface. Buffer interface is not used. </para></note>
<para>The above two figures apply to both HDK development and SNAP framework. The difference is, for HDK developers, they work on the AFU by themselves. For SNAP developers, they make use of the snap_core logic and only work on action_wrapper. The AFU part for SNAP developers contains following blocks:</para>
<figure pgwide="1" xml:id="afu">
<title>AFU diagram in SNAP framework</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/afu.png" format="PNG" scalefit="1" width="100%" align="center" />
</imageobject>
</mediaobject>
</figure>
<para>
AFU logic RTL files are open-sourced. Developer can make modifications for their own purpose, like adding multiple DDR channels, adding NVMe and Ethernet controllers.
</para>

</section>

<section><title>Enable a new card in SNAP</title>
<para>For a new FPGA card, the detailed items to update can be classified into following sections:</para>
<itemizedlist>
<listitem><para>Preparations</para></listitem>
<listitem><para>Hardware RTL, setup, simulation</para></listitem>
<listitem><para>Software and tools</para></listitem>
<listitem><para>Testing</para></listitem>
<listitem><para>Publishing</para></listitem>
</itemizedlist>
<section><title>Preppartions</title>
<para>First, give a FPGACARD name. It should start from the company's name, following with the card ID and be short. For example. ADKU3 = Alpha-Data ADM-PCIE-KU3. Get follow information from the card vendor. (You can check the "Status" column to trace the progress.)</para>
<!-- A table starts -->
<table frame="all" pgwide="1" xml:id="info1">
<title>Information to collect</title>
<tgroup cols="2">
<colspec colname="c2" colwidth="15*" />
<colspec colname="c3" colwidth="35*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">Item</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Description</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry><para>FPGACARD</para></entry>
<entry><para>Short card name used in SNAP</para></entry>
</row>
<row>
<entry><para>FPGACHIP</para></entry>
<entry><para>FPGA part name, for example, xcvu9p-fsgd2104-2L-e</para></entry>
</row>
<row>
<entry><para>Flash Type</para></entry>
<entry><para>Flash chip that attached to FPGA, for example mt28gu01gaax1e-bpi-x16. And the related xdc files for FPGA config.</para></entry>
</row>
<row>
<entry><para>DDR MC IP</para></entry>
<entry><para>Short card name used in SNAP</para></entry>
</row>
<row>
<entry><para>FPGACARD</para></entry>
<entry><para>DDR memory controller Vivado IP tcl/xdc file. </para></entry>
</row>
<row>
<entry><para>Other peripherals</para></entry>
<entry><para>NVMe IP, Ethernet IP and so on (Optional)</para></entry>
</row>
<row>
<entry><para>IO pins</para></entry>
<entry><para>PACKAGE_PIN for base_image or bsp: flash, pcie, i2c etc.</para>
<para>PACKAGE_PIN for peripheral IPs.</para></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section><title>SNAP environment updates</title>
<para>The best way is to grep some keywords like "S241" or "AD8K5" under the directories and look for the locations that need modifications.</para>
<note>
<para>If you meet files ending with "_source", like "psl_fpga.vhd_source", that means this file will be pre-processed to generate the output file without "_source" suffix, like "psl_fpga.vhd". There are <userinput>#ifdef</userinput> macros or comments like <userinput>-- only for NVME_USED=TRUE</userinput>. They help to create a target VHDL/Verilog file with different configurations.</para>
</note>
<para>Below lists the files to change. There may be some differences with new commits in SNAP git repository. Keep in mind they include: </para>
<itemizedlist>
<listitem><para>snap_config and environmental files</para></listitem>
<listitem><para>Hardware: psl_accel and psl_fpga (top) RTL files</para></listitem>
<listitem><para>Hardware: tcl files for the workflow</para></listitem>
<listitem><para>Hardware: Board: xdc files for IO/floorplan/clock/bitstream</para></listitem>
<listitem><para>Hardware: DDR: create_ip, sim model, xdc files</para></listitem>
<listitem><para>Hardware: Other IP: create_ip, sim model, xdc files</para></listitem>
<listitem><para>Software: New card type, register definition</para></listitem>
<listitem><para>Testing: jenkins</para></listitem>
<listitem><para>Readme and Documents</para></listitem>
</itemizedlist>
<note>
<itemizedlist>
<listitem><para> For CAPI1.0, you need to generate a new PSL checkpoint file and upload it to OpenPower Portal. Chapter TODO describes the details.</para></listitem>
<listitem><para> For CAPI2.0, you need to add a ${FPGACARD} directory in capi2-bsp git repository. Copy an existing folder as a start and follow the README file.</para></listitem>
<listitem><para> Make sure the information in xdc/tcl files are permitted to be open-source.</para></listitem>
<listitem><para> Send email to OpenPower Acceleration Workgroup or contact your representative to apply for a subsystem device ID for the new card. For example, ADKU3 uses 0x0605. S241 uses 0x0660. </para></listitem>
<listitem><para> You also need to update <link xlink:href="https://github.com/ibm-capi/capi-utils">https://github.com/ibm-capi/capi-utils</link> to allow capi-flash-script to program this new card. Subsystem ID will be used there. It is also used in snap/software/tools/snap_find_card. </para></listitem>
</itemizedlist>
</note>

<table frame="all" pgwide="1" xml:id="filelist">
<title>Config files to change</title>
<tgroup cols="2">
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="25*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">File name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Changes done</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry><para>scripts/Kconfig</para></entry>
<entry><para>adding card to the Kconfig menu. Provide Flash information (size/type/user address)</para></entry>
</row>
<row>
<entry><para>hardware/doc/SNAP-Registers.md</para></entry>
<entry><para>SNAP registers for new card - doc</para></entry>
</row>
<row>
<entry><para>hardware/setup/snap_config.sh</para></entry>
<entry><para>SNAP registers - setting</para></entry>
</row>
</tbody>
</tgroup>
</table>

<table frame="all" pgwide="1" xml:id="rtlchange">
<title>RTL/xdc/tcl files to change</title>
<tgroup cols="2">
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="25*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">File name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Changes done</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row><entry><para>hardware/hdl/core/psl_accel_${FPGACARD}.vhd_source</para></entry><entry><para> specific to card</para></entry></row>
<row><entry><para>hardware/hdl/core/psl_accel_types.vhd_source</para></entry><entry><para>specific to card</para></entry></row>
<row><entry><para>hardware/hdl/core/psl_fpga_${FPGACARD}.vhd_source</para></entry><entry><para> specific to card</para></entry></row>
<row><entry><para>hardware/setup/${FPGACARD}/capi_bsp_pblock.xdc</para></entry><entry><para> specific to card</para></entry></row>
<row><entry><para>hardware/setup/${FPGACARD}/snap_${FPGACARD}.xdc</para></entry><entry><para> specific to card</para></entry></row>
<row><entry><para>hardware/setup/${FPGACARD}/snap_ddr4pins.xdc</para></entry><entry><para> specific to card</para></entry></row>
<row><entry><para>hardware/setup/build_mcs.tcl</para></entry><entry><para>declare card name</para></entry></row>
<row><entry><para>hardware/setup/create_framework.tcl</para></entry><entry><para>declare card name</para></entry></row>
<row><entry><para>hardware/setup/create_snap_ip.tcl</para></entry><entry><para>declare card name and its IP</para></entry></row>
<row><entry><para>hardware/setup/flash_mcs.tcl</para></entry><entry><para>declare card name</para></entry></row>
<row><entry><para>hardware/setup/snap_bitstream_post.tcl</para></entry><entry><para>declare card name</para></entry></row>
<row><entry><para>hardware/setup/snap_bitstream_pre.tcl</para></entry><entry><para>declare card name</para></entry></row>
<row><entry><para>hardware/setup/snap_bitstream_step.tcl</para></entry><entry><para>declare card name</para></entry></row>
<row><entry><para>hardware/setup/snap_impl_step.tcl</para></entry><entry><para>declare card name</para></entry></row>
<row><entry><para>hardware/snap_check_psl</para></entry><entry><para>declare card name</para></entry></row>
</tbody>
</tgroup>
</table>

<table frame="all" pgwide="1" xml:id="swchange">
<title>Software files to change</title>
<tgroup cols="2">
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="25*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">File name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Changes done</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row><entry><para>software/lib/snap.c</para></entry><entry><para>declare card name</para></entry></row>
<row><entry><para>software/tools/snap_find_card</para></entry><entry><para>declare card name + id</para></entry></row>
<row><entry><para>software/include/snap_regs.h</para></entry><entry><para>SNAP registers - setting</para></entry></row>
</tbody>
</tgroup>
</table>

<table frame="all" pgwide="1" xml:id="otherchange">
<title>Other files to change</title>
<tgroup cols="2">
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="25*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">File name</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">Changes done</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row><entry><para>actions/scripts/snap_jenkins.sh</para></entry><entry><para>jenkins tests (optional)</para></entry></row>
<row><entry><para>defconfig/{FPGACARD}*.defconfig</para></entry><entry><para>For silent jenkins testing (optional)</para></entry></row>
<row><entry><para>README.md</para></entry><entry><para>Announce a new card is supported </para></entry></row>
</tbody>
</tgroup>
</table>


</section>
</section>
</chapter>



323
enable_capi_snap/ch_example.xml
Unescape Escape View File

@ -0,0 +1,323 @@
<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<chapter version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_examples">
<!-- Chapter Title goes here. -->
<title>Enable CAPI2 card</title>
<section>
<title>Section Title goes here</title>
<para>This Section covers something of interest to a limited number of people and shows a 1st level section</para>

<section xml:id="list_example_label">
<title>Example Itemized List</title>
<para>
Here is an example of an itemized list</para>
<itemizedlist>
<title>A list title is completely optional</title>
<listitem>
<para>
Item you don't care about</para>
<itemizedlist>
<listitem>
<para>Perhaps you'd like a sub-list</para>
<itemizedlist>
<listitem>
<para>Oooh, here's about another</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Item you might care about </para>
</listitem>
<listitem>
<para>
Item you do care about </para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Example ordered list</title>
<para>
All good documents need ordered lists.</para>
<orderedlist>
<title>Another purely optional title</title>
<listitem>
<para>First item</para>
</listitem>
<listitem>
<para>Second item</para>
<orderedlist numeration="loweralpha">
<listitem>
<para>first indented item</para>
</listitem>
<listitem>
<para> second indented item</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Third item</para>
</listitem>
</orderedlist>
</section>

<section>
<title>Example figure with embedded graphic</title>
<para>
Here is how you embed a graphic.</para>
<figure pgwide="1" xml:id="figure_label">
<title>Example figure</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/example_graphic.bmp" format="BMP" scalefit="1" width="100%" />
</imageobject>
</mediaobject>
</figure>
<note><para>Raw images such as the bitmap (bmp) file above may become blurry as they are scaled.
Scalable graphic formats like SVG (Scalable Vector Graphics) embed and scale the best.</para></note>
</section>

<section>
<title>Example table</title>
<para>Of course all good documents need tables. Here's how you build a basic table.</para>

<table frame="all" pgwide="1" xml:id="table_label">
<title>Example Table Title</title>
<tgroup cols="4">
<colspec colname="c1" colwidth="25*" />
<colspec colname="c2" colwidth="25*" />
<colspec colname="c3" colwidth="25*" />
<colspec colname="c4" colwidth="25*" />
<thead>
<row>
<entry>
<para>
<emphasis role="bold">1st Column Heading</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">2nd Column Heading</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">3rd Column Heading</emphasis>
</para>
</entry>
<entry>
<para>
<emphasis role="bold">4th Column Heading</emphasis>
</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para>Yes</para>
</entry>
<entry>
<para><phrase role="color:red">Red</phrase></para>
<para><phrase role="color:green">Green</phrase></para>
<para><phrase role="color:blue">Blue</phrase></para>
<para><phrase role="color:#FFBF00">Custom (Amber)</phrase></para>
</entry>
<entry>
<para>MAIN_Junk</para>
</entry>
<entry>
<para>More_Junk</para>
</entry>
</row>
<row>
<entry namest='c1' nameend='c3' align='center'>
<para>merged cells horizontal</para>
</entry>
<entry>
<para>cell_stuff</para>
</entry>
</row>
<row>
<entry morerows='1'>
<para>Merge cells vertical</para>
</entry>
<entry>
<para>filler</para>
</entry>
<entry namest='c3' nameend='c4' morerows='1' align='center'>
<para>merge cells both ways</para>
</entry>
</row>
<row>
<entry>
<para>filler 2</para>
</entry>
</row>
<row>
<entry>
<para>How about we put a list in the table cell</para>
<itemizedlist>
<listitem>
<para>item 1</para>
</listitem>
<listitem>
<para>item 2</para>
</listitem>
<listitem>
<para>item 2</para>
</listitem>
</itemizedlist>
</entry>
<entry>
<para>Another Cell</para>
</entry>
<entry>
<para>Yet Another Cell</para>
</entry>
<entry>
<para>Finally the last cell</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Example of crossreferences and footnotes</title>
<para>To reference another section or table is pretty easy. For example: see <xref linkend="table_label" /> for how tables look.</para>
<para>Lists are shown in <xref linkend="list_example_label" /> and if you need to make a footnote
<footnote xml:id="foot_id"><para>The footnote text goes here and can reference something like <xref linkend="figure_label" /> for additional explanation.</para></footnote>
For clarification that is easy. Of course you might want an additional reference to the footnote <footnoteref linkend="foot_id"/> which can also be done easily.</para>
<para>Lastly you probably want to mark text by making it <emphasis>italic text example</emphasis> or <emphasis role='bold'>Bold Text Example</emphasis>.</para>
</section>
<section>
<title>Example of code citations and user input</title>
<para>When showing user input, you want a nice sceen-looking layout, a prompt, monospace text, and a way to differentiate input from output. Here's an example:
<screen><prompt>$ </prompt><userinput>echo "Hello world"</userinput>
Hello world
<prompt>$ </prompt></screen>
</para>
<para>Docbook also allows for formatting and display of common languages, allowing for whitespace
and line returns just as they are written. Here's a sample snippet of C code with line numbering enabled:<programlisting linenumbering="numbered"><![CDATA[#include<stdio.h>
main()
{
printf("Hello world\n");
}]]></programlisting></para>
<para>If code formatting is not quite what you need, simply displaying text "literally" may suffice as follows: <literal>This is my literal
text. It ignores whitespace.</literal></para>
</section>
<section>
<title>Example of special characters in text</title>
<para>Sometimes in text you need special characters. These can be provided using their UNICODE values such as &#8800; (&amp;#8800),
&#x2126; (&amp;#x2126), and &#8710; (&amp;#8710;).
These can be "coded" using the form <literal>&amp;#</literal><emphasis>ddddd</emphasis><literal>;</literal> where <emphasis>ddddd</emphasis> is
the up to five digit decimal representation of the character. The form <literal>&amp;#x</literal><emphasis>hhhh</emphasis><literal>;</literal> where
<emphasis>hhhh</emphasis> is the up to 4 digit hexidecimal representation of the character.</para>
<para>This formatting works well as long as the symbol to which you are referring is contained in the font set
used for the document -- Arimo for standard text and Cousine for monospace. If when building a document, you see a message like
"WARNING, Glyph...not available in font 'Arimo',"
see <xref linkend="symbol_font" /> in <xref linkend="docbook_extensions" /> for details on using the provided symbol fonts explicitly.</para>
</section>
<xi:include href="sec_example.xml"/>
<section xml:id="docbook_extensions">
<title>Examples of OpenPOWER Foundation Docbook extensions</title>
<para>The OpenPOWER Foundation Maven Plugin supports a number of extensions that are not pure Docbook. These are:</para>

<simplesect>
<title>Setting text color explicitly</title>
<para>Text color can be controlled using <literal>&lt;phrase role="color:</literal><emphasis>color_name</emphasis><literal>"&gt;</literal>
tag where <emphasis>color_name</emphasis> contains the color setting. For example, this
text:<programlisting><![CDATA[<para role="color:red">A red sentence contains a <phrase role="color:blue">blue</phrase> word.</para>]]></programlisting> produces this sentence:</para>
<para role="color:red">A red sentence contains a <phrase role="color:blue">blue</phrase> word.</para>
<para>Valid colors include either a keyword color name or a numerical RGB specification. Keyword names are common with the HTML 4 specificiation:
<literal>aqua</literal>, <literal>black</literal>, <literal>blue</literal>, <literal>fuchsia</literal>, <literal>gray</literal>,
<literal>green</literal>, <literal>lime</literal>, <literal>maroon</literal>, <literal>navy</literal>, <literal>olive</literal>,
<literal>purple</literal>, <literal>red</literal>, <literal>silver</literal>, <literal>teal</literal>, <literal>white</literal>,
and <literal>yellow</literal>. Additionally, RGB values can be <literal>#nnnnnn</literal> where <literal>nnnnnn</literal> is a hexidecimal color value or
<literal>rgb(n1, n2, n3)</literal> where <literal>n1</literal>, <literal>n2</literal>, and <literal>n3</literal> are integers 0-255.</para>
<para>This tag has also been implemented on the following tags: <literal>&lt;thead&gt;</literal>,
<literal>&lt;tbody&gt;</literal>, and <literal>&lt;tfoot&gt;</literal>.</para>
<warning><para>This parameter should only be used for tags listed above.</para></warning>
</simplesect>
<simplesect>
<title>Inserting line breaks</title>
<para>Line breaks can be introduced using <literal>&lt;?linebreak?&gt;</literal> tags. For example, this
text:<programlisting><![CDATA[<para>A line break <?linebreak?> in the middle of text</para>]]></programlisting> produces this sentence:</para>
<para>A line break <?linebreak?> in the middle of text</para>
<para>This tag becomes useful in table text spacing.</para>
</simplesect>
<simplesect>
<title>Inserting page breaks</title>
<para>Page breaks can be introduced using <literal>&lt;?hard-pagebreak?&gt;</literal> tags. For example, this
text:<programlisting><![CDATA[<para>A page break</para> <?hard-pagebreak?> <para>Between two paragraphs</para>]]></programlisting> produces this output:</para>
<para>A page break</para> <?hard-pagebreak?> <para>Between two paragraphs</para>
<para>This tag becomes useful in placing tables on page. Placing this statement before a large table may prevent it from spanning a page.</para>
<warning><para>Because the XSL template behind the Processing Instruction generates
a <programlisting><![CDATA[<fo:block break-after='page'/>]]></programlisting> in
the book FO output, this instruction should be used in the outer most blocks of a section to work effectively. Use inside lists and other structural
components may result in the text after the break being dropped. <emphasis role="bold">User beware!</emphasis>.</para></warning>
</simplesect>
<simplesect>
<title>Varying the font size</title>
<para>Font sizes can also be set using the
<literal>&lt;phrase role="font-size:</literal><emphasis>size</emphasis><literal>"&gt;</literal>
tag where <emphasis>size</emphasis> contains a size value such as "6pt" or "50%" or "1.5em".</para>
<para>For example, a paragraph can be made to be 6 point as follows:<programlisting><![CDATA[<para>A sentence that contains some <phrase role="font-size:6pt">6pt font</phrase>,
<phrase role="font-size:50%">50% font</phrase>, and
<phrase role="font-size:1.5em">1.5em font</phrase> in it.</para>]]></programlisting> produces this output:</para>
<para>A sentence that contains some <phrase role="font-size:6pt">6pt font</phrase>,
<phrase role="font-size:50%">50% font</phrase>, and <phrase role="font-size:1.5em">1.5em font</phrase> in it.</para>
<para>This tag has also been implemented on the following tags: <literal>&lt;para&gt;</literal>,
<literal>&lt;thead&gt;</literal>, <literal>&lt;tbody&gt;</literal>, and <literal>&lt;tfoot&gt;</literal>.</para>
<warning><para>This parameter should only be used for tags listed above.</para></warning>
</simplesect>
<simplesect xml:id="symbol_font">
<title>Using additional symbols</title>
<para>If you find that the Arimo and Cousine fonts do not contain the special symbol you need
for your document, you may use the additional symbol font provided for document (STIX Two Math).
Due to an unimplemented feature in the Apach FO Processor, selection of this
font needs to be explicitly performed using the
<literal>&lt;symbol role="symbolfont"&gt;</literal> wrapper around your symbol value.</para>
<para>For example, the symbol coding of <programlisting><![CDATA[&#x2A01;]]></programlisting> should produce
a circle with a cross in here "&#x2A01;", but instead creates a "Glyph...not available in font 'Arimo'" error
on document build and the PDF renders as a "#".</para>
<para>Re-coding this to use <programlisting><![CDATA[<symbol role="symbolfont">&#x2A01;</symbol>]]></programlisting> produces
the correct symbole here "<symbol role="symbolfont">&#x2A01;</symbol>".</para>
<para>If this still does not provide the symbol you expected, double check the code and the font maps found at
<link xlink:href="http://www.stixfonts.org/charactertable.html">http://www.stixfonts.org/charactertable.html</link>.</para>
</simplesect>
</section>

</section>
</chapter>

207
enable_capi_snap/ch_genpsl_capi10.xml
Unescape Escape View File

@ -0,0 +1,207 @@
<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!--
About the XML editing:
It's really hard. I am using gvim (Macvim)
I downloaded a filetype plugin from https://github.com/othree/xml.vim.git
(git clone it, and copy the ftplugin folder into your ~/.vim folder. )
It helps a little bit. use ':help xml-plugin' to see what it has.


BTW, I also turned on spelling checking by ':set spell spelllang=en_us' in vim.
You can put it into your ~/.vimrc (no comma needed).
If you want to disable the spell checking,just ':set nospell'

There is another trick. You will find that the spelling checker doesn't work
for your paragraphs. I found an alternative way is to ':set filetype=html'


-->
<chapter version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chapter_psl">
<!-- Chapter Title goes here. -->
<title>Work with CAPI1.0 HDK project</title>

<note>
<para>
Ask your contact representative or write to capi@us.ibm.com to get a CAPI1.0 HDK project to start. This chapter only works for CAPI1.0, running on Power8. </para>
</note>
<section> <title>Steps and directory structure</title>
<para>We use an "Out-of-context" flow to generate a PSL dcp file. For a new FPGA card, following steps need to be done:</para>
<figure pgwide="1" xml:id="step4">
<title>Four steps to build a PSL checkpoint</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/psl-4steps.png" format="PNG" scalefit="1" width="80%" align="center" />
</imageobject>
</mediaobject>
</figure>
<para>We use an "Out-of-context" flow to generate a PSL dcp file. The directory structure is as following:</para>
<figure pgwide="1" xml:id="hdk-dir">
<title>HDK directory structure</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/hdk-structure.png" format="PNG" scalefit="1" width="90%" align="center" />
</imageobject>
</mediaobject>
</figure>
<para>
In <emphasis role="bold">build_dir/Sources</emphasis>
</para>
<itemizedlist>
<listitem><para>The "prj" directory includes the source file lists.</para></listitem>
<listitem><para>The "top" directory includes the top design file "psl_fpga.vhdl" and the wrapper for AFU "psl_accel.vhdl"</para></listitem>
<listitem><para>PSL source files are in "psl" directory.</para></listitem>
<listitem><para>AFU source files are in "afu" directory.</para></listitem>
<listitem><para>"cores" includes 4 Xilinx IP cores used by PSL.</para></listitem>
<listitem><para>"xdc" are the constraint files used by PSL and the top design.</para></listitem>
</itemizedlist>
<para>In build_dir, psl_fpga.tcl is the script "entrance". It assigns the FPGA chip information, and the build flow. </para>
<para>FPGA chip information is needed for a new FPGA card, for example:</para>
<screen>set device "xcku115"
set package "-flva1517"
set speed "-2-e"</screen>
<para>And some controlling bits are for two build flows:</para>
<para>1. Build a PSL checkpoint.</para>
<para>2. Build a whole FPGA image (including AFU).</para>

</section>
<section><title>Generate PSL Checkpoint (b_route_design.dcp)</title>
<para>In this section, we just talk about the first build flow - "build a PSL checkpoint". Read it when you need to enable a FPGA card on CAPI1.0 or to fix a bug and update b_routed_design.dcp. The controlling bits should be set as:</para>
<screen>####flow control
set run.topSynth 1
set run.oocSynth 1
set run.tdImpl 0
set run.oocImpl 1
set run.topImpl 0
set run.flatImpl 0</screen>
<para>The outfile file will be placed in "Checkpoint" directory, the file name is "b_route_design.dcp".</para>

<section><title>Upgrade Xilinx IP cores</title>
<para>When a FPGA chip type is changed, or the Vivado tool version has been upgraded, you need to upgrade the Xilinx IP cores that are used in PSL module. PSL module has instantiated four Xilinx IP cores (in Sources/cores):</para>
<itemizedlist>
<listitem><para>pcie3_ultrascale_0</para></listitem>
<listitem><para>sem_ultra_0 (Soft Error Migration)</para></listitem>
<listitem><para>clk_wiz_0</para></listitem>
<listitem><para>tx_wr_fifo</para></listitem>
</itemizedlist>
<para>Steps to upgrade them:</para>
<orderedlist>
<listitem><para>Open Vivado GUI</para></listitem>
<listitem><para>Create a new project. For the second time, just open the project with the four IP cores.</para></listitem>
<listitem><para>Import IP cores (by importing *.xci files under "Source/cores/xxx" directory). For the second time, this step is not needed.</para></listitem>
<listitem><para>Set FPGA type in Project Settings.</para></listitem>
<listitem><para>Run "Tools->Report->Report IP Status"</para></listitem>
<listitem><para>"Upgrade All" and read the upgrade log.</para></listitem>
</orderedlist>
<figure pgwide="1" xml:id="ip-update">
<title>Small project to update IPs</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/ip-update.png" format="PNG" scalefit="1" width="100%" align="center" />
</imageobject>
</mediaobject>
</figure>
<figure pgwide="1" xml:id="report-ip">
<title>Report IP Status</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/report-ip.png" format="PNG" scalefit="1" width="70%" align="center" />
</imageobject>
</mediaobject>
</figure>
<note>
<para>For PCIe IP, you need to change subsystem_id for a new card. Right click pcie3_ultrascale_0 -> Reconfig IP and change the subsystem ID field. </para>
<para>Ask an IBM representative for the subsystem ID. </para>
</note>
</section>
<section><title>Input xdc files</title>
<para>The IO pin package information for the new card should be provided by card vendor. Generally, they include Flash Interface, PCIe Interface and other interfaces like I2C and LED. Sample code with IO pins in b_phys.xdc:</para>
<para>Refer to Xilinx document UG575 for detailed pin package information.</para>
<para>Example:</para>
<screen>set_property PACKAGE_PIN AJ15 [get_ports {o_flash_a[1]}]
set_property PACKAGE_PIN AK15 [get_ports {o_flash_a[2]}]
set_property PACKAGE_PIN AH14 [get_ports {o_flash_a[3]}]

set_property IOSTANDARD LVCMOS18 [get_ports {o_flash_a[1]}]
set_property IOSTANDARD LVCMOS18 [get_ports {o_flash_a[2]}]
set_property IOSTANDARD LVCMOS18 [get_ports {o_flash_a[3]}]</screen>
<para>Some other constraints also must be updated for the new selection of FPGA chip. It defines the floorplan for PSL. </para>
<note>
<para>There is also a patch to keep VSEC address for Vivado2017.4 and newer Vivado version:</para>
<screen>set_property PF0_SECONDARY_PCIE_CAP_NEXTPTR 12'h400 [get_cells *pcihip0/psl_pcihip0_inst/inst/pcie3_uscale_top_inst/pcie3_uscale_wrapper_inst/PCIE_3_1_inst]</screen>
<para>This is the base address for VSEC registers. capi-utils uses it to set the register address to send bitstream data to flash controller.</para>
<para><emphasis role="bold">Update:</emphasis>This step is not needed after "ECAP update (#28)" commit of capi-utils in Feb 2018.</para>
</note>

</section>
<section><title>Run Vivado to generate PSL checkpoint</title>
<screen>vivado -mode batch -source psl_fpga.tcl -notrace</screen>
<para>The checkpoint file b_route_design.dcp will be generated and put in "Checkpoint" directory. With this checkpoint file, we can continue to build a full FPGA bit image and validate it on hardware.</para>
</section>
</section>

<section><title>Generate full FPGA image</title>
<section><title>Steps</title>
<figure pgwide="1" xml:id="full-steps">
<title>Steps to build the full FPGA image</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/full-steps.png" format="PNG" scalefit="1" width="70%" align="center" />
</imageobject>
</mediaobject>
</figure>
<para>This time the controlling bits should be set to:</para>
<screen>####flow control
set run.topSynth 1
set run.oocSynth 0
set run.tdImpl 0
set run.oocImpl 0
set run.topImpl 1
set run.flatImpl 0</screen>
</section>
<section><title>Check top design file psl_fpga.vhdl</title>
<para>For a new card, the IO pins and functions may be different to your reference card design. So the logic in top file psl_fpga.vhdl needs to be updated.</para>
<para>Similarly, the xdc file "……topimp.xdc" also needs to be updated.</para>
</section>
<section><title>Prepare filelist for psl_fpga.prj</title>
<para>The "prj" file is a file list. It should contain all the AFU design files. Edit it.</para>
</section>
<section><title>Run Vivado</title>
<para>Two sub steps are here.</para>
<screen>vivado -mode batch -source psl_fpga.tcl -notrace</screen>
<para>Now the bit file is generated</para>
<screen>vivado -mode batch -source write_bitstream.tcl -notrace</screen>
<para>Now you get the bin files to be program to the FPGA flash.</para>

<para>For more information about FPGA configuration, please refer to Xilinx Document UG570.</para>
<para>Then you can program the generated bin file to FPGA either by JTAG or on-line programming tools <link xlink:href="https://github.com/ibm-capi/capi-utils">capi-utils</link></para>
</section>
</section>


</chapter>



94
enable_capi_snap/ch_introduction.xml
Unescape Escape View File

@ -0,0 +1,94 @@
<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!--
About the XML editing:
It's really hard. I am using gvim (Macvim)
I downloaded a filetype plugin from https://github.com/othree/xml.vim.git
(git clone it, and copy the ftplugin folder into your ~/.vim folder. )
It helps a little bit. use ':help xml-plugin' to see what it has.


BTW, I also turned on spelling checking by ':set spell spelllang=en_us' in vim.
You can put it into your ~/.vimrc (no comma needed).
If you want to disable the spell checking,just ':set nospell'

There is another trick. You will find that the spelling checker doesn't work
for your paragraphs. I found an alternative way is to ':set filetype=html'


-->
<chapter version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="chapter_introduction">
<!-- Chapter Title goes here. -->
<title>Introduction</title>

<section> <title>What is CAPI</title>
<para>CAPI stands for "Coherent Accelerator Processor Interface" which enables FPGA to access Host memory by virtual address. You can find more introduction about this interface on <link xlink:href="https://developer.ibm.com/linuxonpower/capi/">https://developer.ibm.com/linuxonpower/capi/</link>. It is an important feature to develop hardware accelerators in heterogeneous computing. In this document, the "hardware accelerators" are built on FPGA. </para>
<figure pgwide="1" xml:id="capi1">
<title>CAPI(1.0 and 2.0) basic concept</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/capi1.png" format="PNG" scalefit="1" width="70%" />
</imageobject>
</mediaobject>
</figure>
<para>A complete accelerator has software part (APP, or Applications) running on CPU Processor and the hardware part (AFU, Acceleration Function Unit) running on FPGA chip. APP and AFU are sharing host memory, that means, they both can read and write the 2^64 range of virtual memory address. To make it happen, CAPI technology has a CAPP (Coherent Acceleration Processor Proxy) logic unit in Processor chip, and also needs a PSL (Processor Service Layer) logic unit in FPGA chip. For CAPI1.0 and CAPI2.0, the interconnection between processor and FPGA is using PCIe physical links and PCIe form factor. CAPI1.0 uses PCIe Gen3x8 and CAPI2.0 uses PCIe Gen4x8 or Gen3x16. (For OpenCAPI, the physical links and the connected datalink layer and transportation layer all change to OpenCAPI. Please check <link xlink:href="https://opencapi.org">https://opencapi.org</link> for more information. It is not covered in this document.)</para>
</section>
<section> <title>HDK and SNAP</title>
<para> Let's focus on the FPGA side.</para>
<para> A customer FPGA card needs to have a PSL module (Processor Service Interface) to become a "CAPI-enabled" card. This PSL module is provided by IBM. For CAPI1.0, it is in the form of a post-implemented dcp file (Xilinx Vivado design checkpoint). For CAPI2.0, it is encrypted source code. They can be downloaded at <link xlink:href="https://www.ibm.com/systems/power/openpower">https://www.ibm.com/systems/power/openpower</link>. From the menu, select "CAPI","Coherent Accelerator Processor Interface (CAPI)" or directly click the "CAPI" icon to go to the CAPI section. Then download the appropriate files depending on your target system being POWER8 (CAPI 1.0) or POWER9 (CAPI 2.0). You need to register an IBM ID to download them.</para>
<para>A project from FPGA Vendors (i.e, a Xilinx Vivado project), including PSL module and sample user logic (AFU), is delivered to acceleration developers. This project is called HDK (Hardware Development Kit). </para>
<figure pgwide="1" xml:id="hdk1">
<title>Develop an acceleration on HDK</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/hdk.png" format="PNG" scalefit="1" width="80%" align="center"/>
</imageobject>
</mediaobject>
</figure>

<para>Working on HDK, developers need to know the details about PSL interface specifications. You can find <link xlink:href="http://openpowerfoundation.org/wp-content/uploads/resources/psl-afu-spec/content/go01.html"> CAPI1.0 PSL Spec</link> and <link xlink:href="http://openpowerfoundation.org/wp-content/uploads/resources/v2-psl-afu-spec/content/ch_preface.html"> CAPI2.0 PSL Spec</link> or search "PSL/AFU interface" in your web browser. But they have differences. To hide the differences on the interface and provide an industry standard interface protocol (AXI), we also created SNAP framework. </para>
<para>SNAP is the abbreviation of Storage, Networking and Analytics Programming. It is an open-source framework <link xlink:href="https://github.com/open-power/snap"> https://github.com/open-power/snap</link>. On the FPGA side, SNAP framework adds a PSL/AXI bridge, a DDR SDRAM controller and an optional NVMe controller. Thus, the developer can focus on their acceleration kernel logic (here we call it hardware action) and interface the framework via several AXI ports. </para>
<figure pgwide="1" xml:id="snap1">
<title>Develop an acceleration on SNAP</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/snap.png" format="PNG" scalefit="1" width="90%" align="center" />
</imageobject>
</mediaobject>
</figure>

<para> For both CAPI1.0 and CAPI2.0, people can choose to work on HDK or on SNAP. The preferred way is to work on SNAP. In the following chapters, we will introduce:</para>
<itemizedlist>
<listitem><para> Enable a FPGA card in SNAP </para></listitem>
<listitem><para> Generate a PSL Checkpoint (CAPI1.0 only) </para></listitem>
<listitem><para> Work with HDK (CAPI1.0) </para></listitem>
<listitem><para> Work with HDK (CAPI2.0) </para></listitem>
</itemizedlist>

<para>For most of the new cards on Power9, just reading the chapter of "Enable a FPGA card in SNAP" is enough. You can find abundant materials on how to develop an accelerator with SNAP (Training videos, "docs" folder on github, or other webpages) so they are not discussed in this document.</para>
</section>
</chapter>



BIN
enable_capi_snap/figures/.DS_Store vendored
View File

Binary file not shown.

BIN
enable_capi_snap/figures/afu.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 307 KiB

BIN
enable_capi_snap/figures/base_image.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 518 KiB

BIN
enable_capi_snap/figures/bsp.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 527 KiB

BIN
enable_capi_snap/figures/capi1.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 749 KiB

BIN
enable_capi_snap/figures/full-steps.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
enable_capi_snap/figures/hdk-structure.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 88 KiB

BIN
enable_capi_snap/figures/hdk.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 97 KiB

BIN
enable_capi_snap/figures/ip-update.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 111 KiB

BIN
enable_capi_snap/figures/psl-4steps.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
enable_capi_snap/figures/report-ip.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 52 KiB

BIN
enable_capi_snap/figures/snap-structure.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 109 KiB

BIN
enable_capi_snap/figures/snap-structure_white.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 103 KiB

BIN
enable_capi_snap/figures/snap.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 100 KiB

161
enable_capi_snap/pom.xml
Unescape Escape View File

@ -0,0 +1,161 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>

<groupId>org.openpowerfoundation.docs</groupId>
<artifactId>workgroup-pom</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<modelVersion>4.0.0</modelVersion>

<!-- TODO: Rename the artifactID field to some appropriate for your new document -->
<artifactId>todo-artifact_id</artifactId>

<packaging>jar</packaging>
<!-- TODO: Rename the name field to some appropriate for your new document -->
<name>enable-fpga-to-capi-snap</name>

<properties>
<!-- This is set by Jenkins according to the branch. -->
<release.path.name></release.path.name>
<comments.enabled>0</comments.enabled>
</properties>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- ################################################ -->
<build>
<plugins>
<plugin>

<groupId>org.openpowerfoundation.docs</groupId>

<artifactId>openpowerdocs-maven-plugin</artifactId>
<!-- version set in ../pom.xml -->
<executions>
<execution>
<id>generate-webhelp</id>
<goals>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<!-- These parameters only apply to webhelp -->
<enableDisqus>${comments.enabled}</enableDisqus>
<disqusShortname>openpower-template-guide</disqusShortname>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
<generateToc>
appendix toc,title
article/appendix nop
article toc,title
book toc,title,figure,table,example,equation
book/appendix nop
book/chapter nop
chapter toc,title
chapter/section nop
section toc
part toc,title
reference toc,title
set toc,title
</generateToc>
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
<sectionAutolabel>1</sectionAutolabel>
<tocSectionDepth>1</tocSectionDepth>
<sectionLabelIncludesComponentLabel>1</sectionLabelIncludesComponentLabel>

<!-- TODO: Rename the webhelpDirname field to the new directory for new document -->
<webhelpDirname>enable-fpga-to-capi-snap</webhelpDirname>

<!-- TODO: Rename the pdfFilenameBase field to the PDF name for new document -->
<pdfFilenameBase>enable-fpga-to-capi-snap</pdfFilenameBase>

<!-- TODO: Define the appropriate work product type. These values are defined by the IPR Policy.
Consult with the Work Group Chair or a Technical Steering Committee member if you have
questions about which value to select.
If no value is provided below, the document will default to "Work Group Notes".-->
<!--workProduct>workgroupNotes</workProduct-->
<workProduct>workgroupSpecification</workProduct>
<!-- workProduct>candidateStandard</workProduct -->
<!-- workProduct>openpowerStandard</workProduct -->

<!-- TODO: Set the appropriate security policy for the document. For documents
which are not "public" this will affect the document title page and
create a vertical running ribbon on the internal margin of the
security status in all CAPS. Values and definitions are formally
defined by the IPR policy. A layman's definition follows:

public = this document may be shared outside the
foundation and thus this setting must be
used only when completely sure it allowed
foundationConfidential = this document may be shared freely with
OpenPOWER Foundation members but may not be
shared publicly
workgroupConfidential = this document may only be shared within the
work group and should not be shared with
other Foundation members or the public

The appropriate starting security for a new document is "workgroupConfidential". -->
<security>workgroupConfidential</security>
<!-- security>foundationConfidential</security -->
<!-- security>public</security -->

<!-- TODO: Set the appropriate work flow status for the document. For documents
which are not "published" this will affect the document title page
and create a vertical running ribbon on the internal margin of the
security status in all CAPS. Values and definitions are formally
defined by the IPR policy. A layman's definition follows:

published = this document has completed all reviews and has
been published
draft = this document is actively being updated and has
not yet been reviewed
review = this document is presently being reviewed

The appropriate starting security for a new document is "draft". -->
<documentStatus>draft</documentStatus>
<!-- documentStatus>review</documentStatus -->
<!-- documentStatus>published</documentStatus -->

</configuration>
</execution>
</executions>
<configuration>
<!-- These parameters apply to pdf and webhelp -->
<xincludeSupported>true</xincludeSupported>
<sourceDirectory>.</sourceDirectory>
<includes>
<!-- TODO: If you desire, you may change the following filename to something more appropriate for the new document -->
bk_main.xml
</includes>

<!-- **TODO: Set to the correct project URL. This likely needs input from the TSC. -->
<!-- canonicalUrlBase>http://openpowerfoundation.org/docs/template-guide/content</canonicalUrlBase -->
<glossaryCollection>${basedir}/../glossary/glossary-terms.xml</glossaryCollection>
<includeCoverLogo>1</includeCoverLogo>
<coverUrl>www.openpowerfoundation.org</coverUrl>
</configuration>
</plugin>
</plugins>
</build>
</project>

25
enable_capi_snap/sec_example.xml
Unescape Escape View File

@ -0,0 +1,25 @@
<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_example">

<title>Sample section include </title>
<para>This section was developed in a separate file but included in the document by using the following
text:<programlisting><![CDATA[ <xi:include href="sec_example.xml"/>]]></programlisting>
where <literal>sec_example.xml</literal> is the source file name.</para>

</section>

4
pom.xml
Unescape Escape View File

@ -17,8 +17,6 @@
<modules> <modules>
<!-- TODO: Add new documents are build in the project, add their directories to this list to <!-- TODO: Add new documents are build in the project, add their directories to this list to
enable all document builds from the top level --> enable all document builds from the top level -->
<module>doc_dev_guide</module> <module>enable_capi_snap</module>
<module>doc_template</module>
<module>errata_template</module>
</modules> </modules>
</project> </project>

Write Preview
Loading…
Cancel
Save