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

[jhuber6]

Summary

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

[jhuber6]

Clean up leftover change

[jdoerfert]

Honestly, I feel this is too pessimistic and short sighted. I understand we likely don't want everything on a GPU, maybe event can't, but I would not be so eager to guess for some of the things mentioned here. File I/O, for one, is on my TODO list. The entire "we do not want dependencies" is nice, but also somewhat irrelevant given that the vendor libs are linked in (to this day) anyway. Sure, we do not link them into libcgpu, but that is not because of some grant design, IMHO, but rather because we didn't need to (yet). Once libmgpu arrives, we will have to (or link libdevice later), so we will do what the motivation now states we don't want to.

libc/docs/gpu/motivation.rst

17

typo

55

2x currently

FWIW, GPUs have thread local variables, aka. local

[JonChesterfield]

Way back I started down this path because I thought running N lua virtual machines on a gpu would be an interesting programming model and the reference lua machine is written in C. Whether that's motivation for anyone else is not totally clear to me.

In principle I'd like to be able to do things like put a sqlite database instance in a persistent kernel. In general a persistent kernel that spawns other threads on the GPU and occasionally calls into the CPU is an interesting alternative to the current offload in batches model. Perhaps we'll be able to DMA from a nic into GPU memory, do some maths, push results back without the host cpu doing anything much.

Today my primary interest in libc is as a precise and comprehensive vehicle for stress testing the GPU back ends, so that when people try to use them for general purpose software things they have a better experience, but tomorrow I hope it'll be the layer below more complicated GPU applications.

libc/docs/gpu/motivation.rst

21

Libc isn't really here to provide host services. It's to provide a familiar userspace. It's also a reasonable foundation for bigger userspace stuff, notably libc++. Weve just started with the host services part because without syscall a lot of libc can't do anything.

[jhuber6]

Changing up, addressing comments

[jhuber6]

In D152028#4392240, @jdoerfert wrote:

Honestly, I feel this is too pessimistic and short sighted. I understand we likely don't want everything on a GPU, maybe event can't, but I would not be so eager to guess for some of the things mentioned here. File I/O, for one, is on my TODO list.

I think that File I/O should be mostly straightforward. The existing interface I pushed for puts support pretty much just keeps a reference to a FILE * on the host. Using newer CUDA with asyncs in a separate stream we should be able to generically support H2D or D2H memcpy, so we should probably have some logic that lets us use that if the device pointer is global

The entire "we do not want dependencies" is nice, but also somewhat irrelevant given that the vendor libs are linked in (to this day) anyway. Sure, we do not link them into libcgpu, but that is not because of some grant design, IMHO, but rather because we didn't need to (yet). Once libmgpu arrives, we will have to (or link libdevice later), so we will do what the motivation now states we don't want to.

So, a long-term goal of this project is to provide a lot of those facilities in a more complete way. I think the initial invocation of libmgpu.a will simply map to the vendor libraries, but we can easily extend it further using a more generic implementation.

[jdoerfert]

I still think it's too negative but OK for now

libc/docs/gpu/motivation.rst

38

@tianshilei1992 Can you link the IWOMP paper here please. In a follow up.

47–48

libc/docs/gpu/index.rst

 learn more about this project.
 
 .. toctree::
 
    using
    support
    testing
    rpc
+   motivation

libc/docs/gpu/motivation.rst

+.. _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
+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.
+
+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 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``.

libc/docs/gpu/support.rst

 .. _libc_gpu_support:
 
 ===================
 Supported Functions
 ===================
 
 .. include:: ../check.rst
 
 .. contents:: Table of Contents
   :depth: 4
   :local:
 
 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
 -------
 
 =============  =========  ============
 Function Name  Available  RPC Required
 =============  =========  ============
 isalnum        |check|

libc/docs/gpu/testing.rst

.. contents:: Table of Contents
   :depth: 4
   :local:
 
 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:
 
 .. code-block:: sh
 
    $> clang++ crt1.o test.cpp --target=amdgcn-amd-amdhsa -mcpu=gfx90a -flto
    $> ./amdhsa_loader --threads 1 --blocks 1 a.out
    Test Passed!
 
 Unlike the exported ``libcgpu.a``, the testing architecture can only support a
 single architecture at a time. This is either detected automatically, or set
 manually by the user using ``LIBC_GPU_TEST_ARCHITECTURE``. The latter is useful
 in cases where the user does not build LLVM's libc on machine with the GPU to
 use for testing.