codekingpro/portable-devtools
114k
1//
2// NVIDIA_COPYRIGHT_BEGIN
3//
4// Copyright (c) 2014-2023, NVIDIA CORPORATION. All rights reserved.
5//
6// NVIDIA CORPORATION and its licensors retain all intellectual property
7// and proprietary rights in and to this software, related documentation
8// and any modifications thereto. Any use, reproduction, disclosure or
9// distribution of this software and related documentation without an express
10// license agreement from NVIDIA CORPORATION is strictly prohibited.
11//
12// NVIDIA_COPYRIGHT_END
13//
14
15#ifndef NVVM_H
16#define NVVM_H
17
18#ifdef __cplusplus
19extern "C" {
20#endif /* __cplusplus */
21
22#include <stdlib.h>
23
24
25/*****************************//**
26 *
27 * \defgroup error Error Handling
28 *
29 ********************************/
30
31
32/**
33 * \ingroup error
34 * \brief NVVM API call result code.
35 */
36typedef enum {
37 NVVM_SUCCESS = 0,
38 NVVM_ERROR_OUT_OF_MEMORY = 1,
39 NVVM_ERROR_PROGRAM_CREATION_FAILURE = 2,
40 NVVM_ERROR_IR_VERSION_MISMATCH = 3,
41 NVVM_ERROR_INVALID_INPUT = 4,
42 NVVM_ERROR_INVALID_PROGRAM = 5,
43 NVVM_ERROR_INVALID_IR = 6,
44 NVVM_ERROR_INVALID_OPTION = 7,
45 NVVM_ERROR_NO_MODULE_IN_PROGRAM = 8,
46 NVVM_ERROR_COMPILATION = 9
47} nvvmResult;
48
49
50/**
51 * \ingroup error
52 * \brief Get the message string for the given #nvvmResult code.
53 *
54 * \param [in] result NVVM API result code.
55 * \return Message string for the given #nvvmResult code.
56 */
57const char *nvvmGetErrorString(nvvmResult result);
58
59
60/****************************************//**
61 *
62 * \defgroup query General Information Query
63 *
64 *******************************************/
65
66
67/**
68 * \ingroup query
69 * \brief Get the NVVM version.
70 *
71 * \param [out] major NVVM major version number.
72 * \param [out] minor NVVM minor version number.
73 * \return
74 * - \link ::nvvmResult NVVM_SUCCESS \endlink
75 *
76 */
77nvvmResult nvvmVersion(int *major, int *minor);
78
79
80/**
81 * \ingroup query
82 * \brief Get the NVVM IR version.
83 *
84 * \param [out] majorIR NVVM IR major version number.
85 * \param [out] minorIR NVVM IR minor version number.
86 * \param [out] majorDbg NVVM IR debug metadata major version number.
87 * \param [out] minorDbg NVVM IR debug metadata minor version number.
88 * \return
89 * - \link ::nvvmResult NVVM_SUCCESS \endlink
90 *
91 */
92nvvmResult nvvmIRVersion(int *majorIR, int *minorIR, int *majorDbg, int *minorDbg);
93
94
95/********************************//**
96 *
97 * \defgroup compilation Compilation
98 *
99 ***********************************/
100
101/**
102 * \ingroup compilation
103 * \brief NVVM Program.
104 *
105 * An opaque handle for a program.
106 */
107typedef struct _nvvmProgram *nvvmProgram;
108
109/**
110 * \ingroup compilation
111 * \brief Create a program, and set the value of its handle to \p *prog.
112 *
113 * \param [in] prog NVVM program.
114 * \return
115 * - \link ::nvvmResult NVVM_SUCCESS \endlink
116 * - \link ::nvvmResult NVVM_ERROR_OUT_OF_MEMORY \endlink
117 * - \link ::nvvmResult NVVM_ERROR_INVALID_PROGRAM \endlink
118 *
119 * \see nvvmDestroyProgram()
120 */
121nvvmResult nvvmCreateProgram(nvvmProgram *prog);
122
123
124/**
125 * \ingroup compilation
126 * \brief Destroy a program.
127 *
128 * \param [in] prog NVVM program.
129 * \return
130 * - \link ::nvvmResult NVVM_SUCCESS \endlink
131 * - \link ::nvvmResult NVVM_ERROR_INVALID_PROGRAM \endlink
132 *
133 * \see nvvmCreateProgram()
134 */
135nvvmResult nvvmDestroyProgram(nvvmProgram *prog);
136
137
138/**
139 * \ingroup compilation
140 * \brief Add a module level NVVM IR to a program.
141 *
142 * The \p buffer should contain an NVVM IR module.
143 * The module should have NVVM IR either in the LLVM 7.0.1 bitcode
144 * representation or in the LLVM 7.0.1 text representation. Support for reading
145 * the text representation of NVVM IR is deprecated and may be removed in a
146 * later version.
147 *
148 * \param [in] prog NVVM program.
149 * \param [in] buffer NVVM IR module in the bitcode or text
150 * representation.
151 * \param [in] size Size of the NVVM IR module.
152 * \param [in] name Name of the NVVM IR module.
153 * If NULL, "<unnamed>" is used as the name.
154 * \return
155 * - \link ::nvvmResult NVVM_SUCCESS \endlink
156 * - \link ::nvvmResult NVVM_ERROR_OUT_OF_MEMORY \endlink
157 * - \link ::nvvmResult NVVM_ERROR_INVALID_INPUT \endlink
158 * - \link ::nvvmResult NVVM_ERROR_INVALID_PROGRAM \endlink
159 */
160nvvmResult nvvmAddModuleToProgram(nvvmProgram prog, const char *buffer, size_t size, const char *name);
161
162/**
163 * \ingroup compilation
164 * \brief Add a module level NVVM IR to a program.
165 *
166 * The \p buffer should contain an NVVM IR module. The module should have NVVM
167 * IR in the LLVM 7.0.1 bitcode representation.
168 *
169 * A module added using this API is lazily loaded - the only symbols loaded
170 * are those that are required by module(s) loaded using
171 * nvvmAddModuleToProgram. It is an error for a program to have
172 * all modules loaded using this API. Compiler may also optimize entities
173 * in this module by making them internal to the linked NVVM IR module,
174 * making them eligible for other optimizations. Due to these
175 * optimizations, this API to load a module is more efficient and should
176 * be used where possible.
177 *
178 * \param [in] prog NVVM program.
179 * \param [in] buffer NVVM IR module in the bitcode representation.
180 * \param [in] size Size of the NVVM IR module.
181 * \param [in] name Name of the NVVM IR module.
182 * If NULL, "<unnamed>" is used as the name.
183 * \return
184 * - \link ::nvvmResult NVVM_SUCCESS \endlink
185 * - \link ::nvvmResult NVVM_ERROR_OUT_OF_MEMORY \endlink
186 * - \link ::nvvmResult NVVM_ERROR_INVALID_INPUT \endlink
187 * - \link ::nvvmResult NVVM_ERROR_INVALID_PROGRAM \endlink
188 */
189nvvmResult nvvmLazyAddModuleToProgram(nvvmProgram prog, const char *buffer, size_t size, const char *name);
190
191/**
192 * \ingroup compilation
193 * \brief Compile the NVVM program.
194 *
195 * The NVVM IR modules in the program will be linked at the IR level.
196 * The linked IR program is compiled to PTX.
197 *
198 * The target datalayout in the linked IR program is used to
199 * determine the address size (32bit vs 64bit).
200 *
201 * The valid compiler options are:
202 *
203 * - -g (enable generation of full debugging information).
204 * Full debug support is only valid with '-opt=0'. Debug support
205 * requires the input module to utilize NVVM IR Debug Metadata.
206 * Line number (line info) only generation is also enabled via NVVM IR
207 * Debug Metadata, there is no specific libNVVM API flag for that case.
208 * - -opt=
209 * - 0 (disable optimizations)
210 * - 3 (default, enable optimizations)
211 * - -arch=
212 * - compute_50
213 * - compute_52 (default)
214 * - compute_53
215 * - compute_60
216 * - compute_61
217 * - compute_62
218 * - compute_70
219 * - compute_72
220 * - compute_75
221 * - compute_80
222 * - compute_87
223 * - compute_89
224 * - compute_90
225 * - -ftz=
226 * - 0 (default, preserve denormal values, when performing
227 * single-precision floating-point operations)
228 * - 1 (flush denormal values to zero, when performing
229 * single-precision floating-point operations)
230 * - -prec-sqrt=
231 * - 0 (use a faster approximation for single-precision
232 * floating-point square root)
233 * - 1 (default, use IEEE round-to-nearest mode for
234 * single-precision floating-point square root)
235 * - -prec-div=
236 * - 0 (use a faster approximation for single-precision
237 * floating-point division and reciprocals)
238 * - 1 (default, use IEEE round-to-nearest mode for
239 * single-precision floating-point division and reciprocals)
240 * - -fma=
241 * - 0 (disable FMA contraction)
242 * - 1 (default, enable FMA contraction)
243 * - -jump-table-density=[0-101]
244 * Specify the case density percentage in switch statements, and use
245 * it as a minimal threshold to determine whether jump table(brx.idx
246 * instruction) will be used to implement a switch statement. Default
247 * value is 101. The percentage ranges from 0 to 101 inclusively.
248 * - -gen-lto (Generate LTO IR instead of PTX).
249 *
250 * \param [in] prog NVVM program.
251 * \param [in] numOptions Number of compiler \p options passed.
252 * \param [in] options Compiler options in the form of C string array.
253 * \return
254 * - \link ::nvvmResult NVVM_SUCCESS \endlink
255 * - \link ::nvvmResult NVVM_ERROR_OUT_OF_MEMORY \endlink
256 * - \link ::nvvmResult NVVM_ERROR_IR_VERSION_MISMATCH \endlink
257 * - \link ::nvvmResult NVVM_ERROR_INVALID_PROGRAM \endlink
258 * - \link ::nvvmResult NVVM_ERROR_INVALID_OPTION \endlink
259 * - \link ::nvvmResult NVVM_ERROR_NO_MODULE_IN_PROGRAM \endlink
260 * - \link ::nvvmResult NVVM_ERROR_COMPILATION \endlink
261 */
262nvvmResult nvvmCompileProgram(nvvmProgram prog, int numOptions, const char **options);
263
264/**
265 * \ingroup compilation
266 * \brief Verify the NVVM program.
267 *
268 * The valid compiler options are:
269 *
270 * Same as for nvvmCompileProgram().
271 *
272 * \param [in] prog NVVM program.
273 * \param [in] numOptions Number of compiler \p options passed.
274 * \param [in] options Compiler options in the form of C string array.
275 * \return
276 * - \link ::nvvmResult NVVM_SUCCESS \endlink
277 * - \link ::nvvmResult NVVM_ERROR_OUT_OF_MEMORY \endlink
278 * - \link ::nvvmResult NVVM_ERROR_IR_VERSION_MISMATCH \endlink
279 * - \link ::nvvmResult NVVM_ERROR_INVALID_PROGRAM \endlink
280 * - \link ::nvvmResult NVVM_ERROR_INVALID_IR \endlink
281 * - \link ::nvvmResult NVVM_ERROR_INVALID_OPTION \endlink
282 * - \link ::nvvmResult NVVM_ERROR_NO_MODULE_IN_PROGRAM \endlink
283 *
284 * \see nvvmCompileProgram()
285 */
286nvvmResult nvvmVerifyProgram(nvvmProgram prog, int numOptions, const char **options);
287
288/**
289 * \ingroup compilation
290 * \brief Get the size of the compiled result.
291 *
292 * \param [in] prog NVVM program.
293 * \param [out] bufferSizeRet Size of the compiled result (including the
294 * trailing NULL).
295 * \return
296 * - \link ::nvvmResult NVVM_SUCCESS \endlink
297 * - \link ::nvvmResult NVVM_ERROR_INVALID_PROGRAM \endlink
298 */
299nvvmResult nvvmGetCompiledResultSize(nvvmProgram prog, size_t *bufferSizeRet);
300
301
302/**
303 * \ingroup compilation
304 * \brief Get the compiled result.
305 *
306 * The result is stored in the memory pointed to by \p buffer.
307 *
308 * \param [in] prog NVVM program.
309 * \param [out] buffer Compiled result.
310 * \return
311 * - \link ::nvvmResult NVVM_SUCCESS \endlink
312 * - \link ::nvvmResult NVVM_ERROR_INVALID_PROGRAM \endlink
313 */
314nvvmResult nvvmGetCompiledResult(nvvmProgram prog, char *buffer);
315
316/**
317 * \ingroup compilation
318 * \brief Get the Size of Compiler/Verifier Message.
319 *
320 * The size of the message string (including the trailing NULL) is stored into
321 * \p bufferSizeRet when the return value is NVVM_SUCCESS.
322 *
323 * \param [in] prog NVVM program.
324 * \param [out] bufferSizeRet Size of the compilation/verification log
325 (including the trailing NULL).
326 * \return
327 * - \link ::nvvmResult NVVM_SUCCESS \endlink
328 * - \link ::nvvmResult NVVM_ERROR_INVALID_PROGRAM \endlink
329 */
330nvvmResult nvvmGetProgramLogSize(nvvmProgram prog, size_t *bufferSizeRet);
331
332/**
333 * \ingroup compilation
334 * \brief Get the Compiler/Verifier Message.
335 *
336 * The NULL terminated message string is stored in the memory pointed to by
337 * \p buffer when the return value is NVVM_SUCCESS.
338 *
339 * \param [in] prog NVVM program.
340 * \param [out] buffer Compilation/Verification log.
341 * \return
342 * - \link ::nvvmResult NVVM_SUCCESS \endlink
343 * - \link ::nvvmResult NVVM_ERROR_INVALID_PROGRAM \endlink
344 */
345nvvmResult nvvmGetProgramLog(nvvmProgram prog, char *buffer);
346
347#ifdef __cplusplus
348}
349#endif /* __cplusplus */
350
351#endif /* NVVM_H */
352