1 Scope

This specification is a detailed description of the Common Intermediate Language (CIL) instruction set, part of the specification of the Common Language Infrastructure. Partition I describes the architecture of the CLI and provides an overview of a large number of issues relating to the CIL instruction set. That overview is essential to an understanding of the instruction set as described here.

ANNOTATION

The importance of section 1 in Partition III cannot be overemphasized, particularly if you are writing a compiler or want to understand the output of a compiler. It will also help you if you care about the numeric characteristics of your computation, and it should help you pick a language that provides the numeric characteristics you want.

Each instruction description describes a set of related CLI machine instructions. Each instruction definition consists of five parts:

• A table describing the binary format, assembly language notation, and description of each variant of the instruction. See Partition III, section 1.2.

• A stack transition diagram that describes the state of the evaluation stack before and after the instruction is executed. See Partition III, section 1.3.

• An English description of the instruction. See Partition III, section 1.4.

• A list of exceptions that might be thrown by the instruction. See Partition I, section 12.4.2 for details. There are three exceptions which may be thrown by any instruction and are not listed with the instruction:

  ExecutionEngineException indicates that the internal state of the Execution Engine is corrupted and execution cannot continue. (Note: In a system that executes only verifiable code this exception is not thrown.)

  StackOverflowException indicates that the hardware stack size has been exceeded. The precise timing of this exception and the conditions under which it occurs are implementation-specific. (Note: This exception is unrelated to the maximum stack size described in Partition III, section 1.7.4. That size relates to the depth of the evaluation stack that is part of the method state described in Partition I [section 12.3.2], while this exception has to do with the implementation of that method state on physical hardware.)

  OutOfMemoryException indicates that the available memory space has been exhausted, either because the instruction inherently allocates memory (newobj, newarr) or for an implementation-specific reason (for example, an implementation based on just-in-time compilation to native code may run out of space to store the translated method while executing the first call or callvirt to a given method).

• A section describing the verifiability conditions associated with the instruction. See Partition III, section 1.8.

In addition, operations that have a numeric operand also specify an operand type table that describes how they operate based on the type of the operand. See Partition III, section 1.5.

Note that not all instructions are included in all CLI profiles. See Partition IV for details.

1.1 Data Types

While the Common Type System (CTS) defines a rich type system and the Common Language Specification (CLS) specifies a subset that can be used for language interoperability, the CLI itself deals with a much simpler set of types. These types include user-defined value types and a subset of the built-in types. The subset is collectively known as the "basic CLI types":

• A subset of the full numeric types (int32, int64, native int, and F)

• Object references (O) without distinction between the type of object referenced

• Pointer types (native unsigned int and &) without distinction as to the type pointed to

Note that object references and pointer types may be assigned the value null. This is defined throughout the CLI to be zero (a bit pattern of all bits zero).

ANNOTATION

Understanding the descriptions in this section of data types, particularly information on the numeric types, is an important part of understanding the VES. Although the CTS specifies a full set of data types, the instruction set clearly supports a much smaller set. The first section of Partition III describes how the VES, without having the full type set built in, handles all of the CTS data types.

One way to view the CLI is that there are actually three type systems, compatible but different. First is the Common Type System (CTS), supported by the metadata, and described in Partition I and the first half of Partition II. This is the richest type system, describing types for all languages, and having many features that affect only a subset of languages. This is the type system that programmers see, through the filter of the languages they use.

The next type system, smaller than the CTS, is the type system that verifiers use. A verifier checks for subtype relationships between reference types, and the distinctions among all the value types, etc., but sees no distinction, for example, between a signed and an unsigned integer.

Finally, there is the smallest type system the type system of which the VES is aware. This type system contains a subset of the full numeric type system (32- and 64-bit integers, native-size integers, and floating point), both managed and unmanaged pointers, and distinguishes between value types. Although the VES needs to know about the size and shape of value types, it sees objects only as a reference. From the point of view of the VES, all reference types are treated as one type O. This reflects the fact that from an implementation point of view, objects are all represented the same way (typically, as a pointer to data with a standard header on the heap). There are a few object model instructions, but beyond that, the VES has a very simple view of objects, leaving type checking to languages and verifiers.

From that small data type set, then, the class library uses the CIL instruction set to produce all of the CTS data types. For example, although the VES knows only about signed integers, there are both signed and unsigned instructions like add. Similarly, some instructions check for overflow, while others do not.

It is the job of the compiler to use the appropriate instruction to get the desired result. For example, as far as the VES operations on the evaluation stack are concerned, it is legitimate to have only one floating point type, and it does not care about its size, which can be anything greater than or equal to 64 bits. It is also legitimate to have more than one floating point type, typically a 32-bit representation and a 64-bit representation. The VES makes the distinction about the size of numeric values only when storing these values to or reading from the heap, statics, local variables, or method arguments. Microsoft's Common Language Runtime, an implementation of the VES, has set that VES floating point size at 64 bits. The compiler must use CIL instructions that force that value back to 32 bits, when appropriate.

If you are writing a compiler, want to understand the output of your compiler, or want to understand the VES, it is essential to understand this section.

1.1.1 Numeric Data Types

• The CLI only operates on the numeric types int32 (4-byte signed integers), int64 (8-byte signed integers), native int (native-size integers), and F (native-size floating point numbers). The CIL instruction set, however, allows additional data types to be implemented:

• Short integers. The evaluation stack only holds 4- or 8-byte integers, but other locations (arguments, local variables, statics, array elements, fields) may hold 1- or 2-byte integers. Loading from these locations onto the stack either zero-extends (ldind.u*, ldelem.u*, etc.) or sign-extends (ldind.i*, ldelem.i*, etc.) to a 4-byte value. Storing to integers (stind.u1, stelem.i2, etc.) truncates. Use the conv.ovf.* instructions to detect when this truncation results in a value that doesn't correctly represent the original value.

NOTE

Short integers are loaded as 4-byte numbers on all architectures, and these 4-byte numbers must always be tracked as distinct from 8-byte numbers. This helps portability of code by ensuring that the default arithmetic behavior (i.e., when no conv or conv.ovf instructions are executed) will have identical results on all implementations.

Convert instructions that yield short integer values actually leave an int32 (32-bit) value on the stack, but it is guaranteed that only the low bits have meaning (i.e., the more significant bits are all zero for the unsigned conversions or a sign extension for the signed conversions). To correctly simulate the full set of short integer operations, a conversion to the short form is required before the div, rem, shr, comparison, and conditional branch instructions.

In addition to the explicit conversion instructions, there are four cases where the CLI handles short integers in a special way:

• Assignment to a local (stloc) or argument (starg) whose type is declared to be a short integer type automatically truncates to the size specified for the local or argument.

• Loading from a local (ldloc) or argument (ldarg) whose type is declared to be a short signed integer type automatically sign-extends.

• Calling a procedure with an argument that is a short integer type is equivalent to assignment to the argument value, so it truncates.

• Returning a value from a method whose return type is a short integer is modeled as storing into a short integer within the called procedure (i.e., the CLI automatically truncates) and then loading from a short integer within the calling procedure (i.e., the CLI automatically zero- or sign-extends).

In the last two cases it is up to the native calling convention to determine whether values are actually truncated or extended, as well as whether this is done in the called procedure or the calling procedure. The CIL instruction sequence is unaffected, and it is as though the CIL sequence included an appropriate conv instruction.

• 4-byte integers. The shortest value actually stored on the stack is a 4-byte integer. These can be converted to 8-byte integers or native-size integers using conv.* instructions. Native-size integers can be converted to 4-byte integers, but doing so is not portable across architectures. The conv.i4 and conv.u4 can be used for this conversion if the excess significant bits should be ignored; the conv.ovf.i4 and conv.ovf.u4 instructions can be used to detect the loss of information. Arithmetic operations allow 4-byte integers to be combined with native-size integers, resulting in native-size integers. Four-byte integers may not be directly combined with 8-byte integers (they must be converted to 8-byte integers first).

• Native-size integers. Native-size integers can be combined with 4-byte integers using any of the normal arithmetic instructions, and the result will be a native-size integer. Native-size integers must be explicitly converted to 8-byte integers before they can be combined with 8-byte integers.

• 8-byte integers. Supporting 8-byte integers on 32-bit hardware may be expensive, whereas 32-bit arithmetic is available and efficient on current 64-bit hardware. For this reason, numeric instructions allow int32 and native int data types to be intermixed (yielding the largest type used as input), but these types cannot be combined with int64s. Instead, a native int or int32 must be explicitly converted to int64 before it can be combined with an int64.

• Unsigned integers. Special instructions are used to interpret integers on the stack as though they were unsigned, rather than tagging the stack locations as being unsigned.

• Floating point numbers. See also Partition I, section 12.1.3. Storage locations for floating point numbers (statics, array elements, and fields of classes) are of fixed size. The supported storage sizes are float32 and float64. Everywhere else (on the evaluation stack, as arguments, as return types, and as local variables), floating point numbers are represented using an internal floating point type. In each such instance, the nominal type of the variable or expression is either float32 or float64, but its value may be represented internally with additional range and/or precision. The size of the internal floating point representation is implementation-dependent, may vary, and shall have precision at least as great as that of the variable or expression being represented. An implicit widening conversion to the internal representation from float32 or float64 is performed when those types are loaded from storage. The internal representation is typically the natural size for the hardware, or as required for efficient implementation of an operation. The internal representation shall have the following characteristics:

  • The internal representation shall have precision and range greater than or equal to the nominal type.

  • Conversions to and from the internal representation shall preserve value. (Note: This implies that an implicit widening conversion from float32 (or float64) to the internal representation, followed by an explicit conversion from the internal representation to float32 (or float64), will result in a value that is identical to the original float32 (or float64) value.)

NOTE

The above specification allows a compliant implementation to avoid rounding to the precision of the target type on intermediate computations, and thus permits the use of wider precision hardware registers, as well as the application of optimizing transformations which result in the same or greater precision, such as contractions. Where exactly reproducible behavior is required by a language or application, explicit conversions may be used.

When a floating point value whose internal representation has greater range and/or precision than its nominal type is put in a storage location, it is automatically coerced to the type of the storage location. This may involve a loss of precision or the creation of an out-of-range value (NaN, +infinity, or infinity). However, the value may be retained in the internal representation for future use, if it is reloaded from the storage location without having been modified. It is the responsibility of the compiler to ensure that the memory location is still valid at the time of a subsequent load, taking into account the effects of aliasing and other execution threads (see Partition I, section 12.6). This freedom to carry extra precision is not permitted, however, following the execution of an explicit conversion (conv.r4 or conv.r8), at which time the internal representation must be exactly representable in the associated type.

NOTE

To detect values that cannot be converted to a particular storage type, use a conversion instruction (conv.r4, or conv.r8) and then check for an out-of-range value using ckfinite. To detect underflow when converting to a particular storage type, a comparison to zero is required before and after the conversion.

NOTE

This standard does not specify the behavior of arithmetic operations on denormalized floating point numbers, nor does it specify when or whether such representations should be created. This is in keeping with IEC 60559:1989. In addition, this standard does not specify how to access the exact bit pattern of NaNs that are created, nor the behavior when converting a NaN between 32-bit and 64-bit representation. All of this behavior is deliberately left implementation-specific.

1.1.2 Boolean Data Type

A CLI Boolean type occupies 1 byte in memory. A bit pattern of all zeros denotes a value of false. A bit pattern with any bit set (analogous to a non-zero integer) denotes a value of true.

1.1.3 Object References

Object references (type O) are completely opaque. There are no arithmetic instructions that allow object references as operands, and the only comparison operations permitted are equality (and inequality) between two object references. There are no conversion operations defined on object references. Object references are created by certain CIL object instructions (notably newobj and newarr). Object references can be passed as arguments, stored as local variables, returned as values, and stored in arrays and as fields of objects.

1.1.4 Runtime Pointer Types

There are two kinds of pointers: unmanaged pointers and managed pointers. For pointers into the same array or object, the following arithmetic operations are defined:

• Adding an integer to a pointer, where the integer is interpreted as a number of bytes, results in a pointer of the same kind.

• Subtracting an integer (number of bytes) from a pointer results in a pointer of the same kind. Note that subtracting a pointer from an integer is not permitted.

• Two pointers, regardless of kind, can be subtracted from one another, producing an integer that specifies the number of bytes between the addresses they reference.

None of these operations is allowed in verifiable code.

It is important to understand the impact on the garbage collector of using arithmetic on the different kinds of pointers. Since unmanaged pointers must never reference memory that is controlled by the garbage collector, performing arithmetic on them can endanger the memory safety of the system (hence it is not verifiable), but since they are not reported to the garbage collector there is no impact on its operation.

Managed pointers, however, are reported to the garbage collector. As part of garbage collection both the contents of the location to which they point and the pointer itself can be modified. The garbage collector will ignore managed pointers if they point into memory that is not under its control (the evaluation stack, the call stack, static memory, or memory under the control of another allocator). If, however, a managed pointer refers to memory controlled by the garbage collector it must point to either a field of an object, an element of an array, or the address of the element just past the end of an array. If address arithmetic is used to create a managed pointer that refers to any other location (an object header or a gap in the allocated memory), the garbage collector's operation is unspecified.

1.1.4.1 Unmanaged Pointers

Unmanaged pointers are the traditional pointers used in languages like C and C++. There are no restrictions on their use, although for the most part they result in code that cannot be verified. While it is perfectly legal to mark locations that contain unmanaged pointers as though they were unsigned integers (and this is, in fact, how they are treated by the CLI), it is often better to mark them as unmanaged pointers to a specific type of data. This is done by using ELEMENT_TYPE_PTR in a signature for a return value, a local variable, or an argument or by using a pointer type for a field or array element.

Unmanaged pointers are not reported to the garbage collector and can be used in any way that an integer can be used.

• Unmanaged pointers should be treated as unsigned (i.e., use conv.ovf.u rather than conv.ovf.i, etc.).

• Verifiable code cannot use unmanaged pointers to reference memory.

• Unverified code can pass an unmanaged pointer to a method that expects a managed pointer. This is safe only if one of the following is true:

  • The unmanaged pointer refers to memory that is not in memory managed by the garbage collector.

  • The unmanaged pointer refers to a field within an object.

  • The unmanaged pointer refers to an element within an array.

  • The unmanaged pointer refers to the location where the element following the last element in an array would be located.

1.1.4.2 Managed Pointers (type &)

Managed pointers (&) may point to a local variable, a method argument, a field of an object [(this includes an instance or static field of an object)], a field of a value type, an element of an array, or the address where an element just past the end of an array would be stored (for pointer indexes into managed arrays). Managed pointers cannot be null. (They must be reported to the garbage collector, even if they do not point to managed memory.)

ANNOTATION

Managed pointers are an innovation of the CLI. Although the designers of the C# language initially did not want to include them, ultimately they have found them useful. By including managed pointers in C#, it becomes possible to implement out parameters, so that, in contrast to Java, it is not necessary to create a data structure to return multiple out parameters.

Managed pointers are specified by using ELEMENT_TYPE_BYREF in a signature for a return value, a local variable, or an argument or by using a by-ref type for a field or array element.

• Managed pointers can be passed as arguments and stored in local variables.

• If you pass a parameter by reference, the corresponding argument is a managed pointer.

• Managed pointers cannot be stored in static variables, array elements, or fields of objects or value types.

• Managed pointers are not interchangeable with object references.

• A managed pointer cannot point to another managed pointer, but it can point to an object reference or a value type.

• Managed pointers that do not point to managed memory can be converted (using conv.u or conv.ovf.u) into unmanaged pointers, but this is not verifiable.

