Intel® oneAPI Programming Guide

Programming Guide

Contents

Use DPC++ Shared Library With Third-Party Applications

Use the
Intel® oneAPI
DPC++/C++
 Compiler
 to compile your DPC++ code to a C-standard shared library (
.so
 file on Linux and
.dll
 file on Windows). You can then call this library from other third-party code to access a broad base of accelerated functions from your preferred programming language.
DPC++ Functions Packaged into a Shared Library File For Use in Third-party Applications
To use a DPC++ shared library with a third-party application, perform these steps:

Define the Shared Library Interface

Intel® recommends defining an interface between the C-standard shared library and your DPC++ code. The interface must include functions you want to export and how those functions interface with your DPC++ code. Prefix the functions that you want to include in the shared library with
extern "C"
.
If you do not prefix with
extern "C"
, then the functions appear with mangled names in the shared library.
Consider the following example code of the
vector_add
 function: 
extern "C" int vector_add(int *a, int *b, int **c, size_t vector_len) {

  // Create device selector for the device of your interest.
  #if FPGA_EMULATOR
    // DPC++ extension: FPGA emulator selector on systems without an FPGA card.
    ext::intel::fpga_emulator_selector d_selector;
  #elif FPGA
    // DPC++ extension: FPGA selector on systems with an FPGA card.
    ext::intel::fpga_selector d_selector;
  #else
    // The default device selector selects the most performant device.
    default_selector d_selector;
  #endif

  try {
    queue q(d_selector, exception_handler);


    // DPC++ code interface:
    // Vector addition in DPC++ 
    VectorAddKernel(q, a, b, c, vector_len); 
  } catch (exception const &e) {
    std::cout << "An exception is caught for vector add.\n";
    return -1
  }

  return 0;
}

Generate the Shared Library File in Linux

If you are using a Linux system, then perform these steps to generate the shared library file:
  1. Compile the DPC++ device code separately. 
    dpcpp -fPIC –fintelfpga –fsycl-link=image [kernel src files] –o <hw image name> -Xshardware
    Where:
    fPIC
    Determines whether the compiler generates position-independent code for the host portion of the device image. Option
    -fPIC
     specifies full symbol preemption. Global symbol definitions as well as global symbol references get default (that is, preemptable) visibility unless explicitly specified otherwise. You must use this option when building shared objects. You can also specify this option as
    -fpic
    .
    PIC
     is required so that pointers in the shared library reference global addresses and not local addresses.
    fintelfpga
    Targets FPGA devices.
    fsycl-link=image
    Informs the
    Intel® oneAPI
    DPC++/C++
     Compiler
     to perform partial linking of device binaries for use with FPGA.
    Xshardware
    Compiles for hardware instead of the emulator.
  2. Compile the DPC++ host code separately. 
    dpcpp –fPIC –fintelfpga <host src files> -o <host image name> -c -DFPGA=1
    Where:
    DFPGA=1
    Sets a compiler macro,
    FPGA
    , equal to 1. It is used in the device selector to change between target devices (requires corresponding host code to support this). This is optional as you can also set your device selector to FPGA.
  3. Link the host and device images and create the binary. 
    dpcpp –fPIC –fintelfpga –shared <host image name> <hw image name> -o lib<library name>.so
    Where:
    shared
    Outputs a shared library (
    .so
     file).
    Output file name
    Prefix with
    lib
     for the GCC type of compilers. For additional information, see Shared libraries with GCC on Linux. For example: 
    gcc -Wall -fPIC -L. -o out.a -l<library name>.so
Instead of the above multi-step process, you can also perform a single-step compilation to generate the shared library. However, you must perform a full compile if you want to build the executable for testing purposes (for example,
a.out
) or if you make changes in the DPC++ code or C interface.

Generate the Shared Library File in Windows

If you are using a Windows system, then perform these steps to generate the library file:
  • Intel® recommends creating a new configuration in the same project properties. That way if you want to build the application, you can avoid changing the configuration type for your project.
  • Creating a Windows library with the default Intel® oneAPI Base Toolkit and FPGA add-on for Intel® PAC with Intel® Arria® 10 GX FPGA and Intel® Stratix® 10 SX FPGA is supported only for FPGA emulation. For custom platforms, contact your board vendor for Windows support for FPGA hardware compiles.
  1. In Microsoft Visual Studio*, navigate to
    Project
    Properties
    . The
    Property Pages
     dialog is displayed for your project.
  2. Under the
    Configuration Properties
    General
    Project Defaults
    Configuration Type
     option, select
    Dynamic Library (.dll)
     from the drop-down list.
    Project Properties Dialog
  3. Click
    OK
     to close the dialog.
The project automatically builds to create a dynamic library (
.dll
)

Use the Shared Library

These steps may vary depending on the language or compiler you decide to use. Consult the specifications for your desired language for more details. See Shared libraries with GCC on Linux for an example.
Generally, follow these steps to use the shared library:
  1. Use the shared library function call in your third-party host code.
  2. Link your host code with the shared library during the compilation.
  3. Ensure that the library file is discoverable. For example: 
    export LD_LIBRARY_PATH=<lib file location>:$LD_LIBRARY_PATH
The following is an example illustration of using the shared library:
Example Use of the Shared Library

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.