From a7867ce89eec8ee5a147137899c46ad1d19b775d Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Fri, 29 Mar 2024 17:35:02 -0500 Subject: [PATCH 1/2] Adds documentation via annotations to config flags --- numba_dpex/core/config.py | 148 ++++++++++++++++++++++++++++++-------- 1 file changed, 117 insertions(+), 31 deletions(-) diff --git a/numba_dpex/core/config.py b/numba_dpex/core/config.py index 0e5adbacc8..db64c5a91a 100644 --- a/numba_dpex/core/config.py +++ b/numba_dpex/core/config.py @@ -2,8 +2,35 @@ # # SPDX-License-Identifier: Apache-2.0 +""" +The config options are meant to provide extra information and tweak optimization +configurations to help debug code generation issues. + +There are two ways of setting these config options: + +- Config options can be directly set programmatically, *e.g.*, + + .. code-block:: python + + from numba_dpex.core.config import DUMP_KERNEL_LLVM + + DUMP_KERNEL_LLVM = 1 + +- The options can also be set globally using environment flags. The name of the + environment variable for every config option is annotated next to its + definition. + + .. code-block:: bash + + export NUMBA_DPEX_DUMP_KERNEL_LLVM = 1 + +""" + +from __future__ import annotations + import logging import os +from typing import Annotated from numba.core import config @@ -50,39 +77,98 @@ def __getattr__(name): return getattr(config, name) -# To save intermediate files generated by th compiler -SAVE_IR_FILES = _readenv("NUMBA_DPEX_SAVE_IR_FILES", int, 0) - -# Dump offload diagnostics -OFFLOAD_DIAGNOSTICS = _readenv("NUMBA_DPEX_OFFLOAD_DIAGNOSTICS", int, 0) - -# Emit debug info -DEBUG = _readenv("NUMBA_DPEX_DEBUG", int, config.DEBUG) -# The default value for the `debug` flag -DEBUGINFO_DEFAULT = _readenv( - "NUMBA_DPEX_DEBUGINFO", int, config.DEBUGINFO_DEFAULT -) - -# Emit LLVM IR generated for kernel decorated function -DUMP_KERNEL_LLVM = _readenv("NUMBA_DPEX_DUMP_KERNEL_LLVM", int, 0) - -# Emit LLVM module generated to launch a kernel decorated function -DUMP_KERNEL_LAUNCHER = _readenv("NUMBA_DPEX_DUMP_KERNEL_LAUNCHER", int, 0) - -# Enables debug printf messages inside the kernel launcher module generated for -# a kernel decorated function -DEBUG_KERNEL_LAUNCHER = _readenv("NUMBA_DPEX_DEBUG_KERNEL_LAUNCHER", int, 0) - -# Sets build kernel options for the kernel compilation on the device side. -# For available OpenCL options refer -# https://intel.github.io/llvm-docs/clang/ClangCommandLineReference.html#opencl-options -BUILD_KERNEL_OPTIONS = _readenv("NUMBA_DPEX_BUILD_KERNEL_OPTIONS", str, "") +SAVE_IR_FILES: Annotated[ + int, + "Save the IR files (LLVM and SPIRV-V) generated for each kernel to" + " current directory", + "default = 0", + "ENVIRONMENT FLAG: NUMBA_DPEX_SAVE_IR_FILES", +] = _readenv("NUMBA_DPEX_SAVE_IR_FILES", int, 0) + +OFFLOAD_DIAGNOSTICS: Annotated[ + int, + "Print diagnostic information for automatic offloading of parfor nodes " + "to kernels", + "default = 0", + "ENVIRONMENT FLAG: NUMBA_DPEX_OFFLOAD_DIAGNOSTICS", +] = _readenv("NUMBA_DPEX_OFFLOAD_DIAGNOSTICS", int, 0) + +DEBUG: Annotated[ + int, + "Generates extra debug prints when set to a non-zero value", + "default = 0", + "ENVIRONMENT FLAG: NUMBA_DPEX_DEBUG", +] = _readenv("NUMBA_DPEX_DEBUG", int, config.DEBUG) + +DEBUGINFO_DEFAULT: Annotated[ + int, + "Compiles in the debug mode generating debug symbols in the compiler IR. " + 'It is a global way of setting the "debug" keyword for all ' + "numba_dpex.kernel and numba_dpex.device_func decorators " + "used in a program.", + "default = 0", + "ENVIRONMENT FLAG: NUMBA_DPEX_DEBUGINFO", +] = _readenv("NUMBA_DPEX_DEBUGINFO", int, config.DEBUGINFO_DEFAULT) + +DUMP_KERNEL_LLVM: Annotated[ + int, + "Writes the optimized LLVM IR generated for a " + "numba_dpex.kernel decorated function to current directory", + "default = 0", + "ENVIRONMENT FLAG: NUMBA_DPEX_DUMP_KERNEL_LLVM", +] = _readenv("NUMBA_DPEX_DUMP_KERNEL_LLVM", int, 0) + +DUMP_KERNEL_LAUNCHER: Annotated[ + int, + "Writes the optimized LLVM IR generated for every " + "numba_dpex.call_kernel function to current directory", + "default = 0", + "ENVIRONMENT FLAG: NUMBA_DPEX_DUMP_KERNEL_LAUNCHER", +] = _readenv("NUMBA_DPEX_DUMP_KERNEL_LAUNCHER", int, 0) + +DEBUG_KERNEL_LAUNCHER: Annotated[ + int, + "Enables debug printf messages inside the compiled module generated for a " + "numba_dpex.call_kernel function." + "default = 0", + "ENVIRONMENT FLAG: NUMBA_DPEX_DEBUG_KERNEL_LAUNCHER", +] = _readenv("NUMBA_DPEX_DEBUG_KERNEL_LAUNCHER", int, 0) + +BUILD_KERNEL_OPTIONS: Annotated[ + str, + "Can use used to pass extra flags to the device driver compiler during " + "kernel compilation. For available OpenCL options refer " + "https://intel.github.io/llvm-docs/clang/ClangCommandLineReference.html#opencl-options", + 'default = ""', + "ENVIRONMENT FLAG: NUMBA_DPEX_BUILD_KERNEL_OPTIONS", +] = _readenv("NUMBA_DPEX_BUILD_KERNEL_OPTIONS", str, "") TESTING_SKIP_NO_DEBUGGING = _readenv( "NUMBA_DPEX_TESTING_SKIP_NO_DEBUGGING", int, 1 ) -TESTING_LOG_DEBUGGING = _readenv("NUMBA_DPEX_TESTING_LOG_DEBUGGING", int, DEBUG) - -DPEX_OPT = _readenv("NUMBA_DPEX_OPT", int, 2) -INLINE_THRESHOLD = _readenv("NUMBA_DPEX_INLINE_THRESHOLD", int, 2) +TESTING_LOG_DEBUGGING: Annotated[ + int, + "Generates extra logs when using gdb to debug a kernel", + "defaults = 0", + "ENVIRONMENT_FLAG: NUMBA_DPEX_TESTING_LOG_DEBUGGING", +] = _readenv("NUMBA_DPEX_TESTING_LOG_DEBUGGING", int, DEBUG) + +DPEX_OPT: Annotated[ + int, + "Sets the optimization level globally for every function " + "compiled by numba-dpex", + "default = 2", + "ENVIRONMENT_FLAG: NUMBA_DPEX_OPT", +] = _readenv("NUMBA_DPEX_OPT", int, 2) + +INLINE_THRESHOLD: Annotated[ + int, + "Sets the inlining-threshold level globally for every function " + "compiled by numba-dpex. A higher value enables more aggressive inlining " + "settings for the compiler. Note: Even if NUMBA_DPEX_INLINE_THRESHOLD is " + 'set to 0, many internal functions that are attributed "alwaysinline" ' + "will still get inlined.", + "default = 2", + "ENVIRONMENT_FLAG: NUMBA_DPEX_INLINE_THRESHOLD", +] = _readenv("NUMBA_DPEX_INLINE_THRESHOLD", int, 2) From 017b09249f500123c203f3f841653446984d24bb Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Fri, 29 Mar 2024 17:36:03 -0500 Subject: [PATCH 2/2] Configs are now automatically documented using in source annotations --- docs/_templates/autoapi/python/module.rst | 8 ++- docs/source/config_options.rst | 6 +++ docs/source/index.rst | 1 + docs/source/user_guide/config.rst | 65 ----------------------- 4 files changed, 13 insertions(+), 67 deletions(-) create mode 100644 docs/source/config_options.rst delete mode 100644 docs/source/user_guide/config.rst diff --git a/docs/_templates/autoapi/python/module.rst b/docs/_templates/autoapi/python/module.rst index 32143c3957..31613043bd 100644 --- a/docs/_templates/autoapi/python/module.rst +++ b/docs/_templates/autoapi/python/module.rst @@ -1,8 +1,11 @@ {% import 'macros.rst' as macros %} {% if not obj.display %} +{% if not "config" in obj.name %} + :orphan: +{% endif %} {% endif %} {{ obj.name }} {{ "=" * obj.name|length }} @@ -57,13 +60,14 @@ Submodules {% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %} {% endif %} {% if visible_children %} -Overview --------- + {% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %} {% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %} {% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %} {% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %} +Overview +-------- {% block classes scoped %} {% if visible_classes %} {{ macros.auto_summary(visible_classes, title="Classes") }} diff --git a/docs/source/config_options.rst b/docs/source/config_options.rst new file mode 100644 index 0000000000..07cfd99c22 --- /dev/null +++ b/docs/source/config_options.rst @@ -0,0 +1,6 @@ +.. _configopts: + +Configuration Options +##################### + +.. include:: ./autoapi/numba_dpex/core/config/index.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 8a540cac8f..de42d5524f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -48,6 +48,7 @@ Data Parallel Extension for Numba* programming_model user_guide/index autoapi/index + config_options experimental/index useful_links diff --git a/docs/source/user_guide/config.rst b/docs/source/user_guide/config.rst deleted file mode 100644 index e98b85521c..0000000000 --- a/docs/source/user_guide/config.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. include:: ./../ext_links.txt - -Configuration Options for ``numba-dpex`` -======================================== - -``numba-dpex`` provides a set of environment variables and flags for configuring -different aspects of the compilation, debugging and execution of programs. The -configuration flags of ``numba-dpex`` are mostly inherited from those of Numba*. -They are defined in :file:`numba_dpex/core/config.py`. - -.. note:: - In order to enable/disable each of the configuration flags, a ``NUMBA_DPEX`` - prefix needs to be appended before each variable. For example, in order to - turn ``SAVE_IR_FILES`` flag on, it needs to be passed as ``NUMBA_DPEX_SAVE_IR_FILES=1`` - - For example: - - .. code-block:: bash - - user@host:~/NUMBA_DPEX_SAVE_IR_FILES=1 python numba_dpex_program.py - - -The list of available configuration flags are listed as follows: - -``SAVE_IR_FILES``: - A flag to save the Numba* intermediate representation (IR) files generated by the compiler. Set to ``0`` by default. - -``SPIRV_VAL``: - A flag to turn Numba*'s ``SPIRV-VALIDATION`` switch. Set to ``0`` by default. - -``OFFLOAD_DIAGNOSTICS``: - A flag to dump the offload diagnostics. Set to ``0`` by default. - -``NATIVE_FP_ATOMICS``: - A flag to activate the native floating point (FP) atomcis support for supported devices. Requires ``llvm-spirv`` supporting the FP atomics extension. Set to ``0`` by default. - -``DEBUG``: - A flag to emit the debug info, inherited from |numba.core.config.DEBUG|_. - -``DEBUGINFO_DEFAULT``: - The default value for the `debug` flag. Inherited from |numba.core.config.DEBUGINFO_DEFAULT|_. - -``DUMP_KERNEL_LLVM``: - A flag to emit LLVM assembly language format (``.ll``). Inherited from |numba.core.config.DUMP_OPTIMIZED|_. - -``ENABLE_CACHE``: - A flag to enable caching, set ``NUMBA_DPEX_ENABLE_CACHE=0`` to turn off. Set to ``1`` by default. - -``CACHE_SIZE``: - A flag to specify the default cache size. Set to ``20`` by default. - -``DEBUG_CACHE``: - A flag to enable debugging of cahcing mechanism, set ``1`` to turn it on. - -``STATIC_LOCAL_MEM_PASS``: - A flag to turn on the ``ConstantSizeStaticLocalMemoryPass`` in the kernel pipeline. The pass is turned off by default. - - -.. |numba.core.config.DEBUG| replace:: ``numba.core.config.DEBUG`` -.. |numba.core.config.DEBUGINFO_DEFAULT| replace:: ``numba.core.config.DEBUGINFO_DEFAULT`` -.. |numba.core.config.DUMP_OPTIMIZED| replace:: ``numba.core.config.DUMP_OPTIMIZED`` - -.. _`numba.core.config.DEBUG`: https://github.com/numba/numba/blob/main/numba/core/config.py#L202 -.. _`numba.core.config.DEBUGINFO_DEFAULT`: https://github.com/numba/numba/blob/main/numba/core/config.py#L488 -.. _`numba.core.config.DUMP_OPTIMIZED`: https://github.com/numba/numba/blob/main/numba/core/config.py#L301