• Unverified code that erroneously converts a managed pointer into an unmanaged pointer can seriously compromise the integrity of the CLI. This conversion is safe if any of the following is known to be true:

  1. The managed pointer does not point into the garbage collector's memory area.

  2. The memory referred to has been pinned for the entire time that the unmanaged pointer is in use.

  3. A garbage collection cannot occur while the unmanaged pointer is in use.

  4. The garbage collector for the given implementation of the CLI is known to not move the referenced memory.

ANNOTATION

It is important to understand these rules concerning when you can safely convert managed pointers to unmanaged pointers, and when you cannot. The detailed rules above are complicated, but the model is simple. Managed pointers that represent value types on the stack can be converted to unmanaged pointers, as long as the data referenced cannot move. Otherwise, managed pointers cannot be converted.

Two points are captured in these rules. First, it is verifiable to convert a managed pointer to an unmanaged pointer only if you can prove that the data it references cannot move. Second, uses of managed pointers that are verifiable guarantee that the managed pointer always points to something that exists. For example, you cannot point a managed pointer to something on the stack and return it as a value, because the stack frame may have gone away. This is also why you cannot store a managed pointer in a static variable: the managed pointer might point to something on the stack when the stack frame has gone away.

1.2 Instruction Variant Table

In Partition III, section 3, an instruction variant table is presented for each instruction. It describes each variant of the instructions. The Format column of the table lists the opcode for the instruction variant, along with any arguments that follow the instruction in the instruction stream. For example:

Format	Assembly Format	Description
FE 0A <unsigned int16>	Ldarga argNum	Fetch the address of argument argNum.
0F <unsigned int8>	Ldarga.s argNum	Fetch the address of argument argNum, short form.

The first one or two hex numbers in the Format column show how this instruction is encoded (its "opcode"). So, the ldarga instruction is encoded as a byte holding FE, followed by another holding 0A. Italicized type names represent numbers that should follow in the instruction stream. In this example a 2-byte quantity that is to be treated as an unsigned integer directly follows the FE 0A opcode.

Any of the fixed-size built-in types (int8, unsigned int8, int16, unsigned int16, int32, unsigned int32, int64, unsigned in64, float32, and float64) can appear in format descriptions. These types define the number of bytes for the argument and how it should be interpreted (signed, unsigned, or floating point). In addition, a metadata token can appear, indicated as <T>. Tokens are encoded as 4-byte integers. All argument numbers are encoded least-significant-byte-at-smallest-address (a pattern commonly termed "little-endian"). Bytes for instruction opcodes and arguments are packed as tightly as possible (no alignment padding is done).

The Assembly Format column defines an assembly code mnemonic for each instruction variant. For those instructions that have instruction stream arguments, this column also assigns names to each of the arguments to the instruction. For each instruction argument, there is a name in the assembly format. These names are used later in the instruction description.

1.2.1 Opcode Encodings

CIL opcodes are 1 or more bytes long; they may be followed by zero or more operand bytes. All opcodes whose first byte lies in the range 0x00 through 0xEF, or 0xFC through 0xFF, are reserved for standardization. Opcodes whose first byte lies in the range 0xF0 through 0xFB, inclusive, are available for experimental purposes. The use of experimental opcodes in any method renders the method invalid and hence unverifiable.

ANNOTATION

The opcode encodings in this section are important if you are implementing a VES or writing a compiler. Some analysis tools may also require this information.

The currently defined encodings are specified in Table 6-1, Opcode Encodings.

Table 6-1. Opcode Encodings

0x00	nop	0x08	ldloc.2
0x01	break	0x09	ldloc.3
0x02	ldarg.0	0x0a	stloc.0
0x03	ldarg.1	0x0b	stloc.1
0x04	ldarg.2	0x0c	stloc.2
0x05	ldarg.3	0x0d	stloc.3
0x06	ldloc.0	0x0e	ldarg.s
0x07	ldloc.1	0x0f	ldarga.s
0x10	starg.s	0x28	call
0x11	ldloc.s	0x29	calli
0x12	ldloca.s	0x2a	ret
0x13	stloc.s	0x2b	br.s
0x14	ldnull	0x2c	brfalse.s
0x15	ldc.i4.m1	0x2d	brtrue.s
0x16	ldc.i4.0	0x2e	beq.s
0x17	ldc.i4.1	0x2f	bge.s
0x18	ldc.i4.2	0x30	bgt.s
0x19	ldc.i4.3	0x31	ble.s
0x1a	ldc.i4.4	0x32	blt.s
0x1b	ldc.i4.5	0x33	bne.un.s
0x1c	ldc.i4.6	0x34	bge.un.s
0x1d	ldc.i4.7	0x35	bgt.un.s
0x1e	ldc.i4.8	0x36	ble.un.s
0x1f	ldc.i4.s	0x37	blt.un.s
0x20	ldc.i4	0x38	br
0x21	ldc.i8	0x39	brfalse
0x22	ldc.r4	0x3a	brtrue
0x23	ldc.r8	0x3b	beq
0x25	dup	0x3c	bge
0x26	pop	0x3d	bgt
0x27	jmp	0x3e	ble
0x3f	blt	0x56	stind.r4
0x40	bne.un	0x57	stind.r8
0x41	bge.un	0x58	add
0x42	bgt.un	0x59	sub
0x43	ble.un	0x5a	mul
0x44	blt.un	0x5b	div
0x45	switch	0x5c	div.un
0x46	ldind.i1	0x5d	rem
0x47	ldind.u1	0x5e	rem.un
0x48	ldind.i2	0x5f	and
0x49	ldind.u2	0x60	or
0x4a	ldind.i4	0x61	xor
0x4b	ldind.u4	0x62	shl
0x4c	ldind.i8	0x63	shr
0x4d	ldind.i	0x64	shr.un
0x4e	ldind.r4	0x65	neg
0x4f	ldind.r8	0x66	not
0x50	ldind.ref	0x67	conv.i1
0x51	stind.ref	0x68	conv.i2
0x52	stind.i1	0x69	conv.i4
0x53	stind.i2	0x6a	conv.i8
0x54	stind.i4	0x6b	conv.r4
0x55	stind.i8	0x6c	conv.r8
0x6d	conv.u4	0x85	conv.ovf.i8.un
0x6e	conv.u8	0x86	conv.ovf.u1.un
0x6f	callvirt	0x87	conv.ovf.u2.un
0x70	cpobj	0x88	conv.ovf.u4.un
0x71	ldobj	0x89	conv.ovf.u8.un
0x72	ldstr	0x8a	conv.ovf.i.un
0x73	newobj	0x8b	conv.ovf.u.un
0x74	castclass	0x8c	box
0x75	isinst	0x8d	newarr
0x76	conv.r.un	0x8e	ldlen
0x79	unbox	0x8f	ldelema
0x7a	throw	0x90	ldelem.i1
0x7b	ldfld	0x91	ldelem.u1
0x7c	ldflda	0x92	ldelem.i2
0x7d	stfld	0x93	ldelem.u2
0x7e	ldsfld	0x94	ldelem.i4
0x7f	ldsflda	0x95	ldelem.u4
0x80	stsfld	0x96	ldelem.i8
0x81	stobj	0x97	ldelem.i
0x82	conv.ovf.i1.un	0x98	ldelem.r4
0x83	conv.ovf.i2.un	0x99	ldelem.r8
0x84	conv.ovf.i4.un	0x9a	ldelem.ref
0x9b	stelem.i	0xd4	conv.ovf.i
0x9c	stelem.i1	0xd5	conv.ovf.u
0x9d	stelem.i2	0xd6	add.ovf
0x9e	stelem.i4	0xd7	add.ovf.un
0x9f	stelem.i8	0xd8	mul.ovf
0xa0	stelem.r4	0xd9	mul.ovf.un
0xa1	stelem.r8	0xda	sub.ovf
0xa2	stelem.ref	0xdb	sub.ovf.un
0xb3	conv.ovf.i1	0xdc	endfinally
0xb4	conv.ovf.u1	0xdd	leave
0xb5	conv.ovf.i2	0xde	leave.s
0xb6	conv.ovf.u2	0xdf	stind.i
0xb7	conv.ovf.i4	0xe0	conv.u
0xb8	conv.ovf.u4	0xfe 0x00	arglist
0xb9	conv.ovf.i8	0xfe 0x01	ceq
0xba	conv.ovf.u8	0xfe 0x02	cgt
0xc2	refanyval	0xfe 0x03	cgt.un
0xc3	ckfinite	0xfe 0x04	clt
0xc6	mkrefany	0xfe 0x05	clt.un
0xd0	ldtoken	0xfe 0x06	ldftn
0xd1	conv.u2	0xfe 0x07	ldvirtftn
0xd2	conv.u1	0xfe 0x09	ldarg
0xd3	conv.i	0xfe 0x0a	ldarga
0xfe 0x0b	starg	0xfe 0x14	tail.
0xfe 0x0c	ldloc	0xfe 0x15	initobj
0xfe 0x0d	ldloca	0xfe 0x17	cpblk
0xfe 0x0e	stloc	0xfe 0x18	initblk
0xfe 0x0f	localloc	0xfe 0x1a	rethrow
0xfe 0x11	endfilter	0xfe 0x1c	sizeof
0xfe 0x12	unaligned.	0xfe 0x1d	refanytype
0xfe 0x13	volatile.

