OmniSciDB  d2f719934e
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
nvtx_helpers.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2021 OmniSci, Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #pragma once
18 
19 #ifdef HAVE_NVTX
20 #include <nvtx3/nvToolsExt.h>
21 #ifdef HAVE_CUDA
22 #include <nvtx3/nvToolsExtCuda.h>
23 #endif // HAVE_CUDA
24 #else // HAVE_NVTX
25 using nvtxDomainHandle_t = void*;
26 using nvtxRangeId_t = uint64_t;
27 #endif // HAVE_NVTX
28 
29 #ifdef HAVE_CUDA
30 #include <cuda.h>
31 #endif // HAVE_CUDA
32 
33 namespace nvtx_helpers {
34 
35 // Standard categories for the Omnisci domain
36 // Additional temporary categories can be named with name_domain_category().
37 // Permanent categories should be aded to the enum here and in nvtx_helpers.cpp
39 
40 #ifdef HAVE_NVTX
41 //
42 // Create / destroy domain and name categories
43 //
44 void init();
45 void shutdown();
46 
47 //
48 // Omnisci domain
49 //
50 
51 // Get the domain handle
52 // To add ranges to the domain that do not use the default categories, get the
53 // handle and use the domain_range_* functions. This allows using distinct colors or
54 // specialized categories
55 
56 // NOTE: The domain will be null if NVTX profiling is not enabled by the nsys launcher.
57 // The various nvtxDomain* function appear to check for this case, but if the caller does
58 // extra work for NVTX it's a good idea to check if the domain pointer is null first
60 
61 // Push and pop ranges
62 // Pass __FILE__ as the file param and it will be appended after name, or nullptr to
63 // ignore
64 void omnisci_range_push(Category c, const char* name, const char* file);
65 void omnisci_range_pop();
66 
67 [[nodiscard]] nvtxRangeId_t omnisci_range_start(Category c, const char* name);
69 
70 void omnisci_set_mark(Category c, const char* message);
71 
72 //
73 // Resource naming
74 //
75 // We need the OS thread ID, not the pthreads id for this method, so this is somewhat
76 // limiting since the only easy way to get the ID is by naming it from the thread itself
77 // TODO: use nvtxDomainResourceCreate to name a thread using a pthead identifier
78 void name_current_thread(const char* name);
79 
80 //
81 // Name Cuda resources
82 //
83 // Naming Cuda resources seems iffy (it doesn't always work)
84 #ifdef HAVE_CUDA
85 inline void name_cuda_device(CUdevice device, const char* name) {
86  nvtxNameCuDeviceA(device, name);
87 }
88 inline void name_cuda_context(CUcontext context, const char* name) {
89  nvtxNameCuContextA(context, name);
90 }
91 inline void name_cuda_stream(CUstream stream, const char* name) {
92  nvtxNameCuStreamA(stream, name);
93 }
94 inline void name_cuda_event(CUevent event, const char* name) {
95  nvtxNameCuEventA(event, name);
96 }
97 #endif // HAVE_CUDA
98 
99 // Name a category index. If using a custom category as part of the Omnisci domain, you
100 // must ensure the ID does not conflict with the Category enum above
101 inline void name_category(uint32_t category, const char* name) {
102  nvtxNameCategory(category, name);
103 }
104 
105 inline void name_domain_category(nvtxDomainHandle_t domain,
106  uint32_t category,
107  const char* name) {
108  nvtxDomainNameCategoryA(domain, category, name);
109 }
110 
111 //
112 // Wrappers for custom timeline usage outside the Omnisci domain
113 //
114 
115 // Create a basic event object
116 inline nvtxEventAttributes_t make_event_attrib(const char* name, uint32_t color) {
117  nvtxEventAttributes_t event_attrib = {};
118  event_attrib.version = NVTX_VERSION;
119  event_attrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
120  if (color != 0) {
121  event_attrib.colorType = NVTX_COLOR_ARGB;
122  event_attrib.color = color;
123  }
124  event_attrib.messageType = NVTX_MESSAGE_TYPE_ASCII;
125  event_attrib.message.ascii = name;
126  return event_attrib;
127 }
128 
129 //
130 // Default domain marker and range support. These will be grouped under the NVTX domain
131 //
132 
133 // Mark an instantaneous event
134 inline void set_mark(const char* message) {
135  nvtxMark(message);
136 }
137 
138 // Push a generic nested range begin (no domain or color)
139 inline void range_push(const char* name) {
140  nvtxRangePushA(name);
141 }
142 
143 // Push a nested range begin with attributes
144 inline void range_push(const char* name, const uint32_t category, const uint32_t color) {
145  auto event_attrib = make_event_attrib(name, color);
146  nvtxRangePushEx(&event_attrib);
147 }
148 
149 // Pop a nested range
150 inline void range_pop() {
151  nvtxRangePop();
152 }
153 
154 // Start an unnested range with no attributes
155 [[nodiscard]] inline nvtxRangeId_t range_start(const char* name) {
156  return nvtxRangeStartA(name);
157 }
158 
159 // Start an unnested range with attributes
160 [[nodiscard]] inline nvtxRangeId_t range_start(const char* name,
161  const uint32_t category,
162  const uint32_t color) {
163  auto event_attrib = make_event_attrib(name, color);
164  return nvtxRangeStartEx(&event_attrib);
165 }
166 
167 // End an unnested range
168 inline void range_end(const nvtxRangeId_t range) {
169  nvtxRangeEnd(range);
170 }
171 
172 //
173 // Custom domain support
174 //
175 
176 // Create a custom domain use in domain calls
177 [[nodiscard]] inline nvtxDomainHandle_t create_domain(const char* name) {
178  return nvtxDomainCreateA(name);
179 }
180 
181 // Destroy a custom domain
182 inline void destroy_domain(nvtxDomainHandle_t domain) {
183  nvtxDomainDestroy(domain);
184 }
185 
186 // Set an instantaneous event in a custom domain
187 inline void set_domain_mark(nvtxDomainHandle_t domain, const char* name, uint32_t color) {
188  auto event_attrib = make_event_attrib(name, color);
189  nvtxDomainMarkEx(domain, &event_attrib);
190 }
191 
192 // Push a nested domain range including attributes
193 inline void domain_range_push(nvtxDomainHandle_t domain,
194  const char* name,
195  uint32_t category,
196  uint32_t color) {
197  auto event_attrib = make_event_attrib(name, color);
198  event_attrib.category = category;
199  nvtxDomainRangePushEx(domain, &event_attrib);
200 }
201 
202 // Pop a nested range from a domain
203 inline void domain_range_pop(nvtxDomainHandle_t domain) {
204  nvtxDomainRangePop(domain);
205 }
206 
207 // Start an unnested range with attributes
208 [[nodiscard]] inline nvtxRangeId_t domain_range_start(nvtxDomainHandle_t domain,
209  const char* name,
210  const uint32_t category,
211  const uint32_t color) {
212  auto event_attrib = make_event_attrib(name, color);
213  return nvtxDomainRangeStartEx(domain, &event_attrib);
214 }
215 
216 // End an unnested range
217 inline void domain_range_end(nvtxDomainHandle_t domain, nvtxRangeId_t range) {
218  nvtxDomainRangeEnd(domain, range);
219 }
220 
221 #else // HAVE_NVTX
222 
223 //
224 // Stub functions
225 // These should be optimized out in release builds
226 //
227 inline void init() {}
228 inline void shutdown() {}
229 
230 inline void omnisci_range_push(Category, const char*, const char*) {}
231 inline void omnisci_range_pop() {}
232 inline nvtxRangeId_t omnisci_range_start(Category, const char*) {
233  return nvtxRangeId_t{};
234 }
235 inline void omnisci_range_end(nvtxRangeId_t) {}
236 inline void omnisci_set_mark(Category, const char*) {}
237 
238 inline void name_current_thread(const char*) {}
239 inline void name_category(uint32_t category, const char* name) {}
241  uint32_t category,
242  const char* name) {}
243 
244 inline void set_mark(const char*) {}
245 inline void range_push(const char*) {}
246 inline void range_pop() {}
247 inline nvtxRangeId_t range_start(const char*) {
248  return nvtxRangeId_t{};
249 }
250 inline nvtxRangeId_t range_start(const char*, uint32_t, uint32_t) {
251  return nvtxRangeId_t{};
252 }
253 inline void range_end(nvtxRangeId_t) {}
254 
255 inline nvtxDomainHandle_t create_domain(const char*) {
256  return nullptr;
257 }
259 inline void set_domain_mark(nvtxDomainHandle_t, const char*, uint32_t) {}
260 inline void domain_range_push(nvtxDomainHandle_t, const char*, uint32_t, uint32_t) {}
262 
263 #ifdef HAVE_CUDA
264 inline void name_cuda_device(CUdevice, const char*) {}
265 inline void name_cuda_context(CUcontext, const char*) {}
266 inline void name_cuda_stream(CUstream, const char*) {}
267 inline void name_cuda_event(CUevent, const char*) {}
268 #endif // HAVE_CUDA
269 
270 #endif // HAVE_NVTX
271 
272 } // namespace nvtx_helpers
const nvtxDomainHandle_t get_omnisci_domain()
void set_mark(const char *)
Definition: nvtx_helpers.h:244
void range_pop()
Definition: nvtx_helpers.h:246
int CUcontext
Definition: nocuda.h:22
void omnisci_range_end(nvtxRangeId_t r)
void omnisci_range_pop()
string name
Definition: setup.in.py:72
void name_domain_category(nvtxDomainHandle_t domain, uint32_t category, const char *name)
Definition: nvtx_helpers.h:240
void name_category(uint32_t category, const char *name)
Definition: nvtx_helpers.h:239
void destroy_domain(nvtxDomainHandle_t)
Definition: nvtx_helpers.h:258
void omnisci_range_push(Category c, const char *name, const char *file)
void set_domain_mark(nvtxDomainHandle_t, const char *, uint32_t)
Definition: nvtx_helpers.h:259
void name_current_thread(const char *name)
void domain_range_pop(nvtxDomainHandle_t)
Definition: nvtx_helpers.h:261
void omnisci_set_mark(Category c, const char *name)
uint64_t nvtxRangeId_t
Definition: nvtx_helpers.h:26
void domain_range_push(nvtxDomainHandle_t, const char *, uint32_t, uint32_t)
Definition: nvtx_helpers.h:260
int CUdevice
Definition: nocuda.h:20
void range_push(const char *)
Definition: nvtx_helpers.h:245
nvtxDomainHandle_t create_domain(const char *)
Definition: nvtx_helpers.h:255
nvtxRangeId_t range_start(const char *)
Definition: nvtx_helpers.h:247
void range_end(nvtxRangeId_t)
Definition: nvtx_helpers.h:253
nvtxRangeId_t omnisci_range_start(Category c, const char *name)
void * nvtxDomainHandle_t
Definition: nvtx_helpers.h:25