hphp/runtime/vm/jit/unique-stubs.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-present Facebook, Inc. (http://www.facebook.com)  |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16
  17 #pragma once
  18
  19 #include "hphp/runtime/vm/call-flags.h"
  20 #include "hphp/runtime/vm/hhbc.h"
  21
  22 #include "hphp/runtime/vm/jit/code-cache.h"
  23 #include "hphp/runtime/vm/jit/containers.h"
  24 #include "hphp/runtime/vm/jit/types.h"
  25 #include "hphp/runtime/vm/jit/phys-reg.h"
  26 #include "hphp/runtime/vm/jit/srcdb.h"
  27 #include "hphp/runtime/vm/jit/stack-offsets.h"
  28
  29 #include <string>
  30 #include <vector>
  31
  32 namespace HPHP {
  33
  34 struct ActRec;
  35 struct SrcKey;
  36
  37 namespace Debug { struct DebugInfo; }
  38
  39 namespace jit {
  40
  41 ///////////////////////////////////////////////////////////////////////////////
  42
  43 constexpr int kNumFreeLocalsHelpers = 7;
  44
  45 /*
  46  * Addresses of various unique, long-lived JIT helper routines.
  47  *
  48  * The global set of unique stubs is emitted when we initialize the TC.
  49  */
  50 struct UniqueStubs {
  51   /*
  52    * Unique stubs, ABIs, and stack alignment.
  53    *
  54    * A lot of complex control flow occurs amongst the various unique stubs, as
  55    * well as between the unique stubs and the TC.  This complexity is
  56    * exacerbated by the profusion of different ABIs used when entering and
  57    * exiting the stubs.
  58    *
  59    * The goal of the documentation in this file is to enumerate all the ways
  60    * each stub is reached, as well as to clarify the ABI boundaries they
  61    * implement to, if any.
  62    *
  63    * Among the most important ABI invariants in jitted code is this:
  64    *
  65    *    - In the body of a PHP function, after the initial instructions of the
  66    *      func prologue, the native stack pointer is always 16-byte aligned.
  67    *
  68    * This holds even when the register allocator inserts stack spills; we
  69    * always offset the native stack pointer in increments of 16.
  70    *
  71    * Many target architectures have 16-byte stack alignment restrictions.  On
  72    * x64, for example, the stack must be 16-byte aligned before calls, to allow
  73    * the compiler to safely use aligned movs, e.g., for saving callee-saved XMM
  74    * registers.  On AArch64, attempting to address the stack pointer when it is
  75    * not 16-byte aligned results in a fault.
  76    *
  77    * Our alignment invariant should be sufficient for architectures with
  78    * 16-byte (or looser) alignment constraints.  We don't currently support any
  79    * higher- order alignment restrictions.
  80    *
  81    * Our other ABI concern is calling convention.  HHVM supports three distinct
  82    * calling conventions:
  83    *    - native: C++ helper calls on the targeted architecture
  84    *    - PHP:    calls between PHP functions, as well as to those unique stubs
  85    *              which play the same role as various parts of PHP functions
  86    *    - stub:   calls to unique stubs that implement helper routines
  87    *
  88    * Maintaining native stack alignment, and appropriately stashing the return
  89    * address, is shared between the call, return, and callee prologue
  90    * instructions for each convention:
  91    *
  92    *            +---------------------+---------+-----------+
  93    *            | main call instrs    | return  | prologue  |
  94    *  +---------+---------------------+---------+-----------+
  95    *  | native  | call{,r,m,s}        | ret     | N/A       |
  96    *  +---------+---------------------+---------+-----------+
  97    *  | PHP     | phpcall             | phpret  | phplogue  |
  98    *  +---------+---------------------+---------+----------+
  99    *  | stub    | callstub            | stubret | stublogue |
 100    *  +---------+---------------------+---------+-----------+
 101    *
 102    * Further documentation on these calling conventions can be found in
 103    * vasm-instr.h, alongside the corresponding instructions.
 104    *
 105    * Each stub is documented below with a (hopefully) exhaustive list of ways
 106    * it is reached, as well as the context under which it is reached:
 107    *    - func guard:     pre-phplogue{}; an intermediate state where
 108    *                      addressing the stack and making native calls are
 109    *                      forbidden
 110    *    - func prologue:  implements a phplogue{}
 111    *    - func body:      dominated by a phplogue{}; already ABI-conforming
 112    *    - stub:           implements a stublogue{}
 113    */
 114
 115   /////////////////////////////////////////////////////////////////////////////
 116   // Function entry.
 117
 118   /*
 119    * Dynamically dispatch to the appropriate func prologue based on the
 120    * information in php_call_regs, while repacking arguments as needed.
 121    *
 122    * @reached:  callphp from TC
 123    * @context:  func guard
 124    */
 125   TCA funcPrologueRedispatch;
 126   TCA funcPrologueRedispatchUnpack;
 127
 128   /*
 129    * Look up or emit a func prologue and jump to it---or, failing that, call
 130    * native routines that do the same work.
 131    *
 132    * All entries in the prologue tables of all Funcs are initialized to this
 133    * stub, so that we can lazily generate their prologues.  If codegen for the
 134    * prologue succeeds, we update the prologue table to point to the new
 135    * prologue instead of this stub.
 136    *
 137    * @reached:  callphpr from TC
 138    *            callphps from TC
 139    *            jmp from immutableBindCallStub
 140    *            jmp from funcPrologueRedispatch
 141    *            jmp from funcPrologueRedispatchUnpack
 142    * @context:  func prologue
 143    */
 144   TCA fcallHelperThunk;
 145   TCA fcallHelperNoTranslateThunk;
 146
 147   /*
 148    * Call EventHook::onFunctionCall() and handle the case where it requests
 149    * that we skip the function.
 150    *
 151    * @reached:  vinvoke from func prologue
 152    *            jmp from functionSurprisedOrStackOverflow
 153    * @context:  stub
 154    */
 155   TCA functionEnterHelper;
 156
 157   /*
 158    * Handle either a surprise condition or a stack overflow.
 159    *
 160    * Also gracefully handles spurious wake-ups that result from racing with a
 161    * background thread clearing surprise flags.
 162    *
 163    * @reached:  vinvoke from func prologue
 164    * @context:  stub
 165    */
 166   TCA functionSurprisedOrStackOverflow;
 167
 168
 169   /////////////////////////////////////////////////////////////////////////////
 170   // Function return.
 171
 172   /*
 173    * Return from a function when the ActRec was pushed by the interpreter.
 174    *
 175    * The return IP on the ActRec will be set to one of these stubs, so if
 176    * someone tries to execute a return instruction, handlePostInterpRet() gets
 177    * a chance to translate the code starting at the return address.
 178    *
 179    * Generators need a different stub because the ActRec for a generator is in
 180    * the heap.
 181    *
 182    * @reached:  phpret from TC
 183    * @context:  func body (after returning to caller)
 184    */
 185   TCA retHelper;
 186   TCA genRetHelper;       // version for generator
 187   TCA asyncGenRetHelper;  // version for async generators
 188
 189   /*
 190    * Return from a function when the ActRec was pushed by an inlined call.
 191    *
 192    * This is the same as retHelper, but is kept separate to aid in debugging.
 193    *
 194    * @reached:  phpret from TC
 195    * @context:  func body (after returning to caller)
 196    */
 197   TCA retInlHelper;
 198
 199   /*
 200    * Return from a resumed async function.
 201    *
 202    * Store result into the AsyncFunctionWaitHandle, mark it as finished and
 203    * unblock its parents. Check whether the first parent is eligible to be
 204    * resumed directly (it is an AsyncFunctionWaitHandle in the same context
 205    * with a non-null resume address), and do so if possible. Otherwise, jump
 206    * to asyncSwitchCtrl. Slow version doesn't try to resume and just returns
 207    * to the asio scheduler.
 208    *
 209    * rvmfp() should point to the ActRec of the AsyncFunctionWaitHandle that
 210    * is returning, rvmsp() should point to an uninitialized cell on the
 211    * stack containing garbage.
 212    *
 213    * @reached:  jmp from TC
 214    * @context:  func body
 215    */
 216   TCA asyncFuncRet;
 217   TCA asyncFuncRetSlow;
 218
 219   /*
 220    * Async function finish-suspend-and-resume stub.
 221    *
 222    * Check for fast resumables on the AsioContext runnable queue.  If one is
 223    * found that is ready to run, jump to it directly; otherwise, leave the TC
 224    * and return to the scheduler.
 225    *
 226    * rvmfp() should point to the ActRec of the WaitHandle that is suspending.
 227    *
 228    * @reached:  jmp from TC
 229    * @context:  func body
 230    */
 231   TCA asyncSwitchCtrl;
 232
 233
 234   /////////////////////////////////////////////////////////////////////////////
 235   // Function calls.
 236
 237   /*
 238    * Stub for immutable PHP calls.
 239    *
 240    * @reached:  callphps from TC
 241    * @context:  func prologue
 242    */
 243   TCA immutableBindCallStub;
 244
 245
 246   /////////////////////////////////////////////////////////////////////////////
 247   // Interpreter stubs.
 248
 249   /*
 250    * Restart execution based on the value of vmpc.  Used, e.g., to resume
 251    * execution after an InterpOne.
 252    *
 253    * Expects that all VM registers are synced.
 254    *
 255    * @reached:  entry from jit::enterTC
 256    *            jmp from fcallHelperThunk
 257    *            call from enterTCHelper
 258    * @context:  func body
 259    */
 260   TCA resumeHelper;
 261   TCA resumeHelperNoTranslate;
 262
 263   /*
 264    * Like resumeHelper, but interpret a basic block first to ensure we make
 265    * forward progress.
 266    *
 267    * interpHelper expects the correct value of vmpc to be in the first argument
 268    * register and syncs it, whereas interpHelperSyncedPC expects vmpc to be
 269    * synced a priori.  Both stubs will sync the vmsp and vmfp registers to
 270    * vmRegs before passing control to the interpreter.
 271    *
 272    * @reached:  jmp from TC
 273    * @context:  func body
 274    */
 275   TCA interpHelper;
 276   TCA interpHelperSyncedPC;
 277   TCA interpHelperNoTranslate;
 278
 279   /*
 280    * Stubs for each bytecode with the CF flag, which InterpOne the bytecode and
 281    * then call resumeHelper.
 282    *
 283    * These stubs expect rvmfp() and rvmsp() to be live, and rAsm to contain the
 284    * offset to the bytecode to interpret.
 285    *
 286    * @reached:  jmp from TC
 287    * @context:  func body
 288    */
 289   jit::fast_map<Op, TCA> interpOneCFHelpers;
 290
 291
 292   /////////////////////////////////////////////////////////////////////////////
 293   // DecRefs.
 294
 295   /*
 296    * Expensive, generic decref of a value with an unknown (but known to be
 297    * refcounted) DataType.
 298    *
 299    * The value to be decref'd should be in the first two argument registers
 300    * (data, type).  All GP registers are saved around the destructor call.
 301    *
 302    * @reached:  callfaststub from TC
 303    * @context:  stub
 304    */
 305   TCA decRefGeneric;
 306
 307   /*
 308    * Perform generic decrefs of locals on function return.
 309    *
 310    * Each freeLocalHelpers[i] is an entry point to a partially-unrolled loop.
 311    * freeManyLocalsHelper should be used instead when there are more than
 312    * kNumFreeLocalsHelpers locals.
 313    *
 314    * These helpers expect the address of the frame's last local variable (which
 315    * has the lowest address) to be passed in the second argument register.  The
 316    * first argument register is ignored.
 317    *
 318    * @reached:  vcall from TC
 319    * @context:  stub
 320    */
 321   TCA freeLocalsHelpers[kNumFreeLocalsHelpers];
 322   TCA freeManyLocalsHelper;
 323
 324
 325   /////////////////////////////////////////////////////////////////////////////
 326   // Other stubs.
 327
 328   /*
 329    * Enter (or reenter) the TC.
 330    *
 331    * This is an assembly stub called from native code to transfer control
 332    * (back) to jitted PHP code.
 333    *
 334    * enterTCExit is the address returned to when we leave the TC.
 335    */
 336   void (*enterTCHelper)(TCA start, ActRec* fp, void* tl, TypedValue* sp,
 337                         ActRec* firstAR);
 338   TCA enterTCExit;
 339
 340   /*
 341    * Return from this VM nesting level to the previous one.
 342    *
 343    * This has the same effect as a leavetc{} instruction---it pops the address
 344    * of enterTCExit off the stack and transfers control to it.
 345    *
 346    * @reached:  phpret from TC
 347    *            jmp from TC
 348    * @context:  func body
 349    */
 350   TCA callToExit;
 351
 352   /*
 353    * Perform dispatch at the end of a catch block.
 354    *
 355    * The endCatchHelper passes the current vmfp() to the unwinder to determine
 356    * the catch trace of the return address of the parent frame.
 357    *
 358    * The endCatchStublogueHelper passes the current vmfp() and RIP saved in
 359    * the stublogue header. Unwinder uses it to determine the catch trace of
 360    * the return adddress belonging to the same logical vmfp().
 361    *
 362    * The endCatchStubloguePrologueHelper initializes the ActRec space pointed
 363    * to by the rvmsp() to uninits and continues at endCatchStublogueHelper.
 364    *
 365    * If the unwinder has set state indicating a return address to jump to, we
 366    * load vmfp and vmsp and jump there.  Otherwise, we call _Unwind_Resume.
 367    */
 368   TCA resumeCPPUnwind;
 369   TCA endCatchSkipTeardownHelper;
 370   TCA endCatchTeardownThisHelper;
 371   TCA endCatchHelper;
 372   TCA endCatchHelperPast;
 373   TCA endCatchStublogueHelper;
 374   TCA endCatchStubloguePrologueHelper;
 375   TCA unwinderAsyncRet;
 376   TCA unwinderAsyncNullRet;
 377
 378   /*
 379    * Throws an exception from the unwinder to enter the itanium unwinder
 380    */
 381   TCA throwExceptionWhileUnwinding;
 382
 383   /*
 384    * Service request helper.
 385    *
 386    * Packs service request arguments into a struct on the stack before calling
 387    * the C++ service request handler.
 388    *
 389    * @reached:  jmp from TC
 390    * @context:  func body
 391    */
 392   TCA handleSRHelper;
 393
 394   /*
 395    * Handle a request to retranslate the current function in optimized mode.
 396    * See svcreq::handleRetranslateOpt() for more details.
 397    *
 398    * @reached:  jmp from TC
 399    * @context:  func body
 400    */
 401   TCA handleRetranslateOpt;
 402
 403   /////////////////////////////////////////////////////////////////////////////
 404
 405   /*
 406    * Emit the full set of unique stubs to `code'.
 407    */
 408   void emitAll(CodeCache& code, Debug::DebugInfo& dbg);
 409
 410   /*
 411    * Utility for logging stub addresses during startup and registering the gdb
 412    * symbols.  It's often useful to know where they were when debugging.
 413    */
 414   void add(const char* name,
 415            const CodeCache& code,
 416            TCA start,
 417            CodeCache::View view,
 418            TransLoc loc,
 419            Debug::DebugInfo& dbg);
 420
 421   /*
 422    * If the given address is within one of the registered stubs, return a
 423    * string indicating which stub and how far in it is: "retHelper+0xfa".
 424    *
 425    * Otherwise, return a string representation of the raw address: "0xabcdef".
 426    */
 427   std::string describe(TCA addr) const;
 428
 429 private:
 430   /*
 431    * Emit all Resumable-related unique stubs to `code'.
 432    */
 433   void emitAllResumable(CodeCache& code, Debug::DebugInfo& dbg);
 434
 435   struct StubRange {
 436     std::string name;
 437     TCA start, end;
 438
 439     bool operator<(const StubRange& other) const {
 440       return start < other.start;
 441     }
 442
 443     bool contains(TCA address) const {
 444       return start <= address && address < end;
 445     }
 446   };
 447
 448   std::vector<StubRange> m_ranges;
 449 };
 450
 451 ////////////////////////////////////////////////////////////////////////////////
 452
 453 /*
 454  * Registers that are live on entry to an interpOneCFHelper.
 455  */
 456 RegSet interp_one_cf_regs();
 457
 458 /*
 459  * Emit code to `v' which jumps to interpHelper with the proper arguments.
 460  */
 461 void emitInterpReq(Vout& v, SrcKey sk, SBInvOffset spOff);
 462 void emitInterpReqNoTranslate(Vout& v, SrcKey sk, SBInvOffset spOff);
 463
 464 ///////////////////////////////////////////////////////////////////////////////
 465
 466 /*
 467  * Wrappers around the enterTC*Helper stubs, called from enterTC*().
 468  */
 469 void enterTCImpl(TCA start);
 470
 471 ///////////////////////////////////////////////////////////////////////////////
 472
 473 }}