GpuPluginAbi.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2026 Caleb Buahin
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

 
#ifndef OPENSWMM_ENGINE_2D_GPU_PLUGIN_ABI_H
#define OPENSWMM_ENGINE_2D_GPU_PLUGIN_ABI_H
 
/*
 * Export/visibility marker for the two ABI entry points.
 *
 * The declaration here and the definition in each plugin .cpp must agree on
 * linkage or MSVC rejects the definition with C2375 ("redefinition; different
 * linkage") — a plain `extern "C"` declaration followed by an
 * `__declspec(dllexport)` definition is a mismatch. A plugin translation unit
 * defines OPENSWMM_GPU_PLUGIN_BUILD (see the gpu CMakeLists) so it both
 * declares and defines the symbols as dllexport. The core never link-imports
 * these (it resolves them via dlsym/GetProcAddress), so the non-plugin case is
 * a no-op marker.
 */
#if defined(_WIN32)
#if defined(OPENSWMM_GPU_PLUGIN_BUILD)
#define OPENSWMM_GPU_ABI __declspec(dllexport)
#else
#define OPENSWMM_GPU_ABI
#endif
#elif defined(__GNUC__)
#define OPENSWMM_GPU_ABI __attribute__((visibility("default")))
#else
#define OPENSWMM_GPU_ABI
#endif
 
#ifdef __cplusplus
extern "C" {
#endif

/* v5: reject v3/v4 C++ vtables predating completedSourceTime and the current
 * state layouts. A matching build contract and plugin-owned destruction are
 * mandatory. Never accept an older version through a thread-count fallback. */
/* v6: SurfaceTransportState adds the canonical RK2 age-generation ledger;
 * SurfaceStateData offsets therefore change. Rebuild every surface plugin.
 * The independent C-only groundwater raw-recharge ABI remains v1. */
/* v7: SurfaceStateData adds accepted runtime-forcing rainfall receipts.
 * Rebuild surface plugins; independent raw groundwater recharge remains v1. */
/* v8: SurfaceStateData adds gross applied boundary-water transfer arrays.
 * Rebuild surface plugins; independent raw groundwater recharge remains v1. */
/* v9: SolverOptions2D adds the physical-time momentum smoothing reference
 * interval. Rebuild surface plugins to match the changed option layout. */
#define OPENSWMM_GPU_ABI_VERSION 9

typedef enum OpenSwmmGpuVendor {
    OPENSWMM_GPU_VENDOR_NONE = 0,  
    OPENSWMM_GPU_VENDOR_CUDA = 1,  
    OPENSWMM_GPU_VENDOR_HIP = 2,   
    OPENSWMM_GPU_VENDOR_SYCL = 3,  
    OPENSWMM_GPU_VENDOR_OPENMP = 4 
} OpenSwmmGpuVendor;

typedef struct OpenSwmmGpuProbe {
    int abi_version;                     
    int device_count;                    
    int vendor;                          
    char device_name[128];               
    unsigned long long device_mem_bytes; 
    int requested_threads;
} OpenSwmmGpuProbe;

OPENSWMM_GPU_ABI int openswmm_gpu_probe(OpenSwmmGpuProbe* out);

OPENSWMM_GPU_ABI void* openswmm_make_gpu_explicit_solver(const OpenSwmmGpuProbe* probe);

OPENSWMM_GPU_ABI const char* openswmm_gpu_build_contract(void);
OPENSWMM_GPU_ABI void openswmm_destroy_gpu_explicit_solver(void* solver);
OPENSWMM_GPU_ABI const char* openswmm_gpu_last_error(void);

OPENSWMM_GPU_ABI int openswmm_gpu_host_threads(void);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* OPENSWMM_ENGINE_2D_GPU_PLUGIN_ABI_H */