diff --git a/libc/CMakeLists.txt b/libc/CMakeLists.txt --- a/libc/CMakeLists.txt +++ b/libc/CMakeLists.txt @@ -21,6 +21,7 @@ if(LLVM_LIBC_FULL_BUILD OR LIBC_GPU_BUILD OR LIBC_GPU_ARCHITECTURES) if(NOT LIBC_HDRGEN_EXE) # We need to set up hdrgen first since other targets depend on it. + add_subdirectory(docs) add_subdirectory(utils/LibcTableGenUtil) add_subdirectory(utils/HdrGen) else() diff --git a/libc/docs/gpu/index.rst b/libc/docs/gpu/index.rst --- a/libc/docs/gpu/index.rst +++ b/libc/docs/gpu/index.rst @@ -16,3 +16,4 @@ support testing rpc + motivation diff --git a/libc/docs/gpu/motivation.rst b/libc/docs/gpu/motivation.rst new file mode 100644 --- /dev/null +++ b/libc/docs/gpu/motivation.rst @@ -0,0 +1,58 @@ +.. _libc_gpu_motivation: + +========================== +Motivation and Limitations +========================== + +.. contents:: Table of Contents + :depth: 4 + :local: + +Motivation +========== + +This project aims to provide a subset of the C standard library to users of GPU +accelerators. We deliberately choose to only implement a subset of the C library +as some features are not expressly useful or easily implemented on the GPU. This +will be discussed further in `Limitations `_. The main +motivation behind this project is to provide a common implementation of host +services for the GPU. + +The main idea behind this project is that programming GPUs can be as +straightforward as programming on CPUs. This project aims to validate the GPU as +a more general-purpose target and to simplify the incidental complexity of +existing device libraries. The implementations here will also enable more +complex implementations of other libraries on the GPU, such as ``libc++``. + +Currently, host services and C library features are provided sparsely by the +different GPU vendors. We wish to provide these functions more completely and +make their implementations available in a common format. This is useful for +targets like OpenMP offloading or SYCL which wish to unify the offloading +toolchain. We also aim to provide these functions in a format compatible with +offloading in ``Clang`` so that we can treat the C library for the GPU as a +standard static library. + +For this reason, we primarily are focused on functions that are provided by +existing device libraries such as ``printf``, ``malloc``, and ``free``. We also +compile the ``libc`` source code directly without any offloading runtime. The +goal is to provide a library without any existing dependencies that can be used +to stand up various services for any target capable of linking the bitcode. + +We also wish to use the existing LLVM C library unit test suite to expand test +coverage targeting GPUs. For this reason we build `tests on the GPU +`_ that can run a unit test as if it were being run on the +CPU. This also helps users port applications that traditionally were run on the +CPU. + +.. _libc_gpu_limitations: + +Limitations +=========== + +We currently only implement a subset of the standard C library. The GPU does not +currently support thread local variables so variables like ``errno`` are not +provided. Furthermore, the GPU under the OpenCL model cannot safely provide a +mutex interface, nor would it be profitable if implemented. This means that +features like file buffering are not implemented on the GPU. We can also not +easily provide threading features on the GPU due to the execution model so these +will be ignored, as will features like ``locale`` or ``time``. diff --git a/libc/docs/gpu/support.rst b/libc/docs/gpu/support.rst --- a/libc/docs/gpu/support.rst +++ b/libc/docs/gpu/support.rst @@ -12,7 +12,7 @@ The following functions and headers are supported at least partially on the device. Some functions are implemented fully on the GPU, while others require a -`remote procedure call `. +`remote procedure call `_. ctype.h ------- diff --git a/libc/docs/gpu/testing.rst b/libc/docs/gpu/testing.rst --- a/libc/docs/gpu/testing.rst +++ b/libc/docs/gpu/testing.rst @@ -19,7 +19,7 @@ The testing support in LLVM's libc implementation for GPUs is designed to mimic the standard unit tests as much as possible. We use the `remote procedure call -` support to provide the necessary utilities like printing from +`_ support to provide the necessary utilities like printing from the GPU. Execution is performed by emitting a ``_start`` kernel from the GPU that is then called by an external loader utility. This is an example of how this can be done manually: