error.hpp

Go to the documentation of this file.

#pragma once
#ifndef CUDA_API_WRAPPERS_ERROR_HPP_
#define CUDA_API_WRAPPERS_ERROR_HPP_

#include "types.hpp"
#include <cuda_runtime_api.h>

#include <type_traits>
#include <string>
#include <stdexcept>

namespace cuda {

namespace status {

enum named_t : ::std::underlying_type<status_t>::type {
    success                          = CUDA_SUCCESS, 
    memory_allocation_failure        = CUDA_ERROR_OUT_OF_MEMORY, // corresponds to cudaErrorMemoryAllocation
    not_yet_initialized              = CUDA_ERROR_NOT_INITIALIZED, // corresponds to cudaErrorInitializationError
    already_deinitialized            = CUDA_ERROR_DEINITIALIZED, // corresponds to cudaErrorCudartUnloading
    profiler_disabled                = CUDA_ERROR_PROFILER_DISABLED,
#if CUDA_VERSION >= 10100
    profiler_not_initialized         = CUDA_ERROR_PROFILER_NOT_INITIALIZED,
#endif
    profiler_already_started         = CUDA_ERROR_PROFILER_ALREADY_STARTED,
    profiler_already_stopped         = CUDA_ERROR_PROFILER_ALREADY_STOPPED,
#if CUDA_VERSION >= 11100
    stub_library                     = CUDA_ERROR_STUB_LIBRARY,
    device_not_licensed              = CUDA_ERROR_DEVICE_NOT_LICENSED,
#endif
    prior_launch_failure             = cudaErrorPriorLaunchFailure,
    launch_timeout                   = CUDA_ERROR_LAUNCH_TIMEOUT,
    launch_out_of_resources          = CUDA_ERROR_LAUNCH_OUT_OF_RESOURCES,
    kernel_launch_incompatible_texturing_mode = CUDA_ERROR_LAUNCH_INCOMPATIBLE_TEXTURING,
    invalid_kernel_function          = cudaErrorInvalidDeviceFunction,
    invalid_configuration            = cudaErrorInvalidConfiguration,
    invalid_device                   = CUDA_ERROR_INVALID_DEVICE,
    invalid_value                    = CUDA_ERROR_INVALID_VALUE,
    invalid_pitch_value              = cudaErrorInvalidPitchValue,
    invalid_symbol                   = cudaErrorInvalidSymbol,
    map_buffer_object_failed         = CUDA_ERROR_MAP_FAILED, // corresponds to cudaErrorMapBufferObjectFailed,
    unmap_buffer_object_failed       = CUDA_ERROR_UNMAP_FAILED, // corresponds to cudaErrorUnmapBufferObjectFailed,
    array_still_mapped               = CUDA_ERROR_ARRAY_IS_MAPPED,
    resource_already_mapped          = CUDA_ERROR_ALREADY_MAPPED,
    resource_already_acquired        = CUDA_ERROR_ALREADY_ACQUIRED,
    resource_not_mapped              = CUDA_ERROR_NOT_MAPPED,
    not_mapped_as_pointer            = CUDA_ERROR_NOT_MAPPED_AS_POINTER,
    not_mapped_as_array              = CUDA_ERROR_NOT_MAPPED_AS_ARRAY,
    invalid_host_pointer             = cudaErrorInvalidHostPointer,
    invalid_device_pointer           = cudaErrorInvalidDevicePointer,
    invalid_texture                  = cudaErrorInvalidTexture,
    invalid_texture_binding          = cudaErrorInvalidTextureBinding,
    invalid_channel_descriptor       = cudaErrorInvalidChannelDescriptor,
    invalid_memcpy_direction         = cudaErrorInvalidMemcpyDirection,
    address_of_constant              = cudaErrorAddressOfConstant,
    texture_fetch_failed             = cudaErrorTextureFetchFailed,
    texture_not_bound                = cudaErrorTextureNotBound,
    synchronization_error            = cudaErrorSynchronizationError,
    invalid_filter_setting           = cudaErrorInvalidFilterSetting,
    invalid_norm_setting             = cudaErrorInvalidNormSetting,
    mixed_device_execution           = cudaErrorMixedDeviceExecution,
    unknown                          = CUDA_ERROR_UNKNOWN,
    not_yet_implemented              = cudaErrorNotYetImplemented,
    memory_value_too_large           = cudaErrorMemoryValueTooLarge,
    invalid_resource_handle          = CUDA_ERROR_INVALID_HANDLE,
#if CUDA_VERSION >= 10000
    resource_not_in_valid_state     = CUDA_ERROR_ILLEGAL_STATE,
#endif
    async_operations_not_yet_completed = CUDA_ERROR_NOT_READY,
    insufficient_driver              = cudaErrorInsufficientDriver,
    set_on_active_process            = cudaErrorSetOnActiveProcess,
    invalid_surface                  = cudaErrorInvalidSurface,
    symbol_not_found                 = CUDA_ERROR_NOT_FOUND, // corresponds to cudaErrorSymbolNotFound
    no_device                        = CUDA_ERROR_NO_DEVICE,
    ecc_uncorrectable                = CUDA_ERROR_ECC_UNCORRECTABLE,
    shared_object_symbol_not_found   = CUDA_ERROR_SHARED_OBJECT_SYMBOL_NOT_FOUND,
    invalid_source                   = CUDA_ERROR_INVALID_SOURCE,
    file_not_found                   = CUDA_ERROR_FILE_NOT_FOUND,
    shared_object_init_failed        = CUDA_ERROR_SHARED_OBJECT_INIT_FAILED,
    jit_compiler_not_found           = CUDA_ERROR_JIT_COMPILER_NOT_FOUND,
#if CUDA_VERSION >= 11100
    unsupported_ptx_version          = CUDA_ERROR_UNSUPPORTED_PTX_VERSION,
#endif
#if CUDA_VERSION >= 11200
    jit_compilation_disabled         = CUDA_ERROR_JIT_COMPILATION_DISABLED,
#endif
#if CUDA_VERSION >= 11400
    unsupported_exec_affinity        = CUDA_ERROR_UNSUPPORTED_EXEC_AFFINITY,
#endif
    unsupported_limit                = CUDA_ERROR_UNSUPPORTED_LIMIT,
    duplicate_variable_name          = cudaErrorDuplicateVariableName,
    duplicate_texture_name           = cudaErrorDuplicateTextureName,
    duplicate_surface_name           = cudaErrorDuplicateSurfaceName,
    devices_unavailable              = cudaErrorDevicesUnavailable,
    invalid_kernel_image             = CUDA_ERROR_INVALID_IMAGE, // corresponds to cudaErrorInvalidKernelImage,
    no_kernel_image_for_device       = CUDA_ERROR_NO_BINARY_FOR_GPU, // corresponds to cudaErrorNoKernelImageForDevice,
    incompatible_driver_context      = cudaErrorIncompatibleDriverContext,
    missing_configuration            = cudaErrorMissingConfiguration,
    invalid_context                  = CUDA_ERROR_INVALID_CONTEXT,
    context_already_current          = CUDA_ERROR_CONTEXT_ALREADY_CURRENT,
    context_already_in_use           = CUDA_ERROR_CONTEXT_ALREADY_IN_USE,
    peer_access_already_enabled      = CUDA_ERROR_PEER_ACCESS_ALREADY_ENABLED,
    peer_access_not_enabled          = CUDA_ERROR_PEER_ACCESS_NOT_ENABLED,
    device_already_in_use            = cudaErrorDeviceAlreadyInUse,
    primary_context_already_active   = CUDA_ERROR_PRIMARY_CONTEXT_ACTIVE,
    context_is_destroyed             = CUDA_ERROR_CONTEXT_IS_DESTROYED,
    primary_context_is_uninitialized = CUDA_ERROR_CONTEXT_IS_DESTROYED, // an alias!
#if CUDA_VERSION >= 10200
    device_uninitialized             = cudaErrorDeviceUninitialized,
#endif
    assert                           = CUDA_ERROR_ASSERT,
    too_many_peers                   = CUDA_ERROR_TOO_MANY_PEERS,
    host_memory_already_registered   = CUDA_ERROR_HOST_MEMORY_ALREADY_REGISTERED,
    host_memory_not_registered       = CUDA_ERROR_HOST_MEMORY_NOT_REGISTERED,
    operating_system                 = CUDA_ERROR_OPERATING_SYSTEM,
    peer_access_unsupported          = CUDA_ERROR_PEER_ACCESS_UNSUPPORTED,
    launch_max_depth_exceeded        = cudaErrorLaunchMaxDepthExceeded,
    launch_file_scoped_tex           = cudaErrorLaunchFileScopedTex,
    launch_file_scoped_surf          = cudaErrorLaunchFileScopedSurf,
    sync_depth_exceeded              = cudaErrorSyncDepthExceeded,
    launch_pending_count_exceeded    = cudaErrorLaunchPendingCountExceeded,
    invalid_device_function          = cudaErrorInvalidDeviceFunction,
    not_permitted                    = CUDA_ERROR_NOT_PERMITTED,
    not_supported                    = CUDA_ERROR_NOT_SUPPORTED,
    hardware_stack_error             = CUDA_ERROR_HARDWARE_STACK_ERROR,
    illegal_instruction              = CUDA_ERROR_ILLEGAL_INSTRUCTION,
    misaligned_address               = CUDA_ERROR_MISALIGNED_ADDRESS,
    exception_during_kernel_execution = CUDA_ERROR_LAUNCH_FAILED,
    cooperative_launch_too_large     = CUDA_ERROR_COOPERATIVE_LAUNCH_TOO_LARGE,
    invalid_address_space            = CUDA_ERROR_INVALID_ADDRESS_SPACE,
    invalid_pc                       = CUDA_ERROR_INVALID_PC,
    illegal_address                  = CUDA_ERROR_ILLEGAL_ADDRESS,
    invalid_ptx                      = CUDA_ERROR_INVALID_PTX,
    invalid_graphics_context         = CUDA_ERROR_INVALID_GRAPHICS_CONTEXT,
    nvlink_uncorrectable             = CUDA_ERROR_NVLINK_UNCORRECTABLE,
    startup_failure                  = cudaErrorStartupFailure,
    api_failure_base                 = cudaErrorApiFailureBase,
#if CUDA_VERSION >= 10000
    system_not_ready                 = CUDA_ERROR_SYSTEM_NOT_READY,
    stream_capture_unsupported       = CUDA_ERROR_STREAM_CAPTURE_UNSUPPORTED,
    stream_capture_invalidated       = CUDA_ERROR_STREAM_CAPTURE_INVALIDATED,
    stream_capture_merge             = CUDA_ERROR_STREAM_CAPTURE_MERGE,
    stream_capture_unmatched         = CUDA_ERROR_STREAM_CAPTURE_UNMATCHED,
    stream_capture_unjoined          = CUDA_ERROR_STREAM_CAPTURE_UNJOINED,
    stream_capture_isolation         = CUDA_ERROR_STREAM_CAPTURE_ISOLATION,
    stream_capture_disallowed_implicit_dependency = CUDA_ERROR_STREAM_CAPTURE_IMPLICIT,
    not_permitted_on_captured_event  = CUDA_ERROR_CAPTURED_EVENT,
#endif
#if CUDA_VERSION >= 10100
    system_driver_mismatch           = CUDA_ERROR_SYSTEM_DRIVER_MISMATCH,
    not_supported_on_device          = CUDA_ERROR_COMPAT_NOT_SUPPORTED_ON_DEVICE,
    stream_capture_wrong_thread      = CUDA_ERROR_STREAM_CAPTURE_WRONG_THREAD,
#endif
#if CUDA_VERSION >= 10200
    timeout_lapsed                   = CUDA_ERROR_TIMEOUT,
    graph_update_would_violate_constraints = CUDA_ERROR_GRAPH_EXEC_UPDATE_FAILURE,
#endif
#if CUDA_VERSION >= 11400
    mps_connection_failed            = CUDA_ERROR_MPS_CONNECTION_FAILED,
    mps_rpc_failure                  = CUDA_ERROR_MPS_RPC_FAILURE,
    mps_server_not_ready             = CUDA_ERROR_MPS_SERVER_NOT_READY,
    mps_max_clients_reached          = CUDA_ERROR_MPS_MAX_CLIENTS_REACHED,
    mps_max_connections_reached      = CUDA_ERROR_MPS_MAX_CONNECTIONS_REACHED,
    async_error_in_external_device   = CUDA_ERROR_EXTERNAL_DEVICE,
#endif // CUDA_VERSION >= 11400
#if CUDA_VERSION >= 12000
    invalid_cluster_size             = CUDA_ERROR_INVALID_CLUSTER_SIZE,
#endif // CUDA_VERSION >= 12000
#if CUDA_VERSION >= 12040
    necessary_function_not_loaded    = CUDA_ERROR_FUNCTION_NOT_LOADED,
    invalid_resource_type            = CUDA_ERROR_INVALID_RESOURCE_TYPE,
    resources_insufficient_or_inapplicable
                                     = CUDA_ERROR_INVALID_RESOURCE_CONFIGURATION,
#endif // CUDA_VERSION >= 12040
#if CUDA_VERSION >= 12080
    key_rotation_sequence_failure    = CUDA_ERROR_KEY_ROTATION,
#endif // CUDA_VERSION >= 12080
#if CUDA_VERSION >= 13010
    not_permitted_on_detached_stream = CUDA_ERROR_STREAM_DETACHED,
#endif // CUDA_VERSION >= 13010
};

constexpr inline bool operator==(const status_t& lhs, const named_t& rhs) noexcept { return lhs == static_cast<status_t>(rhs); }
constexpr inline bool operator!=(const status_t& lhs, const named_t& rhs) noexcept { return lhs != static_cast<status_t>(rhs); }
constexpr inline bool operator==(const named_t& lhs, const status_t& rhs) noexcept { return static_cast<status_t>(lhs) == rhs; }
constexpr inline bool operator!=(const named_t& lhs, const status_t& rhs) noexcept { return static_cast<status_t>(lhs) != rhs; }

} // namespace status

constexpr bool is_success(status_t status)  { return status == static_cast<status_t>(status::success); }
constexpr bool is_success(cudaError_t status) { return static_cast<status_t>(status) == static_cast<status_t>(status::success); }

constexpr bool is_failure(status_t status)  { return not is_success(status); }
constexpr bool is_failure(cudaError_t status)  { return is_failure(static_cast<status_t>(status)); }

inline ::std::string describe(status_t status)
{
    // Even though status_t aliases the driver's CUresult type, some values are actually
    // runtime error codes. The driver will fail to identify them (they're luckily distinct),
    // and we can't distinguish proper failure from the case of a Runtime-API-only error
    // code - so we also try the runtime API.
    const char* description;
    auto description_lookup_status = cuGetErrorString(status, &description);
    return (description_lookup_status == CUDA_SUCCESS) ?
        description : cudaGetErrorString(static_cast<cudaError_t>(status));
}
inline ::std::string describe(cudaError_t status) { return cudaGetErrorString(status); }

namespace detail_ {

template <typename I, bool UpperCase = false>
::std::string as_hex(I x)
{
    static_assert(::std::is_unsigned<I>::value, "only signed representations are supported");
    unsigned num_hex_digits = 2*sizeof(I);
    if (x == 0) return "0x0";

    enum { bits_per_hex_digit = 4 }; // = log_2 of 16
    static const char* digit_characters =
        UpperCase ? "0123456789ABCDEF" : "0123456789abcdef" ;

    ::std::string result(num_hex_digits,'0');
    for (unsigned digit_index = 0; digit_index < num_hex_digits ; digit_index++)
    {
        size_t bit_offset = (num_hex_digits - 1 - digit_index) * bits_per_hex_digit;
        auto hexadecimal_digit = (x >> bit_offset) & 0xF;
        result[digit_index] = digit_characters[hexadecimal_digit];
    }
    return "0x0" + result.substr(result.find_first_not_of('0'), ::std::string::npos);
}

// TODO: Perhaps find a way to avoid the extra function, so that as_hex() can
// be called for pointer types as well? Would be easier with boost's uint<T>...
template <typename I, bool UpperCase = false>
inline ::std::string ptr_as_hex(const I* ptr)
{
    return as_hex(reinterpret_cast<uintptr_t>(ptr));
}

} // namespace detail_

class runtime_error : public ::std::runtime_error {
public:
    runtime_error(status_t error_code) :
        ::std::runtime_error(describe(error_code)), code_(error_code)
    { }
    // I wonder if I should do this the other way around
    runtime_error(status_t error_code, const ::std::string& what_arg) :
        ::std::runtime_error(what_arg + ": " + describe(error_code)),
        code_(error_code)
    { }
    // I wonder if I should do this the other way around
    runtime_error(status_t error_code, ::std::string&& what_arg) :
        runtime_error(error_code, what_arg)
    { }
    explicit runtime_error(status::named_t error_code) :
        runtime_error(static_cast<status_t>(error_code)) { }
    runtime_error(status::named_t error_code, const ::std::string& what_arg) :
        runtime_error(static_cast<status_t>(error_code), what_arg) { }
    runtime_error(status::named_t error_code, ::std::string&& what_arg) :
        runtime_error(static_cast<status_t>(error_code), what_arg) { }

protected:
    runtime_error(status_t error_code, ::std::runtime_error&& err) :
        ::std::runtime_error(::std::move(err)), code_(error_code)
    { }

public:
    static runtime_error with_message_override(status_t error_code, ::std::string complete_what_arg)
    {
        return runtime_error(error_code, ::std::runtime_error(::std::move(complete_what_arg)));
    }

