[C2x] Implement the `unreachable` macro for WG14 N2826

[aaron.ballman]

Summary

This exposes __builtin_unreachable as the expansion for the unreachable macro in C2x. I added this definition under __need_STDDEF_H_misc on the assumption there is no need for a separate need macro to control adding this.

[erichkeane]

clang/lib/Headers/stddef.h

108

Is this REALLY required to be a macro by standard? Is it so they don't have to steal the word/can do #undef? This is going to result in a worse diagnostic here any time we diagnose on this line.

[aaron.ballman]

clang/lib/Headers/stddef.h

108

Yes, it's required to be a macro by the C standard. According to my personal notes:

This led us up to a preference poll, does WG14 prefer the syntax variant over the macro variant in N2826? 3/12/5 (no consensus). Does WG14 prefer to put the macro into <stddef.h> as in N2826 in C23? 11/2/7 (consensus). Does WG14 want to adopt the unreachable feature Change 5 & 6 with stddef.h in place of HEADER.h into C23? 13/2/6 (consensus).

I don't think the diagnostic behavior here will be any different than for offsetof (defined a few lines below), right?

[erichkeane]

clang/lib/Headers/stddef.h

108

offsetof is what made me ask this question :D I guess we do the whole 'macro-like' escape in other places, but everything here is already crap, so I guess this is no different.

clang/docs/ReleaseNotes.rst

 AIX Support
 -----------
 
 C Language Changes in Clang
 ---------------------------
 
 C2x Feature Support
 -------------------
+- Implemented the ``unreachable`` macro in freestanding ``<stddef.h>`` for
+  `WG14 N2826 <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2826.pdf>`_
 
 C++ Language Changes in Clang
 -----------------------------
 - Improved ``-O0`` code generation for calls to ``std::forward_like``. Similarly to
   ``std::move, std::forward`` et al. it is now treated as a compiler builtin and implemented
   directly rather than instantiating the definition from the standard library.
 
 C++20 Feature Support

clang/lib/Headers/stddef.h

 #endif /* defined(__need_NULL) */
 
 /* FIXME: This is using the placeholder dates Clang produces for these macros
    in C2x mode; switch to the correct values once they've been published. */
 #if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202000L
 typedef typeof(nullptr) nullptr_t;
 #endif /* defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202000L */
 
+#if defined(__need_STDDEF_H_misc) && defined(__STDC_VERSION__) &&              \
+    __STDC_VERSION__ >= 202000L
+#define unreachable() __builtin_unreachable()
+#endif /* defined(__need_STDDEF_H_misc) && >= C23 */
+
 #if defined(__need_STDDEF_H_misc)
 #if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L) ||              \
     (defined(__cplusplus) && __cplusplus >= 201103L)
 #include "__stddef_max_align_t.h"
 #endif
 #define offsetof(t, d) __builtin_offsetof(t, d)
 #undef __need_STDDEF_H_misc
 #endif  /* defined(__need_STDDEF_H_misc) */

clang/test/C/C2x/n2826.c

+// RUN: %clang_cc1 -ffreestanding -emit-llvm -o - -std=c2x %s | FileCheck %s
+// RUN: %clang_cc1 -ffreestanding -std=c17 -verify %s
+
+/* WG14 N2826: Clang 17
+ * Add annotations for unreachable control flow v2
+ */
+#include <stddef.h>
+
+enum E {
+  Zero,
+  One,
+  Two,
+};
+
+int test(enum E e) {
+  switch (e) {
+  case Zero: return 0;
+  case One: return 1;
+  case Two: return 2;
+  }
+  unreachable(); // expected-error {{call to undeclared function 'unreachable'}}
+}
+
+// CHECK: switch i32 %0, label %[[EPILOG:.+]] [
+// CHECK: [[EPILOG]]:
+// CHECK-NEXT: unreachable

clang/www/c_status.html

</tr>
     <tr>
       <td>Disambiguate the storage class of some compound literals</td>
       <td><a href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2819.pdf">N2819</a></td>
       <td class="unknown" align="center">Unknown</td>
     </tr>
     <tr>
       <td>Add annotations for unreachable control flow v2</td>
       <td><a href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2826.pdf">N2826</a></td>
-      <td class="none" align="center">No</td>
+      <td class="unreleased" align="center">Clang 17</td>
     </tr>
     <tr>
       <td>Unicode Sequences More Than 21 Bits are a Constraint Violation r0</td>
       <td><a href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2828.htm">N2828</a></td>
       <td class="full" align="center">Clang 3.6</td>
     </tr>
     <tr>
       <td>Make assert() macro user friendly for C and C++ v2</td>