1// Licensed to the .NET Foundation under one or more agreements.
2// The .NET Foundation licenses this file to you under the MIT license.
3// See the LICENSE file in the project root for more information.
4
5/*****************************************************************************
6 ** **
7 ** ICeeFileGen.h - code generator interface. **
8 ** **
9 ** This interface provides functionality to create a CLR PE executable. **
10 ** This will typically be used by compilers to generate their compiled **
11 ** output executable. **
12 ** **
13 *****************************************************************************/
14
15/*
16 This is how this is typically used:
17
18 // Step #1 ... Get CLR hosting API:
19 #include <mscoree.h>
20 #include <metahost.h>
21
22 ICLRMetaHost * pMetaHost;
23 CLRCreateInstance(CLSID_CLRMetaHost, IID_ICLRMetaHost, &pMetaHost); // defined in mscoree.h
24
25 ICLRRuntimeInfo * pCLRRuntimeInfo;
26 pMetaHost->GetRuntime(wszClrVersion, IID_ICLRRuntimeInfo, &pCLRRuntimeInfo);
27
28 // Step #2 ... use mscorpe APIs to create a file generator
29 CreateICeeFileGen(...); // Get a ICeeFileGen
30
31 CreateCeeFile(...); // Get a HCEEFILE (called for every output file needed)
32 SetOutputFileName(...); // Set the name for the output file
33 pEmit = IMetaDataEmit object; // Get a metadata emitter
34 GetSectionBlock(...);, AddSectionReloc(...); ... // Get blocks, write non-metadata information, and add necessary relocation
35 EmitMetaDataEx(pEmit); // Write out the metadata
36 GenerateCeeFile(...); // Write out the file. Implicitly calls LinkCeeFile and FixupCeeFile
37
38 DestroyICeeFileGen(...); // Release the ICeeFileGen object
39*/
40
41
42#ifndef _ICEEFILEGEN_H_
43#define _ICEEFILEGEN_H_
44
45#include <ole2.h>
46#include "cor.h"
47
48class ICeeFileGen;
49
50typedef void *HCEEFILE;
51
52EXTERN_C HRESULT __stdcall CreateICeeFileGen(ICeeFileGen** pCeeFileGen);
53EXTERN_C HRESULT __stdcall DestroyICeeFileGen(ICeeFileGen ** ppCeeFileGen);
54
55typedef HRESULT (__stdcall * PFN_CreateICeeFileGen)(ICeeFileGen ** ceeFileGen); // call this to instantiate an ICeeFileGen interface
56typedef HRESULT (__stdcall * PFN_DestroyICeeFileGen)(ICeeFileGen ** ceeFileGen); // call this to delete an ICeeFileGen
57
58#define ICEE_CREATE_FILE_PE32 0x00000001 // Create a PE (32-bit)
59#define ICEE_CREATE_FILE_PE64 0x00000002 // Create a PE+ (64-bit)
60#define ICEE_CREATE_FILE_CORMAIN_STUB 0x00000004 // add a mscoree!_Cor___Main call stub
61#define ICEE_CREATE_FILE_STRIP_RELOCS 0x00000008 // strip the .reloc section
62#define ICEE_CREATE_FILE_EMIT_FIXUPS 0x00000010 // emit fixups for use by Vulcan
63
64#define ICEE_CREATE_MACHINE_MASK 0x0000FF00 // space for up to 256 machine targets (note: most users just do a bit check, not an equality compare after applying the mask)
65#define ICEE_CREATE_MACHINE_ILLEGAL 0x00000000 // An illegal machine name
66#define ICEE_CREATE_MACHINE_I386 0x00000100 // Create a IMAGE_FILE_MACHINE_I386
67#define ICEE_CREATE_MACHINE_IA64 0x00000200 // Create a IMAGE_FILE_MACHINE_IA64
68#define ICEE_CREATE_MACHINE_AMD64 0x00000400 // Create a IMAGE_FILE_MACHINE_AMD64
69#define ICEE_CREATE_MACHINE_ARM 0x00000800 // Create a IMAGE_FILE_MACHINE_ARMNT
70#define ICEE_CREATE_MACHINE_ARM64 0x00001000 // Create a IMAGE_FILE_MACHINE_ARM64
71
72 // Pass this to CreateCeeFileEx to create a pure IL Exe or DLL
73#define ICEE_CREATE_FILE_PURE_IL ICEE_CREATE_FILE_PE32 | \
74 ICEE_CREATE_FILE_CORMAIN_STUB | \
75 ICEE_CREATE_MACHINE_I386
76
77class ICeeFileGen {
78 public:
79 virtual HRESULT CreateCeeFile(HCEEFILE *ceeFile); // call this to instantiate a file handle
80
81 // <TODO>@FUTURE: remove this function. We no longer support mdScope.</TODO>
82 virtual HRESULT EmitMetaData (HCEEFILE ceeFile, IMetaDataEmit *emitter, mdScope scope);
83 virtual HRESULT EmitLibraryName (HCEEFILE ceeFile, IMetaDataEmit *emitter, mdScope scope);
84 virtual HRESULT EmitMethod (); // <TODO>@FUTURE: remove</TODO>
85 virtual HRESULT GetMethodRVA (HCEEFILE ceeFile, ULONG codeOffset, ULONG *codeRVA);
86 virtual HRESULT EmitSignature (); // <TODO>@FUTURE: remove</TODO>
87
88 virtual HRESULT EmitString (HCEEFILE ceeFile,_In_ LPWSTR strValue, ULONG *strRef);
89 virtual HRESULT GenerateCeeFile (HCEEFILE ceeFile);
90
91 virtual HRESULT SetOutputFileName (HCEEFILE ceeFile, _In_ LPWSTR outputFileName);
92 _Return_type_success_(return == S_OK)
93 virtual HRESULT GetOutputFileName (HCEEFILE ceeFile, _Out_ LPWSTR *outputFileName);
94
95 virtual HRESULT SetResourceFileName (HCEEFILE ceeFile, _In_ LPWSTR resourceFileName);
96
97 _Return_type_success_(return == S_OK)
98 virtual HRESULT GetResourceFileName (HCEEFILE ceeFile, _Out_ LPWSTR *resourceFileName);
99
100 virtual HRESULT SetImageBase(HCEEFILE ceeFile, size_t imageBase);
101
102 virtual HRESULT SetSubsystem(HCEEFILE ceeFile, DWORD subsystem, DWORD major, DWORD minor);
103
104 virtual HRESULT SetEntryClassToken (); //<TODO>@FUTURE: remove</TODO>
105 virtual HRESULT GetEntryClassToken (); //<TODO>@FUTURE: remove</TODO>
106
107 virtual HRESULT SetEntryPointDescr (); //<TODO>@FUTURE: remove</TODO>
108 virtual HRESULT GetEntryPointDescr (); //<TODO>@FUTURE: remove</TODO>
109
110 virtual HRESULT SetEntryPointFlags (); //<TODO>@FUTURE: remove</TODO>
111 virtual HRESULT GetEntryPointFlags (); //<TODO>@FUTURE: remove</TODO>
112
113 virtual HRESULT SetDllSwitch (HCEEFILE ceeFile, BOOL dllSwitch);
114 virtual HRESULT GetDllSwitch (HCEEFILE ceeFile, BOOL *dllSwitch);
115
116 virtual HRESULT SetLibraryName (HCEEFILE ceeFile, _In_ LPWSTR LibraryName);
117 _Return_type_success_( return == S_OK )
118 virtual HRESULT GetLibraryName (HCEEFILE ceeFile, _Out_ LPWSTR *LibraryName);
119
120 virtual HRESULT SetLibraryGuid (HCEEFILE ceeFile, _In_ LPWSTR LibraryGuid);
121
122 virtual HRESULT DestroyCeeFile(HCEEFILE *ceeFile); // call this to delete a file handle
123
124 virtual HRESULT GetSectionCreate (HCEEFILE ceeFile, const char *name, DWORD flags, HCEESECTION *section);
125 virtual HRESULT GetIlSection (HCEEFILE ceeFile, HCEESECTION *section);
126 virtual HRESULT GetRdataSection (HCEEFILE ceeFile, HCEESECTION *section);
127
128 virtual HRESULT GetSectionDataLen (HCEESECTION section, ULONG *dataLen);
129 virtual HRESULT GetSectionBlock (HCEESECTION section, ULONG len, ULONG align=1, void **ppBytes=0);
130 virtual HRESULT TruncateSection (HCEESECTION section, ULONG len);
131 virtual HRESULT AddSectionReloc (HCEESECTION section, ULONG offset, HCEESECTION relativeTo, CeeSectionRelocType relocType);
132
133 // deprecated: use SetDirectoryEntry instead
134 virtual HRESULT SetSectionDirectoryEntry (HCEESECTION section, ULONG num);
135
136 virtual HRESULT CreateSig (); //<TODO>@FUTURE: Remove</TODO>
137 virtual HRESULT AddSigArg (); //<TODO>@FUTURE: Remove</TODO>
138 virtual HRESULT SetSigReturnType (); //<TODO>@FUTURE: Remove</TODO>
139 virtual HRESULT SetSigCallingConvention (); //<TODO>@FUTURE: Remove</TODO>
140 virtual HRESULT DeleteSig (); //<TODO>@FUTURE: Remove</TODO>
141
142 virtual HRESULT SetEntryPoint (HCEEFILE ceeFile, mdMethodDef method);
143 virtual HRESULT GetEntryPoint (HCEEFILE ceeFile, mdMethodDef *method);
144
145 virtual HRESULT SetComImageFlags (HCEEFILE ceeFile, DWORD mask);
146 virtual HRESULT GetComImageFlags (HCEEFILE ceeFile, DWORD *mask);
147
148 // get IMapToken interface for tracking mapped tokens
149 virtual HRESULT GetIMapTokenIface(HCEEFILE ceeFile, IMetaDataEmit *emitter, IUnknown **pIMapToken);
150 virtual HRESULT SetDirectoryEntry (HCEEFILE ceeFile, HCEESECTION section, ULONG num, ULONG size, ULONG offset = 0);
151
152 // Write out the metadata in "emitter" to the metadata section in "ceeFile"
153 // Use EmitMetaDataAt() for more control
154 virtual HRESULT EmitMetaDataEx (HCEEFILE ceeFile, IMetaDataEmit *emitter);
155
156 virtual HRESULT EmitLibraryNameEx (HCEEFILE ceeFile, IMetaDataEmit *emitter);
157 virtual HRESULT GetIMapTokenIfaceEx(HCEEFILE ceeFile, IMetaDataEmit *emitter, IUnknown **pIMapToken);
158
159 virtual HRESULT EmitMacroDefinitions(HCEEFILE ceeFile, void *pData, DWORD cData);
160 virtual HRESULT CreateCeeFileFromICeeGen(
161 ICeeGen *pFromICeeGen, HCEEFILE *ceeFile, DWORD createFlags = ICEE_CREATE_FILE_PURE_IL); // call this to instantiate a file handle
162
163 virtual HRESULT SetManifestEntry(HCEEFILE ceeFile, ULONG size, ULONG offset);
164
165 virtual HRESULT SetEnCRVABase(HCEEFILE ceeFile, ULONG dataBase, ULONG rdataBase);
166 virtual HRESULT GenerateCeeMemoryImage (HCEEFILE ceeFile, void **ppImage);
167
168 virtual HRESULT ComputeSectionOffset(HCEESECTION section, _In_ char *ptr,
169 unsigned *offset);
170
171 virtual HRESULT ComputeOffset(HCEEFILE file, _In_ char *ptr,
172 HCEESECTION *pSection, unsigned *offset);
173
174 virtual HRESULT GetCorHeader(HCEEFILE ceeFile,
175 IMAGE_COR20_HEADER **header);
176
177 // Layout the sections and assign their starting addresses
178 virtual HRESULT LinkCeeFile (HCEEFILE ceeFile);
179
180 // Apply relocations to any pointer data. Also generate PE base relocs
181 virtual HRESULT FixupCeeFile (HCEEFILE ceeFile);
182
183 // Base RVA assinged to the section. To be called only after LinkCeeFile()
184 virtual HRESULT GetSectionRVA (HCEESECTION section, ULONG *rva);
185
186 _Return_type_success_(return == S_OK)
187 virtual HRESULT ComputeSectionPointer(HCEESECTION section, ULONG offset,
188 _Out_ char **ptr);
189
190 virtual HRESULT SetObjSwitch (HCEEFILE ceeFile, BOOL objSwitch);
191 virtual HRESULT GetObjSwitch (HCEEFILE ceeFile, BOOL *objSwitch);
192 virtual HRESULT SetVTableEntry(HCEEFILE ceeFile, ULONG size, ULONG offset);
193 // See the end of interface for another overload of AetVTableEntry
194
195 virtual HRESULT SetStrongNameEntry(HCEEFILE ceeFile, ULONG size, ULONG offset);
196
197 // Emit the metadata from "emitter".
198 // If 'section != 0, it will put the data in 'buffer'. This
199 // buffer is assumed to be in 'section' at 'offset' and of size 'buffLen'
200 // (should use GetSaveSize to insure that buffer is big enough
201 virtual HRESULT EmitMetaDataAt (HCEEFILE ceeFile, IMetaDataEmit *emitter,
202 HCEESECTION section, DWORD offset,
203 BYTE* buffer, unsigned buffLen);
204
205 virtual HRESULT GetFileTimeStamp (HCEEFILE ceeFile, DWORD *pTimeStamp);
206
207 // Add a notification handler. If it implements an interface that
208 // the ICeeFileGen understands, S_OK is returned. Otherwise,
209 // E_NOINTERFACE.
210 virtual HRESULT AddNotificationHandler(HCEEFILE ceeFile,
211 IUnknown *pHandler);
212
213 virtual HRESULT SetFileAlignment(HCEEFILE ceeFile, ULONG fileAlignment);
214
215 virtual HRESULT ClearComImageFlags (HCEEFILE ceeFile, DWORD mask);
216
217 // call this to instantiate a PE+ (64-bit PE file)
218 virtual HRESULT CreateCeeFileEx(HCEEFILE *ceeFile, ULONG createFlags);
219 virtual HRESULT SetImageBase64(HCEEFILE ceeFile, ULONGLONG imageBase);
220
221 virtual HRESULT GetHeaderInfo (HCEEFILE ceeFile, PIMAGE_NT_HEADERS *ppNtHeaders,
222 PIMAGE_SECTION_HEADER *ppSections,
223 ULONG *pNumSections);
224
225 // Seed file is a base file which is copied over into the output file
226 // Note that there are restrictions on the seed file (the sections
227 // cannot be relocated), and that the copy is not complete as the new
228 // headers overwrite the seed file headers.
229 virtual HRESULT CreateCeeFileEx2(HCEEFILE *ceeFile, ULONG createFlags,
230 LPCWSTR seedFileName = NULL);
231
232 virtual HRESULT SetVTableEntry64(HCEEFILE ceeFile, ULONG size, void* ptr);
233};
234
235#endif
236