EBGeometry_GPURuntime.hpp File Reference

Backend-neutral GPU runtime API layer (CUDA or HIP) plus the EBGEOMETRY_GPU_CHECK macro. More...

#include "EBGeometry_GPU.hpp"
#include <cstddef>
#include <cstdio>
#include <cstdlib>

Include dependency graph for EBGeometry_GPURuntime.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Namespaces
namespace	EBGeometry
	Namespace containing all of EBGeometry's functionality.
namespace	EBGeometry::GPU
	Backend-neutral GPU runtime API surface (CUDA or HIP).

Macros
#define	EBGEOMETRY_GPU_CHECK(x)
	Always-on GPU runtime API error check: prints the failing call and aborts.

Typedefs
using	EBGeometry::GPU::Error = int
	Backend runtime error code (cudaError_t under CUDA, hipError_t under HIP).
using	EBGeometry::GPU::MemcpyKind = int
	Memory-copy direction (cudaMemcpyKind under CUDA, hipMemcpyKind under HIP).

Functions
Error	EBGeometry::GPU::memAlloc (void **a_devicePtr, size_t a_numBytes) noexcept
	Allocate device memory (cudaMalloc / hipMalloc).
Error	EBGeometry::GPU::memFree (void *a_devicePtr) noexcept
	Free device memory allocated with memAlloc (cudaFree / hipFree).
Error	EBGeometry::GPU::memAllocManaged (void **a_ptr, size_t a_numBytes) noexcept
	Allocate managed (unified) memory accessible from host and device (cudaMallocManaged / hipMallocManaged).
Error	EBGeometry::GPU::memAllocHost (void **a_ptr, size_t a_numBytes) noexcept
	Allocate page-locked (pinned) host memory (cudaHostAlloc / hipHostMalloc).
Error	EBGeometry::GPU::memAllocHostMapped (void **a_ptr, size_t a_numBytes) noexcept
	Allocate page-locked (pinned) host memory that is additionally mapped into the device address space for zero-copy access (cudaHostAlloc with cudaHostAllocMapped / hipHostMalloc with hipHostMallocMapped). Under unified virtual addressing the returned host pointer is directly valid on the device. Free with memFreeHost.
Error	EBGeometry::GPU::memFreeHost (void *a_ptr) noexcept
	Free page-locked host memory allocated with memAllocHost (cudaFreeHost / hipHostFree).
Error	EBGeometry::GPU::memcpy (void *a_dst, const void *a_src, size_t a_numBytes, MemcpyKind a_kind) noexcept
	Copy memory between host and device (cudaMemcpy / hipMemcpy). Synchronous.
Error	EBGeometry::GPU::getDeviceCount (int *a_count) noexcept
	Get the number of available GPU devices (cudaGetDeviceCount / hipGetDeviceCount).
Error	EBGeometry::GPU::getLastError () noexcept
	Get and clear the last runtime error (cudaGetLastError / hipGetLastError).
Error	EBGeometry::GPU::deviceSynchronize () noexcept
	Block until the device has finished all preceding work (cudaDeviceSynchronize / hipDeviceSynchronize).
const char *	EBGeometry::GPU::getErrorString (Error a_error) noexcept
	Get the human-readable description of an error code (cudaGetErrorString / hipGetErrorString).
bool	EBGeometry::GPU::isShutdownError (Error a_error) noexcept
	True for the errors a runtime call returns once the runtime has shut down at program exit (cudaErrorCudartUnloading or cudaErrorContextIsDestroyed under CUDA, hipErrorDeinitialized or hipErrorContextIsDestroyed under HIP).
const char *	EBGeometry::GPU::getErrorHint (Error a_error) noexcept
	What to do about an error that means the binary has no code this GPU can run: the binary was built for another architecture, or carries only PTX that the driver, older than the toolkit, cannot compile (cudaErrorUnsupportedPtxVersion or cudaErrorNoKernelImageForDevice under CUDA, hipErrorNoBinaryForGpu under HIP).

Variables
constexpr Error	EBGeometry::GPU::Success = 0
	Success value of Error (cudaSuccess / hipSuccess).
constexpr MemcpyKind	EBGeometry::GPU::MemcpyHostToDevice = 1
	Host-to-device copy direction (cudaMemcpyHostToDevice / hipMemcpyHostToDevice).
constexpr MemcpyKind	EBGeometry::GPU::MemcpyDeviceToHost = 2
	Device-to-host copy direction (cudaMemcpyDeviceToHost / hipMemcpyDeviceToHost).

Detailed Description

Backend-neutral GPU runtime API layer (CUDA or HIP) plus the EBGEOMETRY_GPU_CHECK macro.

Unlike EBGeometry_GPU.hpp – which only detects the offload compiler and defines the decoration macros, pulling in no backend runtime headers – this header IS the runtime-API layer: it includes the backend runtime header (<cuda_runtime.h> or <hip/hip_runtime.h>) and exposes the small memory-management/error surface EBGeometry needs through backend-neutral aliases and inline wrappers in the EBGeometry::GPU namespace, so any translation unit that uses it compiles unchanged whether built as a CUDA (.cu) or HIP (.hip) translation unit. On an ordinary host compiler the whole header is inert (empty after preprocessing), so the umbrella EBGeometry.hpp can include it unconditionally.

HIP is checked before CUDA: hipcc on the NVIDIA platform defines both __HIPCC__ and __CUDACC__, and there the hip* entry points exist and forward to cuda*, so mapping to hip* whenever __HIPCC__ is defined is correct on both HIP platforms.

Author

Robert Marskar

Macro Definition Documentation

EBGEOMETRY_GPU_CHECK

#define EBGEOMETRY_GPU_CHECK

(

x

)

Value:

  do {                                                                                 \
    const EBGeometry::GPU::Error ebgeometry_gpu_err = (x);                             \
    if (ebgeometry_gpu_err != EBGeometry::GPU::Success) {                              \
      std::fprintf(stderr,                                                             \
                   "EBGeometry GPU error: %s\n  call: %s\n  file: %s\n  line: %d%s\n", \
                   EBGeometry::GPU::getErrorString(ebgeometry_gpu_err),                \
                   #x,                                                                 \
                   __FILE__,                                                           \
                   __LINE__,                                                           \
                   EBGeometry::GPU::getErrorHint(ebgeometry_gpu_err));                 \
      std::abort();                                                                    \
    }                                                                                  \
  } while (0)

Always-on GPU runtime API error check: prints the failing call and aborts.

Host-side only. Deliberately NOT gated on EBGEOMETRY_ENABLE_ASSERTIONS (unlike EBGEOMETRY_EXPECT): a failed allocation or copy leaves the caller holding a null or dangling device pointer, which a release build must not silently proceed to use. Abort (rather than an exception) matches the library's no-exceptions convention.

Parameters

x	GPU runtime API call (or any expression) yielding an EBGeometry::GPU::Error.