[coroutines] Adding builtins for coroutine intrinsics and backendutil support.

Summary:
With this commit simple coroutines can be created in plain C using coroutine builtins.

Reviewers: rnk, EricWF, rsmith

Subscribers: modocache, mgorny, mehdi_amini, beanz, cfe-commits

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

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@283155 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 76 insertions, 0 deletions

diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst
index 51ac3ab1a8..64e6ffb7f3 100644
--- a/docs/LanguageExtensions.rst
+++ b/docs/LanguageExtensions.rst
@@ -1865,6 +1865,82 @@ The types ``T`` currently supported are:
 Note that the compiler does not guarantee that non-temporal loads or stores
 will be used.
 
+C++ Coroutines support builtins
+--------------------------------
+
+.. warning::
+  This is a work in progress. Compatibility across Clang/LLVM releases is not 
+  guaranteed.
+
+Clang provides experimental builtins to support C++ Coroutines as defined by
+http://wg21.link/P0057. The following four are intended to be used by the
+standard library to implement `std::experimental::coroutine_handle` type.
+
+**Syntax**:
+
+.. code-block:: c
+
+  void  __builtin_coro_resume(void *addr);
+  void  __builtin_coro_destroy(void *addr);
+  bool  __builtin_coro_done(void *addr);
+  void *__builtin_coro_promise(void *addr, int alignment, bool from_promise)
+
+**Example of use**:
+
+.. code-block:: c++
+
+  template <> struct coroutine_handle<void> {
+    void resume() const { __builtin_coro_resume(ptr); }
+    void destroy() const { __builtin_coro_destroy(ptr); }
+    bool done() const { return __builtin_coro_done(ptr); }
+    // ...
+  protected:
+    void *ptr;
+  };
+
+  template <typename Promise> struct coroutine_handle : coroutine_handle<> {
+    // ...
+    Promise &promise() const {
+      return *reinterpret_cast<Promise *>(
+        __builtin_coro_promise(ptr, alignof(Promise), /*from-promise=*/false));
+    }
+    static coroutine_handle from_promise(Promise &promise) {
+      coroutine_handle p;
+      p.ptr = __builtin_coro_promise(&promise, alignof(Promise),
+                                                      /*from-promise=*/true);
+      return p;
+    }
+  };
+
+
+Other coroutine builtins are either for internal clang use or for use during
+development of the coroutine feature. See `Coroutines in LLVM
+<http://llvm.org/docs/Coroutines.html#intrinsics>`_ for
+more information on their semantics. Note that builtins matching the intrinsics
+that take token as the first parameter (llvm.coro.begin, llvm.coro.alloc, 
+llvm.coro.free and llvm.coro.suspend) omit the token parameter and fill it to
+an appropriate value during the emission.
+
+**Syntax**:
+
+.. code-block:: c
+
+  size_t __builtin_coro_size()
+  void  *__builtin_coro_frame()
+  void  *__builtin_coro_free(void *coro_frame)
+
+  void  *__builtin_coro_id(int align, void *promise, void *fnaddr, void *parts)
+  bool   __builtin_coro_alloc()
+  void  *__builtin_coro_begin(void *memory)
+  void   __builtin_coro_end(void *coro_frame, bool unwind)
+  char   __builtin_coro_suspend(bool final)
+  bool   __builtin_coro_param(void *original, void *copy)
+
+Note that there is no builtin matching the `llvm.coro.save` intrinsic. LLVM
+automatically will insert one if the first argument to `llvm.coro.suspend` is
+token `none`. If a user calls `__builin_suspend`, clang will insert `token none`
+as the first argument to the intrinsic.
+
 Non-standard C++11 Attributes
 =============================