[docs] Finish misc MyST migration (#210209 )

Tracking issue: #201242
See the [migration guide] for more information.

[migration guide]:
https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines

This is a stacked PR based on #210208, which is the standalone rename
commit for this miscellaneous Markdown migration batch.

This was prepared with rst2myst plus LLM-assisted cleanup. LLDB man
pages are intentionally left as reStructuredText because LLDB man-page
building should not take on Markdown parser dependencies.

Unfortunately, many of these miscellaneous docs do not have working
standalone doc build targets, so I was not able to render HTML for all
of them. I think the scope is small enough that this is reviewable by
hand.

2026-07-17 11:56:59 -07:00

4.3 KiB

Raw Blame History

SYCL runtime implementation

:::{contents} :local: true :::

(index)=

Current Status

The implementation is in the very early stages of upstreaming. The first milestone is to get support for a simple SYCL application with device code using Unified Shared Memory:

#include <sycl/sycl.hpp>

class TestKernel;

int main() {
  sycl::queue q;

  const size_t dataSize = 32;
  int *dataPtr = sycl::malloc_shared<int>(32, q);
  for (int i = 0; i < dataSize; ++i)
    dataPtr[i] = 0;

  q.submit([&](sycl::handler &cgh) {
    cgh.parallel_for<TestKernel>(
        sycl::range<1>(dataSize),
        [=](sycl::id<1> idx) { dataPtr[idx] = idx[0]; });
  });
  q.wait();

  bool error = false;
  for (int i = 0; i < dataSize; ++i)
    if (dataPtr[i] != i) error = true;

  free(dataPtr, q);

  return error;
}

This requires at least partial support of the following functionality on the libsycl side:

sycl::platform class
sycl::device class
sycl::context class
sycl::queue class
sycl::handler class
sycl::id and sycl::range classes
Unified shared memory allocation/deallocation
Program manager, an internal component for retrieving and using device images from the multi-architectural binaries

Build steps

To build LLVM with libsycl runtime enabled the following script can be used.

#!/bin/sh

build_llvm=`pwd`/build-llvm
installprefix=`pwd`/install
llvm=`pwd`
mkdir -p $build_llvm
mkdir -p $installprefix

cmake -G Ninja -S $llvm/llvm -B $build_llvm \
      -DLLVM_ENABLE_PROJECTS="clang" \
      -DLLVM_INSTALL_UTILS=ON \
      -DCMAKE_INSTALL_PREFIX=$installprefix \
      -DLLVM_ENABLE_RUNTIMES="offload;openmp;libsycl" \
      -DCMAKE_BUILD_TYPE=Release \
      # must be default and configured in liboffload,
      # requires level zero, see offload/cmake/Modules/LibomptargetGetDependencies.cmake
      -DLIBOMPTARGET_PLUGINS_TO_BUILD=level_zero

ninja -C $build_llvm install

Limitations

Libsycl is not currently supported on Windows because it depends on liboffload which doesn't currently support Windows.

TODO for added SYCL classes

exception: methods with context are not implemented, to add once context is ready
platform: deprecated info descriptor is not implemented (info::platform::extensions), to implement on RT level with device::get_info<info::device::aspects>()
device:
- get_info: to find an efficient way to map descriptors to liboffload types, add other descriptors, add cache of info data
- has(aspect): same as get_info
- create_sub_devices: partitioning is not supported by liboffload now, blocked
- has_extension: deprecated API, to implement on RT level with device::has
device selection: to add compatibility with old SYCL 1.2.1 device selectors, still part of SYCL 2020 specification
context: to implement get_info, properties & public constructors once context support is added to liboffload
queue:
- to implement USM methods
  - memcpy: enable the host-to-host case (blocked by liboffload limitations)
- to implement synchronization methods
- to implement submit & copy with accessors (low priority)
- get_info & properties
- ctors that accepts context (blocked by lack of liboffload support)
- nd_range kernel submissions: offset is not supported by liboffload now, SYCL2020 deprecated feature
- cross-context events wait (host tasks are needed)
- implement check if lambda arguments are device copyable (requires clang support of corresponding builtins) unless FE will fully cover it
- kernel instantiating on host (debugging purposes)
property_list: to fully implement and integrate with existing SYCL runtime classes supporting it
usm allocations:
- add aligned functions (blocked by liboffload support)
- forward templated funcs to alignment methods (rewrite current impl)
- handle sub devices once they are implemented (blocked by liboffload support)
event:
- get_info, get_profiling_info (no liboffload support) are not implemented
- get_wait_list should be aligned with the results of this discussion: https://github.com/KhronosGroup/SYCL-Docs/issues/1017
range, id - __SYCL_DISABLE_ID_TO_INT_CONV__ and __SYCL_ASSUME_ID_RANGE optimizations are not implemented
general opens:
- define a way to report errors from object dtors
- unittests: add functions to reset libsycl internal state completely (static variables)

4.3 KiB Raw Blame History