1.3 Stack Transition Diagram

The stack transition diagram displays the state of the evaluation stack before and after the instruction is executed. Below is a typical stack transition diagram.

…, value1, value2 …, result

This diagram indicates that the stack must have at least two elements on it, and in the definition the topmost value ("top of stack" or "most recently pushed") will be called value2 and the value underneath (pushed prior to value2) will be called value1. (In diagrams like this, the stack grows to the right, along the page.) The instruction removes these values from the stack and replaces them by another value, called result in the description.

1.4 English Description

The English description describes any details about the instructions that are not immediately apparent once the format and stack transition have been described.

1.5 Operand Type Table

Many CIL operations take numeric operands on the stack. These operations fall into several categories, depending on how they deal with the types of the operands. The following tables summarize the valid kinds of operand types and the type of the result. Notice that the types referred to here are the types as tracked by the CLI rather than the more detailed types used by tools such as CIL verification. The types tracked by the CLI are: int32, int64, native int, F, O, and &.

ANNOTATION

There is a great deal of data in these tables that may be easy to overlook, and in some cases to misunderstand. Each table is important and describes the effect on the numeric types of a set of CIL instructions. The CIL instruction descriptions throughout Partition III refer back to these tables.

Compiler writers need to look at these tables in light of what their language requires. For example, if a language allows adding a 32- and a 64-bit value, then the compiler must decide whether the 32-bit value must be sign-extended. Depending on the decision, the compiler must emit either the sign-extension or non-sign-extension instruction. It is the compiler's job to match its type system to the VES's type system.

Portable CIL programs cannot depend on invalid operations. Any compiler that emits invalid operations is relying on implementation details of a particular VES, which is inadvisable. The standard does not specify what happens when such operations are executed. Among the possibilities are that the VES may terminate operation of the program, proceed with an incorrect result, or generate a runtime exception.

1.5.1 Binary Numeric Operations

A op B (used for add, div, mul, rem, and sub). Table 6-2, Binary Numeric Operations, shows the result type, for each possible combination of operand types. Boxes holding simply a result type apply to all five instructions. Boxes marked indicate an invalid CIL instruction. Shaded boxes indicate a CIL instruction that is not verifiable. Boxes with a list of instructions are valid only for those instructions.

Table 6-2. Binary Numeric Operations

		B's Type
		int32	int64	native int	F	&	O
A's Type	int32	int32		native int		& (add)
	int64		int64
	native int	native int		native int		& (add)
	F				F
	&	& (add, sub)		& (add, sub)		native int (sub)
	O

ANNOTATION

For all VES types except objects, you are allowed arithmetic operations on two of the same numeric type. In most cases, the result is the same type. But for pointers, subtracting two pointers results in an integer, which is the distance between them. Pointer arithmetic is allowed, and involves adding an integer to, or subtracting an integer from a pointer. For example, if you have a pointer to a field in an array, you can add a known integer to get to the next array, or subtract to get to the previous array. If you know the distance between two fields within an object, it is possible to add or subtract a value to get there, but these operations are always unverifiable.

1.5.2 Unary Numeric Operations

Used for the neg instruction. Boxes marked [in Table 6-3, Unary Numeric Operations,] indicate an invalid CIL instruction. All valid uses of this instruction are verifiable.

Table 6-3. Unary Numeric Operations

Operand Type	int32	int64	native int	F	&	O
Result Type	int32	int64	native int	F

1.5.3 Binary Comparison or Branch Operations

These return a Boolean value or branch based on the top two values on the stack. Used for beq, beq.s, bge, bge.s, bge.un, bge.un.s, bgt, bgt.s, bgt.un, bgt.un.s, ble, ble.s, ble.un, ble.un.s, blt, blt.s, blt.un, blt.un.s, bne.un, bne.un.s, ceq, cgt, cgt.un, clt, clt.un. Boxes marked [in Table 6-4, Binary Comparison or Branch Operations,] indicate that all instructions are valid for that combination of operand types. Boxes marked indicate invalid CIL sequences. Shaded boxes indicate a CIL instruction that is not verifiable. Boxes with a list of instructions are valid only for those instructions.

ANNOTATION

It is always possible to compare two values of the same type. The only possible comparison for objects is to branch on whether they are the same or not the same, and compare for equality. In comparisons where the types are not the same, in most cases the standard does not specify a result. Although you can compare 32-bit integers and native integers, because native integers are assumed to be at least 32 bits, if the compiler knows that native integers are 64 bits, it can also ensure that 64-bit/native integer comparisons are valid. If you know that native integers are 64 bits, it is up to the compiler to make the comparison valid. In comparing a pointer to a native integer, the only valid operations are the same as when comparing two objects (branch on equal or not equal, compare for equality).

Table 6-4. Binary Comparison or Branch Operations

	int32	int64	native int	F	&	O
int32
int64
native int					beq[.s], bne.un[.s], ceq
F
&			beq[.s], bne.un[.s], ceq		[1]
O						beq[.s], bne.un[.s], ceq[2]
Note: If the two operands are not pointers into the same array, then the result is simply the distance apart in the garbage-collected heap of two unrelated data items. This distance apart will almost certainly change at the next garbage collection. Essentially, the result cannot be used to compute anything useful.

^[1] Except for beq, bne.un (or short versions), or ceq, these combinations make sense if both operands are known to be pointers to elements of the same array. However, there is no security issue for a CLI that does not check this constraint.

^[2] cgt.un is allowed and verifiable on ObjectRefs (O). This is commonly used when comparing an ObjectRef with null (there is no "compare-not-equal" instruction, which would otherwise be a more obvious solution).

1.5.4 Integer Operations

These operate only on integer types. Used for and, div.un, not, or, rem.un, xor. The div.un and rem.un instructions treat their arguments as unsigned integers and produce the bit pattern corresponding to the unsigned result. As described in the CLI specification, however, the CLI makes no distinction between signed and unsigned integers on the stack. The not instruction is unary and returns the same type as the input. The shl and shr instructions return the same type as their first operand, and their second operand must be of type native unsigned int. Boxes marked [in Table 6-5, Integer Operations,] indicate invalid CIL sequences. All other boxes denote verifiable combinations of operands.

Table 6-5. Integer Operations

	int32	int64	native int	F	&	O
int32	int32		native int
int64		int64
native int	native int		native int
F
&
O

