What a ReadyToRun image is
A .NET assembly normally holds only IL, which the runtime compiles to machine code the first time each method runs. A ReadyToRun (R2R) assembly was compiled ahead of time by crossgen2: it is still a normal .NET assembly (all the metadata and the IL are kept, so it works anywhere the IL does) with machine code for one operating system and processor added, and tables that tell the runtime where each method’s code is. If the runtime accepts the image it uses the native code and skips the compile; otherwise it falls back to the IL.
The image is a PE file like any assembly. Its CLR header has ILONLY clear and IL_LIBRARY set (the flags are 0x4 in the images made for this page) and a ManagedNativeHeader directory that points at the ReadyToRun header. The COFF
machine field is the real processor XOR a number for the target operating system, so that a Windows loader does not try to run a Linux image: Windows 0, macOS 0x4644, Linux 0x7B79, FreeBSD 0xADC4, NetBSD 0x1993 (an osx-arm64 image says 0xEC20, which is 0xAA64 xor 0x4644). The explorer undoes it and says both.
The header
| Field | Size | Meaning |
|---|---|---|
| Signature | 4 | 0x00525452: the bytes 52 54 52 00, “RTR” and a zero |
| MajorVersion, MinorVersion | 2 + 2 | the format version: a different major version is a format older runtimes cannot read |
| Flags | 4 | PLATFORM_NEUTRAL_SOURCE 1, SKIP_TYPE_VALIDATION 2, PARTIAL 4, NONSHARED_PINVOKE_STUBS 8, EMBEDDED_MSIL 0x10, COMPONENT 0x20, MULTIMODULE_VERSION_BUBBLE 0x40, UNRELATED_R2R_CODE 0x80 |
| NumberOfSections | 4 | how many 12-byte section entries follow |
| sections | 12 each | a type number, the RVA and the size of the section’s data |
The images made for this page by crossgen2 10.0.15 have version 16.0, the flags 0x4B (PLATFORM_NEUTRAL_SOURCE, SKIP_TYPE_VALIDATION, NONSHARED_PINVOKE_STUBS, MULTIMODULE_VERSION_BUBBLE) and 14 sections (a header of 184 bytes); the explorer shows the version of the file it reads and does not say which runtime wrote which version.
The sections
| Type | Name | Holds |
|---|---|---|
| 100 | CompilerIdentifier | the compiler’s name and version as text |
| 101 | ImportSections | 20-byte records: the cells the runtime fills in (method entry points, type handles, string literals, helpers), their size, type, entry size, the RVA of their signatures and auxiliary data |
| 102 | RuntimeFunctions | one entry for each compiled function: x64 12 bytes (begin, end, unwind data), the other processors 8 bytes (begin, unwind data) |
| 103 | MethodDefEntryPoints | a native array indexed by MethodDef row number: for each compiled method, which runtime function is its code and whether fixups come first |
| 104 | ExceptionInfo | exception handling data of the compiled methods |
| 105 | DebugInfo | the native debug information of the methods |
| 106 | DelayLoadMethodCallThunks | thunks the method calls go through until they are resolved |
| 108 | AvailableTypes | a hash table of the type definitions the image knows |
| 109 | InstanceEntryPoints | a hash table of compiled instantiations of generic methods and methods of generic types |
| 110, 114, 119 | InliningInfo, InliningInfo2, CrossModuleInlineInfo | which methods were inlined into which |
| 111, 117 | ProfileDataInfo, PgoInstrumentationData | data of profile-guided optimisation |
| 112 | ManifestMetadata | an ECMA-335 metadata blob with the extra assembly references the code needs |
| 113 | AttributePresence | which attributes are present |
| 115, 116 | ComponentAssemblies, OwnerCompositeExecutable | composite images |
| 118 | ManifestAssemblyMvids | the MVIDs of the assemblies in the manifest metadata |
| 120 | HotColdMap | which runtime functions are cold parts of a method |
| 121, 122, 123 | MethodIsGenericMap, EnclosingTypeMap, TypeGenericInfoMap | maps of generic methods, nesting and type parameters |
The type numbers and the sizes of the records are the runtime’s (our reading of its documentation readytorun-format.md and header readytorun.h); the test below compares each section’s address and size with the node crossgen2 wrote there, which confirms the numbers that appear in the images made here, not those of sections that crossgen2 did not write.
Finding a method’s code
The MethodDefEntryPoints section is a native array, a compact structure of the runtime for arrays that are mostly empty. It starts with a number written as (count << 2) | size in the runtime’s variable-length encoding
(1 to 5 bytes, the length in the low bits of the first byte), where count is the number of MethodDef rows and size says whether the index below holds 1, 2 or 4-byte offsets. Then comes an index with one offset for each block of 16 rows, and for each block a small binary tree
written in the same encoding that leads to the entry of a row or says it has none. An entry is a number: shifted right by 1 it is the index of the method’s runtime function; if its low bit is set, bit 1 says that a list of fixups (things the runtime must resolve before the code can run) is stored before the entry, and the index is the number shifted right by 2.
The RuntimeFunctions table then gives the start of that function’s code (an RVA; on x64 also its end). A method that has exception funclets or a cold part has several consecutive runtime functions. The explorer lists each function with the method it belongs to. Compiled instantiations of generic methods are in the InstanceEntryPoints hash table, which the explorer does not decode: their runtime functions are listed as code near the method before them. On ARM64 the end of a function comes from its unwind data; on x86 and ARM it is taken as the start of the next function, which includes alignment padding.
The native code
The explorer disassembles each runtime function with its own decoders: x64 and x86 with the x86 decoder, ARM64 with the AArch64 decoder and ARM with the Thumb-2 decoder. The listing shows the code as it is: calls into the runtime go through the import cells, so their targets show as indirect calls and are not named. Unwind information, GC information and the debug maps are not decoded.
What the explorer shows
- The ReadyToRun header node with its fields and every section entry; a node for the data of each section (the runtime functions and the import sections row by row, the manifest metadata summarised); and a node for the native code of each runtime function, in the tree where the bytes are.
- The ReadyToRun image section (version, processor, operating system, flags, compiler), the sections table, the Native code listing and the table of compiled methods with their tokens, addresses and sizes.
Checked against crossgen2, which writes a map of the image it makes (every node with its address and size, and the compiled methods). Eight images of a test library were made for windows-x64, windows-x86, windows-arm64, linux-x64, linux-arm, linux-arm64, osx-x64 and osx-arm64: the header address and size, the 112 sections (14 in each) and the 408 compiled methods (51 of 53 in each: the other two are generic instantiations) all agree with the maps, and the machine and operating system are read back as built. The reader was also run over the 322 ReadyToRun images of the .NET 10 shared framework and runtime pack on this machine (209,547 compiled methods): no problems, runtime functions in address order, every method inside the image. The managed native header directory agrees with System.Reflection.PortableExecutable.
Not described
Known, not yet covered
- Reference: the hash tables of AvailableTypes and InstanceEntryPoints, the fixup lists, the exception, debug, inlining and profile sections, the unwind and GC information, composite images (several assemblies in one native image) and the platform-neutral and partial flags are not described; the sections show as bytes.
- Viewer: the native code is shown as machine instructions only; calls to the runtime and other methods are not named. The function ends on x86 and ARM include padding. Which runtime version wrote which format version is not stated.
Unknown
- Reference: the meaning of section numbers that crossgen2 did not write in the images made here (115, 116, 120 and others) rests on the runtime’s header file alone, and so do the names of the header flag bits: the images made here carry the four bits 1, 2, 8 and 0x40, and no second source confirms their names.
Links
Reference
- ReadyToRun format – the runtime’s own description of the header, the sections and the native formats
- ReadyToRun compilation – how to make an image (PublishReadyToRun)