MSILFileFormatSpec.docx

1、MSILFileFormatSpecCommon Language RuntimeFile Format SpecThis document defines the extensions, for the Common Language Runtime (CLR), to the Microsoft PE (Portable Executable) file format that development tools and compilers will generate, and that the CLR will load and execute. This spec encompasse

2、s a description of the following: header and tags; metadata; MSIL and native code structures; issues of reordering and fix-ups. Generally, all format issues are covered except the actual code sections. The reader is referred to the following additional related runtime specifications: ILInstrSet_cor_

3、Intermediate_Language and Metadata API_cor_COM_Metadata_Emit_Import_Interface_Specification for emitting the metadata portion of the CLR fileThis is preliminary documentation and subject to changeLast updated: 10 October 2000Table Of Contents1 Overview 41.1 Structure of the Runtime File Format 41.2

4、Producers and Consumers of the Runtime File Format 51.3 Requirements Addressed by the Runtime File Format Design 51.4 OS Interactions 72 Emitting A Valid CLR Image 82.1 File Headers 82.1.1 Signature 82.1.2 COFF Header 82.1.2.1 Machine Type 82.1.2.2 Characteristics 82.1.3 Optional Header 92.1.3.1 Opt

5、ional Header Standard Fields 92.1.3.2 Optional Header Windows NT-Specific Fields 102.1.3.2.1 SubSystem Settings 112.1.3.2.2 Stack Reserve Size 112.1.3.3 Optional Header Data Directories 122.1.4 Storing Runtime Data in Sections 132.1.5 Runtime Header 132.1.5.1 Runtime Header Definition 142.1.5.2 Runt

6、ime Flags 152.1.5.3 Entry Point Meta Data Token 152.1.5.4 VTable Fixup 162.1.5.5 Resources 172.1.5.6 Strong Name Signature 172.2 Section Headers 172.3 Modifications to Existing PE Data 172.3.1 Import Address Table (IAT) 182.3.2 Export Section (.edata) 182.3.3 Thread Local Storage Table 182.3.4 Reloc

7、ations 183 Intermediate Language 203.1 Local Variable Layout 203.2 File Format Structure Definitions 203.2.1 Method Body 203.2.1.1 Method Header Type Values 213.2.1.2 Tiny Format 213.2.1.3 Fat Format 213.2.1.4 IMAGE_COR_ILMETHOD 223.2.1.5 IMAGE_COR_ILMETHOD_TINY 223.2.1.6 IMAGE_COR_ILMETHOD_FAT 223.

8、2.1.6.1 Flags for Method Headers 233.2.2 Section Data 233.2.3 IMAGE_COR_ILMETHOD_SECT_EH 243.2.3.1 IMAGE_COR_ILMETHOD_SECT_EH_SMALL 243.2.3.2 CorExceptionFlag Values 243.2.3.3 IMAGE_COR_ILMETHOD_SECT_EH_CLAUSE_SMALL 253.2.3.4 IMAGE_COR_ILMETHOD_SECT_EH_FAT 253.2.4 IMAGE_COR_ILMETHOD_SECT_EH_CLAUSE_F

9、AT 264 Code Transitions 274.1 Call Transitions 274.1.1 Transition Types 27Effects on Like Pieces of Code 28Affects on IL Code 28Affects on Native Code 284.2 Runtime Header Support for Transitions 284.2.1 VTableFixups 284.2.2 Export Address Table Fix-ups 295 Entry Points 315.1 Runtime APIs 315.1.1 _C

10、orExeMain 315.1.2 _CorDllMain 315.1.3 Entry Points for Windows CE 315.2 Shut Down Requirements 315.3 Entry Point Stubs 315.3.1 Runtime Aware OS Loader 315.3.2 Non Runtime Aware OS Loader 325.3.3 Sample x86 Stubs 321 OverviewThis document specifies a file format for Common Language Runtime (CLR) comp

11、onents that is based on, and is a strict extension of, the current Microsoft Windows Portable Executable (PE) and Common Object File Format (COFF). This extended PE/COFF format enables the Windows operating system to recognize runtime images, accommodates code emitted as runtime Microsoft intermedia

12、te language (MSIL) or native code, and accommodates runtime metadata as an integral part of the emitted code. This section provides a brief overview of and motivation for the design approach, including a summary of requirements and constraints. Subsequent sections present the technical specification

13、s as a delta from the current Windows PE/COFF file format, in sufficient detail that a tool or compiler can use the specifications to emit valid runtime images. The entire document assumes familiarity with the current PE/COFF structure and terminology. For more information, refer to the “Microsoft P

