Skip to content

Commit a7867ce

Browse files
author
Diptorup Deb
committed
Adds documentation via annotations to config flags
1 parent f6a79b4 commit a7867ce

File tree

1 file changed

+117
-31
lines changed

1 file changed

+117
-31
lines changed

‎numba_dpex/core/config.py

Lines changed: 117 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,35 @@
22
#
33
# SPDX-License-Identifier: Apache-2.0
44

5+
"""
6+
The config options are meant to provide extra information and tweak optimization
7+
configurations to help debug code generation issues.
8+
9+
There are two ways of setting these config options:
10+
11+
- Config options can be directly set programmatically, *e.g.*,
12+
13+
.. code-block:: python
14+
15+
from numba_dpex.core.config import DUMP_KERNEL_LLVM
16+
17+
DUMP_KERNEL_LLVM = 1
18+
19+
- The options can also be set globally using environment flags. The name of the
20+
environment variable for every config option is annotated next to its
21+
definition.
22+
23+
.. code-block:: bash
24+
25+
export NUMBA_DPEX_DUMP_KERNEL_LLVM = 1
26+
27+
"""
28+
29+
from __future__ import annotations
30+
531
import logging
632
import os
33+
from typing import Annotated
734

835
from numba.core import config
936

@@ -50,39 +77,98 @@ def __getattr__(name):
5077
return getattr(config, name)
5178

5279

53-
# To save intermediate files generated by th compiler
54-
SAVE_IR_FILES = _readenv("NUMBA_DPEX_SAVE_IR_FILES", int, 0)
55-
56-
# Dump offload diagnostics
57-
OFFLOAD_DIAGNOSTICS = _readenv("NUMBA_DPEX_OFFLOAD_DIAGNOSTICS", int, 0)
58-
59-
# Emit debug info
60-
DEBUG = _readenv("NUMBA_DPEX_DEBUG", int, config.DEBUG)
61-
# The default value for the `debug` flag
62-
DEBUGINFO_DEFAULT = _readenv(
63-
"NUMBA_DPEX_DEBUGINFO", int, config.DEBUGINFO_DEFAULT
64-
)
65-
66-
# Emit LLVM IR generated for kernel decorated function
67-
DUMP_KERNEL_LLVM = _readenv("NUMBA_DPEX_DUMP_KERNEL_LLVM", int, 0)
68-
69-
# Emit LLVM module generated to launch a kernel decorated function
70-
DUMP_KERNEL_LAUNCHER = _readenv("NUMBA_DPEX_DUMP_KERNEL_LAUNCHER", int, 0)
71-
72-
# Enables debug printf messages inside the kernel launcher module generated for
73-
# a kernel decorated function
74-
DEBUG_KERNEL_LAUNCHER = _readenv("NUMBA_DPEX_DEBUG_KERNEL_LAUNCHER", int, 0)
75-
76-
# Sets build kernel options for the kernel compilation on the device side.
77-
# For available OpenCL options refer
78-
# https://intel.github.io/llvm-docs/clang/ClangCommandLineReference.html#opencl-options
79-
BUILD_KERNEL_OPTIONS = _readenv("NUMBA_DPEX_BUILD_KERNEL_OPTIONS", str, "")
80+
SAVE_IR_FILES: Annotated[
81+
int,
82+
"Save the IR files (LLVM and SPIRV-V) generated for each kernel to"
83+
" current directory",
84+
"default = 0",
85+
"ENVIRONMENT FLAG: NUMBA_DPEX_SAVE_IR_FILES",
86+
] = _readenv("NUMBA_DPEX_SAVE_IR_FILES", int, 0)
87+
88+
OFFLOAD_DIAGNOSTICS: Annotated[
89+
int,
90+
"Print diagnostic information for automatic offloading of parfor nodes "
91+
"to kernels",
92+
"default = 0",
93+
"ENVIRONMENT FLAG: NUMBA_DPEX_OFFLOAD_DIAGNOSTICS",
94+
] = _readenv("NUMBA_DPEX_OFFLOAD_DIAGNOSTICS", int, 0)
95+
96+
DEBUG: Annotated[
97+
int,
98+
"Generates extra debug prints when set to a non-zero value",
99+
"default = 0",
100+
"ENVIRONMENT FLAG: NUMBA_DPEX_DEBUG",
101+
] = _readenv("NUMBA_DPEX_DEBUG", int, config.DEBUG)
102+
103+
DEBUGINFO_DEFAULT: Annotated[
104+
int,
105+
"Compiles in the debug mode generating debug symbols in the compiler IR. "
106+
'It is a global way of setting the "debug" keyword for all '
107+
"numba_dpex.kernel and numba_dpex.device_func decorators "
108+
"used in a program.",
109+
"default = 0",
110+
"ENVIRONMENT FLAG: NUMBA_DPEX_DEBUGINFO",
111+
] = _readenv("NUMBA_DPEX_DEBUGINFO", int, config.DEBUGINFO_DEFAULT)
112+
113+
DUMP_KERNEL_LLVM: Annotated[
114+
int,
115+
"Writes the optimized LLVM IR generated for a "
116+
"numba_dpex.kernel decorated function to current directory",
117+
"default = 0",
118+
"ENVIRONMENT FLAG: NUMBA_DPEX_DUMP_KERNEL_LLVM",
119+
] = _readenv("NUMBA_DPEX_DUMP_KERNEL_LLVM", int, 0)
120+
121+
DUMP_KERNEL_LAUNCHER: Annotated[
122+
int,
123+
"Writes the optimized LLVM IR generated for every "
124+
"numba_dpex.call_kernel function to current directory",
125+
"default = 0",
126+
"ENVIRONMENT FLAG: NUMBA_DPEX_DUMP_KERNEL_LAUNCHER",
127+
] = _readenv("NUMBA_DPEX_DUMP_KERNEL_LAUNCHER", int, 0)
128+
129+
DEBUG_KERNEL_LAUNCHER: Annotated[
130+
int,
131+
"Enables debug printf messages inside the compiled module generated for a "
132+
"numba_dpex.call_kernel function."
133+
"default = 0",
134+
"ENVIRONMENT FLAG: NUMBA_DPEX_DEBUG_KERNEL_LAUNCHER",
135+
] = _readenv("NUMBA_DPEX_DEBUG_KERNEL_LAUNCHER", int, 0)
136+
137+
BUILD_KERNEL_OPTIONS: Annotated[
138+
str,
139+
"Can use used to pass extra flags to the device driver compiler during "
140+
"kernel compilation. For available OpenCL options refer "
141+
"https://intel.github.io/llvm-docs/clang/ClangCommandLineReference.html#opencl-options",
142+
'default = ""',
143+
"ENVIRONMENT FLAG: NUMBA_DPEX_BUILD_KERNEL_OPTIONS",
144+
] = _readenv("NUMBA_DPEX_BUILD_KERNEL_OPTIONS", str, "")
80145

