Skip to content

[SYCL][DOC] Update C-CXX-StandardLibrary doc to align with latest status #2529

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 25, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -10,27 +10,7 @@ explicitly included in user code.

Implementation requires a special device library to be linked with a
SYCL program. The library should match the C or C++ standard library
used to compile the program:

For example, on Linux with GNU glibc:
.. code:
clang++ -fsycl -c main.cpp -o main.o
clang++ -fsycl main.o $(SYCL_INSTALL)/lib/libsycl-glibc.o -o a.out

or, in case of Windows:
.. code:
clang++ -fsycl -c main.cpp -o main.obj
clang++ -fsycl main.obj %SYCL_INSTALL%/lib/libsycl-msvc.o -o a.exe

For Ahead-Of-Time compilation (AOT), fallback libraries (object files)
must be linked as well:

.. code:
clang++ -fsycl -c -fsycl-targets=spir64_x86_64-unknown-unknown-sycldevice \
main.cpp -o main.o
clang++ -fsycl -fsycl-targets=spir64_x86_64-unknown-unknown-sycldevice \
main.o $(SYCL_INSTALL)/lib/libsycl-glibc.o \
$(SYCL_INSTALL)/lib/libsycl-fallback-cassert.o -o a.out
used to compile the program.

List of supported functions from C standard library:
- assert macro (from <assert.h> or <cassert>)
Expand Down Expand Up @@ -120,12 +100,38 @@ following math functions are not supported now:
- lrintf, lrint
- nexttowardf, nexttoward
- nanf, nan

Device libraries can't support both single and double precision as some
underlying device may not support double precision.
'ldexpf' and 'frexpf' from MSVC <math.h> are implemented using corresponding
double precision version, they can be used only when double precision is
supported by underlying device.

All device libraries without double precision usage are linked by default and
in order to use double precision device library, please add
'-fsycl-device-lib=libm-fp64' or '-fsycl-device-lib=all'.

For example, no options need to be added to use `assert` or float precision
math functions:
.. code:
clang++ -fsycl main.cpp -o main.o

To use double precision math functions:
.. code:
clang++ -fsycl -fsycl-device-lib=libm-fp64 main.cpp -o main.o

For Ahead-Of-Time compilation (AOT), the steps to use device libraries is
same, no options need to be added to use `assert` or float precision math
functions:
.. code:
clang++ -fsycl -fsycl-targets=spir64_x86_64-unknown-unknown-sycldevice \
main.cpp -o main.o

To use double precision math functions in AOT:
.. code:
clang++ -fsycl -fsycl-device-lib=libm-fp64 -fsycl-targets=spir64_x86_64-unknown-unknown-sycldevice \
main.cpp -o main.o

Example of usage
================

Expand Down Expand Up @@ -212,11 +218,7 @@ wrapper libraries are provided with the SYCL compiler that "lower"
libc implementation-specific functions into a stable set of functions,
that can be later handled by a device compiler.

.. code:
clang++ -fsycl -c main.cpp -o main.o
clang++ -fsycl main.o $(SYCL_INSTALL)/lib/libsycl-glibc.o -o a.out

This `libsycl-glibc.o` is one of these wrapper libraries: it provides
This `libsycl-crt.o` is one of these wrapper libraries: it provides
definitions for glibc specific library function, and these definitions
call the corresponding functions from `__devicelib_*` set of
functions.
Expand All @@ -237,11 +239,7 @@ For example, `__assert_fail` from IR above gets transformed into:
unreachable

A single wrapper object provides function wrappers for *all* supported
library functions. Every supported C library implementation (MSVC or
glibc) has its own wrapper library object:

- libsycl-glibc.o
- libsycl-msvc.o
library functions.

SPIR-V
======
Expand Down Expand Up @@ -283,4 +281,5 @@ extension is provided as `libsycl-fallback-cassert.spv`
For AOT compilation, fallback libraries are provided as object files
(e.g. `libsycl-fallback-cassert.o`) which contain device code in LLVM
IR format. Device code in these object files is equivalent to device
code in the `*.spv` files.
code in the `*.spv` files. Those object files are located in compiler
package's 'lib/' folder.
13 changes: 5 additions & 8 deletions sycl/source/detail/program_manager/program_manager.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -388,9 +388,6 @@ RT::PiProgram ProgramManager::getBuiltPIProgram(OSModuleHandle M,
// If device image is not SPIR-V, DeviceLibReqMask will be 0 which means
// no fallback device library will be linked.
uint32_t DeviceLibReqMask = 0;
// FIXME: disable the fallback device libraries online link as not all
// backend supports spv online link. Need to enable it when all backends
// support spv online link.
if (Img.getFormat() == PI_DEVICE_BINARY_TYPE_SPIRV &&
!SYCLConfig<SYCL_DEVICELIB_NO_FALLBACK>::get())
DeviceLibReqMask = getDeviceLibReqMask(Img);
Expand Down Expand Up @@ -797,11 +794,11 @@ ProgramManager::ProgramPtr ProgramManager::build(
LinkOpts = LinkOptions.c_str();
}

// TODO: Because online linking isn't implemented yet on Level Zero, the
// compiler always links against the fallback device libraries. Once
// online linking is supported on all backends, we should remove the line
// below and also change the compiler, so it no longer links the fallback
// code unconditionally.
// TODO: Currently, online linking isn't implemented yet on Level Zero.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi, @kbobrovs
The "TODO" has been added here, we will enable online spv link again once Level Zero supports.
Thank you very much.

// To enable device libraries and unify the behaviors on all backends,
// online linking is disabled temporarily, all fallback device libraries
// will be linked offline. When Level Zero supports online linking, we need
// to remove the line of code below and switch back to online linking.
LinkDeviceLibs = false;

// TODO: this is a temporary workaround for GPU tests for ESIMD compiler.
Expand Down