meta-intel-iss
===============

This layer provides integration for a subset of Intel oneAPI libraries and profilers.

PART 1: README for Wind River Linux LTS 17 and above
PART 2: README for Yocto Project (2.6 and older versions)
PART 3: Errata
PART 4: License


=====================================================
PART 1: README for Wind River Linux (LTS 17)
=====================================================


Dependencies
------------
This layer depends on the Intel(R) System Studio product.


Installing the meta-intel-iss layer
--------------------------------

These steps will register the meta-intel-iss layer with the
Wind River Linux project configuration script.

1. Copy the meta-intel-iss layer into the Wind River installation directory.

2. Register the layer.

Linux:
  $ ./meta-intel-iss/wr-setup/postinst_wr_iss.sh /path/to/ISS_INSTALLATION

Windows:
  > meta-intel-iss\wr-setup\postinst_wr_iss.bat /path/to/ISS_INSTALLATION


EXAMPLES:
  $ meta-intel-iss/wr-setup/postinst_wr_iss.sh /opt/intel
  > meta-intel-iss\wr-setup\postinst_wr_iss.bat "E:/Program Files (x86)/Intel"

NOTE: these scripts require that the meta-intel-iss directory not be a symlink.


Uninstalling the meta-intel-iss layer
----------------------------------

These steps will unregister the meta-intel-iss layer with both Workbench and the
Wind River Linux project configuration script.

1. un-register the layer.

Linux:
  $ ./meta-intel-iss/wr-setup/uninst_wr_iss.sh

Windows:
  > meta-intel-iss\wr-setup\uninst_wr_iss.bat

2. Remove the meta-intel-iss layer from the Wind River installation directory.


Adding Intel(R) System Studio packages to Wind River Linux Projects
----------------------------------------------------------

1. New project configuration

Templates have been provided for each of the Intel(R) System Studio components and
will include the respective package (and dependencies), for example:

  $ .../configure --with-layer=/path/to/meta-intel-iss \
       --with-template=intel-iss-icc-runtime,intel-iss-ippcore,intel-vtune-drivers ...

2. Adding Intel(R) System Studio packages to existing projects

The layer includes recipes that can then be added to the project in
order to  bring the respective content into the project's file system
image, its sysroot, and any exported SDK's.

  (a) Add the path to the meta-intel-iss to the layer conf file

  $ vi <projectdir>/bitbake_build/conf/bblayers.conf

  BBLAYERS = " \
    ...
    /path/to/meta-intel-iss \
    ...
    "

  (b) Add the desired Intel(R) System Studio packages

  $ make -C build intel-iss-icc-runtime.addpkg
  $ make -C build ippcore.addpkg
  $ make -C build intel-iss-vtune-target.addpkg


Workbench Integration
---------------------

  1. Automatic ICC/Intel(R) Integrated Performance Primitives (Intel(R) IPP) build specs

When you create a new application project, for each Intel architecture compatible
build spec an additional ICC compatible build spec will automatically created. It will
invoke the ICC toolchain in addition to including the necessary include and
library paths for the ICC compiler and for Intel(R) IPP libraries.

  2. Sample Applications

The meta-intel-iss includes a set of sample applications for each of the Intel(R) System Studio
components. These samples include all of the respective necessary compiler and
library settings.

  ICC: intrinsic_samples, ipo_samples, optimize, pgo_samples, vec_samples
  Intel(R) IPP: ipptest

Add these sample applications to your workspace with:
  "File > New > Example... > Wind River Linux Application Sample Project"

  3. Enhancing the application's ICC compiler flags

You can apply the ICC optimization flags for applications:

  (a) Select the project, and click "Project > Properties > Build Properties > Tools".
  (b) Select the ICC-specific active build spec for these setting from the pull-down list.
  (c) Select the build tool "C-Compiler" from the pull-down list.
  (d) Adjust or add general ICC flags in the "Tool Flag..." box, for example "-ipo".
  (e) Adjust the production flags in the "Non Debug Mode" box, for example changing
      the optimization level to "-O3".
  (f) The labels are also buttons that can help select the appropriate ICC flags.
  (g) Repeat with the build tools "C-Linker", "C++-Compiler", and "C++-Linker".

You can now right-click on the project and select "Rebuild Project" to assert your changes.

  4. Adding ICC build specs to an existing Application Project

You can refresh an existing project's build specs to pick up new ICC specs by doing:

  * Select "File > Import > General > Build Settings"
  * Select "Default Settings (Wind River Linux ...)", and click "Finish".

NOTE: this update will erase any custom build settings like extra libraries and compiler
flags. For example, the "mthread" sample application would lose its "-lpthread" extra
library flag. In these cases, it may be better to create new versions of such sample
applications, and/or copy any custom flags from another source into the updated project.

  5. Creating a Platform Project in Workbench with ISS components

Adding the meta-intel-iss layer directory allows the many ISS templates to become visible
and easy to add to the project's configuration.

  (a) Create a new Platform Project wizard.
  (b) In the "Layers" section, add the path to the "meta-intel-iss" directory, and
      click "Reload".
  (c) In the "Templates" section, click on "Add". Observe and select the templates for the
      various ISS components, like "icc-runtime" and "ippdc".

  6. Launching Intel(R) VTune Amplifier for Systems GUI from Workbench

You can launch the performance analysis GUI for VTune Amplifier for Systems directly from Workbench.

  (a) Make sure that you are in the "Advanced Device Development" perspective ("Window >
      Open Perspective:).
  (b) Select "Analyze > Performance Studio Tools" (which has the VTune Amplifier for Systems GUI icon).
  (c) You can also click the VTune Amplifier for Systems GUI icon in the Workbench toolbar.


