Coverage for cuda/bindings/nvvm.pyx: 91.04%

1# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. (empty)

2# 

3# SPDX-License-Identifier: Apache-2.0 

4# 

5# This code was automatically generated across versions from 12.0.1 to 13.4.1. Do not modify it directly. 

6# CYTHON-BINDINGS-GENERATED-DO-NOT-MODIFY-THIS-FILE: format=1; content-sha256=d8933fb727fe70e6c790346a9c502409553a5f982b92288b6044a85229e6ce48 

7  

8  

9# <<<< PREAMBLE CONTENT >>>> 

10  

11cimport cpython as _cyb_cpython 

12from cuda.bindings._internal.utils cimport ( 

13 get_nested_resource_ptr as _cyb_get_nested_resource_ptr, 

14 nested_resource as _cyb_nested_resource, 

15) 

16from libc.stdint cimport intptr_t 

17  

18from cuda.bindings._internal._fast_enum import FastEnum as _cyb_FastEnum (empty)

19  

20cdef intptr_t _cyb_get_buffer_pointer(buf, Py_ssize_t size, readonly=True) except?-1: (empty)

21 cdef intptr_t ptr 

22 cdef int flags = _cyb_cpython.PyBUF_ANY_CONTIGUOUS 30 ctx1aCDjklmnobcdefghiABuvwxyzprqst

23 if not readonly: 30 ctx1aCDjklmnobcdefghiABuvwxyzprqst

24 flags |= _cyb_cpython.PyBUF_WRITABLE 16 ctx1jklmnobcdefghiAB

25 cdef int status = -1 30 ctx1aCDjklmnobcdefghiABuvwxyzprqst

26 cdef _cyb_cpython.Py_buffer view 

27 if buf is None: 30 ctx1aCDjklmnobcdefghiABuvwxyzprqst

28 ptr = 0 2 ctx1CD

29 elif isinstance(buf, int): 28 ctx1ajklmnobcdefghiABuvwxyzprqst

30 ptr = <intptr_t>buf 

31 else: 

32 try: 28 ctx1ajklmnobcdefghiABuvwxyzprqst

33 status = _cyb_cpython.PyObject_GetBuffer(buf, &view, flags) 28 ctx1ajklmnobcdefghiABuvwxyzprqst

34 if size != -1: 28 ctx1ajklmnobcdefghiABuvwxyzprqst

35 assert view.len == size 26 ctx1ajklmnobcdefghiuvwxyzprqst

36 except Exception as e: 

37 adj = "writable " if not readonly else "" 

38 raise ValueError( 

39 "buf must be None, a Python int representing the pointer " 

40 f"address to a valid buffer, or a contiguous {adj}" 

41 f"buffer (a ctypes object, NumPy array, bytes, ...), of size {size}" 

42 ) from e 

43 else: 

44 ptr = <intptr_t>view.buf 28 ctx1ajklmnobcdefghiABuvwxyzprqst

45 finally: 

46 if status == 0: 28 ctx1ajklmnobcdefghiABuvwxyzprqst

47 _cyb_cpython.PyBuffer_Release(&view) 28 ctx1ajklmnobcdefghiABuvwxyzprqst

48 return ptr 30 ctx1aCDjklmnobcdefghiABuvwxyzprqst

49  

50  

51# <<<< END OF PREAMBLE CONTENT >>>> 

52  

53cimport cython # NOQA 

54  

55from ._internal.utils cimport (get_nested_resource_ptr, 

56 nested_resource) 

57  

58  

59############################################################################### 

60# Enum 

61############################################################################### 

62  

63class Result(_cyb_FastEnum): (empty)

64 """ 

65 NVVM API call result code. 

66  

67 See `nvvmResult`. 

68 """ 

69 SUCCESS = NVVM_SUCCESS (empty)

70 ERROR_OUT_OF_MEMORY = NVVM_ERROR_OUT_OF_MEMORY (empty)

