codekingpro/portable-devtools
114k
1/*
2 * NVIDIA_COPYRIGHT_BEGIN
3 *
4 * Copyright (c) 2022-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 nvJitLink_INCLUDED
16#define nvJitLink_INCLUDED
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22#include <stdint.h>
23#include <stdlib.h>
24
25/**
26 *
27 * \defgroup error Error codes
28 *
29 */
30
31/** \ingroup error
32 *
33 * \brief The enumerated type nvJitLinkResult defines API call result codes.
34 * nvJitLink APIs return nvJitLinkResult codes to indicate the result.
35 */
36
37typedef enum {
38 NVJITLINK_SUCCESS = 0,
39 NVJITLINK_ERROR_UNRECOGNIZED_OPTION,
40 NVJITLINK_ERROR_MISSING_ARCH, // -arch=sm_NN option not specified
41 NVJITLINK_ERROR_INVALID_INPUT,
42 NVJITLINK_ERROR_PTX_COMPILE,
43 NVJITLINK_ERROR_NVVM_COMPILE,
44 NVJITLINK_ERROR_INTERNAL,
45 NVJITLINK_ERROR_THREADPOOL,
46 NVJITLINK_ERROR_UNRECOGNIZED_INPUT,
47#ifdef NEW_ERROR_CODES // These error codes will appear in a future CUDA release.
48 NVJITLINK_ERROR_NULL_INPUT,
49 NVJITLINK_ERROR_INCOMPATIBLE_OPTIONS,
50 NVJITLINK_ERROR_INCORRECT_INPUT_TYPE,
51 NVJITLINK_ERROR_ARCH_MISMATCH,
52 NVJITLINK_ERROR_OUTDATED_LIBRARY,
53 NVJITLINK_ERROR_MISSING_FATBIN
54#endif
55} nvJitLinkResult;
56
57#ifndef NEW_ERROR_CODES // To avoid breaking compatibility, we map them to existing error codes for now.
58#define NVJITLINK_ERROR_NULL_INPUT NVJITLINK_ERROR_INVALID_INPUT
59#define NVJITLINK_ERROR_INCOMPATIBLE_OPTIONS NVJITLINK_ERROR_INVALID_INPUT
60#define NVJITLINK_ERROR_INCORRECT_INPUT_TYPE NVJITLINK_ERROR_INVALID_INPUT
61#define NVJITLINK_ERROR_ARCH_MISMATCH NVJITLINK_ERROR_INTERNAL
62#define NVJITLINK_ERROR_OUTDATED_LIBRARY NVJITLINK_ERROR_INTERNAL
63#define NVJITLINK_ERROR_MISSING_FATBIN NVJITLINK_ERROR_INVALID_INPUT
64#endif
65
66/**
67 *
68 * \defgroup linking Linking
69 *
70 */
71
72/** \ingroup linking
73 *
74 * \brief The enumerated type nvJitLinkInputType defines the kind of inputs
75 * that can be passed to nvJitLinkAdd* APIs.
76 */
77
78typedef enum {
79 NVJITLINK_INPUT_NONE = 0, // error
80 NVJITLINK_INPUT_CUBIN = 1,
81 NVJITLINK_INPUT_PTX,
82 NVJITLINK_INPUT_LTOIR,
83 NVJITLINK_INPUT_FATBIN,
84 NVJITLINK_INPUT_OBJECT,
85 NVJITLINK_INPUT_LIBRARY,
86 NVJITLINK_INPUT_ANY = 10 // will dynamically determine one of above types
87} nvJitLinkInputType;
88
89/**
90 * \defgroup options Supported Link Options
91 *
92 * nvJitLink supports the link options below.
93 * Option names are prefixed with a single dash (\c -).
94 * Options that take a value have an assignment operator (\c =)
95 * followed by the option value, with no spaces, e.g. \c "-arch=sm_90".
96 *
97 * The supported options are:
98 * - \c -arch=sm_<N\> \n
99 * Pass SM architecture value. See nvcc for valid values of <N\>.
100 * Can use compute_<N\> value instead if only generating PTX.
101 * This is a required option.
102 * - \c -maxrregcount=<N\> \n
103 * Maximum register count.
104 * - \c -time \n
105 * Print timing information to InfoLog.
106 * - \c -verbose \n
107 * Print verbose messages to InfoLog.
108 * - \c -lto \n
109 * Do link time optimization.
110 * - \c -ptx \n
111 * Emit ptx after linking instead of cubin; only supported with \c -lto
112 * - \c -O<N\> \n
113 * Optimization level. Only 0 and 3 are accepted.
114 * - \c -g \n
115 * Generate debug information.
116 * - \c -lineinfo \n
117 * Generate line information.
118 * - \c -ftz=<n\> \n
119 * Flush to zero.
120 * - \c -prec-div=<n\> \n
121 * Precise divide.
122 * - \c -prec-sqrt=<n\> \n
123 * Precise square root.
124 * - \c -fma=<n\> \n
125 * Fast multiply add.
126 * - \c -kernels-used=<name\> \n
127 * Pass list of kernels that are used; any not in the list can be removed.
128 * This option can be specified multiple times.
129 * - \c -variables-used=<name\> \n
130 * Pass list of variables that are used; any not in the list can be removed.
131 * This option can be specified multiple times.
132 * - \c -optimize-unused-variables \n
133 * Normally device code optimization is limited by not knowing what the
134 * host code references. With this option it can assume that if a variable
135 * is not referenced in device code then it can be removed.
136 * - \c -Xptxas=<opt\> \n
137 * Pass <opt\> to ptxas. This option can be called multiple times.
138 * - \c -split-compile=<N\> \n
139 * Split compilation maximum thread count. Use 0 to use all available processors.
140 * Value of 1 disables split compilation (default).
141 * - \c -split-compile-extended=<N\> \n
142 * [Experimental] A more aggressive form of split compilation.
143 * Accepts a maximum thread count value. Use 0 to use all available processors.
144 * Value of 1 disables extended split compilation (default).
145 * - \c -jump-table-density=<N\> \n
146 * When doing LTO, specify the case density percentage in switch statements,
147 * and use it as a minimal threshold to determine whether jump table(brx.idx
148 * instruction) will be used to implement a switch statement. Default
149 * value is 101. The percentage ranges from 0 to 101 inclusively.
150 */
151
152/**
153 * \ingroup linking
154 * \brief nvJitLinkHandle is the unit of linking, and an opaque handle for
155 * a program.
156 *
157 * To link inputs, an instance of nvJitLinkHandle must be created first with
158 * nvJitLinkCreate().
159 */
160
161typedef struct nvJitLink* nvJitLinkHandle; // opaque handle
162
163// For versioning we will have separate API version for each library version
164
165extern nvJitLinkResult __nvJitLinkCreate_12_4(
166 nvJitLinkHandle *handle,
167 uint32_t numOptions,
168 const char **options);
169/**
170 * \ingroup linking
171 * \brief nvJitLinkCreate creates an instance of nvJitLinkHandle with the
172 * given input options, and sets the output parameter \p handle.
173 *
174 * \param [out] handle Address of nvJitLink handle.
175 * \param [in] numOptions Number of options passed.
176 * \param [in] options Array of size \p numOptions of option strings.
177 * \return
178 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
179 * - \link #nvJitLinkResult NVJITLINK_ERROR_UNRECOGNIZED_OPTION\endlink
180 * - \link #nvJitLinkResult NVJITLINK_ERROR_MISSING_ARCH\endlink
181 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
182 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
183 *
184 * It supports options listed in \ref options.
185 *
186 * \see nvJitLinkDestroy
187 */
188#ifndef NVJITLINK_NO_INLINE
189static inline nvJitLinkResult nvJitLinkCreate(
190 nvJitLinkHandle *handle,
191 uint32_t numOptions,
192 const char **options)
193{
194 return __nvJitLinkCreate_12_4 (handle, numOptions, options);
195}
196#endif
197
198extern nvJitLinkResult __nvJitLinkDestroy_12_4 (nvJitLinkHandle *handle);
199/**
200 * \ingroup linking
201 * \brief nvJitLinkDestroy frees the memory associated with the given handle
202 * and sets it to NULL.
203 *
204 * \param [in] handle Address of nvJitLink handle.
205 * \return
206 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
207 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
208 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
209 *
210 * \see nvJitLinkCreate
211 */
212#ifndef NVJITLINK_NO_INLINE
213static inline nvJitLinkResult nvJitLinkDestroy (nvJitLinkHandle *handle)
214{
215 return __nvJitLinkDestroy_12_4 (handle);
216}
217#endif
218
219extern nvJitLinkResult __nvJitLinkAddData_12_4(
220 nvJitLinkHandle handle,
221 nvJitLinkInputType inputType,
222 const void *data,
223 size_t size,
224 const char *name); // name can be null
225/**
226 * \ingroup linking
227 * \brief nvJitLinkAddData adds data image to the link.
228 *
229 * \param [in] handle nvJitLink handle.
230 * \param [in] inputType kind of input.
231 * \param [in] data pointer to data image in memory.
232 * \param [in] size size of the data.
233 * \param [in] name name of input object.
234 * \return
235 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
236 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
237 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
238 */
239#ifndef NVJITLINK_NO_INLINE
240static inline nvJitLinkResult nvJitLinkAddData(
241 nvJitLinkHandle handle,
242 nvJitLinkInputType inputType,
243 const void *data,
244 size_t size,
245 const char *name) // name can be null
246{
247 return __nvJitLinkAddData_12_4 (handle, inputType, data, size, name);
248}
249#endif
250
251extern nvJitLinkResult __nvJitLinkAddFile_12_4(
252 nvJitLinkHandle handle,
253 nvJitLinkInputType inputType,
254 const char *fileName); // includes path to file
255/**
256 * \ingroup linking
257 * \brief nvJitLinkAddFile reads data from file and links it in.
258 *
259 * \param [in] handle nvJitLink handle.
260 * \param [in] inputType kind of input.
261 * \param [in] fileName name of file.
262 * \return
263 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
264 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
265 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
266 */
267#ifndef NVJITLINK_NO_INLINE
268static inline nvJitLinkResult nvJitLinkAddFile(
269 nvJitLinkHandle handle,
270 nvJitLinkInputType inputType,
271 const char *fileName) // includes path to file
272{
273 return __nvJitLinkAddFile_12_4 (handle, inputType, fileName);
274}
275#endif
276
277extern nvJitLinkResult __nvJitLinkComplete_12_4 (nvJitLinkHandle handle);
278/**
279 * \ingroup linking
280 * \brief nvJitLinkComplete does the actual link.
281 *
282 * \param [in] handle nvJitLink handle.
283 * \return
284 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
285 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
286 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
287 */
288#ifndef NVJITLINK_NO_INLINE
289static inline nvJitLinkResult nvJitLinkComplete (nvJitLinkHandle handle)
290{
291 return __nvJitLinkComplete_12_4 (handle);
292}
293#endif
294
295extern nvJitLinkResult __nvJitLinkGetLinkedCubinSize_12_4(
296 nvJitLinkHandle handle,
297 size_t *size);
298/**
299 * \ingroup linking
300 * \brief nvJitLinkGetLinkedCubinSize gets the size of the linked cubin.
301 *
302 * \param [in] handle nvJitLink handle.
303 * \param [out] size Size of the linked cubin.
304 * \return
305 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
306 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
307 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
308 *
309 * \see nvJitLinkGetLinkedCubin
310 */
311#ifndef NVJITLINK_NO_INLINE
312static inline nvJitLinkResult nvJitLinkGetLinkedCubinSize(
313 nvJitLinkHandle handle,
314 size_t *size)
315{
316 return __nvJitLinkGetLinkedCubinSize_12_4 (handle, size);
317}
318#endif
319
320extern nvJitLinkResult __nvJitLinkGetLinkedCubin_12_4(
321 nvJitLinkHandle handle,
322 void *cubin);
323/**
324 * \ingroup linking
325 * \brief nvJitLinkGetLinkedCubin gets the linked cubin.
326 *
327 * \param [in] handle nvJitLink handle.
328 * \param [out] cubin The linked cubin.
329 * \return
330 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
331 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
332 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
333 *
334 * User is responsible for allocating enough space to hold the \p cubin.
335 * \see nvJitLinkGetLinkedCubinSize
336 */
337#ifndef NVJITLINK_NO_INLINE
338static inline nvJitLinkResult nvJitLinkGetLinkedCubin(
339 nvJitLinkHandle handle,
340 void *cubin)
341{
342 return __nvJitLinkGetLinkedCubin_12_4 (handle, cubin);
343}
344#endif
345
346extern nvJitLinkResult __nvJitLinkGetLinkedPtxSize_12_4(
347 nvJitLinkHandle handle,
348 size_t *size);
349/**
350 * \ingroup linking
351 * \brief nvJitLinkGetLinkedPtxSize gets the size of the linked ptx.
352 *
353 * \param [in] handle nvJitLink handle.
354 * \param [out] size Size of the linked PTX.
355 * \return
356 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
357 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
358 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
359 *
360 * Linked PTX is only available when using the \c -lto option.
361 * \see nvJitLinkGetLinkedPtx
362 */
363#ifndef NVJITLINK_NO_INLINE
364static inline nvJitLinkResult nvJitLinkGetLinkedPtxSize(
365 nvJitLinkHandle handle,
366 size_t *size)
367{
368 return __nvJitLinkGetLinkedPtxSize_12_4 (handle, size);
369}
370#endif
371
372extern nvJitLinkResult __nvJitLinkGetLinkedPtx_12_4(
373 nvJitLinkHandle handle,
374 char *ptx);
375/**
376 * \ingroup linking
377 * \brief nvJitLinkGetLinkedPtx gets the linked ptx.
378 *
379 * \param [in] handle nvJitLink handle.
380 * \param [out] ptx The linked PTX.
381 * \return
382 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
383 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
384 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
385 *
386 * Linked PTX is only available when using the \c -lto option.
387 * User is responsible for allocating enough space to hold the \p ptx.
388 * \see nvJitLinkGetLinkedPtxSize
389 */
390#ifndef NVJITLINK_NO_INLINE
391static inline nvJitLinkResult nvJitLinkGetLinkedPtx(
392 nvJitLinkHandle handle,
393 char *ptx)
394{
395 return __nvJitLinkGetLinkedPtx_12_4 (handle, ptx);
396}
397#endif
398
399extern nvJitLinkResult __nvJitLinkGetErrorLogSize_12_4(
400 nvJitLinkHandle handle,
401 size_t *size);
402/**
403 * \ingroup linking
404 * \brief nvJitLinkGetErrorLogSize gets the size of the error log.
405 *
406 * \param [in] handle nvJitLink handle.
407 * \param [out] size Size of the error log.
408 * \return
409 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
410 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
411 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
412 *
413 * \see nvJitLinkGetErrorLog
414 */
415#ifndef NVJITLINK_NO_INLINE
416static inline nvJitLinkResult nvJitLinkGetErrorLogSize(
417 nvJitLinkHandle handle,
418 size_t *size)
419{
420 return __nvJitLinkGetErrorLogSize_12_4 (handle, size);
421}
422#endif
423
424extern nvJitLinkResult __nvJitLinkGetErrorLog_12_4(
425 nvJitLinkHandle handle,
426 char *log);
427/**
428 * \ingroup linking
429 * \brief nvJitLinkGetErrorLog puts any error messages in the log.
430 *
431 * \param [in] handle nvJitLink handle.
432 * \param [out] log The error log.
433 * \return
434 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
435 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
436 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
437 *
438 * User is responsible for allocating enough space to hold the \p log.
439 * \see nvJitLinkGetErrorLogSize
440 */
441#ifndef NVJITLINK_NO_INLINE
442static inline nvJitLinkResult nvJitLinkGetErrorLog(
443 nvJitLinkHandle handle,
444 char *log)
445{
446 return __nvJitLinkGetErrorLog_12_4 (handle, log);
447}
448#endif
449
450extern nvJitLinkResult __nvJitLinkGetInfoLogSize_12_4(
451 nvJitLinkHandle handle,
452 size_t *size);
453/**
454 * \ingroup linking
455 * \brief nvJitLinkGetInfoLogSize gets the size of the info log.
456 *
457 * \param [in] handle nvJitLink handle.
458 * \param [out] size Size of the info log.
459 * \return
460 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
461 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
462 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
463 *
464 * \see nvJitLinkGetInfoLog
465 */
466#ifndef NVJITLINK_NO_INLINE
467static inline nvJitLinkResult nvJitLinkGetInfoLogSize(
468 nvJitLinkHandle handle,
469 size_t *size)
470{
471 return __nvJitLinkGetInfoLogSize_12_4 (handle, size);
472}
473#endif
474
475extern nvJitLinkResult __nvJitLinkGetInfoLog_12_4(
476 nvJitLinkHandle handle,
477 char *log);
478/**
479 * \ingroup linking
480 * \brief nvJitLinkGetInfoLog puts any info messages in the log.
481 *
482 * \param [in] handle nvJitLink handle.
483 * \param [out] log The info log.
484 * \return
485 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
486 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
487 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
488 *
489 * User is responsible for allocating enough space to hold the \p log.
490 * \see nvJitLinkGetInfoLogSize
491 */
492#ifndef NVJITLINK_NO_INLINE
493static inline nvJitLinkResult nvJitLinkGetInfoLog(
494 nvJitLinkHandle handle,
495 char *log)
496{
497 return __nvJitLinkGetInfoLog_12_4 (handle, log);
498}
499#endif
500
501/**
502 * \ingroup linking
503 * \brief nvJitLinkVersion returns the current version of nvJitLink.
504 *
505 * \param [out] major The major version.
506 * \param [out] minor The minor version.
507 * \return
508 * - \link #nvJitLinkResult NVJITLINK_SUCCESS \endlink
509 * - \link #nvJitLinkResult NVJITLINK_ERROR_INVALID_INPUT\endlink
510 * - \link #nvJitLinkResult NVJITLINK_ERROR_INTERNAL\endlink
511 *
512 */
513extern nvJitLinkResult nvJitLinkVersion(
514 unsigned int *major,
515 unsigned int *minor);
516
517#ifdef __cplusplus
518}
519#endif
520
521#endif // nvJitLink_INCLUDED
522
523