81146
TESTING_SKIP_NO_DEBUGGING = _readenv(
82147
"NUMBA_DPEX_TESTING_SKIP_NO_DEBUGGING", int, 1
83148
)
84-
TESTING_LOG_DEBUGGING = _readenv("NUMBA_DPEX_TESTING_LOG_DEBUGGING", int, DEBUG)
85-
86-
DPEX_OPT = _readenv("NUMBA_DPEX_OPT", int, 2)
87149

88-
INLINE_THRESHOLD = _readenv("NUMBA_DPEX_INLINE_THRESHOLD", int, 2)
150+
TESTING_LOG_DEBUGGING: Annotated[
151+
int,
152+
"Generates extra logs when using gdb to debug a kernel",
153+
"defaults = 0",
154+
"ENVIRONMENT_FLAG: NUMBA_DPEX_TESTING_LOG_DEBUGGING",
155+
] = _readenv("NUMBA_DPEX_TESTING_LOG_DEBUGGING", int, DEBUG)
156+
157+
DPEX_OPT: Annotated[
158+
int,
159+
"Sets the optimization level globally for every function "
160+
"compiled by numba-dpex",
161+
"default = 2",
162+
"ENVIRONMENT_FLAG: NUMBA_DPEX_OPT",
163+
] = _readenv("NUMBA_DPEX_OPT", int, 2)
164+
165+
INLINE_THRESHOLD: Annotated[
166+
int,
167+
"Sets the inlining-threshold level globally for every function "
168+
"compiled by numba-dpex. A higher value enables more aggressive inlining "
169+
"settings for the compiler. Note: Even if NUMBA_DPEX_INLINE_THRESHOLD is "
170+
'set to 0, many internal functions that are attributed "alwaysinline" '
171+
"will still get inlined.",
172+
"default = 2",
173+
"ENVIRONMENT_FLAG: NUMBA_DPEX_INLINE_THRESHOLD",
174+
] = _readenv("NUMBA_DPEX_INLINE_THRESHOLD", int, 2)

0 commit comments

Comments
 (0)