71 ERROR_PROGRAM_CREATION_FAILURE = NVVM_ERROR_PROGRAM_CREATION_FAILURE (empty)

72 ERROR_IR_VERSION_MISMATCH = NVVM_ERROR_IR_VERSION_MISMATCH (empty)

73 ERROR_INVALID_INPUT = NVVM_ERROR_INVALID_INPUT (empty)

74 ERROR_INVALID_PROGRAM = NVVM_ERROR_INVALID_PROGRAM (empty)

75 ERROR_INVALID_IR = NVVM_ERROR_INVALID_IR (empty)

76 ERROR_INVALID_OPTION = NVVM_ERROR_INVALID_OPTION (empty)

77 ERROR_NO_MODULE_IN_PROGRAM = NVVM_ERROR_NO_MODULE_IN_PROGRAM (empty)

78 ERROR_COMPILATION = NVVM_ERROR_COMPILATION (empty)

79 ERROR_CANCELLED = NVVM_ERROR_CANCELLED (empty)

80  

81  

82############################################################################### 

83# Error handling 

84############################################################################### 

85  

86class nvvmError(Exception): (empty)

87  

88 def __init__(self, status): (empty)

89 self.status = status 13 ctx1CDjklmnoEF*pq

90 s = Result(status) 13 ctx1CDjklmnoEF*pq

91 cdef str err = f"{s.name} ({s.value})" 13 ctx1CDjklmnoEF*pq

92 super(nvvmError, self).__init__(err) 13 ctx1CDjklmnoEF*pq

93  

94 def __reduce__(self): (empty)

95 return (type(self), (self.status,)) 

96  

97  

98@cython.profile(False) (empty)

99cdef int check_status(int status) except 1 nogil: 

100 if status != 0: 69 ctx1aCDjSkTlUmVnoEFbWcXdYeZf0g1h2i3GAB4R5u6v7w8x9y!z#$%'()HIJKLMNOPQprqst

101 with gil: 12 ctx1CDjklmnoEFpq

102 raise nvvmError(status) 12 ctx1CDjklmnoEFpq

103 return status 69 ctx1aCDjSkTlUmVnoEFbWcXdYeZf0g1h2i3GAB4R5u6v7w8x9y!z#$%'()HIJKLMNOPQprqst

104  

105  

106############################################################################### 

107# Wrapper functions 

108############################################################################### 

109  

110cpdef destroy_program(intptr_t prog): (empty)

111 """Destroy a program. 

112  

113 Args: 

114 prog (intptr_t): nvvm prog. 

115  

116 .. seealso:: `nvvmDestroyProgram` 

117 """ 

118 cdef Program p = <Program>prog 33 ctx1aCDjklmnoEFbcdefghiGABuvwxyzprqst

119 with nogil: 33 ctx1aCDjklmnoEFbcdefghiGABuvwxyzprqst

120 status = nvvmDestroyProgram(&p) 33 ctx1aCDjklmnoEFbcdefghiGABuvwxyzprqst

121 check_status(status) 33 ctx1aCDjklmnoEFbcdefghiGABuvwxyzprqst

122  

123  

124cpdef str get_error_string(int result): (empty)

125 """Get the message string for the given ``nvvmResult`` code. 

126  

127  

128 Args: 

129 result (Result): NVVM API result code. 

130  

131 .. seealso:: `nvvmGetErrorString` 

132 """ 

133 cdef const char *_output_cstr_ 

134 cdef bytes _output_ 

135 with nogil: 1 ctx1+

136 _output_cstr_ = nvvmGetErrorString(<_Result>result) 1 ctx1+

137 _output_ = _output_cstr_ 1 ctx1+

138 return _output_.decode() 1 ctx1+

139  

140  

141cpdef tuple version(): (empty)

142 """Get the NVVM version. 

143  

144  

145 Returns: 

146 A 2-tuple containing: 

147 - int: NVVM major version number. 

148 - int: NVVM minor version number. 

149  

150 .. seealso:: `nvvmVersion` 

151 """ 