14、ortable Executable and Common Object File Format Specification”Structure of the Runtime File FormatThe figure below provides a high-level view of the CLR file format. All runtime images contain the following: Standard PE/COFF headers, with specific guidelines on how field values should be set in a r

15、untime file A runtime header that contains all of the runtime specific data entries. Currently, the runtime header is read-only and may be placed in any read-only section Any of the data one currently finds in a valid PE/COFF image, including imports/exports, data, and code. This spec calls out spec

16、ific areas where we use this data in the runtime.PE / COFF HeadersCLR HeaderCLR Data : metadata, IL method bodies, fix-upsNative Image Sections : .rdata, .rsrc, .data, .text, .The image is a full PE/COFF file image. The normal PE/COFF headers apply. The runtime header is found using directory entry

17、IMAGE_DIRECTORY_COR_DESCRIPTOR in the PE header. The runtime header in turn contains the address and locations of the runtime data in the rest of the image. Note that the runtime data can be merged into other areas of the PE format with the other data based on the attributes of the sections (such as

18、 read only versus execute, etc.). While the bulk of the file format is generated by tools directly, the metadata portion is emitted through an API that abstracts the tools from the underlying data structures. This is in part because the data structures are many and complex, having been tuned for per

19、formance and size, and because we want to be able to do additional tuning of the structures without impacting the tools that are emitting them. And, it is in part because the runtime metadata engine even today supports a number of different formats exposed in a uniform way through the same API. For

20、example, for COM Interop, a consumer of runtime metadata can import a typelib as though it were a perfectly valid runtime metadata file. Refer to the Metadata Interfaces_cor_COM_Metadata_Emit_Import_Interface_Specification spec for details on emitting and consuming the metadata portion of a runtime

21、image.Producers and Consumers of the Runtime File FormatDevelopment tools and compilers will emit runtime images that can be packaged and deployed across a range of runtime-enabled platforms. Development tools will range from RAD tools (including scripting languages) to high-level language compilers

22、. The first category of tools will compile and emit files in a single pass from the development environment. Scripting tools may not even have a need to persist the resulting file, but simply regenerate the code every time its executed. The second category of tools has an incremental approach, first

23、 emitting intermediate compilation units and then linking them together with resources into a loadable runtime image. The file format needs to accommodate not only what the runtime will require in order to load and execute these files, but it needs to make it reasonably straightforward for this rang

24、e of different tools with different internal data structures and compilation models to emit metadata and code efficiently (along with imports/exports, fix-ups, debugging information, etc.).Consumers of the runtime file format include the runtime itself as well as development tools and administrative

25、 tools. The runtime consumes metadata and IL in order to JIT-compile IL to native code. The loader consumes metadata to load classes and track managed data structures. Development tools will import metadata to enable references to runtime types and members. Administrative tools will consume metadata

26、 to browse classes and configure services.Requirements Addressed by the Runtime File Format DesignInitial exploration of alternative design approaches ranged from introducing an entirely new file format for the runtime that would co-exist side-by-side with todays PE file format, to ensuring that the

27、 runtime format was a natural extension of todays Windows PE file. In having chosen the latter approach, it may be instructive to review the requirements that drove the design and spec work.An Option of IL or Native CodeA developer who wants to target a range of runtime platforms may want to build a

28、 component or assembly of components once and compile to native when needed for a particular platform. Options for “when needed” range from deployment time to install time to execution time. In this scenario, the code is emitted as IL, plus the metadata that the runtime JIT compiler(s) use to compil

29、e the IL to native.A developer building a runtime component or application in his or her favorite language may have reason to compile code directly to native. For example, if the code is known to target only a specific platform, there may be no perceived benefit from going through an intermediate la

30、nguage. This does not mean that the developer need forego the benefits of the runtime managed services. In the design presented in this document, the target file format is todays PE file, either .exe or .dll. To be more specific, the runtime recognizes managed native code and unmanaged native code.

31、Both are compiled in any language to the native instruction set of a CPU. Unlike unmanaged native code, managed native code has additional metadata and coding conventions used by the runtime to enable garbage collection, exceptions and other runtime features. The current file format specification do

32、es not describe these metadata and file format extensions. Unmanaged native code is fully supported, emitted using all of the structures of todays PE/COFF.A Combination of IL and Native CodeThe runtime will accept a file containing a mixture of IL and native code. The runtime file format accommodates either one or both naturally in a single format, without requiring compilers to emit, and OS loaders to recognize, a range of different formats for specialized purposes.Self