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//===--------- coredistools.h - Dissassembly tools for CoreClr ------------===//
6//
7// Core Disassembly Tools API Version 1.0.1-prerelease
8// Disassembly tools required by CoreCLR for utilities like
9// GCStress and SuperPMI
10//===----------------------------------------------------------------------===//
11
12#if !defined(_COREDISTOOLS_H_)
13#define _COREDISTOOLS_H_
14
15#include <stdint.h>
16
17#if defined(__cplusplus)
18#define EXTERN_C extern "C"
19#else
20#define EXTERN_C
21#endif // defined(__cplusplus)
22
23#if defined(_MSC_VER)
24#if defined(DllInterfaceExporter)
25#define DllIface EXTERN_C __declspec(dllexport)
26#else
27#define DllIface EXTERN_C __declspec(dllimport)
28#endif // defined(DllInterfaceExporter)
29#else
30#if !defined(__cdecl)
31#if defined(__i386__)
32#define __cdecl __attribute__((cdecl))
33#else
34#define __cdecl
35#endif
36#endif
37#define DllIface EXTERN_C
38#endif // defined(_MSC_VER)
39
40enum TargetArch {
41 Target_Host, // Target is the same as host architecture
42 Target_X86,
43 Target_X64,
44 Target_Thumb,
45 Target_Arm64
46};
47
48struct CorDisasm;
49struct CorAsmDiff;
50
51// The custom print functionality to be provide by the
52// users of this Library
53typedef void(__cdecl *Printer)(const char *msg, ...);
54struct PrintControl {
55 const Printer Error;
56 const Printer Warning;
57 const Printer Log;
58 const Printer Dump;
59};
60
61// The type of a custom function provided by the user to determine
62// if two offsets are considered equivalent wrt diffing code blocks.
63// Offset1 and Offset2 are the two offsets to be compared.
64// BlockOffset is the offest of the instructions (that contain Offset1
65// and Offset2) from the beginning of their respective code blocks.
66// InstructionLength is the length of the current instruction being
67// compared for equivalency.
68typedef bool(__cdecl *OffsetComparator)(const void *UserData, size_t BlockOffset,
69 size_t InstructionLength, uint64_t Offset1,
70 uint64_t Offset2);
71
72// The Export/Import definitions for CoreDistools library are defined below.
73// A typedef for each interface function's type is defined in order to aid
74// the importer.
75
76// Initialize the disassembler, using default print controls
77typedef CorDisasm * __cdecl InitDisasm_t(enum TargetArch Target);
78DllIface InitDisasm_t InitDisasm;
79
80// Initialize the disassembler using custom print controls
81typedef CorDisasm * __cdecl NewDisasm_t(enum TargetArch Target,
82 const PrintControl *PControl);
83DllIface NewDisasm_t NewDisasm;
84
85// Delete the disassembler
86typedef void __cdecl FinishDisasm_t(const CorDisasm *Disasm);
87DllIface FinishDisasm_t FinishDisasm;
88
89// DisasmInstruction -- Disassemble one instruction
90// Arguments:
91// Disasm -- The Disassembler
92// Address -- The address at which the bytes of the instruction
93// are intended to execute
94// Bytes -- Pointer to the actual bytes which need to be disassembled
95// MaxLength -- Number of bytes available in Bytes buffer
96// Returns:
97// -- The Size of the disassembled instruction
98// -- Zero on failure
99typedef size_t __cdecl DisasmInstruction_t(const CorDisasm *Disasm,
100 const uint8_t *Address,
101 const uint8_t *Bytes, size_t Maxlength);
102DllIface DisasmInstruction_t DisasmInstruction;
103
104// Initialize the Code Differ
105typedef CorAsmDiff * __cdecl NewDiffer_t(enum TargetArch Target,
106 const PrintControl *PControl,
107 const OffsetComparator Comparator);
108DllIface NewDiffer_t NewDiffer;
109
110// Delete the Code Differ
111typedef void __cdecl FinishDiff_t(const CorAsmDiff *AsmDiff);
112DllIface FinishDiff_t FinishDiff;
113
114// NearDiffCodeBlocks -- Compare two code blocks for semantic
115// equivalence
116// Arguments:
117// AsmDiff -- The Asm-differ
118// UserData -- Any data the user wishes to pass through into
119// the OffsetComparator
120// Address1 -- Address at which first block will execute
121// Bytes1 -- Pointer to the actual bytes of the first block
122// Size1 -- The size of the first block
123// Address2 -- Address at which second block will execute
124// Bytes2 -- Pointer to the actual bytes of the second block
125// Size2 -- The size of the second block
126// Returns:
127// -- true if the two blocks are equivalent, false if not.
128typedef bool __cdecl NearDiffCodeBlocks_t(const CorAsmDiff *AsmDiff,
129 const void *UserData,
130 const uint8_t *Address1,
131 const uint8_t *Bytes1, size_t Size1,
132 const uint8_t *Address2,
133 const uint8_t *Bytes2, size_t Size2);
134DllIface NearDiffCodeBlocks_t NearDiffCodeBlocks;
135
136// Print a code block according to the Disassembler's Print Controls
137typedef void __cdecl DumpCodeBlock_t(const CorDisasm *Disasm, const uint8_t *Address,
138 const uint8_t *Bytes, size_t Size);
139DllIface DumpCodeBlock_t DumpCodeBlock;
140
141// Print the two code blocks being diffed, according to
142// AsmDiff's PrintControls.
143typedef void __cdecl DumpDiffBlocks_t(const CorAsmDiff *AsmDiff,
144 const uint8_t *Address1, const uint8_t *Bytes1,
145 size_t Size1, const uint8_t *Address2,
146 const uint8_t *Bytes2, size_t Size2);
147DllIface DumpDiffBlocks_t DumpDiffBlocks;
148
149#endif // !defined(_COREDISTOOLS_H_)
150