152 cdef int major 

153 cdef int minor 

154 with nogil: 12 ctx1a5HIJKLMNOPQ

155 __status__ = nvvmVersion(&major, &minor) 12 ctx1a5HIJKLMNOPQ

156 check_status(__status__) 12 ctx1a5HIJKLMNOPQ

157 return (major, minor) 12 ctx1a5HIJKLMNOPQ

158  

159  

160cpdef tuple ir_version(): (empty)

161 """Get the NVVM IR version. 

162  

163  

164 Returns: 

165 A 4-tuple containing: 

166 - int: NVVM IR major version number. 

167 - int: NVVM IR minor version number. 

168 - int: NVVM IR debug metadata major version number. 

169 - int: NVVM IR debug metadata minor version number. 

170  

171 .. seealso:: `nvvmIRVersion` 

172 """ 

173 cdef int major_ir 

174 cdef int minor_ir 

175 cdef int major_dbg 

176 cdef int minor_dbg 

177 with nogil: 40 ctx1aSTUVWXYZ012346789!#$%'()HIJKLMNOPQprqst

178 __status__ = nvvmIRVersion(&major_ir, &minor_ir, &major_dbg, &minor_dbg) 40 ctx1aSTUVWXYZ012346789!#$%'()HIJKLMNOPQprqst

179 check_status(__status__) 40 ctx1aSTUVWXYZ012346789!#$%'()HIJKLMNOPQprqst

180 return (major_ir, minor_ir, major_dbg, minor_dbg) 40 ctx1aSTUVWXYZ012346789!#$%'()HIJKLMNOPQprqst

181  

182  

183cpdef intptr_t create_program() except? 0: (empty)

184 """Create a program, and set the value of its handle to ``*prog``. 

185  

186  

187 Returns: 

188 intptr_t: NVVM program. 

189  

190 .. seealso:: `nvvmCreateProgram` 

191 """ 

192 cdef Program prog 

193 with nogil: 33 ctx1aCDjklmnoEFbcdefghiGABuvwxyzprqst

194 __status__ = nvvmCreateProgram(&prog) 33 ctx1aCDjklmnoEFbcdefghiGABuvwxyzprqst

195 check_status(__status__) 33 ctx1aCDjklmnoEFbcdefghiGABuvwxyzprqst

196 return <intptr_t>prog 33 ctx1aCDjklmnoEFbcdefghiGABuvwxyzprqst

197  

198  

199cpdef add_module_to_program(intptr_t prog, buffer, size_t size, name): (empty)

200 """Add a module level NVVM IR to a program. 

201  

202 The ``buffer`` should contain an NVVM IR module. The module should have NVVM IR 

203 either in the LLVM 7.0.1 bitcode representation or in the LLVM 7.0.1 text 

204 representation. Support for reading the text representation of NVVM IR is 

205 deprecated and may be removed in a later version. 

206  

207 Args: 

208 prog (intptr_t): NVVM program. 

209 buffer (bytes): NVVM IR module in the bitcode or text 

210 representation. 

211 size (size_t): Size of the NVVM IR module. 

212 name (str): Name of the NVVM IR module. If NULL, "<unnamed>" is 

213 used as the name. 

214  

215 .. seealso:: `nvvmAddModuleToProgram` 

216 """ 

217 cdef void* _buffer_ = <void *>_cyb_get_buffer_pointer(buffer, size, readonly=True) 27 ctx1aCjklmnobcdefghiuvwxyzprqst

218 if not isinstance(name, str): 27 ctx1aCjklmnobcdefghiuvwxyzprqst

219 raise TypeError("name must be a Python str") 

220 cdef bytes _temp_name_ = (<str>name).encode() 27 ctx1aCjklmnobcdefghiuvwxyzprqst

221 cdef char* _name_ = _temp_name_ 27 ctx1aCjklmnobcdefghiuvwxyzprqst

222 with nogil: 27 ctx1aCjklmnobcdefghiuvwxyzprqst

