Debian Codegraph @

subprojects/meson-docs/docs/markdown/Cuda-module.md

raw
1 ---
2 short-description: CUDA module
3 authors:
4 - name: Olexa Bilaniuk
5 years: [2019]
6 has-copyright: false
7 ...
8
9 # Unstable CUDA Module
10 _Since: 0.50.0_
11
12 This module provides helper functionality related to the CUDA Toolkit and
13 building code using it.
14
15
16 **Note**: this module is unstable. It is only provided as a technology preview.
17 Its API may change in arbitrary ways between releases or it might be removed
18 from Meson altogether.
19
20
21 ## Importing the module
22
23 The module may be imported as follows:
24
25 ``` meson
26 cuda = [[#import]]('unstable-cuda')
27 ```
28
29 It offers several useful functions that are enumerated below.
30
31
32 ## Functions
33
34 ### `nvcc_arch_flags()`
35 _Since: 0.50.0_
36
37 ``` meson
38 cuda.nvcc_arch_flags(cuda_version_string, ...,
39 detected: string_or_array)
40 ```
41
42 Returns a list of `-gencode` flags that should be passed to `cuda_args:` in
43 order to compile a "fat binary" for the architectures/compute capabilities
44 enumerated in the positional argument(s). The flags shall be acceptable to
45 an NVCC with CUDA Toolkit version string `cuda_version_string`.
46
47 A set of architectures and/or compute capabilities may be specified by:
48
49 - The single positional argument `'All'`, `'Common'` or `'Auto'`
50 - As (an array of)
51 - Architecture names (`'Kepler'`, `'Maxwell+Tegra'`, `'Turing'`) and/or
52 - Compute capabilities (`'3.0'`, `'3.5'`, `'5.3'`, `'7.5'`)
53
54 A suffix of `+PTX` requests PTX code generation for the given architecture.
55 A compute capability given as `A.B(X.Y)` requests PTX generation for an older
56 virtual architecture `X.Y` before binary generation for a newer architecture
57 `A.B`.
58
59 Multiple architectures and compute capabilities may be passed in using
60
61 - Multiple positional arguments
62 - Lists of strings
63 - Space (` `), comma (`,`) or semicolon (`;`)-separated strings
64
65 The single-word architectural sets `'All'`, `'Common'` or `'Auto'`
66 cannot be mixed with architecture names or compute capabilities. Their
67 interpretation is:
68
69 | Name | Compute Capability |
70 |-------------------|--------------------|
71 | `'All'` | All CCs supported by given NVCC compiler. |
72 | `'Common'` | Relatively common CCs supported by given NVCC compiler. Generally excludes Tegra and Tesla devices. |
73 | `'Auto'` | The CCs provided by the `detected:` keyword, filtered for support by given NVCC compiler. |
74
75 The supported architecture names and their corresponding compute capabilities
76 are:
77
78 | Name | Compute Capability |
79 |-------------------|--------------------|
80 | `'Fermi'` | 2.0, 2.1(2.0) |
81 | `'Kepler'` | 3.0, 3.5 |
82 | `'Kepler+Tegra'` | 3.2 |
83 | `'Kepler+Tesla'` | 3.7 |
84 | `'Maxwell'` | 5.0, 5.2 |
85 | `'Maxwell+Tegra'` | 5.3 |
86 | `'Pascal'` | 6.0, 6.1 |
87 | `'Pascal+Tegra'` | 6.2 |
88 | `'Volta'` | 7.0 |
89 | `'Xavier'` | 7.2 |
90 | `'Turing'` | 7.5 |
91 | `'Ampere'` | 8.0, 8.6 |
92
93
94 Examples:
95
96 cuda.nvcc_arch_flags('10.0', '3.0', '3.5', '5.0+PTX')
97 cuda.nvcc_arch_flags('10.0', ['3.0', '3.5', '5.0+PTX'])
98 cuda.nvcc_arch_flags('10.0', [['3.0', '3.5'], '5.0+PTX'])
99 cuda.nvcc_arch_flags('10.0', '3.0 3.5 5.0+PTX')
100 cuda.nvcc_arch_flags('10.0', '3.0,3.5,5.0+PTX')
101 cuda.nvcc_arch_flags('10.0', '3.0;3.5;5.0+PTX')
102 cuda.nvcc_arch_flags('10.0', 'Kepler 5.0+PTX')
103 # Returns ['-gencode', 'arch=compute_30,code=sm_30',
104 # '-gencode', 'arch=compute_35,code=sm_35',
105 # '-gencode', 'arch=compute_50,code=sm_50',
106 # '-gencode', 'arch=compute_50,code=compute_50']
107
108 cuda.nvcc_arch_flags('10.0', '3.5(3.0)')
109 # Returns ['-gencode', 'arch=compute_30,code=sm_35']
110
111 cuda.nvcc_arch_flags('8.0', 'Common')
112 # Returns ['-gencode', 'arch=compute_30,code=sm_30',
113 # '-gencode', 'arch=compute_35,code=sm_35',
114 # '-gencode', 'arch=compute_50,code=sm_50',
115 # '-gencode', 'arch=compute_52,code=sm_52',
116 # '-gencode', 'arch=compute_60,code=sm_60',
117 # '-gencode', 'arch=compute_61,code=sm_61',
118 # '-gencode', 'arch=compute_61,code=compute_61']
119
120 cuda.nvcc_arch_flags('9.2', 'Auto', detected: '6.0 6.0 6.0 6.0')
121 cuda.nvcc_arch_flags('9.2', 'Auto', detected: ['6.0', '6.0', '6.0', '6.0'])
122 # Returns ['-gencode', 'arch=compute_60,code=sm_60']
123
124 cuda.nvcc_arch_flags(nvcc, 'All')
125 # Returns ['-gencode', 'arch=compute_20,code=sm_20',
126 # '-gencode', 'arch=compute_20,code=sm_21',
127 # '-gencode', 'arch=compute_30,code=sm_30',
128 # '-gencode', 'arch=compute_32,code=sm_32',
129 # '-gencode', 'arch=compute_35,code=sm_35',
130 # '-gencode', 'arch=compute_37,code=sm_37',
131 # '-gencode', 'arch=compute_50,code=sm_50', # nvcc.version() < 7.0
132 # '-gencode', 'arch=compute_52,code=sm_52',
133 # '-gencode', 'arch=compute_53,code=sm_53', # nvcc.version() >= 7.0
134 # '-gencode', 'arch=compute_60,code=sm_60',
135 # '-gencode', 'arch=compute_61,code=sm_61', # nvcc.version() >= 8.0
136 # '-gencode', 'arch=compute_70,code=sm_70',
137 # '-gencode', 'arch=compute_72,code=sm_72', # nvcc.version() >= 9.0
138 # '-gencode', 'arch=compute_75,code=sm_75'] # nvcc.version() >= 10.0
139
140 _Note:_ This function is intended to closely replicate CMake's FindCUDA module
141 function `CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable, [list of CUDA compute architectures])`
142
143
144
145 ### `nvcc_arch_readable()`
146 _Since: 0.50.0_
147
148 ``` meson
149 cuda.nvcc_arch_readable(cuda_version_string, ...,
150 detected: string_or_array)
151 ```
152
153 Has precisely the same interface as [`nvcc_arch_flags()`](#nvcc_arch_flags),
154 but rather than returning a list of flags, it returns a "readable" list of
155 architectures that will be compiled for. The output of this function is solely
156 intended for informative message printing.
157
158 archs = '3.0 3.5 5.0+PTX'
159 readable = cuda.nvcc_arch_readable('10.0', archs)
160 message('Building for architectures ' + ' '.join(readable))
161
162 This will print
163
164 Message: Building for architectures sm30 sm35 sm50 compute50
165
166 _Note:_ This function is intended to closely replicate CMake's
167 FindCUDA module function `CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable,
168 [list of CUDA compute architectures])`
169
170
171
172 ### `min_driver_version()`
173 _Since: 0.50.0_
174
175 ``` meson
176 cuda.min_driver_version(cuda_version_string)
177 ```
178
179 Returns the minimum NVIDIA proprietary driver version required, on the
180 host system, by kernels compiled with a CUDA Toolkit with the given
181 version string.
182
183 The output of this function is generally intended for informative
184 message printing, but could be used for assertions or to conditionally
185 enable features known to exist within the minimum NVIDIA driver
186 required.