1.5.5 Shift Operations

Table 6-6, Shift Operations, lists the legal combinations of operands and results for the shift instructions: shl, shr, shr_un. Boxes marked indicate invalid CIL sequences. All other boxes denote verifiable combinations of operand. If the "Shift-By" operand is larger than the width of the "To-Be-Shifted" operand, then the results are implementation-defined (e.g., shift an int32 integer left by 37 bits).

Table 6-6. Shift Operations

		Shift-By
		int32	int64	native int	F	&	O
To Be Shifted	int32	int32		int32
	int64	int64		int64
	native int	native int		native int
	F
	&
	O

1.5.6 Overflow Arithmetic Operations

These operations generate an exception if the result cannot be represented in the target data type. Used for add.ovf, add.ovf.un, mul.ovf, mul.ovf.un, sub.ovf, sub.ovf.un. The shaded uses [in Table 6-7, Overflow Arithmetic Operations,] are not verifiable, while boxes marked indicate invalid CIL sequences

Table 6-7. Overflow Arithmetic Operations

	int32	int64	native int	F	&	O
int32	int32		native int		& add.ovf.un
int64		int64
native int	native int		native int		& add.ovf.un
F
&	& add.ovf.un, sub.ovf.un		& add.ovf.un, sub.ovf.un		native int sub.ovf.un
O

ANNOTATION

Some languages require that an overflow in an operation throws an exception, and some languages ignore it. The CLI standard supports both approaches, but the rules, as stated in this section, are different from the other operations.

1.5.7 Conversion Operations

These operations convert the top item on the evaluation stack from one numeric type to another. The result type is guaranteed to be representable as the data type specified as part of the operation (i.e., the conv.u2 instruction returns a value that can be stored in an unsigned int16). The stack, however, can only store values that are a minimum of 4 bytes wide. Used for the conv.<to type>, conv.ovf.<to type>, and conv.ovf.<to type>.un instructions. The shaded uses [in Table 6-8, Conversion Operations,] are not verifiable, while boxes marked indicate invalid CIL sequences.

Table 6-8. Conversion Operations

		Input (from Evaluation Stack)
		int32	int64	native int	F	&	O
Convert To	int8 unsigned int8 int16 unsigned int16	Truncate[1]	Truncate[1]	Truncate[1]	Truncate to zero[2]
	int32 unsigned int32	Nop	Truncate[1]	Truncate[1]	Truncate to zero[2]
	int64	Sign-extend	Nop	Sign-extend	Truncate to zero[2]	Stop GC tracking[4]	Stop GC tracking[4]
	unsigned int64	Zero-extend	Nop	Zero-extend	Truncate to zero[2]	Stop GC tracking[4]	Stop GC tracking[4]
	native int	Sign-extend	Truncate[1]	Nop	Truncate to zero[2]	Stop GC tracking[4]	Stop GC tracking[4]
	native unsigned int	Zero-extend	Truncate[1]	Nop	Truncate to zero[2]	Stop GC tracking[4]	Stop GC tracking[4]
	All Float Types	To Float	To Float	To Float	Change precision[3]

^[1] "Truncate" means that the number is truncated to the desired size; i.e., the most significant bytes of the input value are simply ignored. If the result is narrower than the minimum stack width of 4 bytes, then this result is zero-extended (if the target type is unsigned) or sign-extended (if the target type is signed). Thus, converting the value 0x1234 ABCD from the evaluation stack to an 8-bit datum yields the result 0xCD; if the target type were int8, this would be sign-extended to give 0xFFFF FFCD; if, instead, the target type were unsigned int8, this would be zero-extended to give 0x0000 00CD.

^[2] "Truncate to zero" means that the floating point number will be converted to an integer by truncation toward zero. Thus, 1.1 is converted to 1, and 1.1 is converted to 1.

^[4] "Stop GC tracking" means that, following the conversion, the item's value will not be reported to subsequent garbage-collection operations (and therefore will not be updated by such operations).

^[3] Converts from the current precision available on the evaluation stack to the precision specified by the instruction. If the stack has more precision than the output size, the conversion is performed using the IEC 60559:1989 "round to nearest" mode to compute the low-order bit of the result.

ANNOTATION

Table 6-8 is very important because it shows the implicit conversions that the VES does and does not do. This table encapsulates information that is most often misunderstood. In conversion operations, it is what you are converting to that determines how you treat the input parameter. For example, suppose there is a 32-bit quantity that you want to convert to a 32-bit signed quantity. What happens if it already has a sign? If it was negative on the stack, the conversion should fail if you are checking for overflow because a negative number will not go into the unsigned representation. Some conversions cause the VES to truncate the value; others cause the VES to extend.

1.6 Implicit Argument Coercion

While the CLI operates only on six types (int32, native int, int64, F, O, and &), the metadata supplies a much richer model for parameters of methods. When about to call a method, the VES performs implicit type conversions, detailed in Table 6-9, Signature Matching. (Conceptually, it inserts the appropriate conv.* instruction into the CIL stream, which may result in an information loss through truncation or rounding.) This implicit conversion occurs for boxes marked . Shaded boxes are not verifiable. Boxes marked indicate invalid CIL sequences. (A compiler is of course free to emit explicit conv.* or conv.*.ovf instructions to achieve any desired effect.)

Further notes concerning this table:

• On a 32-bit machine, passing a native int argument to an unsigned int32 parameter involves no conversion. On a 64-bit machine, it is implicitly converted.

• "Start GC tracking" means that, following the implicit conversion, the item's value will be reported to any subsequent garbage-collection operations, and perhaps changed as a result of the item pointed-to being relocated in the heap.

ANNOTATION

Table 6-9 is another very important table. It details the implicit type conversions that the VES will do when a method is to be called, referred to as signature matching. Compilers need to know which conversions happen automatically. Where a CIL sequence is invalid, the compiler must issue the conv.* or conv.*.ovf instruction to turn it into a valid sequence.

For example, the compiler is responsible for what happens if a floating point value is passed to someone expecting an 8-bit integer. On the other hand, passing a full-sized integer to someone expecting an 8-bit integer triggers an implicit conversion by the VES. In the VES, it is the full 32-bit integer that is passed. If the compiler wanted to make a check, it could truncate the value to 8 bits to make sure it would fit into 8 bits, but that particular operation is not built into the VES.

Table 6-9. Signature Matching

		Stack Parameter
		int32	native int	int64	F	&	O
Type in Signature	int8
	unsigned int8, bool
	int16
	unsigned int16, char
	int32
	unsigned int32
	int64
	unsigned int64
	native int	Sign-0extend
	native unsigned int	Zero-extend	Zero-extend
	float32				Note[4]
	float64				Note[4]
	Class
	Value Type (Note[2])	Note[1]	Note[1]	Note[1]	Note[1]
	By-Ref ( & )		Start GC tracking
	Ref Any (Note[3])

^[4] The CLI is permitted to pass floating point arguments using its internal F type (see Partition III, section 1.1.1). CIL generators may, of course, include an explicit conv.r4, conv.r4.ovf, or similar instruction.

^[2] The CLI's stack can contain a value type. These may only be passed if the particular value type on the stack exactly matches the class required by the corresponding parameter.

^[1] Passing a built-in type to a parameter that is required to be a value type is not allowed.

^[3] There are special instructions to construct and pass a Ref Any.

The VES does type conversions with the equivalent of the convert instruction, but not the convert with overflow. If a compiler needs overflow checking, it must explicitly insert a conv.*.ovf instruction. The implicit conversions by the VES detailed in this table were standardized to save the compiler from inserting numerous convert operations that are mostly harmless and often used in any case.

As it says in this section, a value type may be on the stack, and as it says in note 2 of Table 6-9, it may be passed only if the value type on the stack exactly matches the class required by the corresponding parameter. There is no conversion of value types.