Intel(R) C++ Compiler as a Secondary Toolchain
----------------------------------------------

Intel(R) C++ Compiler(ICC) can be used as a secondary toolchain to build the packages
in WindRiver Linux Platform project. To enable the ICC build for a specific package,
add the following line in the package recipe .bb file.

     TOOLCHAIN_pn-${PN} = "icc"


Intel(R) C++ Compiler and SDK Integration
-----------------------------------------

When the toolschain SDK is exported for the WindRiver Linux Platform project,
an environment setting file for Intel(R) C++ Compiler will be generated automatically
in the folder where the GNU environment setup file is located.

For example, after the installation of exported toolchain SDK, you may find the files:

   /opt/windriver/wrlinux-std-sato/6.0-qemux86/environment-setup-i586-wrs-linux
... and ...
   /opt/windriver/wrlinux-std-sato/6.0-qemux86/environment-setup-i586-wrs-linux-icc

The file "environment-setup-i586-wrs-linux" is used to setup the build environment for GNU
compiler and the file "environment-setup-i586-wrs-linux-icc" is used to set up the build
environment for Intel(R) C++ Compiler.

For example, you can use the following command to set up the ICC build environment:

   $ source /opt/windriver/wrlinux-std-sato/6.0-qemux86/environment-setup-i586-wrs-linux-icc

The $CC, $CXX, and other such environment variables are reset for the Intel(R) C++
Compiler build.


=====================================================
PART 2: README for Yocto Project 2.6
=====================================================


Dependencies
------------
This layer depends on the Intel(R) oneAPI Base ToolKit product.


Installing the meta-intel-iss layer
--------------------------------

These steps will register the meta-intel-iss layer with the ISS installation.

1. Copy the meta-intel-iss layer into a directory.

2. Register the layer.

  $ ./meta-intel-iss/yp-setup/postinst_yp_iss.sh /path/to/ONEAPI_INSTALLATION

EXAMPLE:
  $ ./meta-intel-iss/yp-setup/postinst_yp_iss.sh /opt/intel/oneapi

NOTE: these scripts require that the meta-intel-iss directory not be a symlink.


Uninstalling the meta-intel-iss layer
----------------------------------

These steps will unregister the meta-intel-iss layer with the ISS installation.

1. un-register the layer.

  $ ./meta-intel-iss/yp-setup/uninst_yp_iss.sh

2. Remove the meta-intel-iss layer.


Adding Intel(R) oneAPI packages to Yocto Project Builds
-----------------------------------------------------

The layer includes recipes that can then be added to the project in
order to  bring the respective content into the project's file system
image.

1. Add this layer

Add the path to the meta-intel-iss to the layer conf file

  $ vi "conf/bblayers.conf"

  BBLAYERS = " \
    ...
    /path/to/meta-intel-iss \
    ...
    "

2. Add the desired Intel(R) oneAPI recipes to "conf/local.conf" and comment the ones that are not needed with '#' at the beginning of the line:

  $ vi "conf/local.conf"

  IMAGE_INSTALL_append = " intel-iss-icc-runtime"
  IMAGE_INSTALL_append = " intel-iss-ippdc"
  IMAGE_INSTALL_append = " intel-iss-mkl-target"
  IMAGE_INSTALL_append = " intel-vtune-drivers"
  IMAGE_INSTALL_append = " intel-vtune-sep-driver"


Intel(R) C++ Compiler as a Secondary Toolchain
----------------------------------------------

Intel(R) C++ Compiler(ICC) can be used as a secondary toolchain to build
the packages for target system. To enable the icc build for
a specific package, add the following line in the package recipe .bb file.

      TOOLCHAIN_pn-${PN} = "icc"


Intel(R) C++ Compiler and SDK Integration
-----------------------------------------

When the toolchain SDK is exported for a target system build, an environment setting
file for Intel(R) C++ Compiler will be generated automatically in the folder where
the GNU environment setup file is located.

For example, after the installation of exported toolchain SDK, you may find the files:

   /opt/poky/2.6.2/environment-setup-core2-poky-linux
... and ...
   /opt/poky/2.6.2/environment-setup-core2-poky-linux-icc

The file "environment-setup-core2-poky-linux" is used to setup the build environment
for GNU compiler and the file "environment-setup-core2-poky-linux-icc" is used to set up 
the build environment for Intel(R) C++ Compiler.

For example, you can use the following command to set up the icc build environment:

  $ source /opt/poky/2.6.2/environment-setup-i586-wrs-linux-icc

The $CC, $CXX, and other such environment variables are reset for the Intel(R) C++
Compiler build.


=====================================================
PART 3: Errata
=====================================================


  * When using the Intel(R) IPP recipes with Yocto Project 1.5 (and this Wind River Linux
    5.x), you may see warnings of the form:

    WARNING: QA Issue: XXX-doc doesn't match the [a-z0-9.+-]+ regex

    This version (and earlier) of bitbake gives warnings for upper case
    characters in recipe names. This message can be ignored.


=====================================================
PART 4: License
=====================================================


#/
# Copyright (c) 2013-2015, Wind River Systems, Inc.
# Copyright © 2015 Intel Corporation. All rights reserved.
#
# Redistribution and use in source and binary forms, with or without modification, are
# permitted provided that the following conditions are met:
#
# 1) Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
#
# 2) Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation and/or
# other materials provided with the distribution.
#
# 3) Neither the name of Wind River Systems nor the names of its contributors may be
# used to endorse or promote products derived from this software without specific
# prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
# USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#/
