Intel® oneAPI Programming Guide

Programming Guide

Contents

Use SYCL Shared Library With Third-Party Applications

Use the Intel® oneAPI DPC++/C++ Compiler to compile your SYCL 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.
SYCL Functions Packaged into a Shared Library File For Use in Third-party Applications
To use a 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 SYCL code. The interface must include functions you want to export and how those functions interface with your SYCL 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);
    // SYCL code interface:
    // Vector addition in SYCL
    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 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 and global symbol references get default (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 partially link device binaries for use with FPGA.
    • Xshardware
      : Compiles for hardware instead of the emulator.
  2. Compile the 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 SYCL 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. 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 Intel® Programmable Acceleration Card (PAC) with Intel® Arria® 10 GX FPGA or Intel® FPGA PAC D5005 (previously known as Intel® PAC with Intel® Stratix® 10 SX FPGA) are 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.