223 __status__ = nvvmAddModuleToProgram(<Program>prog, <const char*>_buffer_, size, <const char*>_name_) 27 ctx1aCjklmnobcdefghiuvwxyzprqst

224 check_status(__status__) 27 ctx1aCjklmnobcdefghiuvwxyzprqst

225  

226  

227cpdef lazy_add_module_to_program(intptr_t prog, buffer, size_t size, name): (empty)

228 """Add a module level NVVM IR to a program. 

229  

230 The ``buffer`` should contain an NVVM IR module. The module should have NVVM IR 

231 in the LLVM 7.0.1 bitcode representation. 

232 A module added using this API is lazily loaded - the only symbols loaded are 

233 those that are required by module(s) loaded using nvvmAddModuleToProgram. It is 

234 an error for a program to have all modules loaded using this API. Compiler may 

235 also optimize entities in this module by making them internal to the linked 

236 NVVM IR module, making them eligible for other optimizations. Due to these 

237 optimizations, this API to load a module is more efficient and should be used 

238 where possible. 

239  

240 Args: 

241 prog (intptr_t): NVVM program. 

242 buffer (bytes): NVVM IR module in the bitcode representation. 

243 size (size_t): Size of the NVVM IR module. 

244 name (str): Name of the NVVM IR module. If NULL, "<unnamed>" is 

245 used as the name. 

246  

247 .. seealso:: `nvvmLazyAddModuleToProgram` 

248 """ 

249 cdef void* _buffer_ = <void *>_cyb_get_buffer_pointer(buffer, size, readonly=True) 1 ctx1D

250 if not isinstance(name, str): 1 ctx1D

251 raise TypeError("name must be a Python str") 

252 cdef bytes _temp_name_ = (<str>name).encode() 1 ctx1D

253 cdef char* _name_ = _temp_name_ 1 ctx1D

254 with nogil: 1 ctx1D

255 __status__ = nvvmLazyAddModuleToProgram(<Program>prog, <const char*>_buffer_, size, <const char*>_name_) 1 ctx1D

256 check_status(__status__) 1 ctx1D

257  

258  

259cpdef compile_program(intptr_t prog, int num_options, options): (empty)

260 """Compile the NVVM program. 

261  

262 The NVVM IR modules in the program will be linked at the IR level. The linked 

263 IR program is compiled to PTX. 

264 The target datalayout in the linked IR program is used to determine the address 

265 size (32bit vs 64bit). 

266 The valid compiler options are:. 

267  

268 - -g (enable generation of full debugging information). Full debug support is 

269 only valid with '-opt=0'. Debug support requires the input module to utilize 

270 NVVM IR Debug Metadata. Line number (line info) only generation is also 

271 enabled via NVVM IR Debug Metadata, there is no specific libNVVM API flag for 

272 that case. 

273 - -opt=. 

274 - 0 (disable optimizations). 

275 - 3 (default, enable optimizations). 

276 - -arch=. 

277 - compute_75 (default). 

278 - compute_80. 

279 - compute_87. 

280 - compute_89. 

281 - compute_90. 

282 - compute_90a. 

283 - compute_100. 

284 - compute_100a. 

285 - compute_100f. 

286 - compute_103. 

287 - compute_103a. 

288 - compute_103f. 

289 - compute_110. 

290 - compute_110a. 

291 - compute_110f. 

292 - compute_120. 

293 - compute_120a. 

294 - compute_120f. 

295 - compute_121. 

296 - compute_121a. 

297 - compute_121f. 

298 - -ftz=. 

299 - 0 (default, preserve denormal values, when performing single-precision 

300 floating-point operations). 

301 - 1 (flush denormal values to zero, when performing single-precision 

302 floating-point operations). 

303 - -prec-sqrt=. 

304 - 0 (use a faster approximation for single-precision floating-point square 

305 root). 

306 - 1 (default, use IEEE round-to-nearest mode for single-precision floating- 

307 point square root). 

308 - -prec-div=. 

309 - 0 (use a faster approximation for single-precision floating-point division 

310 and reciprocals). 

311 - 1 (default, use IEEE round-to-nearest mode for single-precision floating- 

312 point division and reciprocals). 

313 - -fma=. 

314 - 0 (disable FMA contraction). 

315 - 1 (default, enable FMA contraction). 

316 - -jump-table-density=[0-101] Specify the case density percentage in switch 

317 statements, and use it as a minimal threshold to determine whether jump 

318 table(brx.idx instruction) will be used to implement a switch statement. 

319 Default value is 101. The percentage ranges from 0 to 101 inclusively. 

320 - -gen-lto (Generate LTO IR instead of PTX). 

321 - -ptx-version-target=[86-94] Specify the target PTX version as (MAJOR VERSION 

322 \* 10 + MINOR VERSION). This is supported only for Blackwell and later 

323 architectures (compute capability compute_100 or greater). Using this option 

324 implies that the operations in incoming ``prog`` are compliant with targeted 

325 PTX version. If not set, highest available PTX version is used. 

326  

327 Args: 

328 prog (intptr_t): NVVM program. 

329 num_options (int): Number of compiler ``options`` passed. 

330 options (object): Compiler options in the form of C string array. It can be: 

331  

332 - an :class:`int` as the pointer address to the nested sequence, or 

333 - a Python sequence of :class:`int`\s, each of which is a pointer address 

334 to a valid sequence of 'char', or 

335 - a nested Python sequence of ``str``. 

336  

337 .. seealso:: `nvvmCompileProgram` 

338 """ 

