Skip to content

Commit 5ff654f

Browse files
ZzEeKkAaZzEeKkAa
authored
Merge pull request #1415 from IntelPython/docs/config_options
[Documentation] config options
2 parents f6a79b4 + 017b092 commit 5ff654f

File tree

5 files changed

+130
-98
lines changed

5 files changed

+130
-98
lines changed

‎docs/_templates/autoapi/python/module.rst

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
{% import 'macros.rst' as macros %}
22

33
{% if not obj.display %}
4+
{% if not "config" in obj.name %}
5+
46
:orphan:
57

8+
{% endif %}
69
{% endif %}
710
{{ obj.name }}
811
{{ "=" * obj.name|length }}
@@ -57,13 +60,14 @@ Submodules
5760
{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %}
5861
{% endif %}
5962
{% if visible_children %}
60-
Overview
61-
--------
63+
6264

6365
{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
6466
{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
6567
{% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %}
6668
{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %}
69+
Overview
70+
--------
6771
{% block classes scoped %}
6872
{% if visible_classes %}
6973
{{ macros.auto_summary(visible_classes, title="Classes") }}

‎docs/source/config_options.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. _configopts:
2+
3+
Configuration Options
4+
#####################
5+
6+
.. include:: ./autoapi/numba_dpex/core/config/index.rst

‎docs/source/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ Data Parallel Extension for Numba*
4848
programming_model
4949
user_guide/index
5050
autoapi/index
51+
config_options
5152
experimental/index
5253
useful_links
5354

‎docs/source/user_guide/config.rst

Lines changed: 0 additions & 65 deletions
This file was deleted.

‎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)