1 /*========================== begin_copyright_notice ============================
2 
3 Copyright (C) 2017-2021 Intel Corporation
4 
5 SPDX-License-Identifier: MIT
6 
7 ============================= end_copyright_notice ===========================*/
8 
9 #pragma once
10 
11 #include <stdint.h>
12 #include <stddef.h>
13 
14 #if defined(_WIN32)
15     // INSIDE_PLUGIN must be defined in the pre-processor definitions of the
16     // CTranslationBlock DLL project
17     #define TRANSLATION_BLOCK_CALLING_CONV __cdecl
18     #ifndef TRANSLATION_BLOCK_API
19         #ifdef INSIDE_PLUGIN
20             #define TRANSLATION_BLOCK_API __declspec(dllexport)
21         #else
22             #define TRANSLATION_BLOCK_API __declspec(dllimport)
23         #endif
24     #endif
25 #else
26 #define TRANSLATION_BLOCK_CALLING_CONV
27     #ifndef TRANSLATION_BLOCK_API
28         #define TRANSLATION_BLOCK_API __attribute__((visibility("default")))
29     #endif
30 #endif
31 
32 namespace TC
33 {
34 static const uint32_t STB_VERSION = 1006UL;
35 static const uint32_t STB_MAX_ERROR_STRING_SIZE = 1024UL;
36 
37 // Forward prototyping
38 struct STB_RegisterArgs;
39 struct STB_CreateArgs;
40 class  CTranslationBlock;
41 
42 extern "C" TRANSLATION_BLOCK_API void TRANSLATION_BLOCK_CALLING_CONV Register(STB_RegisterArgs* pRegisterArgs);
43 extern "C" TRANSLATION_BLOCK_API CTranslationBlock* TRANSLATION_BLOCK_CALLING_CONV Create(STB_CreateArgs* pCreateArgs);
44 extern "C" TRANSLATION_BLOCK_API void TRANSLATION_BLOCK_CALLING_CONV Delete(CTranslationBlock* pBlock);
45 
46 typedef void (TRANSLATION_BLOCK_CALLING_CONV *PFNREGISTER)(STB_RegisterArgs* pRegisterArgs);
47 typedef CTranslationBlock* (TRANSLATION_BLOCK_CALLING_CONV *PFNCREATE)(STB_CreateArgs* pCreateArgs);
48 typedef void (TRANSLATION_BLOCK_CALLING_CONV *PFNDELETE)(CTranslationBlock* pBlock);
49 
50 #undef TRANSLATION_BLOCK_CALLING_CONV
51 
52 /******************************************************************************\
53 
54 Enumeration:
55     TB_DATA_FORMAT
56 
57 Description:
58     Possible i/o formats for the translation classes
59 
60 \******************************************************************************/
61 enum TB_DATA_FORMAT
62 {
63     TB_DATA_FORMAT_UNKNOWN,
64     TB_DATA_FORMAT_OCL_TEXT,
65     TB_DATA_FORMAT_OCL_BINARY,
66     TB_DATA_FORMAT_LLVM_TEXT,
67     TB_DATA_FORMAT_LLVM_BINARY,
68     TB_DATA_FORMAT_GHAL_TEXT,
69     TB_DATA_FORMAT_GHAL_BINARY,
70     TB_DATA_FORMAT_DEVICE_TEXT,
71     TB_DATA_FORMAT_DEVICE_BINARY,
72     TB_DATA_FORMAT_LLVM_ARCHIVE,
73     TB_DATA_FORMAT_ELF,
74     TB_DATA_FORMAT_RS_LLVM_BINARY,
75     TB_DATA_FORMAT_RS_INFO,
76     TB_DATA_FORMAT_SPIR_V,
77     TB_DATA_FORMAT_COHERENT_DEVICE_BINARY,
78     TB_DATA_FORMAT_NON_COHERENT_DEVICE_BINARY,
79     NUM_TB_DATA_FORMATS
80 };
81 
82 /******************************************************************************\
83 
84 Structure:
85     STB_TranslationCode
86 
87 Description:
88     Structure used to describe the requested translation type
89 
90 \******************************************************************************/
91 union STB_TranslationCode
92 {
93     struct
94     {
95         TB_DATA_FORMAT Input  : 16;
96         TB_DATA_FORMAT Output : 16;
97     }Type;
98 
99     uint32_t Code;
100 };
101 
102 /******************************************************************************\
103 
104 Structure:
105     STB_CreateArgs
106 
107 Description:
108     Structure used to store arguments used to pass data to the Create function
109 
110 \******************************************************************************/
111 struct STB_CreateArgs
112 {
113     //INFO keep two first fields in this order ! for version ICBE 1003 compatibility
114     STB_TranslationCode TranslationCode;
115     void*               pCreateData;
116 
STB_CreateArgsSTB_CreateArgs117     STB_CreateArgs()
118     {
119         TranslationCode.Code = 0;
120         pCreateData = NULL;
121     }
122 };
123 
124 /******************************************************************************\
125 
126 Structure:
127     STB_RegisterArgs
128 
129 Description:
130     Structure containing a pointer to an array of supported translation codes
131     and a variable informing us of the size of the translation code array.
132 
133     The calling function is responsible for deleting the memory allocated
134     for the translation code array.
135 
136 Note:
137     Version is contained in this header
138 
139 \******************************************************************************/
140 struct STB_RegisterArgs
141 {
142     uint32_t                 Version;
143     uint32_t                 NumTranslationCodes;
144     STB_TranslationCode*     pTranslationCodes;
145 
STB_RegisterArgsSTB_RegisterArgs146     STB_RegisterArgs()
147     {
148         Version = STB_VERSION;
149         NumTranslationCodes = 0;
150         pTranslationCodes = NULL;
151     }
152 };
153 
154 /******************************************************************************\
155 
156 Structure:
157     STB_TranslateInputArgs
158 
159 Description:
160     Structure used to pass input variables to the translation block
161 
162 \******************************************************************************/
163 struct STB_TranslateInputArgs
164 {
165     char*           pInput;               // data to be translated
166     uint32_t        InputSize;            // size of data to be translated
167     const char*     pOptions;             // list of build/compile options
168     uint32_t        OptionsSize;          // size of options list
169     const char*     pInternalOptions;     // list of build/compile options
170     uint32_t        InternalOptionsSize;  // size of options list
171     void*           pTracingOptions;      // instrumentation options
172     uint32_t        TracingOptionsCount;  // number of instrumentation options
173     void*           GTPinInput;           // input structure for GTPin requests
174     bool            CompileTimeStatisticsEnable;
175     const uint32_t* pSpecConstantsIds;    // user-defined spec constants ids
176     const uint64_t* pSpecConstantsValues; // spec constants values to be translated
177     uint32_t        SpecConstantsSize;    // number of specialization constants
178 
STB_TranslateInputArgsSTB_TranslateInputArgs179     STB_TranslateInputArgs()
180     {
181         pInput                = NULL;
182         InputSize             = 0;
183         pOptions              = NULL;
184         OptionsSize           = 0;
185         pInternalOptions      = NULL;
186         InternalOptionsSize   = 0;
187         pTracingOptions       = NULL;
188         TracingOptionsCount   = 0;
189         GTPinInput            = NULL;
190         CompileTimeStatisticsEnable = false;
191         pSpecConstantsIds     = NULL;
192         pSpecConstantsValues  = NULL;
193         SpecConstantsSize     = 0;
194     }
195 };
196 
197 /******************************************************************************\
198 
199 Structure:
200     STB_TranslateOutputArgs
201 
202 Description:
203     Structure used to hold data returned from the translation block
204 
205 \******************************************************************************/
206 struct STB_TranslateOutputArgs
207 {
208     char*       pOutput;            // pointer to translated data buffer
209     uint32_t    OutputSize;         // translated data buffer size (bytes)
210     char*       pErrorString;       // string to print if translate fails
211     uint32_t    ErrorStringSize;    // size of error string
212     char*       pDebugData;         // pointer to translated debug data buffer
213     uint32_t    DebugDataSize;      // translated debug data data size (bytes)
214 
STB_TranslateOutputArgsSTB_TranslateOutputArgs215     STB_TranslateOutputArgs()
216     {
217         pOutput             = NULL;
218         OutputSize          = 0;
219         pErrorString        = NULL;
220         ErrorStringSize     = 0;
221         pDebugData          = NULL;
222         DebugDataSize       = 0;
223     }
224 };
225 
226 struct TranslationBlockVersion
227 {
228     static const uint32_t VersioningIsUnsupported = (uint32_t)-1;
229     uint32_t TBVersion;   // STB_VERSION version of this translation block
230     uint32_t BuildId;     // build ID (for CI builds) of this translation block
231 };
232 
233 /******************************************************************************\
234 Class:
235     CTranslationBlock
236 
237 Description:
238     Interface used to expose required functions to translation plug-ins
239 \******************************************************************************/
240 class CTranslationBlock
241 {
242 public:
243     virtual bool Translate(
244         const STB_TranslateInputArgs* pInput,
245         STB_TranslateOutputArgs* pOutput ) = 0;
246 
247     virtual bool FreeAllocations( STB_TranslateOutputArgs* pOutput ) = 0;
248 
GetOpcodes(void * pOpcodes,uint32_t pOpcodesSize)249     virtual bool GetOpcodes( void* pOpcodes, uint32_t pOpcodesSize ) { return false; }
GetOpcodesCount(uint32_t * pOpcodesCount,uint32_t * pOpcodeSize)250     virtual bool GetOpcodesCount( uint32_t* pOpcodesCount, uint32_t* pOpcodeSize ){ return false; }
GetVersion()251     virtual TranslationBlockVersion GetVersion() const {
252         TranslationBlockVersion tbv;
253         tbv.TBVersion = TC::STB_VERSION;
254         uint32_t buildId = TranslationBlockVersion::VersioningIsUnsupported;
255 #ifdef TB_BUILD_ID
256         buildId = TB_BUILD_ID;
257 #endif
258         tbv.BuildId = buildId;
259 
260         return tbv;
261     }
~CTranslationBlock()262     virtual ~CTranslationBlock() {}
263 };
264 } // namespace TC
265