339 cdef _cyb_nested_resource[ char ] _options_ 

340 _cyb_get_nested_resource_ptr[char](_options_, options, <char*>NULL) 18 ctx1ajlnEbcdefghiprqst

341 with nogil: 18 ctx1ajlnEbcdefghiprqst

342 __status__ = nvvmCompileProgram(<Program>prog, num_options, <const char**>(_options_.ptrs.data())) 18 ctx1ajlnEbcdefghiprqst

343 check_status(__status__) 18 ctx1ajlnEbcdefghiprqst

344  

345  

346cpdef verify_program(intptr_t prog, int num_options, options): (empty)

347 """Verify the NVVM program. 

348  

349 The valid compiler options are:. 

350 Same as for :func:`compile_program`. 

351  

352 Args: 

353 prog (intptr_t): NVVM program. 

354 num_options (int): Number of compiler ``options`` passed. 

355 options (object): Compiler options in the form of C string array. It can be: 

356  

357 - an :class:`int` as the pointer address to the nested sequence, or 

358 - a Python sequence of :class:`int`\s, each of which is a pointer address 

359 to a valid sequence of 'char', or 

360 - a nested Python sequence of ``str``. 

361  

362 .. seealso:: `nvvmVerifyProgram` 

363 """ 

364 cdef _cyb_nested_resource[ char ] _options_ 

365 _cyb_get_nested_resource_ptr[char](_options_, options, <char*>NULL) 10 ctx1kmoFuvwxyz

366 with nogil: 10 ctx1kmoFuvwxyz

367 __status__ = nvvmVerifyProgram(<Program>prog, num_options, <const char**>(_options_.ptrs.data())) 10 ctx1kmoFuvwxyz

368 check_status(__status__) 10 ctx1kmoFuvwxyz

369  

370  

371cpdef size_t get_compiled_result_size(intptr_t prog) except? 0: (empty)

372 """Get the size of the compiled result. 

373  

374  

375 Args: 

376 prog (intptr_t): NVVM program. 

377  

378 Returns: 

379 size_t: Size of the compiled result (including the trailing NULL). 

380  

381 .. seealso:: `nvvmGetCompiledResultSize` 

382 """ 

383 cdef size_t buffer_size_ret 

384 with nogil: 9 ctx1bcdefghiA