There is one source of confusion: the class library has value types that correspond to certain built-in numeric types. For example, a value type called System.Int32 corresponds to the built-in type int32. Although a programmer may specify the class library's value class, the compiler is responsible for ensuring that it is the built-in int32 that goes into the actual signature in the metadata.

1.7 Restrictions on CIL Code Sequences

As well as detailed restrictions on CIL code sequences to ensure:

• Valid CIL

• Verifiable CIL

there are a few further restrictions, imposed to make it easier to construct a simple CIL-to-native-code compiler. This section specifies the general restrictions that apply in addition to those listed for individual instructions.

ANNOTATION

This section and its subsections are important to those interested in implementing or understanding a VES, compiler designers, and those implementing a JIT compiler. From the point of view of the VES, of interest is mainly what it does not have to do there are some sequences of code the VES never has to handle. Some of the restrictions in this section were included to make it easier to write a VES. The restrictions that were included to make it easier to write a VES, in turn, place restrictions on source language compilers because there are some things they might like to generate but cannot because the VES is not required to handle them.

1.7.1 The Instruction Stream

The implementation of a method is provided by a contiguous block of CIL instructions, encoded as specified below. The address of the instruction block for a method, as well as its length, is specified in the file format (see Partition II, section 24.4, Common Intermediate Language Physical Layout). The first instruction is at the first byte (lowest address) of the instruction block.

Instructions are variable in size. The size of each instruction can be determined (decoded) from the content of the instruction bytes themselves. The size of and ordering of the bytes within an instruction are specified by each instruction definition. Instructions follow each other without padding in a stream of bytes that is both alignment- and byte-order-insensitive.

