libcilkrts/runtime/sysdep.h

   1 /* sysdep.h                  -*-C++-*-
   2  *
   3  *************************************************************************
   4  *
   5  *  Copyright (C) 2009-2016, Intel Corporation
   6  *  All rights reserved.
   7  *
   8  *  Redistribution and use in source and binary forms, with or without
   9  *  modification, are permitted provided that the following conditions
  10  *  are met:
  11  *
  12  *    * Redistributions of source code must retain the above copyright
  13  *      notice, this list of conditions and the following disclaimer.
  14  *    * Redistributions in binary form must reproduce the above copyright
  15  *      notice, this list of conditions and the following disclaimer in
  16  *      the documentation and/or other materials provided with the
  17  *      distribution.
  18  *    * Neither the name of Intel Corporation nor the names of its
  19  *      contributors may be used to endorse or promote products derived
  20  *      from this software without specific prior written permission.
  21  *
  22  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  24  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  25  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  26  *  HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  27  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  28  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
  29  *  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  30  *  AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
  32  *  WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  33  *  POSSIBILITY OF SUCH DAMAGE.
  34  *
  35  *  *********************************************************************
  36  *
  37  *  PLEASE NOTE: This file is a downstream copy of a file mainitained in
  38  *  a repository at cilkplus.org. Changes made to this file that are not
  39  *  submitted through the contribution process detailed at
  40  *  http://www.cilkplus.org/submit-cilk-contribution will be lost the next
  41  *  time that a new version is released. Changes only submitted to the
  42  *  GNU compiler collection or posted to the git repository at
  43  *  https://bitbucket.org/intelcilkruntime/intel-cilk-runtime.git are
  44  *  not tracked.
  45  *
  46  *  We welcome your contributions to this open source project. Thank you
  47  *  for your assistance in helping us improve Cilk Plus.
  48  **************************************************************************/
  49
  50 /**
  51  * @file sysdep.h
  52  *
  53  * @brief Common system-dependent functions
  54  */
  55
  56 #ifndef INCLUDED_SYSDEP_DOT_H
  57 #define INCLUDED_SYSDEP_DOT_H
  58
  59 #include <cilk/common.h>
  60 #include <internal/abi.h>
  61
  62 #include "global_state.h"
  63 #include "full_frame.h"
  64 #include "os.h"
  65 #include "os_mutex.h"
  66
  67 /**
  68  * @brief Default page size for Cilk stacks.
  69  *
  70  * All Cilk stacks should have size that is a multiple of this value.
  71  */
  72 #define PAGE 4096
  73
  74 /**
  75  * @brief Size of a scheduling stack.
  76  *
  77  * A scheduling stack is used to by system workers to execute runtime
  78  * code.  Since this stack is only executing runtime functions, we
  79  * don't need it to be a full size stack.
  80  *
  81  * The number "18" should be small since the runtime doesn't require a
  82  * large stack, but large enough to call "printf" for debugging.
  83  */
  84 #define CILK_SCHEDULING_STACK_SIZE (18*PAGE)
  85
  86 __CILKRTS_BEGIN_EXTERN_C
  87
  88
  89 /**
  90  * Code to initialize the system-dependent portion of the global_state_t
  91  *
  92  * @param g Pointer to the global state.
  93  */
  94 COMMON_SYSDEP
  95 void __cilkrts_init_global_sysdep(global_state_t *g);
  96
  97 /**
  98  * Code to clean up the system-dependent portion of the global_state_t
  99  *
 100  * @param g Pointer to the global state.
 101  */
 102 COMMON_SYSDEP
 103 void __cilkrts_destroy_global_sysdep(global_state_t *g);
 104
 105 /**
 106  * Passes stack range to Cilkscreen.  This functionality should be moved
 107  * into Cilkscreen.
 108  */
 109 COMMON_SYSDEP
 110 void __cilkrts_establish_c_stack(void);
 111
 112
 113 /**
 114  * Save system dependent information in the full_frame and
 115  * __cilkrts_stack_frame.  Part of promoting a
 116  * __cilkrts_stack_frame to a full_frame.
 117  *
 118  * @param w The worker the frame was running on.  Not used.
 119  * @param ff The full frame that is being created for the
 120  * __cilkrts_stack_frame.
 121  * @param sf The __cilkrts_stack_frame that's being promoted
 122  * to a full frame.
 123  * @param state_valid ?
 124  * @param why A description of why make_unrunnable was called.
 125  * Used for debugging.
 126  */
 127 COMMON_SYSDEP
 128 void __cilkrts_make_unrunnable_sysdep(__cilkrts_worker *w,
 129                                       full_frame *ff,
 130                                       __cilkrts_stack_frame *sf,
 131                                       int state_valid,
 132                                       const char *why);
 133
 134
 135 /**
 136  * OS-specific code to spawn worker threads.
 137  *
 138  * @param g The global state.
 139  * @param n Number of worker threads to start.
 140  */
 141 COMMON_SYSDEP
 142 void __cilkrts_start_workers(global_state_t *g, int n);
 143
 144 /**
 145  * @brief OS-specific code to stop worker threads.
 146  *
 147  * @param g The global state.
 148  */
 149 COMMON_SYSDEP
 150 void __cilkrts_stop_workers(global_state_t *g);
 151
 152 /**
 153  * @brief Imports a user thread the first time it returns to a stolen parent.
 154  *
 155  * The thread has been bound to a worker, but additional steps need to
 156  * be taken to start running a scheduling loop.
 157  *
 158  * @param w The worker bound to the thread.
 159  */
 160 COMMON_SYSDEP
 161 void __cilkrts_sysdep_import_user_thread(__cilkrts_worker *w);
 162
 163 /**
 164  * @brief Function to be run for each of the system worker threads.
 165  *
 166  * This declaration also appears in cilk/cilk_undocumented.h -- don't
 167  * change one declaration without also changing the other.
 168  *
 169  * @param arg The context value passed to the thread creation routine for
 170  * the OS we're running on.
 171  *
 172  * @returns OS dependent.
 173  */
 174 #ifdef _WIN32
 175 /* Do not use CILK_API because __cilkrts_worker_stub must be __stdcall */
 176 CILK_EXPORT unsigned __CILKRTS_NOTHROW __stdcall
 177 __cilkrts_worker_stub(void *arg);
 178 #else
 179 /* Do not use CILK_API because __cilkrts_worker_stub have default visibility */
 180 __attribute__((visibility("default")))
 181 void* __CILKRTS_NOTHROW __cilkrts_worker_stub(void *arg);
 182 #endif
 183
 184 /**
 185  * Initialize any OS-depenendent portions of a newly created
 186  * __cilkrts_worker.
 187  *
 188  * Exported for Piersol.  Without the export, Piersol doesn't display
 189  * useful information in the stack trace.  This declaration also appears in
 190  * cilk/cilk_undocumented.h -- do not modify one without modifying the other.
 191  *
 192  * @param w The worker being initialized.
 193  */
 194 COMMON_SYSDEP
 195 CILK_EXPORT
 196 void __cilkrts_init_worker_sysdep(__cilkrts_worker *w);
 197
 198 /**
 199  * Deallocate any OS-depenendent portions of a __cilkrts_worker.
 200  *
 201  * @param w The worker being deallocaed.
 202  */
 203 COMMON_SYSDEP
 204 void __cilkrts_destroy_worker_sysdep(__cilkrts_worker *w);
 205
 206 /**
 207  * Called to do any OS-dependent setup before starting execution on a
 208  * frame. Mostly deals with exception handling data.
 209  *
 210  * @param w The worker the frame will run on.
 211  * @param ff The full_frame that is about to be resumed.
 212  */
 213 COMMON_SYSDEP
 214 void __cilkrts_setup_for_execution_sysdep(__cilkrts_worker *w,
 215                                           full_frame *ff);
 216
 217 /**
 218  * @brief OS-specific implementaton of resetting fiber and frame state
 219  * to resume exeuction.
 220  *
 221  * This method:
 222  *  1. Calculates the value of stack pointer where we should resume
 223  *     execution of "sf".  This calculation uses info stored in the
 224  *     fiber, and takes into account alignment and frame size.
 225  *  2. Updates sf and ff to match the calculated stack pointer.
 226  *
 227  *  On Unix, the stack pointer calculation looks up the base of the
 228  *  stack from the fiber.
 229  *
 230  *  On Windows, this calculation is calls "alloca" to find a stack
 231  *  pointer on the currently executing stack.  Thus, the Windows code
 232  *  assumes @c fiber is the currently executing fiber.
 233  *
 234  * @param fiber   fiber to resume execution on.
 235  * @param ff      full_frame for the frame we're resuming.
 236  * @param sf      __cilkrts_stack_frame that we should resume
 237  * @return    The calculated stack pointer.
 238  */
 239 COMMON_SYSDEP
 240 char* sysdep_reset_jump_buffers_for_resume(cilk_fiber* fiber,
 241                                            full_frame *ff,
 242                                            __cilkrts_stack_frame *sf);
 243
 244 /**
 245  * @brief System-dependent longjmp to user code for resuming execution
 246  *   of a @c __cilkrts_stack_frame.
 247  *
 248  * This method:
 249  *  - Changes the stack pointer in @c sf to @c new_sp.
 250  *  - If @c ff_for_exceptions is not NULL, changes fields in @c sf and
 251  *    @c ff_for_exceptions for exception processing.
 252  *  - Restores any floating point state
 253  *  - Finishes with a longjmp to user code, never to return.
 254  *
 255  * @param new_sp             stack pointer where we should resume execution
 256  * @param sf                 @c __cilkrts_stack_frame for the frame we're resuming.
 257  * @param ff_for_exceptions  full_frame to safe exception info into, if necessary
 258  */
 259 COMMON_SYSDEP
 260 NORETURN
 261 sysdep_longjmp_to_sf(char* new_sp,
 262                      __cilkrts_stack_frame *sf,
 263                      full_frame *ff_for_exceptions);
 264
 265 /**
 266  * @brief System-dependent code to save floating point control information
 267  * to a @c __cilkrts_stack_frame.  This function will be called by compilers
 268  * that cannot inline the code.
 269  *
 270  * Note that this function does *not* save the current floating point
 271  * registers.  It saves the floating point control words that control
 272  * precision and rounding and stuff like that.
 273  *
 274  * This function will be a noop for architectures that don't have warts
 275  * like the floating point control words, or where the information is
 276  * already being saved by the setjmp.
 277  *
 278  * @param sf                 @c __cilkrts_stack_frame for the frame we're
 279  * saving the floating point control information in.
 280  */
 281 COMMON_SYSDEP
 282 void
 283 sysdep_save_fp_ctrl_state(__cilkrts_stack_frame *sf);
 284
 285
 286 /**
 287  * @brief restore x86 floating point state
 288  *
 289  * Only used for x86 and Intel64 processors
 290  */
 291 COMMON_SYSDEP
 292 void restore_x86_fp_state(__cilkrts_stack_frame *sf);
 293
 294 __CILKRTS_END_EXTERN_C
 295
 296 #endif // ! defined(INCLUDED_SYSDEP_DOT_H)