ir.specification

*******************************************
* HipHop Intermediate Representation (HHIR)
*******************************************



Introduction
------------

The HipHop Intermediate Representation (IR) is a typed, in-memory,
static-single-assignment, intermediate-level representation of HHBC programs
used for just in time compilation, with these goals:

  1. Complete. The IR represents a program or program fragment entirely,
     without reference to HHBC or other upstream forms of the program.

  2. Type-Safe. Since the IR deals directly with refined types and internal VM
     types, all operations are typesafe. All instruction parameters have a
     parameter type P, and all variables have a type S. Given an instruction
     with source parameter type P and variable type S, S must be equal to or
     more refined than P (S == P or S <: P).

  3. Machine Independent. Since this IR is intended to be used in a JIT
     compiler, it will always be used in a machine specific context.
     Nevertheless, we rely on machine independence in order to separate
     concerns and increase portability of the VM. Passes which manipulate IR
     based on PHP or HHBC semantics should be portable. Passes which deal with
     machine specifics (such as register allocation) should be done in the
     lower level IR (vasm). Types are machine independent.

The unit of compilation is the IRUnit, which is a collection of Blocks
containing IRInstructions that produce and consume SSATmp values. Blocks are
single-entry, single-exit sequences of instructions (i.e. basic
blocks). Instructions may be annotated with Type parameter which modifies the
instruction's behavior, or with additional compile-time constant data (see
extra-data.h). Each SSATmp has a Type which describes the set of values it may
hold, over its entire live range. Instructions may have side effects, which
occur in execution order.

The static single assignment form guarantees the following two invariants for a
well-formed compilation unit:

  1. Each SSATmp is assigned to by exactly one IRInstruction.

  2. Definitions dominate uses. Every path to an IRInstruction using an SSATmp
     first executes the IRInstruction defining the SSATmp.

Any pass that generates or manipulates IR must preserve these invariants,
however it is possible and expected for the invariants to be temporarily broken
during IR generation or during an optimization pass.


Control Flow
------------

IRUnits have one entry block, zero or more exit blocks, and zero or more catch
blocks. Exit blocks leave the compilation unit in the middle of the same PHP
function using one of several instructions that exit a compilation unit
(e.g. ReqBindJmp). Catch blocks are blocks that are reachable from exceptional
control flow edges, and are executed during unwinding if an exception
propagates through the instruction that had it as a `taken' edge.

No SSATmps are defined on entry to the main Block.

Blocks which are join points may start with a DefLabel with destination
SSATmps. In that case, each predecessor must be a Jmp passing a matching number
of sources. In this case the Jmp acts as a tail-call, passing arguments the
same way a plain call would.

Together, the sources of the Jmp instructions and the destinations of the
DefLabel instructions act as traditional SSA Phi pseudo-functions; The type of
the DefLabel's destination is the type-union of the corresponding sources.
Because the Jmp sources are at the ends of blocks, they do not violate the SSA
dominator rule (rule 2, above).


Types
-----

For an overview of the HHIR type system, see the "Type System" section in
hackers-guide/jit-core.md.


SSATmps
-------

An SSATmp represents a virtual register. Since HHIR uses SSA, an SSATmp may
only be assigned to by one instruction. The type of an SSATmp represents the
set of values it may hold at the point it is defined, which is invariant over
the lifetime of the variable (from the definition point to the last use).


IRInstructions
--------------

An instruction is an executable operation with zero or more inputs (sources),
zero or one result (destination), and possible side effects such as accessing
memory, doing I/O, and which may branch or throw an exception. Some
instructions have a Type parameter which modifies its behavior, or other "extra
data" in an arbitrary C++ struct (see extra-data.h).

Each instruction has a signature which describes its effect, parameter types,
and return type, for example:

  r:Bool = IsType<T> s:Gen

By convention we use infix; destinations on the left, = represents assignment,
then the opcode name, and source parameters. Types are to the right of the
entities they modify, separated by : for results, sources, and variables, or
delimited by <> for instruction modifiers.

Instruction flags further describe their behavior:

HasDest
NaryDest

  The instruction defines exactly one destination variable (HasDest) or a
  varying number of destination variables (NaryDest). These flags are mutually
  exclusive. An instruction with neither of these flags set has zero
  destination variables.

  Note that an instruction's destination variable may sometimes be a copy of
  one of the input variables. (For example, AddElem returns the array it took
  as an input.)

CanCSE

  The instruction is safe to elide through common subexpression elimination.

Essential

  Whether the instruction is essential indicates whether it can be elided
  through certain types of optimizations.

  Currently this is just used to flag whether we are allowed to do dead code
  elimination on it.

CallsNative

  Indicates that the instruction will call a native helper.

  The register allocator uses this to optimize register spills around native
  calls and to bias register allocation toward arguments and return values.

ConsumesRC

  The instruction consumes a reference to one or more of its sources, either by
  decreasing its refcount or storing the reference to memory.

KillsSource

  The instruction calls decref on one or more of its sources. Unless a source
  is known to have a refcount > 1 before the instruction executes, it cannot
  safely be used after the instruction has executed.

ProducesRC

  The instruction produces an incref'd value.

  This flag is currently unused.

MayRaiseError

  The instruction may raise an error, and must have an edge to a catch block.

Terminal

  The instruction has no next instruction; it either jumps, returns, or throws.

Branch

  The instruction has a (sometimes optional) taken edge. Instructions that are
  conditional branches (i.e. a Branch that is not Terminal) will also have a
  next edge.

Passthrough

  The value of the instruction's dest is the same as one of its inputs; it
  differs only in the refcount of the underlying object, the type of the
  variable, or some other property that doesn't affect the value of the
  variable itself.

ModifiesStack

  The instruction modifies the in-memory evaluation stack in the process of
  performing its primary work. It will have a StkPtr destination in addition to
  its primary destination.

HasStackVersion

  This instruction has a counterpart that returns a StkPtr in addition to any
  primary destination. The behavior of the stack-modifying version is otherwise
  identical.

MInstrProp

  The instruction may affect the type and/or value of its base operand,
  operating on object properties.

MInstrElem

  The instruction may affect the type and/or value of its base operand,
  operating on array elements.


Instruction set
---------------

1. Checks and Asserts

Note: Instructions that guard or check boxed types only check that the operand
is boxed, and they ignore the type of the value inside the box (the inner
type). The inner type is normally checked when the value within the box is
about to be loaded, using a separate CheckRefInner instruction.

| CheckType<T>, DRefineS(0), S(Gen), B|E|P

  Check that the type of the src S0 is T, and if so copy it to D. If S0 is not
  type T, branch to block B.

| CheckNullptr, ND, S(CountedStr,Nullptr), B|E|CRc

  If S0 is not a null pointer, branch to block B. This is used to check the
  return value of a native helper that returns a potentially null StringData*.

| AssertType, DRefineS(0), S(Gen,Cls), C|E|P

  Assert that the type of S0 is T, copying it to D.

| CheckTypeMem<T>, ND, S(PtrToGen), B|E

  If the value pointed to by S0 is not type T, branch to the block B.

| GuardLoc<T,localId>, ND, S(FramePtr) S(StkPtr), E

  Guard that type of the given localId on the frame S0 is a subtype of the type
  T; if not, make a fallback jump. (A jump to a service request that chains to
  a retranslation for this tracelet.)

  Returns a new frame pointer representing the same frame as S0 but with the
  knowledge that the guarded local has type T.

| HintLocInner<T,localId>, ND, S(FramePtr), E

  Hint that the inner type of a BoxedCell in localId is likely type T, where T
  is a subtype of BoxedCell. The type must be guarded on before it is known to
  be true (via LdRef).

| CheckLoc<T,localId>, ND, S(FramePtr), B|E

  Check that type of the given localId on the frame S0 is T; if not, branch to
  block B.

  Returns a new frame pointer representing the same frame as S0 but with the
  knowledge that the checked local has type T.

| AssertLoc<T,localId>, ND, S(FramePtr), E

  Asserts that type of the supplied local on the frame S0 is T. This is used
  for local type information, and is similar to GuardLoc except it doesn't
  imply a runtime check (the assertion must've already been proven to be true)
  and cannot cause control flow.

  Returns a new frame pointer representing the same frame as S0 but with the
  knowledge that the asserted local has type T.

| GuardStk<T,offset>, D(StkPtr), S(StkPtr) S(FramePtr), E

  Guard that the type of the cell on the stack pointed to by S0 at offset (in
  cells) is T. If not, make a fallback jump. (A jump to a service request that
  chains to a retranslation for this tracelet.)

  Returns a new StkPtr that represents the same stack but with the knowledge
  that the slot at the index S1 has type T.

| HintStkInner<T,offset>, D(StkPtr), S(StkPtr), E

  Hint that the inner type of the BoxedInitCell on the stack pointed to by S0
  at offset (in cells) is T. The type must be guarded on before it is known to
  be true (via LdRef).

  Returns a new StkPtr that represents the same stack but with the prediction
  information.

| CheckStk<T,offset>, D(StkPtr), S(StkPtr), B|E

  Check that the type of the cell on the stack pointed to by S0 at offset (in
  cells) is T; if not, branch to block B.

  Returns a new StkPtr that represents the same stack but with the knowledge
  that the slot at the index S1 has type T.

| AssertStk<T,offset>, D(StkPtr), S(StkPtr), E

  Returns a new StkPtr that represents the same stack as S0, but with the
  knowledge that the slot at offset (in cells) has type T. This is similar to a
  GuardStk except that it does not imply a runtime check and cannot cause
  control flow.

| CastStk<T,offset>, D(StkPtr), S(StkPtr), Er

  Returns a new StkPtr that represents the same stack as S0, but with the slot
  at offset (in cells) converted to type T.

| CastStkIntToDbl<offset>, D(StkPtr), S(StkPtr), E

  Returns a new StkPtr where the slot at offset has been converted from an
  integer to double.


The following instructions deal with parameter coercion (the standard type
conversion for arguments to HNI functions). If parameter coercion fails these
functions will throw a TVCoercion exception. They may throw other types of
exceptions depending on how coercion is implemented.

| CoerceStk<T,offset,fn,argNum>, D(StkPtr), S(StkPtr), Er

  Returns a new StkPtr that represents the same stack as S0, but with the slot
  at offset (in cells) converted to type T. May throw an exception in the case
  of failed parameter coercion. The callee is f, and the position of the
  argument being coerced is argNum.

| CoerceCellToBool<fn,argNum>, D(Bool), S(Cell), Er

| CoerceCellToInt<fn,argNum>,  D(Int), S(Cell), Er

| CoerceStrToInt<fn,argNum>,   D(Int), S(Str), Er

| CoerceCellToDbl<fn,argNum>,  D(Dbl), S(Cell), Er

| CoerceStrToDbl<fn,argNum>,   D(Dbl), S(Str), Er

  These instructions convert either a Cell or a Str to a primitive type (Bool,
  Int, Dbl) and return the resulting value. They may throw an exception upon
  failed type coercion. They are encoded along with callee Func, fn, and the
  integer position of the argument, argNum, being coerced.

| CheckInit, ND, S(Gen), B

  If S0's type is Uninit, branch to block B.

| CheckInitMem, ND, S(PtrToGen) C(Int), B

  If the value at S0 + S1 (in bytes) has type Uninit, branch to block B.

| CheckCold<TransID>, ND, NA, B|E

  Check if the counter associated with translation TransID is cold (i.e. within
  a fixed threshold). If it's not (i.e. such translation has reached the
  "hotness threshold"), then branch to block B.

| GuardRefs, ND, S(Func) S(Int) C(Int) S(Int) S(Int) S(FramePtr) S(StkPtr), E

  Perform reffiness guard checks. Operands:

    S0 - function pointer for the frame
    S1 - num params expected in the func
    S2 - first bit to check, must be a multiple of 64
    S3 - mask to check (RefDeps::Record::m_mask entries)
    S4 - values to check (RefDeps::Record::m_vals entries)
    S5 - Pointer to the current frame
    S6 - Pointer to the current VM stack

  If any of the checks fail, make a fallback jump. (Jump to a service request
  that will chain to a retranslation of this tracelet.)

| CheckRefs, ND, S(Func) S(Int) C(Int) S(Int) S(Int), B|E

  Perform reffiness guard checks. Operands:

    S0 - function pointer for the frame
    S1 - num params expected in the func
    S2 - first bit to check, must be a multiple of 64
    S3 - mask to check (RefDeps::Record::m_mask entries)
    S4 - values to check (RefDeps::Record::m_vals entries)

  If any of the checks fail, branch to block B.

| EndGuards, ND, NA, E

  A no-op at runtime, this instruction serves to mark the end of the initial
  sequence of guards in a trace.

| CheckNonNull, DSubtract(0, Nullptr), S(Nullptr,Func,PtrToGen,TCA,Cls), B

  If the value in S0 is Nullptr, branch to block B.

| AssertNonNull, DSubtract(0, Nullptr), S(Nullptr,CountedStr,Func), P

  Returns S0, with Nullptr removed from its type. This instruction currently
  supports a very limited range of types but can be expanded if needed.

| CheckStaticLocInit, ND, S(BoxedCell), B

  Check if the static local (RDS) RefData represented by S0 is initialized, and
  if not branch to block B.


2. Arithmetic


| AbsDbl, D(Dbl), S(Dbl), C

| AddInt, D(Int), S(Int) S(Int), C

| SubInt, D(Int), S(Int) S(Int), C

| MulInt, D(Int), S(Int) S(Int), C

| AndInt, D(Int), S(Int) S(Int), C

| AddDbl, D(Dbl), S(Dbl) S(Dbl), C

| SubDbl, D(Dbl), S(Dbl) S(Dbl), C

| MulDbl, D(Dbl), S(Dbl) S(Dbl), C

| DivDbl, D(Dbl), S(Dbl) S(Dbl), B|C

| Sqrt, D(Dbl), S(Dbl), C

| OrInt, D(Int), S(Int) S(Int), C

| XorInt, D(Int), S(Int) S(Int), C

| Shl, D(Int), S(Int) S(Int), C

| Shr, D(Int), S(Int) S(Int), C

| Floor, D(Dbl), S(Dbl), C

| Ceil, D(Dbl), S(Dbl), C

| AddIntO, D(Int), S(Int) S(Int), B|C

| SubIntO, D(Int), S(Int) S(Int), B|C

| MulIntO, D(Int), S(Int) S(Int), B|C

  Double arithmetic, integer arithmetic, and integer bitwise operations.
  Performs the operation described by the opcode name on S0 and S1, and puts
  the result in D.

  Undefined behavior occurs if Mod is given a divisor of zero, or if the
  divisor is -1 and the dividend is the minimum representable integer.

  AbsDbl computes the absolute value of a double-precision value.

  DivDbl will branch to block B when S1 is zero (signed or unsigned). When the
  result of the division is a real valued number DivDbl conforms to IEEE 754.
  In particular should the result of a division be zero the sign will follow
  normal sign rules for division.

  Note that Shr is an arithmetic right shift: The MSB is sign-extended.

  Floor and Ceil will return an integral value not greater, or not less
  than their input respectively. Their use requires SSE 4.1, availability
  should be checked before they are emitted.

  AddIntO, SubIntO, MulIntO perform integer arithmetic on S0 and S1, but will
  branch to block B on integer overflow.

| XorBool, D(Bool), S(Bool) S(Bool), C

  Logical XOR of the two sources. (Note that && and || do not have
  corresponding opcodes because they're handled at the bytecode level, to
  implement short-circuiting.)

| Mod, D(Int), S(Int) S(Int), C

  Compute S0 mod S1. If S1 is -1 or 0 the results are undefined.

3. Type conversions


To array conversions:

| ConvBoolToArr,                D(Arr), S(Bool),                       C|PRc

| ConvDblToArr,                 D(Arr), S(Dbl),                        C|PRc

| ConvIntToArr,                 D(Arr), S(Int),                        C|PRc

| ConvObjToArr,                 D(Arr), S(Obj),                 Er|PRc|CRc|K

| ConvStrToArr,                 D(Arr), S(Str),                      PRc|CRc

| ConvCellToArr,                D(Arr), S(Cell),                Er|PRc|CRc|K


To bool conversions:

| ConvArrToBool,               D(Bool), S(Arr),                           NF

| ConvDblToBool,               D(Bool), S(Dbl),                            C

| ConvIntToBool,               D(Bool), S(Int),                            C

| ConvStrToBool,               D(Bool), S(Str),                           NF

| ConvObjToBool,               D(Bool), S(Obj),                           NF

| ConvCellToBool,              D(Bool), S(Cell),                          NF


To double conversions:

| ConvArrToDbl,                 D(Dbl), S(Arr),                           NF

| ConvBoolToDbl,                D(Dbl), S(Bool),                           C

| ConvIntToDbl,                 D(Dbl), S(Int),                            C

| ConvObjToDbl,                 D(Dbl), S(Obj),                           Er

| ConvStrToDbl,                 D(Dbl), S(Str),                           NF

| ConvCellToDbl,                D(Dbl), S(Cell),                          Er


To int conversions:

| ConvArrToInt,                 D(Int), S(Arr),                           NF

| ConvBoolToInt,                D(Int), S(Bool),                           C

| ConvDblToInt,                 D(Int), S(Dbl),                            C

| ConvObjToInt,                 D(Int), S(Obj),                         Er|K

| ConvStrToInt,                 D(Int), S(Str),                           NF

| ConvCellToInt,                D(Int), S(Cell),                        Er|K


To object conversions:

| ConvCellToObj, D(Obj), S(Cell), Er|CRc|PRc|K


To string conversions:

| ConvBoolToStr,          D(StaticStr), S(Bool),                           C

| ConvDblToStr,                 D(Str), S(Dbl),                          PRc

| ConvIntToStr,                 D(Str), S(Int),                          PRc

| ConvObjToStr,                 D(Str), S(Obj),                       PRc|Er

| ConvResToStr,                 D(Str), S(Res),                       PRc|Er

| ConvCellToStr,                D(Str), S(Cell),                      PRc|Er


  All the above opcodes convert S0 from its current type to the destination
  type, according to the PHP semantics of such a conversion.

| ConvClsToCctx, D(Cctx), S(Cls), C

  Convert a class to a class context (i.e. the class with a 1 or'd into the low
  bit).

4. Boolean predicates

| Gt,                          D(Bool), S(Gen) S(Gen), C

| GtX,                         D(Bool), S(Gen) S(Gen), Er|C

| Gte,                         D(Bool), S(Gen) S(Gen), C

| GteX,                        D(Bool), S(Gen) S(Gen), Er|C

| Lt,                          D(Bool), S(Gen) S(Gen), C

| LtX,                         D(Bool), S(Gen) S(Gen), Er|C

| Lte,                         D(Bool), S(Gen) S(Gen), C

| LteX,                        D(Bool), S(Gen) S(Gen), Er|C

| Eq,                          D(Bool), S(Gen) S(Gen), C

| EqX,                         D(Bool), S(Gen) S(Gen), Er|C

| Neq,                         D(Bool), S(Gen) S(Gen), C

| NeqX,                        D(Bool), S(Gen) S(Gen), Er|C

| Same,                        D(Bool), S(Gen) S(Gen), C

| NSame,                       D(Bool), S(Gen) S(Gen), C

  Perform comparisons with PHP semantics on S0 and S1, and put the result in D.
  The -X versions may re-enter the VM when comparing an Object with a string,
  and therefore may throw exceptions. The non-X versions must not be passed
  (Object,String) pairs, and do not throw. Note that Same and NSame never
  re-enter or throw, for any types.

| GtInt,                       D(Bool), S(Int) S(Int),                     C

| GteInt,                      D(Bool), S(Int) S(Int),                     C

| LtInt,                       D(Bool), S(Int) S(Int),                     C

| LteInt,                      D(Bool), S(Int) S(Int),                     C

| EqInt,                       D(Bool), S(Int) S(Int),                     C

| NeqInt,                      D(Bool), S(Int) S(Int),                     C


  Perform 64-bit integer comparisons.

| GtDbl,                       D(Bool), S(Dbl) S(Dbl),                     C

| GteDbl,                      D(Bool), S(Dbl) S(Dbl),                     C

| LtDbl,                       D(Bool), S(Dbl) S(Dbl),                     C

| LteDbl,                      D(Bool), S(Dbl) S(Dbl),                     C

| EqDbl,                       D(Bool), S(Dbl) S(Dbl),                     C

| NeqDbl,                      D(Bool), S(Dbl) S(Dbl),                     C

  Perform comparisons of doubles. Comparisons that are unordered according to
  IEEE 754 (such as when at least one operand is NaN) result in false.

| InstanceOf, D(Bool), S(Cls) S(Cls|Nullptr), C

  Sets D based on whether S0 is a descendant of the class, interface, or trait
  in S1. (Note that this is always false for a trait). S1 may be null at
  runtime if the class is not defined.

| InstanceOfIface, D(Bool), S(Cls) CStr, C

  Fast path for interface checks. Sets D based on whether S0 implements S1, but
  S1 must be a unique interface. This should only be used in repo-authoritative
  mode.

| ExtendsClass, D(Bool), S(Cls) C(Cls), C

  A fast-path for instanceof checks. Sets D based on whether S0 is a descendant
  of the class in S1, where S1 must be a unique class that is not an interface
  or a trait.

| InstanceOfBitmask,           D(Bool), S(Cls) CStr,                       C

| NInstanceOfBitmask,          D(Bool), S(Cls) CStr,                       C

  A fast-path for instanceof checks. Sets D based on whether S0 is a descendant
  of the class named by S1, where S1 must have a bit allocated for it in the
  fast instance check bitvector (see class.h).

| InterfaceSupportsArr,        D(Bool), S(Str), C

| InterfaceSupportsStr,        D(Bool), S(Str), C

| InterfaceSupportsInt,        D(Bool), S(Str), C

| InterfaceSupportsDbl,        D(Bool), S(Str), C

  Returns whether t instanceof S0 returns true when t is of the given type.

| IsType<T>, D(Bool), S(Cell), C

  Sets D to true iff S0 holds a value that is of type T.

| IsNType<T>, D(Bool), S(Cell), C

  Sets D to true iff S0 holds a value that is not of type T.

| IsTypeMem<T>, D(Bool), S(PtrToGen), NF

  Sets D to true iff the value referenced by S0 is of type T.

  The value in S0 must not be a pointer into the evaluation stack or frame
  locals.

| IsNTypeMem<T>, D(Bool), S(PtrToGen), NF

  Sets D to true iff the value referenced by S0 is not of type T.

| IsScalarType, D(Bool), S(Cell), C

  Returns true if S0 is of type Int, Bool, Dbl or Str. Returns false otherwise.

| IsWaitHandle, D(Bool), S(Obj), C

  Sets D to true iff S0 is a subclass of WaitHandle.


5. Branches


There is a conditional branch instruction for each predicate above, to enable
generating efficient compare-and-branch instruction sequences.


| JmpGt,                            ND, S(Gen) S(Gen),                   B|E

| JmpGte,                           ND, S(Gen) S(Gen),                   B|E

| JmpLt,                            ND, S(Gen) S(Gen),                   B|E

| JmpLte,                           ND, S(Gen) S(Gen),                   B|E

| JmpEq,                            ND, S(Gen) S(Gen),                   B|E

| JmpNeq,                           ND, S(Gen) S(Gen),                   B|E

| JmpSame,                          ND, S(Gen) S(Gen),                   B|E

| JmpNSame,                         ND, S(Gen) S(Gen),                   B|E

| JmpGtInt,                         ND, S(Int) S(Int),                   B|E

| JmpGteInt,                        ND, S(Int) S(Int),                   B|E

| JmpLtInt,                         ND, S(Int) S(Int),                   B|E

| JmpLteInt,                        ND, S(Int) S(Int),                   B|E

| JmpEqInt,                         ND, S(Int) S(Int),                   B|E

| JmpNeqInt,                        ND, S(Int) S(Int),                   B|E

| JmpInstanceOfBitmask,             ND, S(Cls) CStr,                     B|E

| JmpNInstanceOfBitmask,            ND, S(Cls) CStr,                     B|E

  Fused jump instructions. These all operate exactly as their corresponding
  query op, but also take a label to jump to when the condition is true.

| JmpZero,                          ND, S(Int,Bool),                     B|E

| JmpNZero,                         ND, S(Int,Bool),                     B|E

  Conditionally jump to based on S0.

| JmpSSwitchDest, ND, S(TCA), T|E

  Jump to the target of a sswitch statement, leaving the tracelet, where the
  target TCA is S0.

| JmpSwitchDest, ND, S(Int), T|E

  Jump to the target of a switch statement, leaving the tracelet, using table
  metadata <JmpSwitchData> and index S0.

| CheckSurpriseFlags, ND, NA, B|E

  Tests the implementation-specific surprise flags. If they're true, branches
  to block B.

| FunctionReturnHook, ND, S(FramePtr) S(Gen), Er|E

  Suprise flag hook for function returns.

| FunctionSuspendHook, ND, S(FramePtr) C(Bool), Er|E

  Suprise flag hook for suspending async functions.

| Halt, ND, NA, T|E

  Halt execution. Used only in tests, as a terminal instruction that does not
  require any inputs or any successors.

| Jmp, ND, SVar(Top), B|T|E

  Unconditional jump to block B. In the second form, the target block must
  start with a DefLabel with the same number of destinations as Jmp's number of
  sources. Jmp parallel-copies its sources to the DefLabel destinations.

| DefLabel, DMulti, NA, E

  DefLabel defines variables received from a previous Jmp. A DefLabel with zero
  destinations is a no-op, and the predecessor blocks may not necessarily end
  in Jmp. A DefLabel with one or more destinations may only be reached by a Jmp
  instruction with the same number of sources. Ordinary branch instructions may
  not pass values to a DefLabel.

| ClsNeq<class>, D(Bool), S(Cls), C

    Compare S0 to the class `class', returning true if it is not the same.