385 __status__ = nvvmGetCompiledResultSize(<Program>prog, &buffer_size_ret) 9 ctx1bcdefghiA

386 check_status(__status__) 9 ctx1bcdefghiA

387 return buffer_size_ret 9 ctx1bcdefghiA

388  

389  

390cpdef get_compiled_result(intptr_t prog, buffer): (empty)

391 """Get the compiled result. 

392  

393 The result is stored in the memory pointed to by ``buffer``. 

394  

395 Args: 

396 prog (intptr_t): NVVM program. 

397 buffer (bytes): Compiled result. 

398  

399 .. seealso:: `nvvmGetCompiledResult` 

400 """ 

401 cdef void* _buffer_ = <void *>_cyb_get_buffer_pointer(buffer, -1, readonly=False) 9 ctx1bcdefghiA

402 with nogil: 9 ctx1bcdefghiA

403 __status__ = nvvmGetCompiledResult(<Program>prog, <char*>_buffer_) 9 ctx1bcdefghiA

404 check_status(__status__) 9 ctx1bcdefghiA

405  

406  

407cpdef size_t get_program_log_size(intptr_t prog) except? 0: (empty)

408 """Get the Size of Compiler/Verifier Message. 

409  

410 The size of the message string (including the trailing NULL) is stored into 

411 ``buffer_size_ret`` when the return value is NVVM_SUCCESS. 

412  

413 Args: 

414 prog (intptr_t): NVVM program. 

415  

416 Returns: 

417 size_t: Size of the compilation/verification log (including the 

418 trailing NULL). 

419  

420 .. seealso:: `nvvmGetProgramLogSize` 

421 """ 

422 cdef size_t buffer_size_ret 

423 with nogil: 15 ctx1jklmnobcdefghiB

424 __status__ = nvvmGetProgramLogSize(<Program>prog, &buffer_size_ret) 15 ctx1jklmnobcdefghiB

425 check_status(__status__) 15 ctx1jklmnobcdefghiB

426 return buffer_size_ret 15 ctx1jklmnobcdefghiB

427  

428  

429cpdef get_program_log(intptr_t prog, buffer): (empty)

430 """Get the Compiler/Verifier Message. 

431  

432 The NULL terminated message string is stored in the memory pointed to by 

433 ``buffer`` when the return value is NVVM_SUCCESS. 

434  

435 Args: 

436 prog (intptr_t): NVVM program. 

437 buffer (bytes): Compilation/Verification log. 

438  

439 .. seealso:: `nvvmGetProgramLog` 

440 """ 

441 cdef void* _buffer_ = <void *>_cyb_get_buffer_pointer(buffer, -1, readonly=False) 15 ctx1jklmnobcdefghiB

442 with nogil: 15 ctx1jklmnobcdefghiB

443 __status__ = nvvmGetProgramLog(<Program>prog, <char*>_buffer_) 15 ctx1jklmnobcdefghiB

444 check_status(__status__) 15 ctx1jklmnobcdefghiB

445  

446  

447cpdef int llvm_version(arch) except? 0: (empty)

448 """Get the LLVM IR version guaranteed to be supported by NVVM. 

449  

450 The valid arch strings are the ones supported by :func:`compile_program`. 

451  

452 Args: 

453 arch (str): Architecture string. 

454  

455 Returns: 

456 int: IR version number. 

457  

458 .. seealso:: `nvvmLLVMVersion` 

459 """ 

460 if not isinstance(arch, str): 1 ctx1R

461 raise TypeError("arch must be a Python str") 

462 cdef bytes _temp_arch_ = (<str>arch).encode() 1 ctx1R

463 cdef char* _arch_ = _temp_arch_ 1 ctx1R

464 cdef int major 

465 with nogil: 1 ctx1R

466 __status__ = nvvmLLVMVersion(<const char*>_arch_, &major) 1 ctx1R

467 check_status(__status__) 1 ctx1R

468 return major 1 ctx1R

469del _cyb_FastEnum (empty)