Each instruction occupies an exact number of bytes, and until the end of the instruction block, the next instruction begins immediately at the next byte. It is invalid for the instruction block (as specified by the block's length) to end without forming a complete last instruction.

Instruction prefixes extend the length of an instruction without introducing a new instruction; an instruction having one or more prefixes introduces only one instruction that begins at the first byte of the first instruction prefix.

NOTE

Until the end of the instruction block, the instruction following any control transfer instruction is decoded as an instruction and thus participates in locating subsequent instructions even if it is not the target of a branch. Only instructions may appear in the instruction stream, even if unreachable. There are no address-relative data addressing modes, and raw data cannot be directly embedded within the instruction stream. Certain instructions allow embedding of immediate data as part of the instruction; however, that differs from allowing raw data embedded directly in the instruction stream. Unreachable code may appear as the result of machine-generated code and is allowed, but it must always be in the form of properly formed instruction sequences.

The instruction stream can be translated and the associated instruction block discarded prior to execution of the translation. Thus, even instructions that capture and manipulate code addresses, such as call, ret, etc. can be virtualized to operate on translated addresses instead of addresses in the CIL instruction stream.

1.7.2 Valid Branch Targets

The set of addresses composed of the first byte of each instruction identified in the instruction stream defines the only valid instruction targets. Instruction targets include branch targets as specified in branch instructions, targets specified in exception tables such as protected ranges (see Partition I, section 12.4.2 and Partition II, section 18), filters, and handler targets.

Branch instructions specify branch targets as either a 1-byte or a 4-byte signed relative offset; the size of the offset is differentiated by the opcode of the instruction. The offset is defined as being relative to the byte following the branch instruction. (Note: Thus, an offset value of zero targets the immediately following instruction.)

The value of a 1-byte offset is computed by interpreting that byte as a signed 8-bit integer. The value of a 4-byte offset can be computed by concatenating the bytes into a signed integer in the following manner: the byte of lowest address forms the least significant byte, and the byte with the highest address forms the most significant byte of the integer. (Note: This representation is often called "a signed integer in little-endian byte-order.")

ANNOTATION

The major point of this section is that it is invalid to jump into the middle of an instruction. This would be of concern in instructions that take more than 1 byte.

1.7.3 Exception Ranges

Exception tables describe ranges of instructions that are protected by catch, fault, or finally handlers (see Partition I, section 12.4.2 and Partition II, section 18). The starting address of a protected block, filter clause, or handler shall be a valid branch target as specified in Partition III, section 1.7.2. It is invalid for a protected block, filter clause, or handler to end without forming a complete last instruction.

ANNOTATION

The focus of this section is that multi-byte instructions cannot be split across exception boundaries.

1.7.4 Must Provide Maxstack

Every method specifies a maximum number of items that can be pushed onto the CIL evaluation [stack]. The value is stored in the IMAGE_COR_ILMETHOD structure that precedes the CIL body of each method. A method that specifies a maximum number of items less than the amount required by a static analysis of the method (using a traditional control flow graph without analysis of the data) is invalid (hence also unverifiable) and need not be supported by a conforming implementation of the CLI.

NOTE

Maxstack is related to analysis of the program, not to the size of the stack at runtime. It does not specify the maximum size in bytes of a stack frame, but rather the number of items that must be tracked by an analysis tool.

RATIONALE

By analyzing the CIL stream for any method, it is easy to determine how many items will be pushed onto the CIL evaluation stack. However, specifying that maximum number ahead of time helps a CIL-to-native-code compiler (especially a simple one that does only a single pass through the CIL stream) in allocating internal data structures that model the stack and/or verification algorithm.

ANNOTATION

Maxstack is the maximum number of values pushed onto the evaluation stack within the method. It should not be confused with the space allocated at runtime. Maxstack is provided for JIT compilers and verifiers because they need to allocate space to simulate the method evaluation stack. Language compilers are required to compute this required space so that interpreters and JIT compilers can be written without having to scan the method before simulating or executing it.

1.7.5 Backward Branch Constraints

It must be possible, with a single forward-pass through the CIL instruction stream for any method, to infer the exact state of the evaluation stack at every instruction (where by "state" we mean the number and type of each item on the evaluation stack).

In particular, if that single-pass analysis arrives at an instruction, call it location X, that immediately follows an unconditional branch, and where X is not the target of an earlier branch instruction, then the state of the evaluation stack at X, clearly, cannot be derived from existing information. In this case, the CLI demands that the evaluation stack at X be empty.

Following on from this rule, it would clearly be invalid CIL if a later branch instruction to X were to have a non-empty evaluation stack

RATIONALE

This constraint ensures that CIL code can be processed by a simple CIL-to-native-code compiler. It ensures that the state of the evaluation stack at the beginning of each CIL can be inferred from a single, forward-pass analysis of the instruction stream.

Note: The stack state at location X in the above can be inferred by various means: from a previous forward branch to X, because X marks the start of an exception handler, etc.

See the following sections for further information:

• Exceptions: Partition I, section 12.4.2

• Verification conditions for branch instructions: Partition III, section 3

• The tail. prefix: Partition III, section 2.1

ANNOTATION

The backward branch constraint improves the efficiency of the JIT compiler and makes it easier to implement. For the verifier, it is necessary to figure out the data types that have to be on the stack, in a single pass of the code from front to back. This restriction prevents loop rotations that make the early code appear to have something on the stack. Loop rotations are done in native code, and they make sense in some circumstances, but much less in CIL. If that optimization is needed, the JIT could implement it in native code source coming in must not.

1.7.6 Branch Verification Constraints

The target of all branch instructions must be a valid branch target (see Partition III, section 1.7.2) within the method holding that branch instruction.

1.8 Verifiability

Memory safety is a property that ensures programs running in the same address space are correctly isolated from one another (see Partition I, section 8.8). Thus, it is desirable to test whether programs are memory-safe prior to running them. Unfortunately, it is provably impossible to do this with 100% accuracy. Instead, the CLI can test a stronger restriction, called verifiability. Every program that is verified is memory-safe, but some programs that are not verifiable are still memory-safe.

It is perfectly acceptable to generate CIL code that is not verifiable, but that is known to be memory-safe by the compiler writer. Thus, conforming CIL may not be verifiable, even though the producing compiler may know that it is memory-safe. Several important uses of CIL instructions are not verifiable, such as the pointer arithmetic versions of add that are required for the faithful and efficient compilation of C programs. For non-verifiable code, memory safety is the responsibility of the application programmer.

CIL contains a verifiable subset. The verifiability description [for each instruction] gives details of the conditions under which use of an instruction falls within the verifiable subset of CIL. Verification tracks the types of values in much finer detail than is required for the basic functioning of the CLI, because it is checking that a CIL code sequence respects not only the basic rules of the CLI with respect to the safety of garbage collection, but also the typing rules of the CTS. This helps to guarantee the sound operation of the entire CLI.

The verifiability section of each operation description specifies requirements both for correct CIL generation and for verification. Correct CIL generation always requires guaranteeing that the top items on the stack correspond to the types shown in the stack transition diagram. The verifiability section specifies only requirements for correct CIL generation that are not captured in that diagram. Verification tests both the requirements for correct CIL generation and the specific verification conditions that are described with the instruction. The operation of CIL sequences that do not meet the CIL correctness requirements is unspecified. The operation of CIL sequences that meet the correctness requirements but are not verifiable may violate type safety and hence may violate security or memory access constraints.

1.8.1 Flow Control Restrictions for Verifiable CIL

This section specifies a verification algorithm that, combined with information on individual CIL instructions (see Partition III, section 3) and metadata validation (see Partition II), guarantees memory integrity.

The algorithm specified here creates a minimum level for all compliant implementations of the CLI in the sense that any program that is considered verifiable by this algorithm shall be considered verifiable and run correctly on all compliant implementations of the CLI.

The CLI provides a security permission that controls whether or not the CLI shall run programs that may violate memory safety. Any program that is verifiable according to this specification does not violate memory safety, and a conforming implementation of the CLI shall run such programs. The implementation may also run other programs, provided it is able to show they do not violate memory safety (typically because they use a verification algorithm that makes use of specific knowledge about the implementation).

NOTE

While a compliant implementation is required to accept and run any program this verification algorithm states is verifiable, there may be programs that are accepted as verifiable by a given implementation but that this verification algorithm will fail to consider verifiable. Such programs will run in the given implementation but need not be considered verifiable by other implementations.

For example, an implementation of the CLI may choose to correctly track full signatures on method pointers and permit programs to execute the calli instruction even though this is not permitted by the verification algorithm specified here.

Implementers of the CLI are urged to provide a means for testing whether programs generated on their implementation meet this portable verifiability standard. They are also urged to specify where their verification algorithms are more permissive than this standard.

ANNOTATION

Implementation-Specific (Microsoft): The various implementations of the CLI produced by Microsoft use slightly different verification algorithms. In all cases, however, the PEVerify program (part of the .NET SDK) implements the portable verification algorithm as specified in this standard. Programmers are urged to run PEVerify over all code before shipping it for possible use on other implementations of the CLI.

Only valid programs shall be verifiable. For ease of explanation, the verification algorithm described here assumes that the program is valid and does not explicitly call for tests of all validity conditions. Validity conditions are specified on a per-CIL instruction basis (see Partition III, section 3), and on the overall file format in Partition II, section 21.

1.8.1.1 Verification Algorithm

The verification algorithm shall attempt to associate a valid stack state with every CIL instruction. The stack state specifies the number of slots on the CIL stack at that point in the code and, for each slot, a required type that must be present in that slot. The initial stack state is empty (there are no items on the stack).

Verification assumes that the CLI zeros all memory other than the evaluation stack before it is made visible to programs. A conforming implementation of the CLI shall provide this observable behavior. Furthermore, verifiable methods shall have the "zero initialize" bit set, see Partition II, section 24.4.4. If this bit is not set, then a CLI may throw a Verification exception at any point where a local variable is accessed, and where the assembly containing that method has not been granted SecurityPermission.SkipVerification.

ANNOTATION

The "zero init flag" syntax in the assembler syntax is the .local init directive; and in the file format, it is the flag CorILMethod_InitLocals (see Partition II, section 24.4.4).

RATIONALE

This requirement strongly enhances program portability, and a well-known technique (definite-assignment analysis) allows a compiler from CIL to native code to minimize its performance impact. Note that a CLI may optionally choose to perform definite-assignment analysis in such a case, it may confirm that a method, even without the "zero initialize" bit set, may in fact be verifiable (and therefore not throw a Verification exception).

NOTE

Definite-assignment analysis can be used by the CLI to determine which locations are written before they are read. Such locations needn't be zeroed, since it isn't possible to observe the contents of the memory as it was provided by the EE.

Performance measurements on C++ implementations (which do not require definite-assignment analysis) indicate that adding this requirement has almost no impact, even in highly optimized code. Furthermore, customers incorrectly attribute bugs to the compiler when this zeroing is not performed, since such code often fails when small, unrelated changes are made to the program.

The verification algorithm shall simulate all possible control flow paths through the code and ensures that a legal stack state exists for every reachable CIL instruction. The verification algorithm does not take advantage of any data values during its simulation (e.g., it does not perform constant propagation), but uses only type assignments. Details of the type system used for verification and the algorithm used to merge stack states are provided in Partition III, section 1.8.1.3. The verification algorithm terminates as follows:

1. Successfully when all control paths have been simulated

2. Unsuccessfully when it is not possible to compute a valid stack state for a particular CIL instruction

3. Unsuccessfully when additional tests specified in this clause fail

There is a control flow path from every instruction to the subsequent instruction, with the exception of the unconditional branch instructions, throw, rethrow, and ret. Finally, there is a control flow path from each branch instruction (conditional or unconditional) to the branch target (targets, plural, for the switch instruction).

Verification simulates the operation of each CIL instruction to compute the new stack state, and any type mismatch between the specified conditions on the stack state (see Partition III, section 3) and the simulated stack state shall cause the verification algorithm to fail. (Note that verification simulates only the effect on the stack state; it does not perform the actual computation.) The algorithm shall also fail if there is an existing stack state at the next instruction address (for conditional branches or instructions within a try block there may be more than one such address) that cannot be merged with the stack state just computed. For rules of this merge operation, see Partition III, section 1.8.1.3.

ANNOTATION

In Partition III, section 1.8 and its subsections provide a detailed and accurate description of the verification standard. Verifying code according to the rules described here guarantees that all conforming implementations of the CLI will consider it to be verifiable, and the code to be memory-safe. Code that is intended to be portable, such as frameworks, should be verified with a verifier built according to this standard.

Many verifiers permit as verifiable some things that are not allowed according to this description. This does not mean the code is not safe these things are permitted usually to take advantage of features of the platform on which the code is expected to be run. There is no reason that one implementation cannot run as verifiable some things that are not considered verifiable in another implementation. It does mean, however, that if you are a compiler writer, you should be testing your code not by running it through your implementation's verifier, but through this standard verification test, using a tool such as Microsoft's PEVerify, which was designed according to these rules.

1.8.1.2 Verification Type System

The verification algorithm compresses types that are logically equivalent, since they cannot lead to memory safety violations. The types used by the verification algorithm are specified in Partition III, section 1.8.1.2.1; the type compatibility rules are specified in Partition III, section 1.8.1.2.2; and the rules for merging stack states are in Partition III, section 1.8.1.3.

1.8.1.2.1 Verification Types

The following table specifies the mapping of types used in the CLI and those used in verification. Notice that verification compresses the CLI types to a smaller set that maintains information about the size of those types in memory, but then compresses these again to represent the fact that the CLI stack expands 1-, 2-, and 4-byte built-in types into 4-byte types on the stack. Similarly, verification treats floating point numbers on the stack as 64-bit quantities regardless of the actual representation.

Arrays are objects, but with special compatibility rules.

There is a special encoding for null that represents an object known to be the null value, hence with indeterminate actual type.

In the following table, CLI Type is the type as it is described in metadata. The Verification Type is a corresponding type used for type compatibility rules in verification (see Partition III, section 1.8.1.2.2) when considering the types of local variables, incoming arguments, and formal parameters on methods being called. The column Verification Type (in Stack State) is used to simulate instructions that load data onto the stack, and shows the types that are actually maintained in the stack state information of the verification algorithm. The column Managed Pointer to Type shows the type tracked for managed pointers.

CLI Type	Verification Type	Verification Type (in Stack State)	Managed Pointer to Type
int8, unsigned int8, bool	int8	int32	& int8
int16, unsigned int16, char	int16	int32	& int16
int32, unsigned int32	int32	int32	& int32
int64, unsigned int64	int64	int64	& int64
native int, native unsigned int	native int	native int	& native int
float32	float32	float64	& float32
float64	float64	float64	& float64
Any value type	Same type	Same type	& Same type
Any object type	Same type	Same type	& Same type
Method pointer	Same type	Same type	Not valid

A method can be defined as returning a managed pointer, but calls upon such methods are not verifiable.

RATIONALE

Some uses of returning a managed pointer are perfectly verifiable (e.g., returning a reference to a field in an object); but some are not (e.g., returning a pointer to a local variable of the called method). Tracking this in the general case is a burden, and therefore not included in this standard.

1.8.1.2.2 Verification Type Compatibility

The following rules define type compatibility. We use S and T to denote verification types, and the notation "S := T" to indicate that the verification type T can be used wherever the verification type S can be used, while "S !:= T" indicates that T cannot be used where S is expected. These are the verification type compatibility rules. We use T[] to denote an array (of any rank) whose elements are of type T, and T& to denote a managed pointer to type T.

1. [:= is reflexive] for all verification types S, S := S

2. [:= is transitive] for all verification types S, T, and U; if S := T and T := U, then S := U.

3. S := T if S is the base class of T or an interface implemented by T, and T is not a value type.

4. S := T if S and T are both interfaces, and the implementation of T requires the implementation of S.

5. S := null if S is an object type or an interface.

6. S[] := T[] if S := T and the arrays are either both vectors (zero-based, rank one), or neither is a vector and both have the same rank.

7. If S and T are method pointers, then S := T if the signatures (return types, parameter types, calling convention, and any custom attributes or custom modifiers) are the same.

8. Otherwise S !:= T.

1.8.1.3 Merging Stack States

As the verification algorithm simulates all control flow paths, it shall merge the simulated stack state with any existing stack state at the next CIL instruction in the flow. If there is no existing stack state, the simulated stack state is stored for future use. Otherwise the merge shall be computed as follows and stored to replace the existing stack state for the CIL instruction. If the merge fails, the verification algorithm shall fail.

The merge shall be computed by comparing the number of slots in each stack state. If they differ, the merge shall fail. If they match, then the overall merge shall be computed by merging the states slot-by-slot as follows. Let T be the type from the slot on the newly computed state and S be the type from the corresponding slot on the previously stored state. The merged type, U, shall be computed as follows (recall that S := T is the compatibility function defined in Partition III, section 1.8.1.2.2):

1. If S := T, then U=S.

2. Otherwise if T := S, then U=T.

3. Otherwise, if S and T are both object types, then let V be the closest common supertype of S and T; then U=V.

4. Otherwise, the merge shall fail.

ANNOTATION

Implementation-Specific (Microsoft): The V1.0 release of the Microsoft CLI will merge interfaces by arbitrarily choosing the first common interface between the two verification types being merged.

ANNOTATION

For those already familiar with verification, this section may be the single most surprising piece of this algorithm, so it is important to read and understand it completely. This definition makes sense for a standard, but it prohibits a large class of perfectly good programs. Adjusting this rule produces rules that depend on the order in which the verifier does its analysis and requires some control flow analysis that not all verifiers can do. It would be inappropriate to standardize an analysis order for verifiers, so this rule, while limiting, ensures portable files. Some implementations of verifiers that have a specific order to their analysis weaken this rule to allow many more programs to be verifiable.

The issue here is the merging of the stack model at points where multiple flows of control converge. Consider the following C program:

 interface I { int M(); } class A implements I { .... }; class B implements I { .... }; static int Main() { A myA = new A();    B myB = new B();    boolean IsSunday = (System.DateTime.Today.DayOfWeek==System .DateTime.DayOf-       Week.Sunday);    return 3+((IsSunday ? myA : myB).M()); } 

The verifier would see a flow join where the stack has A on one branch and B on the other and might not be able to pick the correct common parent type. So the trade-off is performance versus assured verifiability.

The following is an approximation of the CIL code for Main():

 .class Test { .method static void Main()   { .entrypoint     .locals (class A myA, class B myB, bool IsSunday)     call int32 [System]DateTime::get_DayOfWeek()     ldc.i4.0             // Assuming Sunday is 0     stloc.2           // IsSunday     ldc.i4.3     ldloc.2     brfalse NotSunday     ldloc.0           // myA     brfalse Join NotSunday:     ldloc.1           // myB Join:  // Stack has A or B on it     callvirt int32 I::M() // Not verifiable     ret   } } 

1.8.1.4 Class and Object Initialization Rules

The VES ensures that all statics are initially zeroed (i.e., built-in types are 0 or false, object references are null), hence the verification algorithm does not test for definite assignment to statics.

An object constructor shall not return unless a constructor for the base class or a different construct for the object's class has been called on the newly constructed object. The verification algorithm shall treat the this pointer as uninitialized unless the base class constructor has been called. No operations can be performed on an uninitialized this except for storing into and loading from the object's fields.

NOTE

If the constructor generates an exception, the this pointer in the corresponding catch block is still uninitialized.

1.8.1.5 Delegate Constructors

The verification algorithm shall require that one of the following code sequences is used for constructing delegates; no other code sequence in verifiable code shall contain a newobj instruction for a delegate type. There shall be only one instance constructor method for a delegate (overloading is not allowed).

The verification algorithm shall fail if a branch target is within these instruction sequences (other than at the start of the sequence).

NOTE

See Partition II [section 7] for the signature of delegates and a validity requirement regarding the signature of the method used in the constructor and the signature of Invoke and other methods on the delegate class.

1.8.1.5.1 Delegating via Virtual Dispatch

The following CIL instruction sequence shall be used or the verification algorithm shall fail. The sequence begins with an object on the stack.

 dup ldvirtftn mthd; Method shall be on the class of the object,           ; or one of its parent classes, or an interface           ; implemented by the object newobj delegateclass::.ctor(object, native int) 

RATIONALE

The dup is required to ensure that it is precisely the same object stored in the delegate as was used to compute the virtual method. If another object of a subtype were used, the object and the method wouldn't match and could lead to memory violations.

1.8.1.5.2 Delegating via Instance Dispatch

The following CIL instruction sequence shall be used or the verification algorithm shall fail. The sequence begins with either null or an object on the stack.

 ldftn mthd; Method shall either be a static method or           ; a method on the class of the object on the stack or           ; one of the object's parent classes newobj delegateclass::.ctor(object, native int) 

1.9 Metadata Tokens

Many CIL instructions are followed by a "metadata token." This is a 4-byte value that specifies a row in a metadata table, or a starting byte offset in the Userstring heap. The most-significant byte of the token specifies the table or heap. For example, a value of 0x02 specifies the TypeDef table; a value of 0x70 specifies the Userstring heap. The value corresponds to the number assigned to that metadata table (see Partition II [section 21] for the full list of tables) or to 0x70 for the Userstring heap. The least-significant 3 bytes specify the target row within that metadata table, or starting byte offset within the Userstring heap. The rows within metadata tables are numbered one upward, while offsets in the heap are numbered zero upward. (So, for example, the metadata token with value 0x02000007 specifies row number 7 in the TypeDef table.)

1.10 Exceptions Thrown

A CIL instruction can throw a range of exceptions. The CLI can also throw the general-purpose exception called ExecutionEngineException. See Partition I, section 12.4.2.