compilation_options.hpp

Go to the documentation of this file.

#pragma once
#ifndef CUDA_API_WRAPPERS_RTC_COMPILATION_OPTIONS_HPP_
#define CUDA_API_WRAPPERS_RTC_COMPILATION_OPTIONS_HPP_

#include "cuda/api/detail/option_marshalling.hpp"

#include "../api/device_properties.hpp"
#include "../api/device.hpp"
#include "../api/common_ptx_compilation_options.hpp"

#include <unordered_map>
#include <unordered_set>
#include <sstream>
#include <string>
#include <vector>
#include <cstring>
#include <limits>
#include <iterator>

namespace cuda {

namespace rtc {

enum class cpp_dialect_t {
    cpp03 = 0,
    cpp11 = 1,
    cpp14 = 2,
    cpp17 = 3,
    last = cpp17
};

namespace detail_ {

static constexpr const size_t language_dialect_name_length { 5 };
constexpr const char* cpp_dialect_names[] =  {
    "c++03",
    "c++11",
    "c++14",
    "c++17",
};

inline cpp_dialect_t cpp_dialect_from_name(const char* dialect_name) noexcept(false)
{
    for(auto known_dialect = static_cast<int>(cpp_dialect_t::cpp03);
        known_dialect <= static_cast<int>(cpp_dialect_t::last);
        known_dialect++)
    {
        if (strcmp(detail_::cpp_dialect_names[known_dialect], dialect_name) == 0) {
            return static_cast<cpp_dialect_t>(known_dialect);
        }
    }
    throw ::std::invalid_argument(::std::string("No C++ dialect named \"") + dialect_name + '"');
}

} // namespace detail_

namespace error {

enum handling_method_t { raise_error = 0, suppress = 1, warn = 2 };

using number_t = unsigned;

namespace detail_ {

inline const char* option_name_part(handling_method_t method)
{
    static constexpr const char* parts[] = { "error", "suppress", "warn" };
    return parts[method];
}

} // namespace detail_

} // namespace error

template <source_kind_t Kind>
struct compilation_options_base_t {
    template <typename T>
    using optional = cuda::optional<T>;

    ::std::unordered_set<cuda::device::compute_capability_t> targets_;

public:
    // TODO: Drop the following methods and make targets a custom
    // inner class which can assigned, added to or subtracted from

    compilation_options_base_t& add_target(device::compute_capability_t compute_capability)
    {
        targets_.clear();
        targets_.insert(compute_capability);
        return *this;
    }

    compilation_options_base_t& set_target(device::compute_capability_t compute_capability)
    {
        targets_.clear();
        add_target(compute_capability);
        return *this;
    }

