CAPI-SNAP-Doc/enable_capi_snap/ch_introduction.xml

<!--
  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 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.</para>
    <para> CAPI1.0 uses PCIe Gen3x8. </para>
    <para> CAPI2.0 uses PCIe Gen4x8 or Gen3x16.</para>
    <para> OpenCAPI is not covered in this document. Visit <link xlink:href="https://opencapi.org">https://opencapi.org</link> for more information. </para>
  </section>
  
  
  <section> <title>Enable PSL IP on FPGA</title>
  <para>This document only applies to the cards using Xilinx FPGA chips.</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 OpenPower Foundation. </para>
  <itemizedlist>
     <listitem><para> For CAPI1.0, PSL module and the surrounding board specific modules are provided in the form of a routed dcp file (Xilinx Vivado design checkpoint). It's usually called b_route_design.dcp. </para></listitem>
     <listitem><para> For CAPI2.0, PSL is an IP package with encrypted source code. It's named like ibm.com_CAPI_PSL9_WRAP_2.00.zip.</para></listitem>
   </itemizedlist> 
   <para> 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>Users can develop CAPI accelerators in two modes: HDK and SNAP.</para>
   <para>HDK is the abbreviation of Hardware Development Kit. As shown in the diagram below, on the FPGA side, the Xilinx Vivado project includes two parts: BSP (Board Supporting Package, containing PSL module) and AFU (Acceleration Function Unit). How to generate BSP will be introduced in Chapter <xref linkend="chapter_capi20_bsp" endterm="chapter_capi20_bsp_title"/></para>   
    <figure pgwide="1" xml:id="hdk1">
        <title>Develop an accelerator in HDK mode</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/hdk.png" format="PNG" scalefit="1" width="80%" align="center"/>
          </imageobject>
        </mediaobject>
    </figure> 

    <para>AFU is where to implement user-defined functions. The developer working on AFU needs to understand the protocol between AFU and BSP, which is called PSL/AFU interface specification. Please refer to <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. </para>
    <para>When developing an acceleration, <link xlink:href="https://github.com/ibm-capi/pslse">PSLSE</link> (PSL Simulation Engine) is also needed to make a software-hardware co-simulation which guarantees the correctness of accelerator design. </para>
    <para>When deploying the acceleration to OpenPower servers, it requires user library <link xlink:href="https://github.com/ibm-capi/libcxl">libcxl</link> and kernel module <userinput>cxl</userinput> to run the application. </para>
    <para>In all, HDK mode will provide the maximum control, utilization of resources and shortest latency. However, SNAP mode simplifies and standardizes the application development significantly and is more recommended.</para>
   </section>

  <section> <title>SNAP</title>
          <para>SNAP is the abbreviation of Storage, Networking and Analytics Programming. It is an open-source acceleration development framework <link xlink:href="https://github.com/open-power/snap"> https://github.com/open-power/snap</link>. The benefits are: </para>
          <orderedlist>
          <listitem><para>On the FPGA side, SNAP framework adds a bridge to provide AXI interface to developers. So the developer can focus on acceleration function logic design, and doesn't need to study the details of PSL interface specification. AXI is the defacto industry standard for on-chip bus interconnections and is part of <link xlink:href="https://www.arm.com/products/silicon-ip-system/embedded-system-design/amba-specifications">AMBA (Advanced Microcontroller Bus Architecture)</link>.</para></listitem>
          <listitem><para>It also provides DDR SDRAM controller and an optional NVMe controller. The developer can use the card memory or storage directly.</para></listitem>
          <listitem><para>SNAP supports using HLS (High Level Synthesis) to develop the acceleration functional unit ("Hardware Action" in yellow box). Developers can write C++ functions and Vivado HLS will compile/convert them to Verilog or VHDL design automatically.</para></listitem>
          <listitem><para>A new layer of user library "libsnap" provides more convenient APIs.</para></listitem>
          <listitem><para>SNAP is an integrated developing environment that the developer can configure, create Vivado project, run co-simulation or build bitstream with simple commands.</para></listitem>
          <listitem><para>Many action examples help new developers to get started.</para></listitem>
          </orderedlist>
     <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>Equipping the new FPGA card with SNAP framework needs a few additional steps and is introduced in Chapter <xref linkend="chapter_capi20_snap" endterm="chapter_capi20_snap_title"/></para>
    <note><para>This document focuses on CAPI2.0. For CAPI1.0 enablement, please contact <email>capi-snap-doc@mailinglist.openpowerfoundation.org</email> for more information.</para>
   <para>It is assumed the reader knows how to work on Vivado Project and SNAP already. Many materials on how to develop an accelerator with SNAP can be found in "docs" folder of <link xlink:href="https://github.com/open-power/snap"> snap github</link> or other webpages so they are not discussed in this document.</para></note>

  </section>
 
</chapter>