[libc-commits] [libc] 70b1c39 - [libc][Docs] Add some motivation for the GPU libc

[Joseph Huber via libc-commits]

Author: Joseph Huber
Date: 2023-06-16T15:19:45-05:00
New Revision: 70b1c3999c912c81f2783112980dc2fa7bef270b

URL: https://github.com/llvm/llvm-project/commit/70b1c3999c912c81f2783112980dc2fa7bef270b
DIFF: https://github.com/llvm/llvm-project/commit/70b1c3999c912c81f2783112980dc2fa7bef270b.diff

LOG: [libc][Docs] Add some motivation for the GPU libc

This provides some basic motivation behind the GPU libc. Suggests are welcome.

Reviewed By: jdoerfert

Differential Revision: https://reviews.llvm.org/D152028

Added: 
    libc/docs/gpu/motivation.rst

Modified: 
    libc/docs/gpu/index.rst
    libc/docs/gpu/support.rst
    libc/docs/gpu/testing.rst

Removed: 
    


################################################################################
diff  --git a/libc/docs/gpu/index.rst b/libc/docs/gpu/index.rst
index 0ea54a7235459..2d76548666504 100644
--- a/libc/docs/gpu/index.rst
+++ b/libc/docs/gpu/index.rst
@@ -16,3 +16,4 @@ learn more about this project.
    support
    testing
    rpc
+   motivation

diff  --git a/libc/docs/gpu/motivation.rst b/libc/docs/gpu/motivation.rst
new file mode 100644
index 0000000000000..171287c3f996f
--- /dev/null
+++ b/libc/docs/gpu/motivation.rst
@@ -0,0 +1,51 @@
+.. _libc_gpu_motivation:
+
+==========================
+Motivation and Limitations
+==========================
+
+.. contents:: Table of Contents
+  :depth: 4
+  :local:
+
+Motivation
+==========
+
+This project aims to provide a large 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 <libc_gpu_limitations>`_. 
+The main motivation behind this project is to provide the well understood C 
+library as a firm base for GPU development.
+
+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. The implementations here will also enable more
+complex implementations of other libraries on the GPU, such as ``libc++``.
+
+Host services and C library features are currently provided sparsely by the
+
diff erent 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.
+
+A valuable use for providing C library features on the GPU is for testing. For 
+this reason we build `tests on the GPU <libc_gpu_testing>`_ 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. With this support, we can expand test 
+coverage for the GPU backend to the existing LLVM C library tests.
+
+.. _libc_gpu_limitations:
+
+Limitations
+===========
+
+We only implement a subset of the standard C library. The GPU does not
+currently support thread local variables in all cases, so variables like 
+``errno`` are not provided. Furthermore, the GPU under the OpenCL execution 
+model cannot safely provide a mutex interface. 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
index f557acabd492b..816d9616403e7 100644
--- a/libc/docs/gpu/support.rst
+++ b/libc/docs/gpu/support.rst
@@ -12,7 +12,7 @@ Supported Functions
 
 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 <libc_gpu_rpc>`.
+`remote procedure call <libc_gpu_rpc>`_.
 
 ctype.h
 -------

diff  --git a/libc/docs/gpu/testing.rst b/libc/docs/gpu/testing.rst
index dc82b272b89ec..6e5bed5358cd8 100644
--- a/libc/docs/gpu/testing.rst
+++ b/libc/docs/gpu/testing.rst
@@ -19,7 +19,7 @@ Testing Infrastructure
 
 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
-<libc_gpu_rpc>` support to provide the necessary utilities like printing from
+<libc_gpu_rpc>`_ 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: