Unconditional Branching Instructions

Unconditional branching instructions take no arguments from the stack and have a signed integer parameter. The parameter specifies the offset in bytes from the current position (which is the beginning of the next instruction—the one following the branching instruction) within the IL stream. The ILAsm notation does allow you to specify the offset explicitly (for example, br -234), but this practice is not recommended for an obvious reason: it’s difficult to calculate the offset correctly when you’re writing in a programming language.

It is much safer and less troublesome to use labels instead, letting the ILAsm compiler calculate the correct offsets. Labels, which you’ve already encountered many times, are simple names followed by a colon.

...
Loop:
...
br Loop
...

By default, the IL assembler does not automatically choose between long-parameter and short-parameter forms. Thus, if you specify a short-parameter instruction and put the target label farther away than the short parameter permits, the calculated offset is truncated to 1 byte, and the IL assembler issues an error message. Versions 2.0 and later of the IL assembler feature the command-line option /OPT, which turns on the automatic replacement of long-parameter instructions by the short-parameter instructions whenever the parameter size permits.

Unconditional branching instructions take nothing from the evaluation stack and put nothing on it.

• br <int32> (0x38): Branch <int32> bytes from the current position.
• br.s <int8> (0x2B): The short-parameter form of br.

Conditional Branching Instructions

Conditional branching instructions differ from the unconditional instructions in one aspect only: they branch only if the condition (<value>, which they take from the evaluation stack) is true (nonzero) or false (zero).

• brfalse (brnull, brzero) <int32> (0x39): Branch if <value> is 0.
• brfalse.s (brnull.s, brzero.s) <int8> (0x2C): The short-parameter form of brfalse.
• brtrue (brinst) <int32> (0x3A): Branch if <value> is nonzero.
• brtrue.s (brinst.s) <int8> (0x2D): The short-parameter form of brtrue.

Comparative Branching Instructions

Comparative branching instructions take two values (<value1>, <value2>) from the evaluation stack and compare them according to the <condition> specified by the opcode. Not all combinations of types of <value1> and <value2> are valid; Table 13-1 lists the valid combinations.

• beq <int32> (0x3B): Branch if <value1> is equal to <value2>.
• beq.s <int8> (0x2E): The short-parameter form of beq.
• bne.un <int32> (0x40): Branch if the two values are not equal. Integer values are interpreted as unsigned; floating-point values are compared unordered.
• bne.un.s <int8> (0x33): The short-parameter form of bne.un.
• bge <int32> (0x3C): Branch if <value1> is greater or equal to <value2>.
• bge.s <int8> (0x2F): The short-parameter form of bge.
• bge.un <int32> (0x41): Branch if greater or equal. Integer values are interpreted as unsigned; floating-point values are compared unordered.
• bge.un.s <int8> (0x34): The short-parameter form of bge.un.
• bgt <int32> (0x3D): Branch if greater.
• bgt.s <int8> (0x30): The short-parameter form of bgt.
• bgt.un <int32> (0x42): Branch if greater. Integer values are interpreted as unsigned; floating-point values are compared unordered.
• bgt.un.s <int8> (0x35): The short-parameter form of bgt.un.
• ble <int32>(0x3E): Branch if less or equal.
• ble.s <int8> (0x31): The short-parameter form of ble.
• ble.un <int32> (0x43): Branch if less or equal. Integer values are interpreted as unsigned; floating-point values are compared unordered.
• ble.un.s <int8> (0x36): The short-parameter form of ble.un.
• blt <int32> (0x3F): Branch if less.
• blt.s <int8> (0x32): The short-parameter form of blt.
• blt.un <int32> (0x44): Branch if less. Integer values are interpreted as unsigned; floating-point values are compared unordered.
• blt.un.s <int8> (0x37): The short-parameter form of blt.un.

The switch Instruction

The switch instruction implements a jump table. This instruction is unique in the sense that it has not one, not two, but N+1 parameters following it, where N is the number of cases in the switch. The first parameter is a 4-byte unsigned integer specifying the number of cases, and the following N parameters are 4-byte signed integers specifying offsets to the targets (cases). There is no short-parameter form of this instruction. The ILAsm notation is as follows:

switch(Label1,Label2,...,LabelN)
...                // Default case
Label1:
...
Label2:
...
...
LabelN:
...

As in the case of branching instructions, the ILAsm syntax allows you to replace the labels in a switch(...) instruction with explicit offsets, but I definitely do not recommend this.

The instruction takes one value from the stack and converts it to an unsigned integer. It then switches to the target according to the value of this unsigned integer. A 0 value corresponds to the first target offset on the list. If the value is greater than or equal to the number of targets, the switch instruction is ignored, and control is passed to the instruction immediately following it. In this sense, the default case in ILAsm is always the first (lexically) case of the switch.

• switch <unsigned int32> <int32>...<int32> (0x45): Branch to one of the <int32> offsets; number of the offsets is specified in leading <unsigned int32>.

The break Instruction

This break instruction isnot equivalent to the break statement in C, which is used as an exit from the switch cases or loops. The break instruction in IL inserts a breakpoint into the IL stream and is used to indicate that if a debugger is attached, execution will stop and control will be given to the debugger. If a debugger is not present, the instruction does nothing. This instruction does not have parameters and does not touch the evaluation stack.

• break (0x01): Debugging breakpoint.

Managed EH Block Exiting Instructions

The blocks of code involved in managed exception handling cannot be entered or exited by simple branching because of the strict stack state requirements imposed on them. The leave instruction, or its short-parameter form, is used to exit a guarded block (a try block) or an exception handler block. You cannot use this instruction, however, to exit a filter, finally, or fault block. (For more details about these blocks, see Chapter 14.)

The instruction has one integer parameter specifying the offset of the target and works the same way as an unconditional branching instruction except that it empties the evaluation stack before the branching. The ILAsm notation for this instruction is similar to the notation for unconditional branching instructions: leave <label> or leave <int32>; the latter one is highly unrecommended.

• leave <int32> (0xDD): Clear the stack, and branch <int32> bytes from the current point.
• leave.s <int8> (0xDE): The short-parameter form of leave.

EH Block Ending Instructions

IL has two specific instructions to mark the end of filter, finally, and fault blocks. Unlike leave, these instructions mark the lexical end of a block (the instruction that has the highest offset in the block) rather than an algorithmic end or point of exit (which may just as well be located in the middle of the block). These instructions have no parameters.

• endfilter (0xFE 0x11):The lexical end of a filter block. The instruction takes one 4-byte integer value from the evaluation stack and signals the execution engine whether the associated exception handler should be engaged (a value of 1) or whether the search for the handler for this particular exception should be continued (a value other than 1) because this filter doesn’t know what to do with this particular exception.
• endfinally (endfault) (0xDC): The lexical end of a finally or fault block. This instruction clears the evaluation stack.

The ret Instruction

The return instruction—ret—returns from a called method to the call site (immediately after the call site, to be precise). It has no parameters. If the called method should return a value of a certain type, exactly one value of the required type must be on the evaluation stack at the moment of return. The ret instruction causes this value to be removed from the evaluation stack of the called method and put on the evaluation stack of the calling method. If the called method returns void, its evaluation stack must be empty at the moment of return.

• ret (0x2A): Return from a method.

Stack Manipulation

Stack manipulation instructions work with the evaluation stack and have no parameters.

• nop (0x00): No operation; a placeholder only. The nop instruction is not exactly a stack manipulation instruction, since it does not touch the stack, but I’ve included it here rather than creating a separate category for it. The nop instruction is somewhat useful only in that, as it is a distinct opcode, a line of source code can be bound to it in the PDB file containing the debug information. The Visual Basic compiler introduces a lot of nop instructions because it wants to bind each and every line of the source code to the IL code. The reasoning behind this is not clear; perhaps the Visual Basic programmers want to be able to put breakpoints on comment lines.

  Another useful application of the nop instructions is specific to version 2.0 or later of the common language runtime (or, more exactly, its JIT compiler). Compilers, emitting the debug information into the PDB files, specify so-called code points, which bind source code lines and columns to offsets in the method code. In versions 1.0 and 1.1, the JIT compiler provided the ability to set the breakpoints at any code point specified in the PDB file. In version 2.0, an “optimized” mode was introduced, in which the JIT compiler effectively ignores the code points specified in the PDB and allows setting the breakpoints only according to some “heuristics.” These heuristics include, for example, the moments when the evaluation stack is empty or when nop is encountered. Empty evaluation stack heuristics work for most imperative high-level languages because, as a rule, each completed statement in these languages translates into code that begins and ends with the evaluation stack empty. This does not work, of course, for ILAsm, so in “optimized” mode you cannot set a breakpoint on an arbitrary instruction, and you cannot “walk” the ILAsm code instruction by instruction under a debugger. Inserting nop instructions after each meaningful instruction would probably help, but it is not a feasible option. Fortunately, the traditional mode, which allows setting the breakpoints according to PDB code points, is also supported in versions 2.0+. But I had to fight for preserving it and explain at lengths why it is important. You can find more details of debug modes in Chapter 16.

• dup (0x25): Duplicate the value on the top of the stack. If the stack is empty, the JIT compiler fails because of the stack underflow.
• pop (0x26): Remove the value from the top of the stack. The value is lost. If the stack is empty, the JIT compiler fails. It’s not healthy to invoke dup or pop on an empty stack.

Constant Loading

Constant loading instructions take at most one parameter (the constant to load) and load it on the evaluation stack. The ILAsm syntax requires explicit specification of the constants (in other words, you cannot use a variable or argument name), in decimal or hexadecimal form:

ldc.i4–1
ldc.i40xFFFFFFFF

Some instructions have no parameters because the value to be loaded is specified by the opcode itself.

Note that for integer and floating-point values, the slots of the evaluation stack are either 4- or 8-bytes wide, so the constants being loaded are converted to the suitable size.

• ldc.i4 <int32> (0x20): Load <int32> on the stack.
• ldc.i4.s <int8> (0x1F): Load <int8> on the stack.
• ldc.i4.m1 (ldc.i4.M1) (0x15): Load –1 on the stack.
• ldc.i4.0 (0x16): Load 0.
• ldc.i4.1 (0x17): Load 1.
• ldc.i4.2 (0x18): Load 2.
• ldc.i4.3 (0x19): Load 3.
• ldc.i4.4 (0x1A): Load 4.
• ldc.i4.5 (0x1B): Load 5.
• ldc.i4.6 (0x1C): Load 6.
• ldc.i4.7 (0x1D): Load 7.
• ldc.i4.8 (0x1E): Load 8. (I should have listed these in reverse order so then we could imagine ourselves on Cape Canaveral.)
• ldc.i8 <int64> (0x21): Load <int64> on the stack.
• ldc.r4 <float32> (0x22): Load <float32> (single-precision) on the stack.
• ldc.r8 <float64> (0x23): Load <float64> (double-precision) on the stack. ILAsm permits the use of integer parameters or byte arrays in both the ldc.r4 and ldc.r8 instructions; this is useful when you need to load special floating-point codes denoting positive or negative infinity or NaN. In such cases, the integers are either converted to floating-point numbers or interpreted as binary images of the floating-point numbers; the byte arrays are always interpreted as such binary images:
  • ldc.r4 1078530000 loads floating-point number 1078530000.0.
  • ldc.r4 float32(1078530000) loads 3.1415901184082.
  • ldc.r4 (D0 0F 49 40) loads 3.1415901184082.

Indirect Loading

An indirect loading instruction takes a managed pointer (&) or an unmanaged pointer (native int) from the stack, retrieves the value at this pointer, and puts the value on the stack. The type of value to be retrieved is defined by the opcode. The indirect loading instructions have no parameters.

• ldind.i1 (0x46): Load a signed 1-byte integer from the location specified by the pointer taken from the stack.
• ldind.u1 (0x47): Load an unsigned 1-byte integer.
• ldind.i2 (0x48): Load a signed 2-byte integer.
• ldind.u2 (0x49): Load an unsigned 2-byte integer.
• ldind.i4 (0x4A): Load a signed 4-byte integer.
• ldind.u4 (0x4B): Load an unsigned 4-byte integer.
• ldind.i8 (ldind.u8) (0x4C): Load an 8-byte integer, signed or unsigned.
• ldind.i (0x4D): Load native int, an integer the size of a pointer.
• ldind.r4 (0x4E): Load a single-precision floating-point value.
• ldind.r8 (0x4F): Load a double-precision floating-point value.
• ldind.ref (0x50): Load an object reference.

Indirect Storing

Indirect storing instructions take a value and an address, in that order, from the stack and store the value at the location specified by the address. Since you are copying the memory (stack slot to specified location) without the need to interpret it, all you care about really is the size of the value to be stored. That’s why the indirect storing instructions for integers don’t have “unsigned” modifications. The address can be a managed or an unmanaged pointer. The type of the value to be stored is specified in the opcode. These instructions have no parameters.

• stind.ref (0x51): Store an object reference.
• stind.i1 (0x52): Store a 1-byte integer.
• stind.i2 (0x53): Store a 2-byte integer.
• stind.i4 (0x54): Store a 4-byte integer.
• stind.i8 (0x55): Store an 8-byte integer.
• stind.i (0xDF): Store a pointer-size integer.
• stind.r4 (0x56): Store a single-precision floating-point value.
• stind.r8 (0x57): Store a double-precision floating-point value.

Arithmetical Operations

All instructions performing the arithmetical operations except the negation operation take two operands from the stack and put the result on the stack. If the result value does not fit the result type, the value is truncated. Table 13-2 lists the admissible type combinations of operands and their corresponding result types. If the type combination is not admissible, the result is undefined and will most probably cause an exception. Note also that this table lists generally admissible type combinations of the operands; particular arithmetic instructions may have their own limitations.

The arithmetical operation instructions are as follows:

• add (0x58): Addition.
• sub (0x59): Subtraction.
• mul (0x5A): Multiplication. For floating-point numbers, which have the special values infinity and NaN, the following rule applies:

  0 * infinity = NaN, x * NaN = NaN, x * infinity = infinity

• div (0x5B): Division. For integers, division by 0 results in a DivideByZero exception. For floating-point numbers, the following rule applies:

  0 / 0 = NaN, infinity / infinity = NaN, x / infinity = 0

• div.un (0x5C): Division of operands treated as unsigned (integer operands only).
• rem (0x5D): Remainder, modulo. For integers, modulo 0 results in a DivideByZero exception. For floating-point numbers, the following rule applies:

  infinity rem x = NaN, x rem 0 = NaN, x rem infinity = x, x rem NaN = NaN

• rem.un (0x5E): The remainder of unsigned operands (integer operands only).
• neg (0x65): Negate—that is, invert the sign. This is the only unary arithmetical operation. It takes one operand rather than two from the evaluation stack and puts the result back. This operation is not applicable to managed pointers or object references but is applicable to unmanaged pointers. With integers, a peculiar situation can occur in which the maximum negative number does not change after negation because of the overflow condition during the operation, as shown in this example:

  ldc.i40x80000000// Max. negative number for int32,
                    //-2147483648
  neg
  call void[mscorlib]System.Console::WriteLine(int32)
  // Output: -2147483648;
  // The same effect with subtraction:
  ldc.i4.0
  ldc.i40x80000000
  sub
  call void[mscorlib]System.Console::WriteLine(int32)
  // Output: -2147483648;

  The previous problem is not in any way IL specific; it stems from the binary representation of integer numbers. Floating-point numbers don’t have this problem. Negating NaN returns NaN because NaN, which is not a number, has no sign.

If an arithmetical operation is applied to integer operands and the result overflows the target, the result is bit truncated to fit the target type, with most significant bits thrown away:

ldc.i40xFFFFFFF0// 4294967280
ldc.i40x000000FF// 255
add
call void[mscorlib]System.Console::WriteLine(int32)
// Output: 239 (0xEF);

When int32 and native int are used as operands of arithmetic instructions on a 64-bit platform, int32 operand is sign extended to native int.

Overflow Arithmetical Operations

Overflow arithmetical operations are similar to the arithmetical operations described in the preceding section except that they work with integer operands only and generate an Overflow exception if the result does not fit the target type. The ILAsm notation for the overflow arithmetical operations contains the suffix.ovf following the operation kind. The type compatibility list, shown in Table 13-3, is similar to the list shown in Table 13-2.

The overflow operation instructions are as follows:

• add.ovf (0xD6): Addition.
• add.ovf.un (0xD7): Addition of unsigned operands.
• sub.ovf (0xDA): Subtraction.
• sub.ovf.un (0xDB): Subtraction of unsigned operands.
• mul.ovf (0xD8): Multiplication.
• mul.ovf.un (0xD9): Multiplication of unsigned operands.

Bitwise Operations

Bitwise operations have no parameters and are defined for integer types only; floating-point, pointer, and object reference operands are not allowed. As a result, the related operand type compatibility list, shown in Table 13-4, is pretty simple.

Three of the bitwise operations are binary, taking two operands from the stack and placing one result on the stack; and one is unary, taking one operand from the stack and placing one result on the stack:

• and (0x5F): Bitwise AND (binary).
• or (0x60): Bitwise OR (binary).
• xor (0x61): Bitwise exclusive OR (binary).
• not (0x66): Bitwise inversion (unary). This operation (which is the equivalent of ldc.i4.1; add; neg;), rather than neg, can be used (to some extent) for the integer sign inversion of the maximum negative integer:

  ldc.i40x80000000// Max. negative number for int32,
                    // -2147483648
  not
  call void[mscorlib]System.Console::WriteLine(int32)
  // Output: 2147483647 (0x7FFFFFFF);
  // Of course, it's not +2147483648,
  // which cannot be expressed by an int32,
  // but at least we have the max. positive number

When int32 and native int are used as operands of bitwise instructions on a 64-bit platform, int32 operand is sign-extended to native int.

Shift Operations

Shift operations have no parameters and are defined for integer operands only. The shift operations are binary: they take from the stack the shift count and the value being shifted, in that order, and put the shifted value on the stack. The result always has the same type as the operand being shifted, which can be of any integer type. The type of the shift count cannot be int64 and is limited to int32 or native int.

• shl (0x62): Shift left.
• shr (0x63): Shift right (the most significant bits of the result assume the value of the sign bit of the value being shifted).
• shr.un (0x64): Shift right, treating the shifted value as unsigned (the most significant bits of the result assume the zero value).

It is interesting that, as you can see, there are no rotational shift operations in the IL, and it is not obvious how these operations could be implemented through shl and shr.un because rotational shift operations are size specific: rol(i, n) == (shl(i, n%sizeof(i)) | shr.un(i, sizeof(i)-n%sizeof(i))), where i is the operand being shifted and n is the shift count.

Conversion Operations

The conversion operations have no parameters. They take a value from the stack, convert it to the type specified by the opcode, and put the result back on the stack. The specifics of the conversion obviously depend on the type of the converted value and the target type (the type to which the value is converted). If the type of the value on the stack is the same as the target type, no conversion is necessary, and the operation itself is doing nothing more than bloating the IL code.

For integer source and target types, several rules apply. If the target integer type is narrower than the source type (for example, int32 to int16, or int64 to int32), the value is truncated—that is, the most significant bytes are thrown away. If the situation is the opposite—if the target integer type is wider than the source—the result is either sign-extended or zero-extended, depending on the type of conversion. Conversions to signed integers use sign-extension, and conversions to unsigned integers use zero-extension.

If the source type is a pointer, it can be converted to either unsigned int64 or native unsigned int. In either case, if the converted pointer was managed, it is dropped from the GC tracking and is not automatically updated when the GC rearranges the memory layout. A pointer cannot be used as a target type.

If both source and target types are floating point, the conversion merely results in a change of precision. In float-to-integer conversions, the values are truncated toward 0; for example, the value 1.1 is converted to 1, and the value –2.3 is converted to –2. In integer-to-float conversions, the integer value is simply converted to floating point, possibly losing less significant mantissa bits.

Object references cannot be subject to conversion operations either as a source or as a target.

• conv.i1 (0x67): Convert the value to int8.
• conv.u1 (0xD2): Convert the value to unsigned int8.
• conv.i2 (0x68): Convert the value to int16.
• conv.u2 (0xD1): Convert the value to unsigned int16.
• conv.i4 (0x69): Convert the value to int32.
• conv.u4 (0x6D): Convert the value to unsigned int32.
• conv.i8 (0x6A): Convert the value to int64.
• conv.u8 (0x6E): Convert the value to unsigned int64. This operation can be applied to pointers.
• conv.i (0xD3): Convert the value to native int.
• conv.u (0xE0): Convert the value to native unsigned int. This operation can be applied to pointers.
• conv.r4 (0x6B): Convert the value to float32.
• conv.r8 (0x6C): Convert the value to float64.
• conv.r.un (0x76): Convert an unsigned integer value to floating point value of “native size.” The “native size” is hardware-specific and generally must be wide enough to represent the result without loss of precision or range. For example, for x86 architecture, the “native floating-point size” is 80 bit (width of an FPU register). The “native-sized” floating-point values cannot be stored in memory and can exist only as intermediate computation results. You cannot have a variable of type “native float;” you can only have a float32 or a float64 variable, and when you store the result of conv.r.un operation in a float32 or a float64 variable, the value is truncated accordingly.

Overflow Conversion Operations

Overflow conversion operations differ from the conversion operations described in the preceding section in two aspects: the target types are exclusively integer types, and an Overflow exception is thrown whenever the value must be truncated to fit the target type. In short, the story is the same as it is with overflow arithmetical operations and arithmetical operations. Note that the overflow condition when converting an integer value depends on this value being considered signed or unsigned. That’s why there are special *.un variants of overflow conversion operations, which presume the integer value on stack being unsigned.

• conv.ovf.i1 (0xB3): Convert the value to int8.
• conv.ovf.u1 (0xB4): Convert the value to unsigned int8.
• conv.ovf.i1.un (0x82): Convert an unsigned integer to int8.
• conv.ovf.u1.un (0x86): Convert an unsigned integer to unsigned int8.
• conv.ovf.i2 (0xB5): Convert the value to int16.
• conv.ovf.u2 (0xB6): Convert the value to unsigned int16.
• conv.ovf.i2.un (0x83): Convert an unsigned integer to int16.
• conv.ovf.u2.un (0x87): Convert an unsigned integer to unsigned int16.
• conv.ovf.i4 (0xB7): Convert the value to int32.
• conv.ovf.u4 (0xB8): Convert the value to unsigned int32.
• conv.ovf.i4.un (0x84): Convert an unsigned integer to int32.
• conv.ovf.u4.un (0x88): Convert an unsigned integer to unsigned int32.
• conv.ovf.i8 (0xB9): Convert the value to int64.
• conv.ovf.u8 (0xBA): Convert the value to unsigned int64.
• conv.ovf.i8.un (0x85): Convert an unsigned integer to int64.
• conv.ovf.u8.un (0x89): Convert an unsigned integer to unsigned int64.
• conv.ovf.i (0xD4): Convert the value to native int.
• conv.ovf.u (0xD5): Convert the value to native unsigned int.
• conv.ovf.i.un (0x8A): Convert an unsigned integer to native int.
• conv.ovf.u.un (0x8B): Convert an unsigned integer to native unsigned int.

Logical Condition Check Instructions

Logical condition check operations are similar to comparative branching instructions except that they result not in branching but in putting the condition check result on the stack. The result type is int32, and its value is equal to 1 if the condition checks and 0 otherwise; in other words, logically the result is a Boolean value. The two operands being compared are taken from the stack, and since no branching is performed, the condition check instructions have no parameters.

The logical condition check instructions are useful when you want to store the result of the condition check for multiple use or for later use. If you need the condition check to decide only once and on the spot whether you need to branch, you would be better off using a comparative branching instruction.

The admissible combinations of operand types are the same as for comparative branching instructions (see Table 13-1). There are, however, fewer condition check instructions than conditional branching operations: some conditions are just logical negations of other conditions (“not equal” is not “equal,” “less or equal” is not “greater,” and so on), so it would be redundant to introduce special check instructions for such conditions.

• ceq (0xFE 0x01): Check whether the two values on the stack are equal.
• cgt (0xFE 0x02): Check whether the first value is greater than the second value. It’s the stack you are working with, so the “second” value is the one on the top of the stack.
• cgt.un (0xFE 0x03): Check whether the first value is greater than the second; integer values are compared as unsigned, and floating-point values are compared as unordered.
• clt (0xFE 0x04): Check whether the first value is less than the second value.
• clt.un (0xFE 0x05): Check whether the first value is less than the second; integer values are compared as unsigned, and floating-point values are compared as unordered.
• ckfinite (0xC3): This unary operation, which takes only one value from the stack, is applicable to floating-point values only. It throws an Arithmetic exception if the value is +infinity, -infinity, or NaN. Otherwise, the operation puts the same value back on the stack.

Block Operations

Two IL instructions deal with blocks of memory regardless of the type or types that make up this memory. Because of their type blindness, both instructions are unverifiable.

• cpblk (0xFE 0x17): Copy a block of memory. The instruction has no parameters and takes three operands from the stack in the following order: the size (in bytes) of the block to be copied (unsigned int32), the source address (a pointer or native int), and the destination address (a pointer or native int). The source and destination addresses must be aligned on the size of native int unless the instruction is prefixed with the unaligned. instruction, described in the “Prefix Instructions” section later in this chapter. The cpblk instruction does not deduce the right direction of byte copying when the source and destination areas overlap, so there is no guarantee in such case. The cpblk instruction puts nothing on the stack.
• initblk (0xFE 0x18): Initialize a block of memory. The instruction has no parameters and takes three operands from the evaluation stack: the size of the block in bytes (unsigned int32), the initialization value (int8), and the block start address (a pointer or native int). The alignment rules mentioned apply to the block start address. The initblk instruction puts nothing on the stack. As a result of this operation, each byte within the specified block is assigned the initialization value.

Method Argument Loading

The following instructions are used for loading method argument values on the evaluation stack:

• ldarg <unsigned int16> (0xFE 0x09): Load the argument number <unsigned int16> on the stack. The argument enumeration is zero based, but it’s important to remember that instance methods have an “invisible” argument not specified in the method signature: the class instance pointer, this, which is always argument number 0. The static methods don’t have such an “invisible” argument, so for them the argument number 0 is the first argument specified in the method signature. The total number of arguments cannot exceed 65535 (0xFFFF), which means the argument ordinal cannot exceed 65534. This limitation stems from the fact that the Sequence entry of the Parameter metadata table is only 2 bytes wide.
• ldarg.s <unsigned int8> (0x0E): The short-parameter form of ldarg.
• ldarg.0 (0x02): Load argument number 0 on the stack.
• ldarg.1 (0x03): Load argument number 1 on the stack.
• ldarg.2 (0x04): Load argument number 2 on the stack.
• ldarg.3 (0x05): Load argument number 3 on the stack.

Method Argument Address Loading

These two instructions are used for loading method argument addresses on the evaluation stack:

• ldarga <unsigned int16> (0xFE 0x0A): Load the address of argument number <unsigned int16> on the stack.
• ldarga.s <unsigned int8> (0x0F): The short-parameter form of ldarga.

Method Argument Storing

These two instructions are used for storing a value from the stack in a method argument slot:

• starg <unsigned int16> (0xFE 0x0B): Take a value from the stack and store it in argument slot number <unsigned int16>. The value on the stack must be of the same type as the argument slot or must be convertible to the type of the argument slot. The convertibility rules and effects are the same as those for conversion operations, discussed earlier in this chapter.
• starg.s <unsigned int8> (0x10): The short-parameter form of starg.

Method Argument List

The following instruction is used exclusively in vararg methods to retrieve the method argument list and put an instance of the value type [mscorlib]System.RuntimeArgumentHandle on the stack. Chapter 10 discusses the application of this instruction.

• arglist (0xFE 0x00): Get the argument list handle.

Local Variable Loading

Local variable loading instructions are similar to argument loading instructions except that no “invisible” items appear among the local variables, so local variable number 0 is always the first one specified in the local variable signature.

• ldloc <unsigned int16> (0xFE 0x0C): Load the value of local variable number <unsigned int16> on the stack. Like the argument numbers, local variable numbers can range from 0 to 65534 (0xFFFE). The value 65535, also admissible for unsigned 2-byte integers, is excluded because otherwise the counter of local variables would have to be 4 bytes wide. Limiting the number of the local variables, however standardized, seems arbitrary and implementation specific because the number of the local variables of a method is not stored in the metadata or in the method header, so this limitation comes purely from one particular implementation of the JIT compiler.
• ldloc.s <unsigned int8> (0x11): The short-parameter form of ldloc.
• ldloc.0 (0x06): Load the value of local variable number 0 on the stack.
• ldloc.1 (0x07): Load the value of local variable number 1 on the stack.
• ldloc.2 (0x08): Load the value of local variable number 2 on the stack.
• ldloc.3 (0x09): Load the value of local variable number 3 on the stack.

Local Variable Reference Loading

The following instructions load references (managed pointers) to the local variables on the evaluation stack:

• ldloca <unsigned int16> (0xFE 0x0D): Load the address of local variable number <unsigned int16> on the stack. The local variable number can vary from 0 to 65534 (0xFFFE).
• ldloca.s <unsigned int8> (0x12): The short-parameter form of ldloca.

Local Variable Storing

It would be strange to have local variables and be unable to assign values to them. The following two instructions take care of this aspect of your life:

• stloc <unsigned int16> (0xFE 0x0E): Take the value from the stack, and store it in local variable slot number <unsigned int16>. The value on the stack must be of the same type as the local variable slot or must be convertible to the type of the local variable slot. The convertibility rules and effects are the same as those for the conversion operations discussed earlier in this chapter.
• stloc.s <unsigned int8> (0x13): The short-parameterform of stloc. You’ve probably noticed that using short-parameter forms of argument and local variable manipulation instructions results in a double gain against the standard form: not only is the parameter 1 byte instead of 2, but also the opcode is shorter.

Local Block Allocation

With all due respect to the object-oriented approach, sometimes it is necessary (or just convenient) to obtain a plain, C-style chunk of memory. The IL instruction set provides an instruction for such allocation. It is to be noted, however, that this memory is available only while the method is executing and is deallocated on the method exit (via ret or an exception). Only the allocating method itself and the methods it calls can access this memory.

• localloc (0xFE 0x0F): Allocate a block of memory for the duration of the method execution. The instruction takes the block size (native unsigned int) from the evaluation stack and puts a managed pointer (&) to the allocated block on the evaluation stack. If not enough space is available on the native thread stack, a StackOverflow exception is thrown. This instruction must not appear within any exception handling block. Like any other block instruction, localloc is unverifiable.

Prefix Instructions

The prefix instructions listed in this section have no meaning per se but are used as prefixes for the pointer-consuming instructions—that is, the instructions that take a pointer value from the stack, such as ldind.*, stind.*, ldfld, stfld, ldobj, stobj, initblk, and cpblk—that immediately follow them. When used as prefixes of instructions that don’t consume pointers, the prefix instructions are ignored and do not carry on to the nearest pointer-consuming instruction.

• unaligned. <unsigned int8> (0xFE 0x12): Indicates that the pointer(s) on the stack are aligned on <unsigned int8> rather than on the pointer size. The <unsigned int8> parameter must be 1, 2, or 4.
• volatile. (0xFE 0x13): Indicates that the pointer on the stack is volatile—that is, the value it points at can be modified from another thread of execution and the results of its dereferencing therefore cannot be cached for performance considerations.

A prefix instruction affects only the immediately following instruction and does not mark the respective pointer as unaligned or volatile throughout the entire method. Both prefixes can be used with the same instruction—in other words, the pointer on the stack can be marked as both unaligned and volatile; in such a case, the order of appearance of the prefixes does not matter.

The ILAsm syntax requires the prefix instructions to be separated from the next instruction by at least a space symbol:

volatile. ldind.i4// Correct
 
volatile.
ldind.i4// Correct
 
volatile.ldind.i4// Syntax error

Such a mistake is unlikely with the unaligned. instruction because it requires an integer parameter:

unaligned.4 ldind.i4

The prefix instructions tail. and constrained. are specific to method calling, and the prefix instruction readonly. is specific to array manipulation. These prefix instructions are discussed in respective sections of this chapter.

Direct Calls

The IL instruction set contains three instructions intended for the direct method calls (well, “direct” in the sense that all these instructions directly specify the method being called; some purists would not consider a virtual call “direct” because under the hood it is done via the v-table):

• jmp <token> (0x27): Abandon the current method and jump to the target method, specified by <token>, transferring the current arguments in their present state (which may be different from the original state because the calling method could change the argument values before the jump). Everything else of the current method, including local variables and locally allocated memory, is abandoned. At the moment jmp is invoked, the evaluation stack must be empty, and the arguments are transferred automatically. Because of this, the signature of the target method must exactly match the signature of the method invoking jmp. This instruction should not be used within EH blocks—.try, catch, filter, fault, or finally blocks, discussed in Chapter 14—or within a synchronized region (the code segment protected by a thread lock, such as a mutex). The jmp instruction is unverifiable.
• call <token> (0x28): Call an instance or static method nonvirtually. You can also call a virtual method, but in this case it is called not through the type’s v-table. (If this sounds somehow vague to you, you might want to return to Chapter 10 and, more precisely, to the sample file Virt_not.il.) The real difference between virtual and nonvirtual instance methods becomes obvious when you create an instance of a class, cast it to the parent type of the class, and then call instance methods on this “child-posing-as-parent” instance. The nonvirtual methods are called directly, bypassing the child type’s v-table, so the parent’s methods will be called in this case. Virtual methods are called through the v-table, and hence the overriding child’s methods will be called. To confirm this, carry out a simple experiment: open the sample file Virt_not.il in a text editor, and change callvirt instance void A::Bar( ) to call instance void A::Bar( ). Then recompile the sample, and run it.
• callvirt <token> (0x6F): Call the virtual method specified by <token>. This type of method call is conducted through the instance’s v-table. It is possible to call a nonvirtual instance method using callvirt. In this case, the method is called directly simply because the method cannot be found in the v-table. But unlike call, the callvirt instruction first checks the validity of the object reference (this pointer) before doing anything else, which is a very useful feature. The C# compiler exploits it shamelessly, emitting callvirt to call both virtual and nonvirtual instance methods of classes. I say “of classes” because callvirt requires an object reference as the this pointer and will not accept a managed pointer to a value type instance. To use callvirt with an instance of a value type, you need to box the instance first, thus converting it to a class instance carrying the v-table.

CLR 2.0 or later considers nonvirtual calls of virtual methods unverifiable except in the following cases:

• If the called method is final (cannot be overridden).
• If the instance reference is that of a boxed value type (value types are all sealed).
• If the parent class of the called method is sealed.
• If the calling method and the called method are instance methods of the same class.
• If the instance pointer is a managed pointer to a value type.

These exceptions cover almost all cases when the called virtual method is guaranteed not to be overridden. I say “almost” because there is at least one such case not covered—when the type of the object reference is reliably traceable and the called method belongs to this type:

.class public A
{
    ...
    .method public virtual void f() { ... }
}
.class public B extends A
{
    ...
    .method public virtual void f() { ... }
}
...
newobj instance void B:: .ctor()
dup
// The objects on the stack are known to be B (not B's descendants cast to B)
call instance void B::f()// should be verifiable, the type matches the object
call instance void A::f()// unverifiable – the type doesn't match the object
...

Indirect Calls

Methods in IL can be called indirectly through the function pointer loaded on the evaluation stack. This allows you to make calls to computed targets—for example, to call a method by a function pointer returned by another method. Function pointers used in indirect calls are unmanaged pointers represented by native int. Two instructions load a function pointer to a specified method on the stack, and one other instruction calls a method indirectly:

• ldftn <token> (0xFE 0x06): Load the function pointer to the method specified by <token> of MethodDef or MemberRef type.
• ldvirtftn <token> (0xFE 0x07): Take the object reference (the instance pointer) from the stack, and load the function pointer to the method specified by <token>. The method is looked up in the instance’s v-table.
• calli <token> (0x29): Take the function pointer from the stack, take all the arguments from the stack, and make an indirect method call according to the method signature specified by <token>. <token> must be a valid StandAloneSig token. The function pointer must be on the top of the stack. If the method returns a value, it is pushed on the stack at the completion of the call, just like in direct calls. The calli instruction is unverifiable, which is not surprising, considering that the call is made via an unmanaged pointer, which is itself unverifiable.

It’s easy enough to see that the combination ldftn/calli is equivalent to call, as long as you don’t consider verifiability, and the combination ldvirtftn/calli is equivalent to callvirt.

The ILAsm notation requires full specification of the method in the ldftn and ldvirtftn instructions, similar to the call and callvirt instructions. The method signature accompanying the calli instruction is specified as <call_conv> <ret_type>(<arg_list>). For example,

.locals init(native int fnptr)
...
ldftn void[mscorlib]System.Console::WriteLine(int32)
stloc.0// Store function pointer in local variable
...
ldc.i412345// Load argument
ldloc.0// Load function pointer
calli void(int32)
...

Tail Calls

Tail calls are similar to method jumps (jmp) in the sense that both lead to abandoning the current method and passing the arguments to the tail-called (jumped-at) method. However, since the arguments of a tail call have to be loaded on the evaluation stack explicitly (a tail call discards the stack frame of the current method, unlike a jump, which preserves the stack frame and can use the arguments already loaded), a tail call—unlike a jump—does not require the entire signature of the called method to match the signature of the calling method; only the return types must be the same or compatible. The tail calls are very useful in implementing massively recursive methods: the caller’s stack frame is discarded in the process of a tail call, so there is no risk of overflowing the stack, no matter how deep the recursion is. This is important for the functional languages, which use recursion instead of loops.

Tail calls are distinguished by the prefix instruction tail. immediately preceding a call, callvirt, or calli instruction:

• tail. (0xFE 0x14): Mark the following call instruction as a tail call. This instruction has no parameters and does not work with the stack. In ILAsm, this instruction—like the other prefix instructions unaligned. and volatile., discussed earlier—must be separated from the call instruction that follows it by at least a space symbol.

The difference between a method jump and a tail call is that the tail call instruction pair is verifiable in principle, subject to the verifiability of the call arguments, as long as it is immediately followed (in the caller instruction stream) by the ret instruction. As is the case with other prefix instructions, it is illegal to bypass the prefix and branch directly to the prefixed instruction, in this case, call, callvirt, or calli.

Constrained Virtual Calls

Constrained virtual calls were introduced in version 2.0 of the common language runtime in order to deal with instantiations of generic types or methods when the type whose method is called is represented by a type parameter and hence equally might be a reference type or a value type:

.class public G<(IFoo)T>// Interface IFoo specifies method void Foo(int32)
{
    .method public static void CallVirtFoo(class!T t, int32val)
    {
        // How do I get the object ref?
        // If T is a reference type, I just needldarg.0
        // If T is a value type, I needldarga.s0 and thenbox
        ldarg.1
        callvirt instance void IFoo::Foo(int32)
...

Obviously, the applicable calling mechanism must be identified “on the spot,” when the virtual call is about to be executed and the nature of the type instance becomes known. This is not good—the IL code of the method becomes dependent on the nature of the generic parameter.

The constrained virtual calls, unlike unconstrained calls and virtual calls, require a managed pointer (&) to the type instance (this pointer), whether this instance is an object reference or a value type instance. In unconstrained calls, as you know, the this pointer must be an object reference (O) or a managed pointer (&) to a value type instance. Uniform usage of a managed pointer in constrained calls allows you to use the same IL instructions, “preparing” the instance pointer for the virtual call:

.class public G<(IFoo)T>// Interface IFoo specifies method void Foo(int32)
{
    .method public static void CallVirtFoo(class!T t, int32val)
    {
        ldarga.s0// load managed pointer to t
        ldarg.1
        constrained. class!T
        callvirt instance void IFoo::Foo(int32)
...

The applicable calling mechanism is identified as follows:

• If the type is a reference type (and hence the this pointer is a managed pointer to object reference), then the this pointer is dereferenced yielding the object reference, and the virtual call is executed on this object reference.
• If the type is a value type (and hence the this pointer is a managed pointer to a value type instance) and the type implements the specified method, then the nonvirtual call is executed on the this pointer; it is safe to do because value types are sealed, and the virtual methods implemented by them cannot be possibly overridden.
• If the type is a value type and it does not implement the specified method (must have inherited it from its ancestors System.Object, System.ValueType and maybe System.Enum), then the this pointer is dereferenced yielding a value type instance, which is then boxed yielding an object reference, and the virtual call is executed on this object reference. You cannot use the same trick here and call the method nonvirtually because the value type doesn’t implement it; but at least one of its ancestors does, so the method is present in the (boxed) value type’s v-table.

Constrained calls are distinguished by the prefix instruction constrained. immediately preceding a callvirt or ldvirtftn instruction:

• constrained. <token> (0xFE 0x16): Mark the following virtual call instruction as a constrained call. The <token> usually is a TypeSpec token representing a generic type variable ({E_T_VAR <ordinal>} or {E_T_MVAR <ordinal>}). However, <token> may be a TypeRef or TypeDef token as well, which means that constrained virtual calls can be used with nongeneric types.

The mechanism of constrained virtual calls unifies the way the methods can be called on reference and value types and hence is very useful to compilers, which now don’t have to figure out whether the instance is an object reference or a value type instance. Considering that some languages don’t even make a distinction between reference types and value types and treat all types as objects, the constrained virtual call mechanism is indeed a good addition to the IL instruction set.

Vector Creation

In order to work with a vector, it is necessary to create one. The IL instruction set contains special instructions for vector creation and vector length querying:

• newarr <token> (0x8D): Create a vector. <token> specifies the type of vector elements and must be a valid TypeDef, TypeRef, or TypeSpec token. This instruction pops the number of vector elements (native int or int32) from the stack and pushes an object reference to the created vector on the stack. If the operation fails, an OutOfMemory exception is thrown. If the number of elements happens to be negative, an Overflow exception is thrown. The elements of the newly created vector are zero initialized. For example,

  .locals init(int32[] arr)
  ldc.i4123
  newarr[mscorlib]System.Int32// newarr int32 would work too
  stloc.0

  For specific details about array creation, see the description of the newobj instruction.

• ldlen (0x8E): Get the element count of a vector. This instruction takes an object reference to the vector instance from the stack and puts the element count (native int) on the stack.

Element Address Loading

You can obtain a managed pointer to a single vector element by using the following instruction:

• ldelema <token> (0x8F): Get the address (a managed pointer) of a vector element. <token> specifies the type of the element and must be a valid TypeDef, TypeRef, or TypeSpec token. This instruction takes the element index (native int) and the vector reference (an object reference) from the stack and pushes the managed pointer to the element on the stack.
• readonly. (0xFE 0x1E): Prefix instruction, introduced in version 2.0 of the CLR, to be used with the ldelema instruction. With this prefix, ldelema yields not a managed pointer to the element but a controlled mutability managed pointer, which can be used only as a source pointer but not as a destination pointer. For example, you can use a controlled mutability pointer as an instance pointer when accessing instance fields or methods, as a source pointer in cpobj instruction, or as a pointer in an ldind or ldobj instruction. But it cannot be used in any instruction that would change the instance it points to, such as initobj, stind, stobj, or mkrefany. The main reason for introducing this prefix instruction is to avoid the type check ldelema must execute when the type specified might be a reference class. If the ldelema instruction is preceded by the readonly. prefix, the type check is suppressed, because it is known that the obtained pointer cannot be used for writing purposes (the referent type instance cannot be mutated). Of course, the type might have a method that mutates the instance, and the controlled mutability pointer can be used to call this method and thus mutate the instance. Also, you can use this pointer for the stfld instruction, and if it doesn’t mutate the instance, I don’t know what does. So, a controlled mutability pointer is not exactly a read-only pointer. However, you can only fiddle with this very instance (pointed at by the controlled mutability pointer); you cannot replace it with another instance, and in this sense the pointer is read-only.

Element Loading

Element loading instructions load a vector element of an elementary type on the stack. All these instructions take the element index (native int) and the vector reference (an object reference) from the stack and put the value of the element on the stack. If the vector reference is null, the instructions throw a NullReference exception. If the index is negative or greater than or equal to the element count of the vector, an IndexOutOfRange exception is thrown.

• ldelem.i1 (0x90): Load a vector element of type int8.
• ldelem.u1 (0x91): Load a vector element of type unsigned int8.
• ldelem.i2 (0x92): Load a vector element of type int16.
• ldelem.u2 (0x93): Load a vector element of type unsigned int16.
• ldelem.i4 (0x94): Load a vector element of type int32.
• ldelem.u4 (0x95: Load a vector element of type unsigned int32.
• ldelem.i8 (ldelem.u8) (0x96): Load a vector element of type int64.
• ldelem.i (0x97): Load a vector element of type native int.
• ldelem.r4 (0x98): Load a vector element of type float32.
• ldelem.r8 (0x99): Load a vector element of type float64.
• ldelem.ref (0x9A): Load a vector element of object reference type.
• ldelem (ldelem.any) <token> (0xA3): Load a vector element of the type specified by <token>, which must be a valid TypeDef, TypeRef, or TypeSpec token. This instruction was introduced in version 2.0 of the CLR to deal with, as you probably guessed, vectors and arrays of a type defined by a generic type variable. The good thing about this instruction (and its sister instruction stelem described next) is that it allows you to load elements of vectors of an arbitrary value type.

Element Storing

Element storing instructions store a value from the stack in a vector element of an elementary type. All these instructions take the value to be stored, the element index (native int), and the vector reference (an object reference) from the stack and put nothing on the stack. Generally, the instructions can throw the same exceptions as the ldelem.* instructions described in the preceding section.

• stelem.i (0x9B): Store a value in a vector element of type native int.
• stelem.i1 (0x9C): Store a value in a vector element of type int8.
• stelem.i2 (0x9D): Store a value in a vector element of type int16.
• stelem.i4 (0x9E): Store a value in a vector element of type int32.
• stelem.i8 (0x9F): Store a value in a vector element of type int64.
• stelem.r4 (0xA0): Store a value in a vector element of type float32.
• stelem.r8 (0xA1): Store a value in a vector element of type float64.
• stelem.ref (0xA2): Store a value in a vector element of the object reference type. This instruction involves the casting of the object on the stack to the type of the vector element, so an InvalidCast exception can be thrown.
• stelem (stelem.any) <token> (0xA4): Store a value in a vector element of the type specified by <token>, which must be a valid TypeDef, TypeRef, or TypeSpec token. This instruction was introduced in version 2.0 of the CLR to support vectors and arrays of the type defined by a generic type variable.

Special stelem.* instructions for unsigned integer types are missing for an obvious reason: the stelem.i* instructions are equally applicable to signed and unsigned integer types because the sizes of these integer types are the same.