    status_t code() const { return code_; }

private:
    status_t code_;
};

#define throw_if_error_lazy(status__, ... ) \
do { \
    const ::cuda::status_t tie_status__ = static_cast<::cuda::status_t>(status__); \
    if (::cuda::is_failure(tie_status__)) { \
        throw ::cuda::runtime_error(tie_status__, (__VA_ARGS__)); \
    } \
} while(false)

inline void throw_if_error(status_t status, const ::std::string& message) noexcept(false)
{
    if (is_failure(status)) { throw runtime_error(status, message); }
}

inline void throw_if_error(cudaError_t status, const ::std::string& message) noexcept(false)
{
    throw_if_error(static_cast<status_t>(status), message);
}

inline void throw_if_error(status_t status, ::std::string&& message) noexcept(false)
{
    if (is_failure(status)) { throw runtime_error(status, message); }
}

inline void throw_if_error(cudaError_t status, ::std::string&& message) noexcept(false)
{
    return throw_if_error(static_cast<status_t>(status), message);
}

inline void throw_if_error(status_t status) noexcept(false)
{
    if (is_failure(status)) { throw runtime_error(status); }
}

inline void throw_if_error(cudaError_t status) noexcept(false)
{
    throw_if_error(static_cast<status_t>(status));
}

enum : bool {
    dont_clear_errors = false,
    do_clear_errors    = true
};

namespace detail_ {

namespace outstanding_runtime_error {

inline status_t clear() noexcept
{
    return static_cast<status_t>(cudaGetLastError());
}

inline status_t get() noexcept
{
    return static_cast<status_t>(cudaPeekAtLastError());
}

} // namespace outstanding_runtime_error
} // namespace detail_

namespace outstanding_error {

inline status_t get(bool try_clearing = false) noexcept(true)
{
    static constexpr const unsigned dummy_flags{0};
    auto status = cuInit(dummy_flags);
    if (not is_success(status)) { return status; }
    return static_cast<status_t>(try_clearing ? cudaGetLastError() : cudaPeekAtLastError());
}

inline void ensure_none(const ::std::string &message) noexcept(false)
{
    auto status = get();
    throw_if_error(status, message);
}

inline void ensure_none(const char *message) noexcept(false)
{
    return ensure_none(::std::string{message});
}

inline void ensure_none() noexcept(false)
{
    auto status = get();
    throw_if_error(status);
}

} // namespace outstanding_error

// The following few functions are used in the error messages
// generated for exceptions thrown by various API wrappers.

namespace device {
namespace detail_ {
inline ::std::string identify(device::id_t device_id)
{
    return ::std::string("device ") + ::std::to_string(device_id);
}
} // namespace detail_
} // namespace device

namespace context {
namespace detail_ {

inline ::std::string identify(handle_t handle)
{
    return "context " + cuda::detail_::ptr_as_hex(handle);
}

inline ::std::string identify(handle_t handle, device::id_t device_id)
{
    return identify(handle) + " on " + device::detail_::identify(device_id);
}

} // namespace detail_

namespace current {
namespace detail_ {
inline ::std::string identify(context::handle_t handle)
{
    return "current context: " + context::detail_::identify(handle);
}
inline ::std::string identify(context::handle_t handle, device::id_t device_id)
{
    return "current context: " + context::detail_::identify(handle, device_id);
}
} // namespace detail_
} // namespace current

} // namespace context

namespace device {
namespace primary_context {
namespace detail_ {

inline ::std::string identify(handle_t handle, device::id_t device_id)
{
    return "context " + context::detail_::identify(handle, device_id);
}
inline ::std::string identify(handle_t handle)
{
    return "context " + context::detail_::identify(handle);
}
} // namespace detail_
} // namespace primary_context
} // namespace device

namespace stream {
namespace detail_ {
inline ::std::string identify(handle_t handle)
{
    return "stream " + cuda::detail_::ptr_as_hex(handle);
}
inline ::std::string identify(handle_t handle, device::id_t device_id)
{
    return identify(handle) + " on " + device::detail_::identify(device_id);
}
inline ::std::string identify(handle_t handle, context::handle_t context_handle)
{
    return identify(handle) + " in " + context::detail_::identify(context_handle);
}
inline ::std::string identify(handle_t handle, context::handle_t context_handle, device::id_t device_id)
{
    return identify(handle) + " in " + context::detail_::identify(context_handle, device_id);
}
} // namespace detail_
} // namespace stream

namespace event {
namespace detail_ {
inline ::std::string identify(handle_t handle)
{
    return "event " + cuda::detail_::ptr_as_hex(handle);
}
inline ::std::string identify(handle_t handle, device::id_t device_id)
{
    return identify(handle) + " on " + device::detail_::identify(device_id);
}
inline ::std::string identify(handle_t handle, context::handle_t context_handle)
{
    return identify(handle) + " on " + context::detail_::identify(context_handle);
}
inline ::std::string identify(handle_t handle, context::handle_t context_handle, device::id_t device_id)
{
    return identify(handle) + " on " + context::detail_::identify(context_handle, device_id);
}
} // namespace detail_
} // namespace event

namespace kernel {
namespace detail_ {

inline ::std::string identify(const void* ptr)
{
    return "kernel " + cuda::detail_::ptr_as_hex(ptr);
}
inline ::std::string identify(const void* ptr, device::id_t device_id)
{
    return identify(ptr) + " on " + device::detail_::identify(device_id);
}
inline ::std::string identify(const void* ptr, context::handle_t context_handle)
{
    return identify(ptr) + " in " + context::detail_::identify(context_handle);
}
inline ::std::string identify(const void* ptr, context::handle_t context_handle, device::id_t device_id)
{
    return identify(ptr) + " in " + context::detail_::identify(context_handle, device_id);
}
inline ::std::string identify(handle_t handle)
{
    return "kernel at " + cuda::detail_::ptr_as_hex(handle);
}
inline ::std::string identify(handle_t handle, context::handle_t context_handle)
{
    return identify(handle) + " in " + context::detail_::identify(context_handle);
}
inline ::std::string identify(handle_t handle,  device::id_t device_id)
{
    return identify(handle) + " on " + device::detail_::identify(device_id);
}
inline ::std::string identify(handle_t handle, context::handle_t context_handle, device::id_t device_id)
{
    return identify(handle) + " in " + context::detail_::identify(context_handle, device_id);
}

} // namespace detail_
} // namespace kernel

namespace memory {
namespace detail_ {

inline ::std::string identify(region_t region)
{
    return ::std::string("memory region at ") + cuda::detail_::ptr_as_hex(region.data())
        + " of size " + ::std::to_string(region.size());
}

inline ::std::string identify(location_t location)
{
    switch (location.type) {
    case CU_MEM_LOCATION_TYPE_DEVICE:
        if (location.id != CU_DEVICE_CPU) {
            return "global memory of " + cuda::device::detail_::identify(location.id);
        }
        // fallthrough
    case CU_MEM_LOCATION_TYPE_HOST:
        return "host (system) memory";
    case CU_MEM_LOCATION_TYPE_HOST_NUMA:
        return "host (system) NUMA node " + ::std::to_string(location.id);
    case CU_MEM_LOCATION_TYPE_HOST_NUMA_CURRENT:
        return "current host (system) NUMA node ";
    default:
        return "(invalid)";
    }
}

} // namespace detail_

} // namespace memory

} // namespace cuda

#endif // CUDA_API_WRAPPERS_ERROR_HPP_