6. Reference manipulation


| Box, DBox(0), S(Gen), E|CRc|PRc

  Box S0 if it is unboxed, and put the resulting BoxedCell in D.

| UnboxPtr, DUnboxPtr, S(PtrToGen), NF

  If S0 points to a cell that is KindOfRef, dereference the pointer in the
  TypedValue and return a pointer to the inner-cell in D.

| BoxPtr, DBoxPtr, S(PtrToGen), NF

  Boxes the TypeValue that S0 points to if it is not boxed. The result D points
  to the same TypedValue as S0 but has a more refined type.

  S0 may not already point into a RefData (due to VM invariants), although the
  IR type system does not enforce it.


7. Loads


| LdStack<T,offset>, DParamMayRelax, S(StkPtr), NF

  Loads from S0 at offset (in cells), and puts the value in D as type T.

| TakeStack, ND, S(StackElem), E

  Does nothing at runtime. Acts as a hint to the optimizer that the code is
  taking ownership of a reference to S0.

| LdLoc<T,localId>, DParamMayRelax, S(FramePtr), NF

  Loads local slot localId from the frame S0 and puts the value in D as type T.

| LdLocPseudoMain<T,localId>, DParam, S(FramePtr), B

  Loads local number localId from frame S0 and puts the value in D if the
  local's type is a subtype of T. If the local's type is not a subtype of T,
  then the load does not happen, and this instruction branches to B. This
  instruction is used for loading locals in pseudo-mains, where they can alias
  globals.

| LdStackAddr<T,offset>, DParamPtr(Stk), S(StkPtr), C

  Loads the address of the stack slot given by the pointer in S0 at the offset
  (in cells). T must be a subtype of PtrToStkGen.

| LdLocAddr<T,localId>, DParamPtr(Frame), S(FramePtr), C

  Loads the address of the local slot localId from the frame S0 into D. T must
  be a subtype of PtrToFrameGen.

| LdRDSAddr<T,RDSHandle>, DParam, NA, C

  Load the address of a Gen that lives at the specified RDS handle. The type
  param must be a subtype of PtrToGen.

| LdVectorBase, D(PtrToMembCell), S(Obj), E

| LdPairBase, D(PtrToMembCell), S(Obj), E

  Loads the base pointer to an array of Cells from the given collection
  instance in S0.

| LdMem<T>, DParam, S(PtrToGen) C(Int), NF

  Loads from S0 + S1 (in bytes) and puts the value in D.

| LdContField<T>, DParam, S(Obj) C(Int), NF

  Loads a property from the object referenced by S0 at the offset given by S1
  and puts the value in D. S0 must be a Generator.

| LdElem, D(Cell), S(PtrToCell) S(Int), NF

  Loads the element at index S1 from the base pointer in S0. The index in S1 is
  the number of bytes from the base in S0.

