// Licensed to the .NET Foundation under one or more agreements. // The .NET Foundation licenses this file to you under the MIT license. // See the LICENSE file in the project root for more information. /************************************************************************************** ** ** ** clrinternal.idl - interface definitions for internal usage. ** ** ** **************************************************************************************/ // // Interface descriptions // import "unknwn.idl"; // import mscoree.idl for BucketParameters definition import "mscoree.idl"; cpp_quote("#if 0") typedef struct _OSVERSIONINFOA { DWORD dwOSVersionInfoSize; DWORD dwMajorVersion; DWORD dwMinorVersion; DWORD dwBuildNumber; DWORD dwPlatformId; CHAR szCSDVersion[ 128 ]; // Maintenance string for PSS usage } OSVERSIONINFOA, *POSVERSIONINFOA, *LPOSVERSIONINFOA; typedef struct _OSVERSIONINFOW { DWORD dwOSVersionInfoSize; DWORD dwMajorVersion; DWORD dwMinorVersion; DWORD dwBuildNumber; DWORD dwPlatformId; WCHAR szCSDVersion[ 128 ]; // Maintenance string for PSS usage } OSVERSIONINFOW, *POSVERSIONINFOW, *LPOSVERSIONINFOW, RTL_OSVERSIONINFOW, *PRTL_OSVERSIONINFOW; #ifdef UNICODE typedef OSVERSIONINFOW OSVERSIONINFO; typedef POSVERSIONINFOW POSVERSIONINFO; typedef LPOSVERSIONINFOW LPOSVERSIONINFO; #else typedef OSVERSIONINFOA OSVERSIONINFO; typedef POSVERSIONINFOA POSVERSIONINFO; typedef LPOSVERSIONINFOA LPOSVERSIONINFO; #endif // UNICODE cpp_quote("#endif") // IID IExecutionEngine : uuid(7AF02DAC-2A33-494b-A09F-25E00A93C6F8) cpp_quote("EXTERN_GUID(IID_IExecutionEngine, 0x7AF02DAC, 0x2A33, 0x494b, 0xA0, 0x9F, 0x25, 0xE0, 0x0A, 0x93, 0xC6, 0xF8);") // IID IEEMemoryManager : uuid{17713B61-B59F-4e13-BAAF-91623DC8ADC0} cpp_quote("EXTERN_GUID(IID_IEEMemoryManager, 0x17713b61, 0xb59f, 0x4e13, 0xba, 0xaf, 0x91, 0x62, 0x3d, 0xc8, 0xad, 0xc0);") // This ID is embedded in the CLRDEBUGINFO resource so that the shim can differentiate dlls which happen to be named // clr.dll from official Microsoft clr.dll implementations. This is not intended to authenticate a CLR in a strong // security sense but short of deliberate 3rd party spoofing it should provide a good identity. // // Using a different ID allows us to completely hide different CLR SKUs from each other. The recommendation is to keep // the ID contant between different versions of the same SKU and use mscordbi's logic to determine whether a given // version is compatible. This allows debuggers to give different errors for 'future version of the CLR I don't // support' vs. 'No CLR is loaded at all.' // // This guid first appears in version 4.0 of CLR on x86 and amd64 - earlier versions had no resource // GUID CLR_ID_V4_DESKTOP : uuid{267F3989-D786-4b9a-9AF6-D19E42D557EC} cpp_quote("EXTERN_GUID(CLR_ID_V4_DESKTOP, 0x267f3989, 0xd786, 0x4b9a, 0x9a, 0xf6, 0xd1, 0x9e, 0x42, 0xd5, 0x57, 0xec);") // This guid has been set aside for CoreCLR usage - at present CoreCLR doesn't use it though // GUID CLR_ID_CORECLR : uuid{8CB8E075-0A91-408E-9228-D66E00A3BFF6} cpp_quote("EXTERN_GUID(CLR_ID_CORECLR, 0x8CB8E075, 0x0A91, 0x408E, 0x92, 0x28, 0xD6, 0x6E, 0x00, 0xA3, 0xBF, 0xF6 );") // This guid first appears in the CoreCLR port to Windows Phone 8 - note that it is seperate from the CoreCLR id because it will // potentially have a different verioning lineage than CoreCLR // GUID CLR_ID_PHONE_CLR : uuid{E7237E9C-31C0-488C-AD48-324D3E7ED92A} cpp_quote("EXTERN_GUID(CLR_ID_PHONE_CLR, 0xE7237E9C, 0x31C0, 0x488C, 0xAD, 0x48, 0x32, 0x4D, 0x3E, 0x7E, 0xD9, 0x2A);") // This guid first appears 8/19/14 as CoreCLR evolves to OneCore, ProjectK, and versions of Phone after PhoneBlue // The new guid intentionally creates a breaking change so we can simplify the file naming on mscordaccore.dll and mscordbi.dll // in xplat hosting scenarios. Old versions of dbgshim.dll will not be able to support this. // GUID CLR_ID_ONECORE_CLR : uuid{B1EE760D-6C4A-4533-BA41-6F4F661FABAF} cpp_quote("EXTERN_GUID(CLR_ID_ONECORE_CLR, 0xb1ee760d, 0x6c4a, 0x4533, 0xba, 0x41, 0x6f, 0x4f, 0x66, 0x1f, 0xab, 0xaf);") // IID_IPrivateManagedExceptionReporting : uuid{AD76A023-332D-4298-8001-07AA9350DCA4} cpp_quote("EXTERN_GUID(IID_IPrivateManagedExceptionReporting, 0xad76a023, 0x332d, 0x4298, 0x80, 0x01, 0x07, 0xaa, 0x93, 0x50, 0xdc, 0xa4);") //***************************************************************************** // Interface for exposing services from the EE to other DLLs of the CLR. //***************************************************************************** typedef void * CRITSEC_COOKIE; typedef void * EVENT_COOKIE; typedef void * SEMAPHORE_COOKIE; typedef void * MUTEX_COOKIE; typedef enum { CRST_DEFAULT = 0x0, CRST_REENTRANCY = 0x1, // allow same thread to take lock multiple times. CRST_UNSAFE_SAMELEVEL = 0x2, // AVOID THIS! Can take other locks @ same level in // any order. CRST_UNSAFE_COOPGC = 0x4, // AVOID THIS! Lock must be taken in cooperative mode. CRST_UNSAFE_ANYMODE = 0x8, // AVOID THIS! Lock can be taken in either GC mode. CRST_DEBUGGER_THREAD = 0x10, // This lock can be taken on the debugger's helper thread. CRST_HOST_BREAKABLE = 0x20, // This lock is held while running managed code. It can be terminated by a host. // CRST_UNUSED = 0x40, CRST_TAKEN_DURING_SHUTDOWN = 0x80, // This lock is taken during the shutdown sequence in EEShutdown(helper) CRST_GC_NOTRIGGER_WHEN_TAKEN = 0x100, // User of this lock cannot trigger GC, while it is locked. // Note that Enter on this lock can trigger GC if called from COOPERATIVE mode. // It is useful for locks which can be taken on GC or debugger threads. CRST_DEBUG_ONLY_CHECK_FORBID_SUSPEND_THREAD = 0x200, // Some rare locks should be taken only in ForbidSuspend region (i.e. profiler cannot walk the stack), // this option will assert it in debug mode. } CrstFlags; // Callback function for cleaning up TLS typedef VOID (__stdcall *PTLS_CALLBACK_FUNCTION)(PVOID); [ uuid(7AF02DAC-2A33-494b-A09F-25E00A93C6F8), helpstring("CLR Coordination Interface"), pointer_default(unique), local ] interface IExecutionEngine : IUnknown { // Thread Local Storage is based on logical threads. The underlying // implementation could be threads, fibers, or something more exotic. // Slot numbers are predefined. This is not a general extensibility // mechanism. // Associate a callback function for releasing TLS on thread/fiber death. // This can be NULL. void TLS_AssociateCallback([in] DWORD slot, [in] PTLS_CALLBACK_FUNCTION callback); // Get the TLS block for fast Get/Set operations PVOID* TLS_GetDataBlock(); // Get the value at a slot PVOID TLS_GetValue([in] DWORD slot); // Get the value at a slot, return FALSE if TLS info block doesn't exist BOOL TLS_CheckValue([in] DWORD slot, [out] PVOID * pValue); // Set the value at a slot void TLS_SetValue([in] DWORD slot, [in] PVOID pData); // Free TLS memory block and make callback void TLS_ThreadDetaching(); // Critical Sections are sometimes exposed to the host and therefore need to be // reflected from all CLR DLLs to the EE. // // In addition, we always monitor interactions between the lock & the GC, based // on the GC mode in which the lock is acquired and we restrict what operations // are permitted while holding the lock based on this. // // Finally, we we rank all our locks to prevent deadlock across all the DLLs of // the CLR. This is the level argument to CreateLock. // // All usage of these locks must be exception-safe. To achieve this, we suggest // using Holders (see holder.h & crst.h). In fact, within the EE code cannot // hold locks except by using exception-safe holders. CRITSEC_COOKIE CreateLock([in] LPCSTR szTag, [in] LPCSTR level, [in] CrstFlags flags); void DestroyLock([in] CRITSEC_COOKIE lock); void AcquireLock([in] CRITSEC_COOKIE lock); void ReleaseLock([in] CRITSEC_COOKIE lock); EVENT_COOKIE CreateAutoEvent([in] BOOL bInitialState); EVENT_COOKIE CreateManualEvent([in] BOOL bInitialState); void CloseEvent([in] EVENT_COOKIE event); BOOL ClrSetEvent([in] EVENT_COOKIE event); BOOL ClrResetEvent([in] EVENT_COOKIE event); DWORD WaitForEvent([in] EVENT_COOKIE event, [in] DWORD dwMilliseconds, [in] BOOL bAlertable); DWORD WaitForSingleObject([in] HANDLE handle, [in] DWORD dwMilliseconds); // OS header file defines CreateSemaphore. SEMAPHORE_COOKIE ClrCreateSemaphore([in] DWORD dwInitial, [in] DWORD dwMax); void ClrCloseSemaphore([in] SEMAPHORE_COOKIE semaphore); DWORD ClrWaitForSemaphore([in] SEMAPHORE_COOKIE semaphore, [in] DWORD dwMilliseconds, [in] BOOL bAlertable); BOOL ClrReleaseSemaphore([in] SEMAPHORE_COOKIE semaphore, [in] LONG lReleaseCount, [in] LONG *lpPreviousCount); MUTEX_COOKIE ClrCreateMutex([in]LPSECURITY_ATTRIBUTES lpMutexAttributes, [in]BOOL bInitialOwner, [in]LPCTSTR lpName); DWORD ClrWaitForMutex([in] MUTEX_COOKIE mutex, [in] DWORD dwMilliseconds, [in] BOOL bAlertable); BOOL ClrReleaseMutex([in] MUTEX_COOKIE mutex); void ClrCloseMutex([in] MUTEX_COOKIE mutex); DWORD ClrSleepEx([in] DWORD dwMilliseconds, [in] BOOL bAlertable); BOOL ClrAllocationDisallowed(); void GetLastThrownObjectExceptionFromThread([out] void **ppvException); }; // interface IExecutionEngine //***************************************************************************** // Interface for exposing memory services from the EE to other DLLs of the CLR. //***************************************************************************** cpp_quote("#if !defined(_WINNT_) && !defined(_NTMMAPI_)") typedef void* PMEMORY_BASIC_INFORMATION; cpp_quote("#endif") [ uuid(17713B61-B59F-4e13-BAAF-91623DC8ADC0), helpstring("CLR Memory Manager Interface"), pointer_default(unique), local ] interface IEEMemoryManager : IUnknown { LPVOID ClrVirtualAlloc( [in] LPVOID lpAddress, // region to reserve or commit [in] SIZE_T dwSize, // size of region [in] DWORD flAllocationType, // type of allocation [in] DWORD flProtect // type of access protection ); BOOL ClrVirtualFree( [in] LPVOID lpAddress, // address of region [in] SIZE_T dwSize, // size of region [in] DWORD dwFreeType // operation type ); SIZE_T ClrVirtualQuery( [in] const void* lpAddress, // address of region [in] PMEMORY_BASIC_INFORMATION lpBuffer, // information buffer [in] SIZE_T dwLength // size of buffer ); BOOL ClrVirtualProtect( [in] LPVOID lpAddress, // region of committed pages [in] SIZE_T dwSize, // size of the region [in] DWORD flNewProtect, // desired access protection [in] DWORD* lpflOldProtect // old protection ); HANDLE ClrGetProcessHeap(); HANDLE ClrHeapCreate( [in] DWORD flOptions, // heap allocation attributes [in] SIZE_T dwInitialSize, // initial heap size [in] SIZE_T dwMaximumSize // maximum heap size ); BOOL ClrHeapDestroy( [in] HANDLE hHeap // handle to heap ); LPVOID ClrHeapAlloc( [in] HANDLE hHeap, // handle to private heap block [in] DWORD dwFlags, // heap allocation control [in] SIZE_T dwBytes // number of bytes to allocate ); BOOL ClrHeapFree( [in] HANDLE hHeap, // handle to heap [in] DWORD dwFlags, // heap free options [in] LPVOID lpMem // pointer to memory ); BOOL ClrHeapValidate( [in] HANDLE hHeap, // handle to heap [in] DWORD dwFlags, // heap access options [in] const void* lpMem // optional pointer to memory block ); HANDLE ClrGetProcessExecutableHeap(); }; // interface IEEMemoryManager //******************************************************************************************** // Interface for exposing GetBucketParametersForCurrentException to Watson testing harness. //******************************************************************************************** [ uuid(AD76A023-332D-4298-8001-07AA9350DCA4), helpstring("Private Managed Exception Reporting Interface"), pointer_default(unique), local ] interface IPrivateManagedExceptionReporting : IUnknown { HRESULT GetBucketParametersForCurrentException([out]BucketParameters *pParams); }