[OpenMP] Introduce a new parallel region entry point

[jdoerfert]

Summary

NOTE: Tests and follow up patches missing.

The old parallel region entry point, __kmpc_fork_call, provided a
variadic interface and did not allow to pass information associated
with the parallel. This has various downsides. Handling of variadic
functions is much harder and can be more expensive. Since the if
condition, the num_threads expression, and the proc_bind choice could
not be passed to the old entry point, the frontend needed to setup
the runtime state explicitly "in user code". This makes user code
more complex and is in itself a bad idea as the runtime internals
are now exposed to all the frontends.

The new entry point takes all the values that can be associated with a
omp parallel in OpenMP 5.X and handles the runtime setup internally.

openmp/runtime/src/dllexports

# USED ABOVE __kmpc_critical_with_hint    270
         __kmpc_task_reduction_modifier_init 274
         __kmpc_task_reduction_modifier_fini 275
         __kmpc_task_allow_completion_event  276
         __kmpc_taskred_init                 277
         __kmpc_taskred_modifier_init        278
         __kmpc_omp_target_task_alloc        279
 %endif
 
+# New interface entry points, the OpenMP version number they have been
+# introduced is the suffix.
+
+    __kmpc_parallel_51               280
+
 # User API entry points that have both lower- and upper- case versions for Fortran.
 # Number for lowercase version is indicated.  Number for uppercase is obtained by adding 1000.
 # User API entry points are entry points that start with 'kmp_' or 'omp_'.
 
 omp_destroy_lock                            700
 omp_destroy_nest_lock                       701
 omp_get_dynamic                             702
 omp_get_max_threads                         703

openmp/runtime/src/kmp.h

 KMP_EXPORT kmp_int32 __kmpc_global_num_threads(ident_t *);
 KMP_EXPORT kmp_int32 __kmpc_bound_thread_num(ident_t *);
 KMP_EXPORT kmp_int32 __kmpc_bound_num_threads(ident_t *);
 
 KMP_EXPORT kmp_int32 __kmpc_ok_to_fork(ident_t *);
 KMP_EXPORT void __kmpc_fork_call(ident_t *, kmp_int32 nargs,
                                  kmpc_micro microtask, ...);
 
+/// The parallel region type.
+///
+/// \param global_tid The global thread ID of the executing thread.
+/// \param bound_tid  TODO
+/// \param payload    The payload/closure determined at the invocation.
+typedef void (*kmpc_parallel_region_ty)(kmp_int32 *global_tid,
+                                        kmp_int32 *bound_tid, void *payload);
+
+/// Entry point to start a new parallel region.
+///
+/// \param ident       The source identifier.
+/// \param global_tid  The global thread ID.
+/// \param if_expr     The if(expr), or 1 if none given.
+/// \param num_threads The num_threads(expr), or -1 if none given.
+/// \param proc_bind   The proc_bind, or `proc_bind_default` if none given.
+/// \param fn          The outlined parallel region.
+/// \param payload     The payload passed to the outlined parallel region.
+KMP_EXPORT void __kmpc_parallel_51(ident_t *ident, kmp_int32 global_tid,
+                                   kmp_int32 if_expr, kmp_int32 num_threads,
+                                   kmp_proc_bind_t proc_bind,
+                                   kmpc_parallel_region_ty fn, void *payload);
+
 KMP_EXPORT void __kmpc_serialized_parallel(ident_t *, kmp_int32 global_tid);
 KMP_EXPORT void __kmpc_end_serialized_parallel(ident_t *, kmp_int32 global_tid);
 
 KMP_EXPORT void __kmpc_flush(ident_t *);
 KMP_EXPORT void __kmpc_barrier(ident_t *, kmp_int32 global_tid);
 KMP_EXPORT kmp_int32 __kmpc_master(ident_t *, kmp_int32 global_tid);
 KMP_EXPORT void __kmpc_end_master(ident_t *, kmp_int32 global_tid);
 KMP_EXPORT void __kmpc_ordered(ident_t *, kmp_int32 global_tid);

openmp/runtime/src/kmp_csupport.cpp

 #define __KMP_IMP
 #include "omp.h" /* extern "C" declarations of user-visible routines */
 #include "kmp.h"
 #include "kmp_error.h"
 #include "kmp_i18n.h"
 #include "kmp_itt.h"
 #include "kmp_lock.h"
 #include "kmp_stats.h"
+#include "ompt-internal.h"
 #include "ompt-specific.h"
 
 #define MAX_MESSAGE 512
 
 // flags will be used in future, e.g. to implement openmp_strict library
 // restrictions
 
 /*!
if (previous_state == stats_state_e::SERIAL_REGION) {
     KMP_EXCHANGE_PARTITIONED_TIMER(OMP_serial);
     KMP_SET_THREAD_STATE(previous_state);
   } else {
     KMP_POP_PARTITIONED_TIMER();
   }
 #endif // KMP_STATS_ENABLED
 }
 
+void __kmpc_parallel_51(ident_t *ident, kmp_int32 global_tid, kmp_int32 if_expr,
+                        kmp_int32 num_threads, kmp_proc_bind_t proc_bind,
+                        kmpc_parallel_region_ty fn, void *payload) {
+  // TODO: For now we simply translate to the old way but we should avoid
+  //       the varags call (via __kmpc_fork_call) all together in favor of
+  //       a single closure argument.
+
+  // Handle the serialized case first.
+  if (UNLIKELY(!if_expr)) {
+    __kmpc_serialized_parallel(ident, global_tid);
+    kmp_int32 bound_tid = 0;
+    fn(&global_tid, &bound_tid, payload);
+    __kmpc_end_serialized_parallel(ident, global_tid);
+    return;
+  }
+
+  // Handle the num_threads clause.
+  if (num_threads != -1)
+    __kmpc_push_num_threads(ident, global_tid, num_threads);
+
+  // Handle the proc_bind clause.
+  if (proc_bind != proc_bind_default)
+    __kmpc_push_proc_bind(ident, global_tid, proc_bind);
+
+  __kmpc_fork_call(ident, 1, kmpc_micro(fn), payload);
+}
+
 /*!
 @ingroup PARALLEL
 @param loc source location information
 @param global_tid global thread number
 @param num_teams number of teams requested for the teams construct
 @param num_threads number of threads per team requested for the teams construct
 
 Set the number of teams to be used by the teams construct.