| CheckRefInner<T>, ND, S(BoxedCell), B|E

  TODO(#2939547): this should take BoxedInitCell

  Check that the inner type of the boxed cell in S0 is T, and if not take the
  branch to B.

| LdRef<T>, DParam, S(BoxedCell), NF

  TODO(#2939547): this should take BoxedInitCell

  Loads the value held in the box referenced by S0 and puts the value in D. The
  inner type of S0 must be a subtype of T (usually ensured with a previous
  CheckRefInner).

| LdCtx, D(Ctx), S(FramePtr), C

  Loads into D the value of the m_this/m_cls field out of the frame pointer S0,
  which must be a frame for the function in the LdCtx's Marker. The result
  could be either an object representing the this pointer or a class context.

| CheckCtxThis, ND, S(Ctx), B|E

  Check that the context (m_this or m_cls) in S0 is a non-null $this
  pointer. If not, branch to B.

| CastCtxThis, DThis, S(Ctx), C

  Convert a Ctx known to contain a $this pointer to a specific object type,
  based on the marker func for this instruction.

| LdCctx, D(Cctx), S(FramePtr), C

  Loads into D the value of the m_cls field out of the frame pointer S0. The
  compiler should generate this only if it can prove that the frame does not
  contain a $this pointer.

| LdClsCtx, D(Cls), S(Ctx), C

  Loads into D the class representing the current context. Extracts the class
  from S0, which can be either the this pointer or the context class.

| LdClsCctx, D(Cls), S(Cctx), C

  Loads into D the class representing the current context. Extracts the class
  from the S0, which is a context class.

| LdClsCtor, D(Func), S(Cls), C|Er

  Loads into D the constructor of class S0. If the constructor cannot be called
  from the current context, raise an error.

| DefConst<T>, DParam, NA, C

  Define a constant value of type T. D is presumed to be globally available and
  the DefConst instruction will not actually appear in the IR instruction
  stream.

| Conjure<T>, DParam, NA, NF

  Define a value of type T. This instruction aborts at runtime; it is meant to
  be used in tests or code that is known to be unreachable.

| LdCls, D(Cls), S(Str) C(Cls), C|E|Er

  Loads the class named S0 in the context of the class S1. Invokes autoload and
  may raise an error if the class is not defined. The explicit context
  parameter allows the compiler to simplify this instruction to a DefConst in
  some cases. If S0 is constant, this instruction may be simplified to a
  LdClsCached.

| LdClsCached, D(Cls), CStr, C|E|Er

  Loads the class named S0 via the RDS. Invokes autoload and may raise an error
  if the class is not defined.

| LdClsCachedSafe, D(Cls|Nullptr), CStr, NF

  Loads the class whose name is S0 out of the RDS. If the class is not defined,
  returns a null pointer.

| LdClsInitData, D(PtrToClsInitCell), S(Cls), C

  Loads the pointer to the property initializer array for class S0.

| LookupClsRDSHandle, D(RDSHandle), S(Str), C

  Look up the cached-class RDS handle for a given class name.

| DerefClsRDSHandle, D(Cls), S(RDSHandle), NF

  Dereference an RDS handle that points to a cached class slot.

| LdCns, DCns, CStr, PRc

  Load the constant named S0.

| LookupCns<T,constName>,   DCns, CStr, E|Er|PRc

| LookupCnsE<T,constName>,  DCns, CStr, E|Er|PRc

  Load a constant via the RDS. Raises an undefined constant notice if the
  constant cannot be defined. The E variant will instead throw a fatal error if
  it cannot define the constant.

| LookupCnsU<T,constName,fallbackName>, DCns, CStr CStr, E|Er|PRc

  Load an unqualified constant via the RDS, first by trying constName, then by
  trying fallbackName. Raises a notice if neither can be found.

| LookupClsCns<T,className,constName>, DCns, NA, E|Er|PRc

  Load a class constant for a class via the RDS, invoking autoload if it is not
  defined. This instruction may raise an undefined constant error if autoload
  cannot define the constant.

| LdClsMethodFCacheFunc<clsName,methodName>, D(Func|Nullptr), NA, NF

  Loads the target cache entry for a forwarding call to clsName::methodName.
  May be Nullptr, if the method does not exist or the cache hasn't been filled
  yet.

| LookupClsMethodFCache<clsName,methodName>,
|    D(Func|Nullptr), C(Cls) S(FramePtr),
|    E|Er

  Lookup clsName::methodName in the forwarding class method cache. S0 should be
  the Class named by clsName and S1 should be the current vm frame pointer. May
  return Nullptr if lookup fails using a subset of the required lookup paths,
  indicating that a more complete lookup path should be taken. May throw if the
  method does not exist.

| GetCtxFwdCallDyn<clsName,methodName>, D(Ctx), S(Ctx), PRc

  If S0 is a Cctx, return S0. If S0 is an object, check if clsName::methodName
  is a static method. If it is, return S0's class as a Ctx pointer. If not,
  return S0. If S0 is a Ctx, dynamically check if it is an object or Cctx at
  runtime and perform the operations described above.

| GetCtxFwdCall, D(Ctx), S(Ctx) C(Func), PRc

  If S0 is an object and S1 is static, this opcode returns S0's class. If S0 is
  an object and S1 is not static, this opcode increfs S0 and returns it. If S0
  is a Cctx, this opcode returns S0.

| LdClsMethodCacheFunc<clsName,methodName>, D(Func|Nullptr), NA, NF

  Loads the target cache entry for the method clsName::methodName. The result
  may be Nullptr, if the method does not exist or the cache hasn't been filled
  yet.

| LdClsMethodCacheCls<clsName,methodName>, D(Cctx), NA, NF

  Loads the target cache class context entry for a call to clsName::methodName
  from the current context. This instruction must only be used when the value
  is known to not be empty.

| LookupClsMethodCache<clsName,methodName>, D(Func|Nullptr),
|                                           S(FramePtr),
|                                           E|Er

  Lookup a function in the class method targetcache. The class name and method
  name are clsName and methodName, respectively. S0 is the current vm frame
  pointer. Returns Nullptr if the method cannot be found using a subset of the
  required lookup paths, indicating that a more complete lookup path should be
  taken. May throw if the method does not exist.

| LdClsMethod, D(Func), S(Cls) C(Int), C

  Load a Func* off of the class method table for S0, at offset S1 (in method
  slots).

| LookupClsMethod, ND, S(Cls) S(Str) S(StkPtr) S(FramePtr), E|Er

  Store a pointer to a class method into an activation record. S0 points to the
  class, S1 is the method name, S2 points to the activation record, and S3 is a
  pointer to the current frame (used to get the context). May throw or fatal if
  method is not accessible.

| LdPropAddr<T>, DParamPtr(Prop), S(Obj) C(Int), C

  Load the address of the object property for S0 at offset S1 (in bytes) into
  D.  T must be a subtype of PtrToPropGen.

| LdGblAddr, D(PtrToGblGen), S(Str), B

  Loads a pointer to a global. S0 is the global's name. Branches to B if the
  global is not defined.

| LdGblAddrDef, D(PtrToGblGen), S(Str), E

  Loads a pointer to a global. S0 is the global's name. Defines the global if
  it is not already defined.

| LdClsPropAddrOrNull, D(PtrToSPropGen|Nullptr),
|                      S(Cls) S(Str) C(Cls),
|                      C|E|Er

  Loads a pointer to a static class property. S0 points to the class, S1 is the
  property name, and S2 is the class representing the context of the code
  accessing the property. If class S0 does not have a visible and accessible
  static property named S1, then nullptr is returned.

| LdClsPropAddrOrRaise, D(PtrToSPropGen), S(Cls) S(Str) C(Cls), C|E|Er

  Loads a pointer to a static class property. S0 points to the class, S1 is the
  property name, and S2 is the class representing the context of the code
  accessing the property. If class S0 does not have a visible and accessible
  static property named S1, throw a fatal error.

| LdObjMethod<methodName,fatal>, ND, S(Cls) S(StkPtr), E|Er

  Stores a pointer to an object's method into an activation record. S0 points
  to the object's class, S1 points to the pre-live activation record.  Caches
  the mapping in the target cache. If `fatal' is true, raises a fatal if the
  class does not have an accessible method with the given name and does not
  have a __call method; otherwise (if `fatal' is false), raises a warning and
  puts func that does nothing and returns null (SystemLib::s_nullFunc) on the
  activation record.

| LdObjInvoke, D(Func), S(Cls), B

  Try to load a cached non-static __invoke Func from the Class in S0, or branch
  to block B if it is not present.

| LdArrFuncCtx, ND, S(Arr) S(StkPtr) S(FramePtr), E|Er

  Try to load an array as a function context. This is for use translating
  FPushFunc when the callee is an array. This instruction attempts to populate
  a partially created ActRec pointed to by S1.

| LdArrFPushCuf, ND, S(Arr) S(StkPtr) S(FramePtr), E|Er

| LdStrFPushCuf, ND, S(Str) S(StkPtr) S(FramePtr), E|Er

  Try to resolve a method target for FPushCuf when the callee is an Arr or Str,
  respectively. These instructions mutate a partially created ActRec pointed to
  by S1.

| LdObjClass, D(Cls), S(Obj), C

  Load the class out of the object in S0 and put it in D.

| LdClsName, D(StaticStr), S(Cls), C

  Load the name of the Class* in S0.

| LdFunc, D(Func), S(Str), E|CRc|Er

  Loads the Func whose name is S0. Fatal if the named function is not defined,
  and the function autoloader fails to define it.

| LdFuncCached<funcName>, D(Func), NA, E|Er

  Loads the Func whose name is funcName from the RDS, invoking autoload if it
  not defined yet. Fatal if function autoloader fails to define it.

| LdFuncCachedSafe<funcName>, D(Func|Nullptr), NA, NF

  Try to load the Func named funcName from the RDS. If the function is not
  defined, returns a null pointer.

| LdFuncCachedU<funcName,fallbackName>, D(Func), NA, E|Er

  Try to load a Func named funcName from the RDS, if it isn't defined, try to
  load a Func named fallbackName. If that also isn't defined, invoke autoload.
  If this still doesn't result in a Func, raise a fatal error.

| LdARFuncPtr, D(Func), S(StkPtr,FramePtr) C(Int), C

  Loads the m_func member of an ActRec. S0 is the base address, and S1 is an
  offset, such that S0 + S1 points to the base of the ActRec.

| LdFuncNumParams, D(Int), S(Func), NF

  Returns the value of func->numParams().

| LdStrLen, D(Int), S(Str), NF

  Load the length of the string in S0.

| LdStaticLocCached<func,staticLocalName>, D(BoxedCell), NA, NF

  Load the address of the static local RefData from the targetcache for
  function `func' with the static local variable named `staticLocalName'.


8. Allocation


| AllocObj, DAllocObj, S(Cls), Er

  Allocates a new object of class S1.

| RegisterLiveObj, ND, S(Obj), E

  When EnableObjDestructCall is on, we need to keep track of objects to be able
  to call their destructors when a request exists.  This instruction is
  conditionally emitted to implement that.

| CheckInitProps<class>, ND, NA, B|E

  Check if the properties for class are initialized and branches if not.

| InitProps<class>, ND, NA, E|Er

  Calls the property initializer function (86pinit) for class.  May throw.

| CheckInitSProps<class>, ND, NA, B|E

  Check if static properties for class are initialized and branches if not.

| InitSProps<class>, ND, NA, E|Er

  Calls the static property initializer function (86sinit) for class. May
  throw.

| NewInstanceRaw<class>, DAllocObj, NA, NF

  Allocates an instance of class.

| InitObjProps<class>, ND, S(Obj), E

  Initializes properties of object S0.

| ConstructInstance<class>, DAllocObj, NA, Er

  Call the custom instance constructor of an extension class.

| CustomInstanceInit, DofS(0), S(Obj), Er

  Call the custom instance initializer of object S0.

| NewArray, D(Arr), C(Int), PRc

  Allocate a new array with the expected capacity S0.

| NewMixedArray, D(Arr), C(Int), PRc

  Allocate a new array in mixed mode with the expected capacity S0.

| NewMIArray, D(Arr), C(Int), PRc

  Create a new MIArray.

| NewMSArray, D(Arr), C(Int), PRc

  Create a new MSArray.

| NewVArray, D(Arr), C(Int), PRc

  Create a new VArray.

| NewLikeArray, D(Arr), S(Arr) C(Int), PRc

  Allocate a new array in the same mode as S0 and with expected capacity S1,
  unless S1 == 0, in which case the capacity is set to S0's size.

| AllocPackedArray<size>, DArrPacked, NA, E|PRc

  Allocate a new uninitialized packed array with space for size elements in it.
  The array will be initialized with values using either InitPackedArray or
  InitPackedArrayLoop.

| InitPackedArray<index>, ND, S(Arr) S(Gen), E|CRc

  Store the S1 into the slot at index in array S0. This instruction assumes
  that it doesn't have to incref the value being stored. Used to initialize an
  array allocated with AllocPackedArray.

| InitPackedArrayLoop<size>, ND, S(Arr) S(StkPtr), E|CRc

  Store the top size elements on the stack given by S1 into the array S0.
  Assumes that the first element on the stack is the last element in the array.
  Used to initialize an array allocated with AllocPackedArray that was too big
  to use a series of InitPackedArray instructions.

| NewStructArray<keys...>, D(Arr), S(StkPtr), E|PRc|CRc

  Allocate a new key/value array, given N immediate keys and taking the top N
  elements off the stack given by S0. This instruction assumes it can take the
  values from the stack without increfing them.

| NewCol, D(Obj), C(Int) C(Int), PRc

  Create a new collection, with type S0 and size S1.

| Clone, D(Obj), S(Obj), E|PRc|Er

  Allocate an object by cloning S0.


9. Call & Return

| SpillFrame<numArgs,invName>, D(StkPtr),
|                              S(StkPtr) S(Func,Nullptr) S(Ctx,Cls,Nullptr),
|                              CRc

  Operands:

     S0 - caller stack pointer
     S1 - callee Func or nullptr
     S2 - object (for FPushObjMethod*), class (for FPushClsMethod*), context
          (for FPushClsMethodF), or nullptr (for FPushFunc*).

  Defines the fields for an activation record and writes them to the stack
  pointed to by S1.

| CufIterSpillFrame<numArgs,iterId>, D(StkPtr),
|                                    S(StkPtr) S(FramePtr),
|                                    NF

  Operands:

     S0 - caller stack pointer
     S1 - caller frame pointer

  Defines the fields for an activation record using data from the iterator
  iterId, and writes them to the stack pointed to by S1

| FreeActRec, D(FramePtr), S(FramePtr), NF

  Load the saved frame pointer from the activation record pointed to by S0 into
  D.

| DefInlineFP<func,retBCOff,retSPOff>, D(FramePtr),
|                                      S(StkPtr) S(StkPtr) S(FramePtr),
|                                      NF

  Defines a frame pointer for an inlined function. S0 is a StkPtr that points
  to the ActRec for the callee (i.e. after parameters have been popped). S1 is
  a StkPtr that represents what the inlined function will return to (i.e. it
  points to the stack after the ActRec in S0 is popped).

  `func' is the function being inlined. `retBCOff' and `retSPOff' represent
  what the bytecode and stack offsets should be after the FCall instruction in
  ther caller.

  This instruction is primarily used to represent a frame in the IR in a way
  that allows us to eliminate it entirely. When it cannot be eliminated (or if
  it is pushed into an unlikely path) it performs callee-side responsibilities
  for setting up an activation record (i.e. setting the return ip and m_soff,
  storing the frame pointer into D).

  The caller frame pointer is passed as S2. This is used to keep track of the
  call chain of inlined functions for simplification and dead code elimination.

| InlineReturn, ND, S(FramePtr), E

  Unlinks a frame constructed by DefInlineFP.

| CallArray, D(StkPtr), S(StkPtr) S(FramePtr), E|CRc

  Invoke function corresponding to the current FPI with array args. S0 points
  to the stack resulting after the ActRec for the function and the array of its
  arguments is pushed. CallArray pops the array off the stack, pushes the
  elements of the array as arguments, and invokes the function in the ActRec.

| Call<numParams,returnOff,funcd,destroyLocals>, D(StkPtr),
|                                                S(StkPtr) S(FramePtr),
|                                                E

  Transfer control to a callee, based on the pre-live activation record and set
  of args on the stack pointed to by S0. S1 is the current caller frame
  pointer. The `funcd' in the extra data is a Func* for the callee if we know
  the callee statically.

| NativeImpl<func>, ND, S(FramePtr) S(StkPtr), E

  Execute a call to the native builtin specified by the current function. S0
  and S1 should be the current vmfp and vmsp, respectively.

| CallBuiltin<T>, DBuiltin, S(FramePtr) S(StkPtr) SVar(PtrToGen,Gen), E|Er|PRc

  Call builtin function with N arguments. S0 and S1 should be the current vmfp
  and vmsp, respectively.

  The source and destination types correspond to C++ parameter and return types
  as follows:

    C++ type            HHIR type         Position
    -----------------   ---------         --------
    bool                Bool              source, destination
    int64_t             Int               source, destination
    double              Dbl               source, destination
    const String&       PtrToString       source
    const Array&        PtrToArray        source
    const Object&       PtrToObject       source
    const Variant&      PtrToGen          source
    Variant&            PtrToGen          source (ref param)
    String              {Str|InitNull}    destination
    Array               {Arr|InitNull}    destination
    Object              {Obj|InitNull}    destination
    Variant             {Gen-UninitNull}  destination

| LdRetAddr, D(RetAddr), S(FramePtr), NF

  Load the return address off of the activation record pointed to by S0. The
  return address D is normally provided to a RetCtrl. Between a LdRetAddr and a
  RetCtrl, a FreeActRec is normally emitted to free the activation record S0.
  This is the reason why LdRetAddr is a separate instruction from RetCtrl.

| RetCtrl, ND, S(StkPtr) S(FramePtr) S(RetAddr), T|E

  Ensure that S0 is stored in rVmSp and S1 is stored in rVmFp and then execute
  a hardware procedure-return using the return address specified by S2.

| StRetVal, ND, S(FramePtr) S(Gen), E|CRc

  Writes the value in S1 to the return value slot on the activation record
  pointed to by S0.

| RetAdjustStack, D(StkPtr), S(FramePtr), E

  Loads the new VM stack pointer into the destination. S0 is a pointer to the
  current activation record.

| ReleaseVVOrExit, ND, S(FramePtr), B|E

  Loads the VarEnv slot off the ActRec pointed to by S0. If it is null, does
  nothing. If it is an ExtraArgs, deallocates the ExtraArgs structure.
  Otherwise jumps to block B.

| GenericRetDecRefs, ND, S(FramePtr), E

  Does decrefs of all the current function's locals, where S0 is a pointer to
  the relevant activation record.

  Semantically similar to a series of DecRefLoc.


10. Stores


| StMem, ND, S(PtrToGen) C(Int) S(Gen), E|CRc

  Store S2 into the location S0 + S1 (in bytes).

| StProp, ND, S(Obj) C(Int) S(Gen), E|CRc

  Store S2 into the location S0 + S1 (in bytes).

| StElem, ND, S(PtrToCell) S(Int) S(Cell), E|CRc

  Store S2 into the location given by the index S1 from base pointer S0. The
  index in S1 is the number of bytes from the base in S0.

| StLoc<localId>, ND, S(FramePtr) S(Gen), E|CRc

  Store S1 to local number localId on the frame pointed to by S0.

| StLocNT<localId>, ND, S(FramePtr) S(Gen), E|CRc

  Store S1 to local number localId on the frame pointed to by S0, without
  storing the type.

| StLocPseudoMain<localId>, ND, S(FramePtr) S(Gen), E|CRc

  Behaves just like StLoc, except the hard requirement that it is only emitted
  for pseudo-mains. We don't optimize StGbl the same way as StLoc, as we need
  intraprocedural analysis to know whether the store is truly dead.

| StRef, ND, S(BoxedCell) S(Cell), E|CRc

  Store the value in S1 into the RefData pointed to by S0. Stores the
  RefData::m_type also.

| SpillStack, D(StkPtr), S(StkPtr) C(Int) SVar(StackElem), CRc

  SpillStack synchronizes the virtual execution stack with the physical stack
  by storing a variadic list of SSATmps to the physical stack.

  Operands:

     S0      - current stack pointer

     S1      - stack deficit; indicates the number of elements that need to be
               logically popped before the variadic list is pushed

     S2...   - variadic list of elements to spill, with values representing
               cells. A temp with type None means to keep the previous value on
               the stack.

| ExceptionBarrier, D(StkPtr), S(StkPtr), E

  An essential instruciton that consumes and produces a stack.  This is used in
  places that need to ensure the stack goes to memory and cannot be DCE'd.
  Mostly unnecessary now (catch traces do the same thing), but there are a few
  locations that are not updated.


11. Trace exits


| SyncABIRegs, ND, S(FramePtr) S(StkPtr), E

  Ensures the cross-tracelet ABI registers are in a consistent state in
  preparation for an instruction that may leave the trace.

| EagerSyncVMRegs, ND, S(FramePtr) S(StkPtr), E

  Sync the given vmfp and vmsp to their in-memory locations.

| ReqBindJmp<bcOff,transFlags>, ND, NA, T|E

  Emit a jump to a REQ_BIND_JMP service request to the target offset bcOff.

| ReqRetranslate<transFlags>, ND, NA, T|E

  Emit a jump to a service request that will chain to a retranslation of this
  tracelet.

  This instruction is used in exit traces for a type prediction that occurs at
  the first bytecode offset of a tracelet.

| ReqRetranslateOpt<transId,bcOff>, ND, NA, T|E

  Emit a service request to retranslate, with a higher optimization gear,
  translation transID, which starts at bcOff. This instruction is used in exit
  traces that trigger profile-guided optimizations.

| ReqBindJmpGt,                     ND, S(Gen) S(Gen),                   T|E

| ReqBindJmpGte,                    ND, S(Gen) S(Gen),                   T|E

| ReqBindJmpLt,                     ND, S(Gen) S(Gen),                   T|E

| ReqBindJmpLte,                    ND, S(Gen) S(Gen),                   T|E

| ReqBindJmpEq,                     ND, S(Gen) S(Gen),                   T|E

| ReqBindJmpNeq,                    ND, S(Gen) S(Gen),                   T|E

| ReqBindJmpGtInt,                  ND, S(Int) S(Int),                   T|E

| ReqBindJmpGteInt,                 ND, S(Int) S(Int),                   T|E

| ReqBindJmpLtInt,                  ND, S(Int) S(Int),                   T|E

| ReqBindJmpLteInt,                 ND, S(Int) S(Int),                   T|E

| ReqBindJmpEqInt,                  ND, S(Int) S(Int),                   T|E

| ReqBindJmpNeqInt,                 ND, S(Int) S(Int),                   T|E

| ReqBindJmpSame,                   ND, S(Gen) S(Gen),                   T|E

| ReqBindJmpNSame,                  ND, S(Gen) S(Gen),                   T|E

| ReqBindJmpInstanceOfBitmask,      ND, S(Cls) CStr,                     T|E

| ReqBindJmpNInstanceOfBitmask,     ND, S(Cls) CStr,                     T|E

| ReqBindJmpZero,                   ND, S(Int,Bool),                     T|E

| ReqBindJmpNZero,                  ND, S(Int,Bool),                     T|E

  Test the condition based on the Jmp* op of similar name, and then emit a pair
  of smashable jumps to a REQ_BIND_JMPCC_FIRST service request.

| SideExitJmpGt,                    ND, S(Gen) S(Gen),                     E

| SideExitJmpGte,                   ND, S(Gen) S(Gen),                     E

| SideExitJmpLt,                    ND, S(Gen) S(Gen),                     E

| SideExitJmpLte,                   ND, S(Gen) S(Gen),                     E

| SideExitJmpEq,                    ND, S(Gen) S(Gen),                     E

| SideExitJmpNeq,                   ND, S(Gen) S(Gen),                     E

| SideExitJmpGtInt,                 ND, S(Int) S(Int),                     E

| SideExitJmpGteInt,                ND, S(Int) S(Int),                     E

| SideExitJmpLtInt,                 ND, S(Int) S(Int),                     E

| SideExitJmpLteInt,                ND, S(Int) S(Int),                     E

| SideExitJmpEqInt,                 ND, S(Int) S(Int),                     E

| SideExitJmpNeqInt,                ND, S(Int) S(Int),                     E

| SideExitJmpSame,                  ND, S(Int) S(Int),                     E

| SideExitJmpNSame,                 ND, S(Int) S(Int),                     E

| SideExitJmpInstanceOfBitmask,     ND, S(Cls) CStr,                       E

| SideExitJmpNInstanceOfBitmask,    ND, S(Cls) CStr,                       E

| SideExitJmpZero,                  ND, S(Int,Bool),                       E

| SideExitJmpNZero,                 ND, S(Int,Bool),                       E

  Test the condition based on the Jmp* op of similar name, and then emit a
  smashable jump to a REQ_BIND_SIDE_EXIT service request.

| SideExitGuardLoc<T,locId,takenOff>, ND, S(FramePtr), E

  Test the type of a local, and if it fails jump to a side exit service
  request.

| SideExitGuardStk<T,stackOff,takenOff>, D(StkPtr), S(StkPtr), E

  Test the type of a stack cell, and if it fails jump to a side exit service
  request.


12. Refcounting and copies


| Mov, DofS(0), S(Top), C|P

  Defines D as S0. May imply register-to-register moves at code generation
  time. Does not imply an incref or any other manipulation of S0.

| IncRef, ND, S(Gen), E

  If S0 is a refcounted type, increment its refcount.

| IncRefCtx, ND, S(Ctx), E

  If the Ctx in S0 is a $this pointer, IncRef it.

| DecRefLoc<localId>, ND, S(FramePtr), E

  DecRef the local given by localId on the frame S0.

| DecRefStack<T,offset>, ND, S(StkPtr), E

  DecRef a value of type T at offset on the stack pointed to by S0.

| DecRefThis, ND, S(FramePtr), E

  DecRef the $this pointer in the ActRec S0, if it had one. Does nothing if
  there was a class context or null $this on the ActRec.

| DecRef, ND, S(Gen), E|K|CRc

  Decrease the reference count of S0 by one, and call a destructor for types
  that require it if it goes to zero.

  Note that although DecRef takes a Gen, we don't allow it to use information
  about the inner types of a BoxedCell. This is because we don't guard on the
  inner types of a BoxedCell except when doing LdRef. For any S0 that is a
  strict subtype of BoxedCell, the DecRef must just decref it as if it were a
  BoxedCell.

| DecRefMem, ND, S(PtrToGen) C(Int), E|CRc

  Decref the value pointed to by S0 at offset S1 (in bytes), calling any
  appropriate destructor if the refcount goes to zero.

| DecRefNZ, ND, S(Gen), E|CRc

  Decrease the reference count of S0 by one, do not check if it goes to zero.
  This instruction can be used for more efficient code when it is provable that
  the reference count cannot go to zero.

| TakeRef, ND, S(Gen), NF

  Produce reference, but do not modify the reference count. Used to inform
  refcount optimizer about implicitly owned references.


13. Misc


| DefFP, D(FramePtr), NA, E

  Creates a temporary D representing the current vm frame pointer.

| DefSP<stackOff>, D(StkPtr), S(FramePtr), E

  Creates a temporary D representing the current vm stack pointer. S0 is a
  pointer to the current frame. The 'stackOff' is the logical offset between S0
  and the stack pointer, but in the case of generators this is not the
  physical offset at runtime.

  This instruction is used at the beginning of tracelets to represent the state
  of the stack on entry and does not emit code.

| ReDefSP<offset,spansCall>, D(StkPtr), S(StkPtr) S(FramePtr), NF

  Re-define a stack in terms of a frame pointer S1 and an offset, putting the
  resulting pointer in D. The resulting stack is assumed to give the same view
  as S0, which is a previous stack pointer. (I.e. for getStackValue we just
  chain to S0.)

  This instruction is used when entering or "returning" from an inlined call.
  The one used on entry will generally be DCE'd when the actrec can be
  eliminated. The one on exit is only needed until TODO(#2288359).

  The spansCall boolean is true if there is possibly a Call instructions
  between the definition of S0 and this instruction.

| Count, D(Int), S(Cell), Er

  Computes the number of elements in S0. The count of an array is the number of
  elements it contains, without recursing into containers in the array.
  Subtypes of Bool|Int|Dbl|Str|Res have a count of 1, subtypes of Null have a
  count of 0. The count of objects that implement the Countable interface is
  computed by returning the value of their count method. Objects that do not
  implement Countable have a count of 1.

| CountArray,      D(Int), S(Arr), NF

| CountArrayFast,  D(Int), S(Arr), NF

| CountCollection, D(Int), S(Obj), NF

  Computes the number of elements in S0 using the same definition as Count, but
  with a restriction on the input type.

  CountArray expects any array. CountArrayFast expects an array whose kind is not
  kGlobalsKind. CountCollection expects a collection object.

| Nop, ND, NA, NF

  Does nothing. It's sometimes useful for the simplifier to insert one of these
  in the instruction stream.


14. Runtime helpers


| VerifyParamCls, ND, S(Cls) S(Cls|Nullptr) C(Int) C(Int), E|Er

  Verify parameter type for classes or traits. If S0 does not extend (if S1 is
  a class) or implement (if S1 is an interface) S1, this instruction will raise
  a recoverable fatal error describing the type mismatch.

| VerifyParamCallable, ND, S(Gen) C(Int), E|Er

  If S0 is not callable, as defined by the php function is_callable, this
  instruction will raise a recoverable fatal error describing the type
  mismatch.

| VerifyParamFail, ND, C(Int), E|Er

  Assumes that parameter number S0 in the current function has failed its
  typehint and raises a recoverable fatal error describing the type mismatch.

| VerifyRetCallable, ND, S(Gen), E|Er

  Verify a return type hint.

| VerifyRetCls, ND, S(Cls) S(Cls|Nullptr) C(Int) S(Cell), E|Er

  Verify a return type hint.

| VerifyRetFail, ND, S(Gen), E|Er

  Failure to verify a return type hint.

| RaiseUninitLoc<localId>, ND, S(Str), E|Er

  Raise a notice for an uninitialized local variable.

| WarnNonObjProp, ND, NA, E|Er

  Raise a warning for property access on a non-object base.

| RaiseUndefProp, ND, S(Obj) CStr, E|Er

  Raise a notice for an undefined property named S1 on the class of S0.

| RaiseError, ND, S(Str), E|T|Er

  Raises a fatal error with the text in S0 as its message.

| RaiseWarning, ND, S(Str), E|Er

  Raises a warning with the text in S0 as its message.

| RaiseNotice, ND, S(Str), E|Er

  Raises a notice with the text in S0 as its message.

| RaiseArrayIndexNotice, ND, S(Int), E|Er

  Raises a notice that S0 is an undefined index for an array.

| ClosureStaticLocInit, D(BoxedCell), CStr S(FramePtr) S(Cell), E

  Get boxed value to initialize static local named S0 in frame S1, where S1
  must be either a closure or generatorFromClosure function. If the static
  local has not yet been initialized, its value will be set to S2.

| StaticLocInitCached, ND, S(BoxedCell) S(Cell), E

  Assuming S0 is an uninitialized static local RDS slot, initialize it by
  setting it to the value of S1.

| PrintStr,  ND, S(Str),  E|Er|CRc

| PrintInt,  ND, S(Int),  E|Er|CRc

| PrintBool, ND, S(Bool), E|Er|CRc

  Print for various types.

| ConcatIntStr, D(Str), S(Int) S(Str), Er|PRc

  Concatenate S0 and S1 after converting S0 to String.

| ConcatStrInt, D(Str), S(Str) S(Int), Er|CRc|PRc

  Concatenate S0 and S1 after converting S1 to String.

| ConcatStrStr, D(Str), S(Str) S(Str), Er|CRc|PRc

  Concatenate S0 and S1.

| ConcatCellCell, D(Str), S(Cell) S(Cell), Er|CRc|PRc

  Concatenate S0 and S1 after converting them to strings in a way that obeys
  php semantics. (Calling object __toString methods, etc.)

| ConcatStr3, D(Str), S(Str) S(Str) S(Str), Er|CRc|PRc

  Concatenate S0, S1, and S2.

| ConcatStr4, D(Str), S(Str) S(Str) S(Str) S(Str), Er|CRc|PRc

  Concatenate S0, S1, S2, and S3.

| AddElemStrKey, D(Arr), S(Arr) S(Str) S(Cell), Er|CRc|PRc

  Add S2 to the array S0 for the key S1, and return the resulting array.

| AddElemIntKey, D(Arr), S(Arr) S(Int) S(Cell), Er|CRc|PRc

  Add S2 to the array S0 for the key S1, and return the resulting array.

| AddNewElem, D(Arr), S(Arr) S(Cell), Er|CRc|PRc

  Add S1 as a new element to the array S0.  (Note: S1 must actually be a
  subtype of InitCell for array invariants, but we can't assert this yet in the
  IR because many eval stack slots are not entirely typed wrt initness right
  now.)

| ArrayAdd, D(Arr), S(Arr) S(Arr), Er|CRc|PRc

  Has the effects of the php + operator on the two source arrays.

| AKExists, D(Bool), S(Cell) S(Cell), NF

  Has the effects of array_key_exists(S0, S1). Note that S0 does not need to be
  an array---if it is an Obj the ArrayAccess API will be used, etc.

| ArrayIdx, D(Cell), S(Arr) S(Int,Str) S(Cell), E|PRc

  Checks if S0 contains the key S1, and returns the result if found. Otherwise
  S2 is returned.

| GenericIdx, D(Cell), S(Cell) S(Cell) S(Cell), E|PRc|Er

  Checks if S0 contains the key S1, and returns the result if found. Otherwise
  S2 is returned. If S0 does not support array or indexed access S2 is
  returned.

| LdBindAddr<SrcKey>, D(TCA), NA, NF

  Creates a service request to bind the given target address. Returns a TCA
  pointing either to the service request (before the service request is
  satisfied) or to the native code for the given target address (once the
  service request is satisfied).

| LdSwitchDblIndex, D(Int), S(Dbl) S(Int) S(Int), NF

| LdSwitchStrIndex, D(Int), S(Str) S(Int) S(Int), CRc

| LdSwitchObjIndex, D(Int), S(Obj) S(Int) S(Int), CRc|Er

  These instructions are used to determine the target of a switch statement
  with target range [S1:S1 + S2), when invoked with the value S0. They call
  helper functions to check whether S0 is an numeric integer in the range
  [S1:S1 + S2), and if so return the value S1 - (Int)S0. Else, they return the
  target of the default target, S2 + 1.

| LdSSwitchDestFast, D(TCA), S(Gen), NF

| LdSSwitchDestSlow, D(TCA), S(Gen), E|Er

  Load string switch destinations (two different compilation strategies).

| InterpOne<T,bcOff,numPopped,numPushed>, D(StkPtr),
|                                         S(StkPtr) S(FramePtr),
|                                         E|Er

  Call the interpreter implementation function for one opcode. S0 and S1 are,
  respectively, the VM stack and frame pointers before this instruction. T is
  only present if the instruction pushes to the stack, in which case it is the
  type of the top stack element after the call. `bcOff' is the bytecode
  offset. `numPopped' is the number of stack cells consumed by the instruction,
  and `numPushed' is the number of stack cells produced by the
  instruction. This instruction returns the updated VM stack pointer.

| InterpOneCF<T,bcOff,numPopped,numPushed>, D(StkPtr),
|                                           S(StkPtr) S(FramePtr),
|                                           T|E|Er

  Similar to InterpOne, but for instructions that may modify vmpc.

| OODeclExists<kind>, D(Bool), S(Str) S(Bool), E|Er

  Returns a bool indicating whether the class, interface, or trait named by S0
  exists. Invokes autoload if S1 is true.


15. Generators & Closures


| StClosureCtx, ND, S(Obj) S(Ctx,Nullptr), CRc|E

  Store the context represented by S1 into the closure object S0. S1 may be a
  Nullptr when there is no context (i.e. the closure is being used in a
  non-method).

| StClosureFunc<func>, ND, S(Obj), E

  Store the Func* clone that should be used for calling this closure into the
  closure object S0.

| StClosureArg<offsetBytes>, ND, S(Obj) S(Gen), CRc|E

  Store one of the closure environment arguments (i.e. from the closure's use
  clause) from S1 into the closure object S0.

| CreateCont, D(Obj), S(FramePtr) C(Int) S(TCA,Nullptr) C(Int), E|PRc

  Create a Generator object and suspend the ActRec provided by S0 into its
  embedded ActRec, allocating S1 slots for locals/iterators. Set the native
  resume address to S2 and resume offset to S3.

| CreateAFWH, D(Obj),
|             S(FramePtr) C(Int) S(TCA,Nullptr) C(Int) S(Obj),
|             E|Er|CRc|PRc

  Create an AsyncFunctionWaitHandle object and suspend the ActRec provided by
  S0 into its embedded ActRec, allocating S1 slots for locals/iterators.  Set
  the native resume address to S2, resume offset to S3, and mark it blocked on
  non-finished child S4.

| CreateSSWH, D(Obj), S(Cell), CRc|PRc

  Call c_StaticWaitHandle::CreateSucceeded.

| AFWHPrepareChild, ND, S(FramePtr) S(Obj), E|Er

  Prepare unfinished WaitableWaitHandle object specified by S1 for getting
  awaited by an AsyncFunctionWaitHandle object specified by its ActRec
  provided by S0.

  Injects S1 into the currently running scheduler instance and performs
  cross-scheduler and intra-scheduler cycle detection. Throws if the
  dependency cannot be established.

| ContEnter, D(StkPtr),
|            S(StkPtr) S(FramePtr) S(FramePtr) S(TCA) C(Int),
|            E

  Enters a generator body. S0 is the current stack pointer pointing to fully
  spilled stack, S1 is the current frame pointer, S2 is the generator frame
  pointer embedded in the Generator object, S3 is the address to jump to,
  and S4 is the bytecode offset in the caller to return to when the generator
  suspends or returns.

| ContPreNext, ND, S(Obj) C(Bool), B|E

  Performs operations needed for the next() method of Generator object S0.
  If the generator is already running or finished, or it was not started yet
  and the S1 check-started flag is set, the branch B is taken. Otherwise,
  the generator is marked as running.

| ContStartedCheck, ND, S(Obj), B|E

  Checks if the Generator object S0 has started, and if not branches to
  block B.

| ContValid, D(Bool), S(Obj), E

  Return true if a generator is not done, false otherwise.

| ContArIncKey, ND, S(FramePtr), E

  Special-case key update for generator, ActRec of which is S0, which
  increments the key of a generator if that generator's key is an Int.
  This will cause undefined behavior if the generator's key is not an Int.

| ContArIncIdx, D(Int), S(FramePtr), E

  Increment the internal index in the Generator in S0, and return the new index
  value.

| ContArUpdateIdx, ND, S(FramePtr) S(Int), E

  Updates the internal index of generator with S1 if necessary, i.e. if S1
  is larger than the index. S0 is the pointer to the embedded ActRec.

| LdContActRec, D(FramePtr), S(Obj), C

  Loads the Generator object's ActRec, given a pointer to the generator
  object in S0.

| LdContResumeAddr, D(TCA), S(Obj), E

  Load the resume addr from the Generator in S0.

| StContArState<state>, ND, S(FramePtr), E

  Change the state of the Generator object which has frame pointer S0.

| StContArResume<offset>, ND, S(FramePtr) S(TCA), E

  Store the resume address S1 into the Generator whose ActRec is given by S0,
  marking the offset to resume at as `offset'.

| LdContArValue, DParam, S(FramePtr), PRc

  Loads 'value' from the Generator object ActRec of which is S0.

| StContArValue, ND, S(FramePtr) S(Cell), E|CRc

  Stores 'value' into the Generator object ActRec of which is S0. S1 is the
  new value.

| LdContArKey, DParam, S(FramePtr), PRc

  Loads 'key' from the Generator object ActRec of which is S0.

| StContArKey, ND, S(FramePtr) S(Gen), E|CRc

  Stores 'key' into the Generator object ActRec of which is S0. S1 is the
  new value.

| StAsyncArSucceeded, ND, S(FramePtr), E

  Mark the AsyncFunctionWaitHandle object whose ActRec is given by S0 as
  STATE_SUCCEEDED.

| StAsyncArResume<offset>, ND, S(FramePtr) S(TCA), E

  Store the resume address S1 into the AsyncFunctionWaitHandle whose ActRec is
  given by S0, marking the offset to resume at as `offset'.

| StAsyncArResult, ND, S(FramePtr) S(Cell), E|CRc

  Stores result into the AsyncFunctionWaitHandle object ActRec of which is S0.
  S1 is the value.

| LdAsyncArParentChain, D(ABC), S(FramePtr), NF

  Loads the first parent of the AsyncFunctionWaitHandle object ActRec of which
  is S0.

| AFWHBlockOn, ND, S(FramePtr) S(Obj), E|CRc

  Establish dependency between parent AsyncFunctionWaitHandle object, whose
  ActRec is given by S0, and child WaitableWaitHandle object referenced by S1.

| ABCUnblock, ND, S(ABC), E

  Calls AsioBlockableChain::Unblock.

| LdWHState, D(Int), S(Obj), NF

  Loads the state of the WaitHandle in S0, which is a value from the wait
  handle states in ext_asio.h. This instruction has undefined behavior if S0 is
  not a WaitHandle.

| LdWHResult, D(Cell), S(Obj), NF

  Loads the result of the WaitHandle in S0. This instruction has undefined
  behavior if S0 is not a WaitHandle, or if S0 is not finished.

| LdAFWHActRec, D(FramePtr), S(Obj), C

  Loads the AsyncFunctionWaitHandle object's ActRec, given a pointer to the
  AsyncFunctionWaitHandle object in S0.

| LdResumableArObj, D(Obj), S(FramePtr), C

  Loads the Resumable object, given a Resumable's frame pointer in S0.


16. Debugging, instrumentation, and profiling

| IncStat, ND, C(Int) C(Int) C(Bool), E

  Increment stat counter. S0 is the implementation defined stat counter index,
  S1 is the amount to increment the counter (may be negative), and S2 is a
  'force' flag. This opcode becomes a noop iff (force == false and runtime
  stats are not enabled) at translation time.

| IncTransCounter, ND, NA, E

  Increment a translation counter.  This is probably something related to TC
  print.

| IncStatGrouped, ND, CStr CStr C(Int), E

  Adds the value S2 to the counter named S1, in the category S0.

| IncProfCounter<TransID>, ND, NA, E

  Increment the profiling counter associated with translation TransID.

| DbgAssertRefCount, ND, S(Counted,StaticStr,StaticArr), E

  Assert that S0 has a valid refcount. S0 must be a type with a valid (counted
  or static) _count field. If S0's count is implausible then execute a hardware
  trap instruction (int3 on x64).

| DbgAssertPtr, ND, S(PtrToGen), E

  Assert that S0 points to plausible TypedValue. If the TypedValue is a type
  with a _count field, check that the count field is plausible using the same
  logic as DbgAssertRefCount. Internally this uses always_assert(); failures
  cause an abort (whatever always_assert does).

| DbgAssertType<T>, ND, S(Cell), E

  Assert that S0 is of type T at runtime. If the assertion fails, execution is
  aborted via a hardware exception.

| DbgAssertRetAddr, ND, NA, E

  Assert that the current hardware return address is the expected value. If the
  assertion fails, execution is aborted via a hardware exception.

| RBTrace, ND, NA, E

  Ring buffer tracing.

| ZeroErrorLevel, D(Int), NA, E

| RestoreErrorLevel, ND, S(Int), E

  Helper instructions for fast implementation of the PHP error silencing
  operator (@foo()).


17. Iterators


| IterInit<IterData>,   D(Bool), S(Arr,Obj) S(FramePtr), Er|E|CRc

| IterInitK<IterData>,  D(Bool), S(Arr,Obj) S(FramePtr), Er|E|CRc

| WIterInit<IterData>,  D(Bool), S(Arr,Obj) S(FramePtr), Er|E|CRc

| WIterInitK<IterData>, D(Bool), S(Arr,Obj) S(FramePtr), Er|E|CRc

| MIterInit<T,IterData>,  D(Bool), S(BoxedCell) S(FramePtr), Er|E

| MIterInitK<T,IterData>, D(Bool), S(BoxedCell) S(FramePtr), Er|E

  <IterData> consists of three indices, iterId, keyId and valId. iterId is
  the index of the iterator variable, keyId and valId are indices of local
  variables.

  Initializes the iterator variable whose index is given by iterId.
  This instruction creates the appropriate iterator for the array or object that
  S0 references, and rewinds the new iterator to its start. S0 points to the
  stack frame containing the iterator and local variables with the indices
  iterId, keyId and valId.

  If the new iterator is at its end (i.e., has no elements to iterate over),
  this instruction decrements the refcount of S0 and returns false; otheriwse,
  it stores a reference to S0 in the new iterator and returns true. If the
  iterator is not at its end, then this instruction stores the iterator's first
  value (and key) into the local variable with index valId (and keyId,
  respectively).

  The IterInit and IterInitK instructions always copy the array element by
  value.

  The WIterInit and WIterInitK instructions copy referenced array elements by
  reference, and non-referenced array elements by value.

  The MIterInit and MIterInitK instructions always copy the array element by
  reference, and take a type parameter indicating the inner type of S0.  (This
  must have been proven via guards prior to running this opcode.)  Right now T
  must be Obj or Arr.

  This instruction has the ConsumesRC property because it either decrements the
  reference count of S0 or stores a reference to S0 into the new iterator.

| IterNext<IterData>,   D(Bool), S(FramePtr), Er|E

| IterNextK<IterData>,  D(Bool), S(FramePtr), Er|E

| WIterNext<IterData>,  D(Bool), S(FramePtr), Er|E

| WIterNextK<IterData>, D(Bool), S(FramePtr), Er|E

| MIterNext<IterData>,  D(Bool), S(FramePtr), E

| MIterNextK<IterData>, D(Bool), S(FramePtr), E

  <IterData> consists of three indices, iterId, keyId and valId. iterId is
  the index of the iterator variable, keyId and valId are indices of local
  variables.  S0 points to the stack frame containing the iterator and local
  variables with the indices iterId, keyId and valId.

  Advances the iterator variable whose index is given by iterId.

  If the iterator has reached the end, this instruction frees the iterator
  variable and returns false; otherwise, it returns true. If the iterator has
  not reached its end, then this instruction stores the iterator's next value
  (and key) into the local variable with index valId (and keyId, respectively).

  The IterInit and IterInitK instructions always copy the array element by
  value. The WIterInit and WIterInitK instructions copy referenced array
  elements by reference, and non-referenced array elements by value. The
  MIterNext and MIterNextK instructions always copy the array element by
  reference.

| IterFree,  ND, S(FramePtr), E

| MIterFree, ND, S(FramePtr), E

  Free the iterator variable whose index is given by S1 in the stack frame
  pointed to by S0.

| DecodeCufIter<iterId>, D(Bool), S(Arr,Obj,Str)  S(FramePtr), Er|E

  Decode S0 as a callable, and write the decoded values to the iterator
  specified by IterId. Returns true iff it successfully decoded the callable.
  Does not raise warnings, or throw exceptions.

| CIterFree<iterId>, ND, S(FramePtr), E

  Free the iterator variable whose index is given by IterId in the stack frame
  pointed to by S0.


18. Member instruction support


| DefMIStateBase, D(PtrToMISGen), NA, NF

  Declares a base register for MInstrState. Currently this is always %rsp.

| LdMIStateAddr, DofS(0), S(PtrToMISGen) C(Int), C

  Load an MInstrState address. Returns a pointer to (S0 + S1) with the same
  type as S0. S0 must be the output of a DefMIStateBase.

All of the remaining opcodes in this section are simple wrappers around helper
functions (specified in S0) to perform the corresponding vector operation. If
S1 is a ConstCls it represents the context class for the operation.

SetElem, SetProp, and SetNewElem are used to implement part of the SetM hhbc
opcode, which almost always pushes its first stack input or a CountedStr as its
stack result. The combinations of input types that cause SetM to push anything
other than those two values are vanishingly rare in correct PHP programs, so
these three instructions have been optimized for the common cases. SetNewElem
and SetProp have no destination, allowing the compiler to predict that the
SetM's output will be the same as its input (and optimize accordingly). If that
turns out to not be the case at runtime, the instruction will throw an
InvalidSetMException. The exception will hold a Cell containing the value the
SetM should push on the stack instead of its input value. The runtime is
responsible for catching this exception, finishing execution of the SetM
instruction, pushing the value from the exception on the stack, and proceeding
as appropriate (most likely with a side exit to the next bytecode instruction,
since it has pushed an unexpected type onto the stack).

SetElem is similar to SetProp and SetNewElem but can also be used for setting
characters within strings. When given a string base and a valid offset, SetElem
returns a string representation of the newly inserted character. In all other
cases it returns nullptr or throws an InvalidSetMException. It will throw this
exception when it detects invalid input types, or when trying to set a string
offset that would grow the string beyond the maximum supported size.

The input types that will cause the errors described above are listed here:

SetNewElem will fail if the base is not a subtype of {Null|Str|Arr|Obj} and not
           Bool<false>.
SetElem has the same base constraint as SetNewElem. In addition, the key must
        not be a subtype of {Arr|Obj}.
SetProp will fail if the base is not a subtype of {Obj|Null}.

Any instructions that take a pointer to an MInstrState struct use the various
fields of that struct for holding intermediate values.

| BaseG, D(PtrToRMembCell), S(Str), E|Er

  Get a base from global named S0.

  NB: BaseG returns either a PtrToGblGen, OR a pointer to a ref that is rooted
  in a GblGen.  (I.e. the unbox happens in the C++ helper that this instruction
  calls.)  If it is not a defining BaseG it can also return the
  init_null_variant, so for now it returns a PtrToRMembCell.

| PropX, D(PtrToMemGen), S(Obj,PtrToGen) S(Cell) S(PtrToMISGen), E|Er

  Lookup intermediate property in S0, with key S1.

|STK PropDX, D(PtrToMemGen), S(Obj,PtrToGen) S(Cell) S(PtrToMISGen), MProp|E|Er

  Like PropX, but used for intermediate element lookups that may modify the
  base.

| CGetProp, D(Cell), S(Obj,PtrToGen) S(Cell) S(PtrToMISGen), E|PRc|Er

  Get property with key S1 from S0.

|STK VGetProp, D(BoxedCell),
|              S(Obj,PtrToGen) S(Cell) S(PtrToMISGen),
|              MProp|E|PRc|Er

  Get property with key S1 from base S0 as a reference.

|STK BindProp, ND,
|              S(Obj,PtrToGen) S(Cell) S(BoxedCell) S(PtrToMISGen),
|              MProp|E|Er

  Bind property with key S1 in base S0 to the reference in S2.

|STK SetProp, ND, S(Obj,PtrToGen) S(Cell) S(Cell), MProp|E|Er

  Set property with key S1 in S0 to S2.

| UnsetProp, ND, S(Obj,PtrToGen) S(Cell), E|Er

  Unset an object property.

|STK SetOpProp<op>, D(Cell),
|                   S(Obj,PtrToGen) S(Cell) S(Cell) S(PtrToMISGen),
|                   MProp|E|PRc|Er

  Set op propery with key S1 in base S0, using S2 as the right hand side.

|STK IncDecProp<op>, D(Cell),
|                    S(Obj,PtrToGen) S(Cell) S(PtrToMISGen),
|                    MProp|E|PRc|Er

  Increment/decrement property with key S1 in base S0.

| EmptyProp, D(Bool), S(Obj,PtrToGen) S(Cell), E|Er

  Returns true iff the property with key S1 in base S0 is empty.

| IssetProp, D(Bool), S(Obj,PtrToGen) S(Cell), E|Er

  Returns true iff the property with key S1 in base S0 is set.

| ElemX, D(PtrToMemGen), S(PtrToGen) S(Cell) S(PtrToMISGen), E|Er

  Get intermediate element with key S1 from base S0. The base will not be
  modified.

| ElemArray, D(PtrToMemGen), S(PtrToGen) S(Int,Str), E|Er

| ElemArrayW, D(PtrToMemGen), S(PtrToGen) S(Int,Str), E|Er

  Similar to ElemX, but assumes the base S0 is an array and the key S1 is an
  int/str.  The ElemArrayW version is for Warn member instrs.

|STK ElemDX, D(PtrToMemGen), S(PtrToGen) S(Cell) S(PtrToMISGen), MElem|E|Er

  Like ElemX, but used for intermediate element lookups that may modify the
  base.

|STK ElemUX, D(PtrToMemGen), S(PtrToGen) S(Cell) S(PtrToMISGen), MElem|E|Er

  Like ElemX, but used for intermediate element lookups that may modify the
  base as part of an unset operation.

| ArrayGet, D(Cell), S(Arr) S(Int,Str), PRc|Er

  Get element with key S1 from base S0.

| StringGet, D(StaticStr), S(Str) S(Int), PRc|Er

  Get string representing character at position S1 from base string S0.

| MapGet, D(Cell), S(Obj) S(Int,Str), E|PRc|Er

  Get element with key S1 from base S0.

| CGetElem, D(Cell), S(PtrToGen) S(Cell) S(PtrToMISGen), E|PRc|Er

  Get element with key S1 from S0.

|STK VGetElem, D(BoxedCell), S(PtrToGen) S(Cell) S(PtrToMISGen), MElem|E|PRc|Er

  Get element with key S1 from base S0 as a reference.

|STK BindElem, ND, S(PtrToGen) S(Cell) S(BoxedCell) S(PtrToMISGen), MElem|E|Er

  Bind element with key S1 in base S0 to the reference S2.

| ArraySet, D(Arr), S(Arr) S(Int,Str) S(Cell), E|PRc|CRc|K|Er

  Set element with key S1 in S0 to S2. The dest will be a new Array that should
  replace S0.

| ArraySetRef, ND, S(Arr) S(Int,Str) S(Cell) S(BoxedCell), E|CRc|K|Er

  Like ArraySet, but for binding operations on the array. The parameter in S3
  must point to a RefData with an array type when this instruction is executed,
  and it must be the same array that is in S0.

| MapSet, ND, S(Obj) S(Int,Str) S(Cell), E|Er

  Set element with key S1 in S0 to S2.

|STK SetElem, DSetElem, S(PtrToGen) S(Cell) S(Cell), MElem|E|PRc|Er

  Set element with key S1 in S0 to S2. SetElem returns a Nullptr in the common
  case, where the logical result of the hhbc SetM is its right hand side. In
  the case of string bases, the SetM returns a new string containing the newly
  inserted character. So the return value of this instruction is Nullptr unless
  SetM needed to create a new counted string.

  Furthermore, in the case of "invalid offsets", SetElem may throw an
  InvalidSetMException (see discussion above).

|STK SetWithRefElem, ND,
|                    S(PtrToGen) S(Cell) S(PtrToGen) S(PtrToMISGen),
|                    MElem|E|Er

  Set element with key S1 in S0 to S2.

|STK UnsetElem, ND, S(PtrToGen) S(Cell), MElem|E|Er

  Unsets the element at key S1 in the base S0.

|STK SetOpElem<op>, D(Cell),
|                   S(PtrToGen) S(Cell) S(Cell) S(PtrToMISGen),
|                   MElem|E|PRc|Er

  Set op elem with key S1 in base S0, using S2 as the right hand side.

|STK IncDecElem, D(Cell),
|                S(PtrToGen) S(Cell) S(PtrToMISGen),
|                MElem|E|PRc|Er

  Increment/decrement element with key S1 in base S0.

|STK SetNewElem, ND, S(PtrToGen) S(Cell), MElem|E|Er

  Append the value in S1 to S0.

|STK SetNewElemArray, ND, S(PtrToGen) S(Cell), MElem|E|Er

  Append the value in S1 to S0, where S0 must be a pointer to an array.

|STK SetWithRefNewElem, ND,
|                       S(PtrToGen) S(PtrToGen) S(PtrToMISGen),
|                       MElem|E|Er

  AppendWithRef the value in S1 to S0.

|STK BindNewElem, ND,
|                 S(PtrToGen) S(BoxedCell) S(PtrToMISGen),
|                 MElem|E|Er

  Append the reference in S1 to S0.

| ArrayIsset, D(Bool), S(Arr) S(Int,Str), E|Er

  Returns true iff the element at key S1 in the base S0 is set.

| StringIsset, D(Bool), S(Str) S(Int), NF

  Returns true iff the string S0 has a character at position S1.

| VectorIsset, D(Bool), S(Obj) S(Int), E

  Returns true iff the element at key S1 in the base S0 is set.

| PairIsset, D(Bool), S(Obj) S(Int), E

  Returns true iff the element at key S1 in the base S0 is set.

| MapIsset, D(Bool), S(Obj) S(Int,Str), E

  Returns true iff the element at key S1 in the base S0 is set.

| IssetElem, D(Bool), S(PtrToGen) S(Cell) S(PtrToMISGen), E|Er

  Returns true iff the element at key S1 in S0 is set.

| EmptyElem, D(Bool), S(PtrToGen) S(Cell) S(PtrToMISGen), E|Er

  Returns true iff the element at key S1 in S0 is set and not equal (as defined
  by the hhbc Eq instruction) to false.

| CheckBounds, ND, S(Int) S(Int), E|Er

  Checks that the index in S0 is between 0 (included) and the values in S1
  (excluded). Throws if out of bounds.

| ProfileArray, ND, S(Arr), E

  Profile type of array S0 (i.e. whether it is packed or mixed).

| ProfileStr<key>, ND, S(PtrToGen), E

  Profile exact type of the value pointed to by S0, which must be known to
  point to a string at the time this instruction runs.

| CheckPackedArrayBounds, ND, AK(Packed) S(Int), B|E

  Checks that the index in S1 is within the bounds of the packed array in S0.
  Branches to B if the index is out of bounds.

| CheckTypePackedArrayElem<T>, ND, AK(Packed) S(Int), B|E

  If the array element at S0[S1] is not type T, take the branch.

| IsPackedArrayElemNull, D(Bool), AK(Packed) S(Int), E

  Returns true if the element at index S1 of the packed array in S0 is not
  null.

| LdPackedArrayElem<T>, DArrElem, AK(Packed) S(Int), E

  Loads the element of the packed array in S0 at index S1. If the type param T
  is specified, the destination type intersects it with whatever we'd know from
  the type of S0.

| LdVectorSize, D(Int), S(Obj), E

  Returns the size of the given Vector in S0.

| VectorDoCow, ND, S(Obj), E

  Triggers a copy on write for a Vector that has a live ImmVector sharing
  the same copy of the elements.

| VectorHasImmCopy, ND, S(Obj), B

  Given a vector, check if it has a immutable copy and jump to the taken branch
  if so.

| ColAddNewElemC, D(Obj), S(Obj) S(Cell), Er|CRc|P

  Adds item S0 to the end of collection S0. Throws a fatal error if S0 is not a
  collection. Returns S0.

| ColAddElemC, D(Obj), S(Obj) S(Cell) S(Cell), Er|CRc|P

  Adds item to collection. Inserts item S2 into collection S0 at key S1.
  Throws a fatal error if S0 is not a collection. Returns S0.

| ColIsEmpty, D(Bool), S(Obj), NF

| ColIsNEmpty, D(Bool), S(Obj), NF

  Returns whether a collection instance is empty or not.  S0 must be known to
  be an instance of a collection class at compile time.

19. Exception/unwinding support

| BeginCatch, ND, NA, E

  Marks the beginning of a catch region. Exact behavior is implementation and
  architecture specific.

| EndCatch, ND, S(FramePtr) S(StkPtr), E|T

  Marks the end of a catch region and returns control to the unwinder. Exact
  behavior is implementation and architecture specific.

| UnwindCheckSideExit, ND, S(FramePtr) S(StkPtr), B|E

  Branches to B if the currently executing catch region should return control
  to the unwinder rather than side exiting.  Used to control behavior in catch
  traces for the InvalidSetMException and TVCoercionException situations.

| LdUnwinderValue<T>, DParam, NA, PRc

  Loads the value contained by the current unwinder exception.

| DeleteUnwinderException, ND, NA, E

  Deletes the current unwinder exception.

/* Local Variables: */
/* fill-column: 79 */
/* End: */
vim:textwidth=80