    compilation_options_base_t& set_target(device_t device)
    {
        return set_target(device.compute_capability());
    }
}; // compilation_options_base_t

enum : rtc::optimization_level_t {
    O0 = 0,
    no_optimization = O0,
    O1 = 1,
    O2 = 2,
    O3 = 3,
    maximum_optimization = O3
};

template <source_kind_t Kind>
class compilation_options_t;

template <>
class compilation_options_t<ptx> final :
    public compilation_options_base_t<ptx>,
    public common_ptx_compilation_options_t {
public:
    using parent = compilation_options_base_t<ptx>;
    using parent::parent;

    bool parse_without_code_generation { false };

    bool allow_expensive_optimizations_below_O2 { false };

    bool compile_as_tools_patch { false };

    bool compile_extensible_whole_program { false };

    bool use_fused_multiply_add { true };

    bool verbose { false };

    bool dont_merge_basicblocks { false };

    bool disable_warnings { false };

    bool disable_optimizer_constants { false };

    bool return_at_end_of_kernel { false };

    bool preserve_variable_relocations { false };

    struct {
        bool double_precision_ops { false };
        bool local_memory_use { false };
        bool registers_spill_to_local_memory { false };
        bool indeterminable_stack_size { true };
        // Does the PTX compiler library actually support this? ptxas does, but the PTX compilation API
        // doesn't mention it
        bool double_demotion { false };
    } situation_warnings;

    struct {
        optional<rtc::ptx_register_count_t> kernel {};
        optional<rtc::ptx_register_count_t> device_function {};
    } maximum_register_counts;

    struct caching_mode_spec_t {
        optional<caching_mode_t<memory_operation_t::load>> load {};
        optional<caching_mode_t<memory_operation_t::store>> store {};
    };
    struct {
        caching_mode_spec_t default_ {};
        caching_mode_spec_t forced {};
    } caching_modes;

    optional<caching_mode_t<memory_operation_t::load>>& default_load_caching_mode() override
    {
        return caching_modes.default_.load;
    }

    optional<caching_mode_t<memory_operation_t::load>> default_load_caching_mode() const override
    {
        return caching_modes.default_.load;
    }

    ::std::vector<::std::string> mangled_entry_function_names;

    ::std::vector<::std::string>& entries();
    ::std::vector<::std::string>& kernels();
    ::std::vector<::std::string>& kernel_names();
}; // compilation_options_t<ptx>

template <>
class compilation_options_t<cuda_cpp> final :
    public compilation_options_base_t<cuda_cpp>,
    public common_ptx_compilation_options_t
{
public:
    using parent = compilation_options_base_t<cuda_cpp>;
    using parent::parent;

    bool compile_extensible_whole_program { false };

    bool optimize_device_code_in_debug_mode { false };

    bool support_128bit_integers { false };

    bool indicate_function_inlining { false };

#if CUDA_VERSION >= 11200 && CUDA_VERSION <= 12200

    bool compiler_self_identification { false };
#endif // #if CUDA_VERSION >= 11200 && CUDA_VERSION <= 12200

    bool syntax_check_only { false };

    bool less_builtins { false };

    optional<size_t> maximum_register_count { };

    bool flush_denormal_floats_to_zero { false };

    bool use_precise_square_root { true };

    bool use_precise_division { true };

    bool use_fused_multiply_add { true };

    bool use_fast_math { false };

    bool link_time_optimization { false };

    bool source_dirs_in_include_path { true };

    bool extra_device_vectorization { false };

    optional<cpp_dialect_t> language_dialect { };

    ::std::unordered_set<::std::string> no_value_defines;

    ::std::unordered_set<::std::string> undefines;

    ::std::unordered_map<::std::string,::std::string> valued_defines;

    bool disable_warnings { false };

    bool assume_restrict { false };

    bool default_execution_space_is_device { false };

    bool display_error_numbers { true };

    ::std::string ptxas;

    ::std::vector<::std::string> additional_include_paths;

    ::std::vector<::std::string> preinclude_files;

    bool builtin_move_and_forward { true };

    bool increase_stack_limit_to_max { true };

    bool builtin_initializer_list { true };

    ::std::vector<::std::string> extra_options;

    ::std::unordered_map<error::number_t, error::handling_method_t> error_handling_overrides;

public: // "shorthands" for more complex option setting

    compilation_options_t& clear_language_dialect()
    {
        language_dialect = {};
        return *this;
    }

    compilation_options_t& set_language_dialect(cpp_dialect_t dialect)
    {
        language_dialect = dialect;
        return *this;
    }

    compilation_options_t& set_language_dialect(const char* dialect_name)
    {
        return (dialect_name == nullptr or *dialect_name == '\0') ?
            clear_language_dialect() :
            set_language_dialect(detail_::cpp_dialect_from_name(dialect_name));
    }

    compilation_options_t& set_language_dialect(const ::std::string& dialect_name)
    {
        return dialect_name.empty() ?
            clear_language_dialect() :
            set_language_dialect(dialect_name.c_str());
    }

    compilation_options_t& suppress_error(error::number_t error_number)
    {
        error_handling_overrides[error_number] = error::suppress;
        return *this;
    }

    compilation_options_t& treat_as_error(error::number_t error_number)
    {
        error_handling_overrides[error_number] = error::raise_error;
        return *this;
    }

    compilation_options_t& warn_about(error::number_t error_number)
    {
        error_handling_overrides[error_number] = error::warn;
        return *this;
    }
}; // compilation_options_t<cuda_cpp>

template <typename CompilationOptions>
inline ::std::string render(const CompilationOptions& opts)
{
    return marshalling::render(opts);
}

} // namespace rtc

namespace marshalling {

namespace detail_ {

template <typename MarshalTarget, typename Delimiter>
struct gadget<rtc::compilation_options_t<ptx>, MarshalTarget, Delimiter> {
    static void process(
        const rtc::compilation_options_t<ptx> &opts,
        MarshalTarget &marshalled, Delimiter delimiter,
        bool need_delimiter_after_last_option)
    {
        opt_start_t<Delimiter> opt_start { delimiter };
        // TODO: Consider taking an option to be verbose in specifying compilation flags, and setting option values
        //  even when they are the compiler defaults.

        // flags
        if (opts.generate_relocatable_device_code)  { marshalled << opt_start << "--compile-only";                  }
        if (opts.compile_as_tools_patch)            { marshalled << opt_start << "--compile-as-tools-patch";        }
        if (opts.generate_debug_info)               { marshalled << opt_start << "--device-debug";                  }
        if (opts.generate_source_line_info)         { marshalled << opt_start << "--generate-line-info";            }
        if (opts.compile_extensible_whole_program)  { marshalled << opt_start << "--extensible-whole-program";      }
        if (not opts.use_fused_multiply_add)        { marshalled << opt_start << "--fmad false";                    }
        if (opts.verbose)                           { marshalled << opt_start << "--verbose";                       }
        if (opts.dont_merge_basicblocks)            { marshalled << opt_start << "--dont-merge-basicblocks";        }
        {
            const auto& osw = opts.situation_warnings;
            if (osw.double_precision_ops)            { marshalled << opt_start << "--warn-on-double-precision-use";   }
            if (osw.local_memory_use)                { marshalled << opt_start << "--warn-on-local-memory-usage";     }
            if (osw.registers_spill_to_local_memory) { marshalled << opt_start << "--warn-on-spills";                 }
            if (not osw.indeterminable_stack_size)   { marshalled << opt_start << "--suppress-stack-size-warning";    }
            if (osw.double_demotion)                 { marshalled << opt_start << "--suppress-double-demote-warning"; }
        }
        if (opts.disable_warnings)                  { marshalled << opt_start << "--disable-warnings";              }
        if (opts.disable_optimizer_constants)       { marshalled << opt_start << "--disable-optimizer-constants";   }


        if (opts.return_at_end_of_kernel)           { marshalled << opt_start << "--return-at-end";                 }
        if (opts.preserve_variable_relocations)     { marshalled << opt_start << "--preserve-relocs";               }

        // Non-flag single-value options

        if (opts.optimization_level) {
            marshalled << opt_start << "--opt-level" << opts.optimization_level.value();
            if (opts.optimization_level.value() < rtc::O2
                and opts.allow_expensive_optimizations_below_O2)
            {
                marshalled << opt_start << "--allow-expensive-optimizations";
            }
        }

        if (opts.maximum_register_counts.kernel) {
            marshalled << opt_start << "--maxrregcount " << opts.maximum_register_counts.kernel.value();
        }
        if (opts.maximum_register_counts.device_function) {
            marshalled << opt_start << "--device-function-maxrregcount " << opts.maximum_register_counts.device_function.value();
        }

        {
            const auto& ocm = opts.caching_modes;
            if (ocm.default_.load)  { marshalled << opt_start << "--def-load-cache "    << ocm.default_.load.value();  }
            if (ocm.default_.store) { marshalled << opt_start << "--def-store-cache "   << ocm.default_.store.value(); }
            if (ocm.forced.load)    { marshalled << opt_start << "--force-load-cache "  << ocm.forced.load.value();    }
            if (ocm.forced.store)   { marshalled << opt_start << "--force-store-cache " << ocm.forced.store.value();   }
        }

        // Multi-value options

        for(const auto& target : opts.targets_) {
            auto prefix = opts.parse_without_code_generation ? "compute" : "sm";
            marshalled << opt_start << "--gpu-name=" << prefix << '_'  << target.as_combined_number();
        }

        if (not opts.mangled_entry_function_names.empty()) {
            marshalled << opt_start << "--entry";
            bool first = true;
            for (const auto &entry: opts.mangled_entry_function_names) {
                if (first) { first = false; }
                else { marshalled << ','; }
                marshalled << entry;
            }
        }

        if (need_delimiter_after_last_option) {
            marshalled << opt_start; // If no options were marshalled, this does nothing
        }
    }
};

template <typename MarshalTarget, typename Delimiter>
struct gadget<rtc::compilation_options_t<cuda_cpp>, MarshalTarget, Delimiter> {
    static void process(
        const rtc::compilation_options_t<cuda_cpp>& opts, MarshalTarget& marshalled, Delimiter delimiter,
        bool need_delimiter_after_last_option)
    {
        opt_start_t<Delimiter> opt_start { delimiter };
        if (opts.generate_relocatable_device_code)  { marshalled << opt_start << "--relocatable-device-code=true";      }
        if (opts.compile_extensible_whole_program)  { marshalled << opt_start << "--extensible-whole-program=true";     }
        if (opts.generate_debug_info)               { marshalled << opt_start << "--device-debug";                      }
        if (opts.generate_source_line_info)         { marshalled << opt_start << "--generate-line-info";                }
        if (opts.support_128bit_integers)           { marshalled << opt_start << "--device-int128";                     }
        if (opts.indicate_function_inlining)        { marshalled << opt_start << "--optimization-info=inline";          }
#if CUDA_VERSION >= 11200 && CUDA_VERSION <= 12200
        if (opts.compiler_self_identification)      { marshalled << opt_start << "--version-ident=true";                }
#endif // CUDA_VERSION >= 11200 && CUDA_VERSION <= 12200
        if (opts.syntax_check_only)                 { marshalled << opt_start << "--fdevice-syntax-only";               }
        if (opts.less_builtins)                     { marshalled << opt_start << "--minimal";                           }
        if (not opts.builtin_initializer_list)      { marshalled << opt_start << "--builtin-initializer-list=false";    }
        if (not opts.source_dirs_in_include_path)   { marshalled << opt_start << "--no-source-include";                 }
        if (opts.extra_device_vectorization)        { marshalled << opt_start << "--extra-device-vectorization";        }
        if (opts.disable_warnings)                  { marshalled << opt_start << "--disable-warnings";                  }
        if (opts.assume_restrict)                   { marshalled << opt_start << "--restrict";                          }
        if (opts.default_execution_space_is_device) { marshalled << opt_start << "--device-as-default-execution-space"; }
        if (not opts.display_error_numbers)         { marshalled << opt_start << "--no-display-error-number";           }
        if (not opts.builtin_move_and_forward)      { marshalled << opt_start << "--builtin-move-forward=false";        }
        if (not opts.increase_stack_limit_to_max)   { marshalled << opt_start << "--modify-stack-limit=false";          }
        if (opts.link_time_optimization)            { marshalled << opt_start << "--dlink-time-opt";                    }
        if (opts.use_fast_math)                     { marshalled << opt_start << "--use_fast_math";                     }
        else {
            if (opts.flush_denormal_floats_to_zero) { marshalled << opt_start << "--ftz";                               }
            if (not opts.use_precise_square_root)   { marshalled << opt_start << "--prec-sqrt=false";                   }
            if (not opts.use_precise_division)      { marshalled << opt_start << "--prec-div=false";                    }
            if (not opts.use_fused_multiply_add)    { marshalled << opt_start << "--fmad=false";                        }
        }
        if (opts.optimize_device_code_in_debug_mode) {
            marshalled << opt_start << "--dopt=on";
        }
        if (not opts.ptxas.empty()) {
            marshalled << opt_start << "--ptxas-options=" << opts.ptxas;

        }

        if (opts.language_dialect) {
            marshalled << opt_start << "--std=" << rtc::detail_::cpp_dialect_names[static_cast<unsigned>(opts.language_dialect.value())];
        }

        if (opts.maximum_register_count) {
            marshalled << opt_start << "--maxrregcount=" << opts.maximum_register_count.value();
        }

        // Multi-value options

        for(const auto& target : opts.targets_) {
    #if CUDA_VERSION < 11000
            marshalled << opt_start << "--gpu-architecture=compute_" << target.as_combined_number();
    #else
            marshalled << opt_start << "--gpu-architecture=sm_" << target.as_combined_number();
    #endif
        }

        for(const auto& def : opts.undefines) {
            marshalled << opt_start << "-U" << def;
            // Note: Could alternatively use "--undefine-macro=" instead of "-D"
        }


        for(const auto& def : opts.no_value_defines) {
            marshalled << opt_start << "-D" << def;
            // Note: Could alternatively use "--define-macro=" instead of "-D"
        }

        for(const auto& def : opts.valued_defines) {
            marshalled << opt_start << "-D" << def.first << '=' << def.second;
        }

        for(const auto& path : opts.additional_include_paths) {
            marshalled << opt_start << "--include-path=" << path;
        }

        for(const auto& preinclude_file : opts.preinclude_files) {
            marshalled << opt_start << "--pre-include=" << preinclude_file;
        }

        for(const auto& override : opts.error_handling_overrides) {
            marshalled
                << opt_start << "--diag-" << rtc::error::detail_::option_name_part(override.second)
                << '=' << override.first ;
        }

        for(const auto& extra_opt : opts.extra_options) {
            marshalled << opt_start << extra_opt;
        }

        if (need_delimiter_after_last_option) {
            marshalled << opt_start; // If no options were marshalled, this does nothing
        }
    }
};

} // namespace detail_

} // namespace marshalling

} // namespace cuda

#endif // CUDA_API_WRAPPERS_RTC_COMPILATION_OPTIONS_HPP_