hip_runtime_api.h

Go to the documentation of this file.

/*
Copyright (c) 2015 - present Advanced Micro Devices, Inc. All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
*/

//#pragma once
#ifndef HIP_INCLUDE_HIP_HCC_DETAIL_HIP_RUNTIME_API_H
#define HIP_INCLUDE_HIP_HCC_DETAIL_HIP_RUNTIME_API_H

#include <stdint.h>
#include <stddef.h>

#ifndef GENERIC_GRID_LAUNCH
#define GENERIC_GRID_LAUNCH 1
#endif

#ifndef __HIP_VDI__
#define __HIP_VDI__ 0
#endif

#include <hip/hcc_detail/host_defines.h>
#include <hip/hip_runtime_api.h>
#include <hip/hcc_detail/driver_types.h>
#include <hip/hcc_detail/hip_texture_types.h>
#include <hip/hcc_detail/hip_surface_types.h>

#if !__HIP_VDI__
#include <hsa/hsa.h>
#include <hip/hcc_detail/program_state.hpp>
#endif

#if defined(_MSC_VER)
#define DEPRECATED(msg) __declspec(deprecated(msg))
#else // !defined(_MSC_VER)
#define DEPRECATED(msg) __attribute__ ((deprecated(msg)))
#endif // !defined(_MSC_VER)

#define DEPRECATED_MSG "This API is marked as deprecated and may not be supported in future releases.For more details please refer https://github.com/ROCm-Developer-Tools/HIP/tree/master/docs/markdown/hip_deprecated_api_list"

#if defined(__HCC__) && (__hcc_workweek__ < 16155)
#error("This version of HIP requires a newer version of HCC.");
#endif

#define HIP_LAUNCH_PARAM_BUFFER_POINTER ((void*)0x01)
#define HIP_LAUNCH_PARAM_BUFFER_SIZE ((void*)0x02)
#define HIP_LAUNCH_PARAM_END ((void*)0x03)

#ifdef __cplusplus
  #include <algorithm>
  #include <mutex>
  #include <string>
  #include <unordered_map>
  #include <vector>

  #define __dparm(x) \
          = x
#else
  #define __dparm(x)
#endif

namespace hip_impl {
hipError_t hip_init();
}  // namespace hip_impl

// Structure definitions:
#ifdef __cplusplus
extern "C" {
#endif

//---
// API-visible structures
typedef struct ihipCtx_t* hipCtx_t;

// Note many APIs also use integer deviceIds as an alternative to the device pointer:
typedef int hipDevice_t;

typedef struct ihipStream_t* hipStream_t;

// TODO: IPC implementation

#define hipIpcMemLazyEnablePeerAccess 0

#define HIP_IPC_HANDLE_SIZE 64

typedef struct hipIpcMemHandle_st {
    char reserved[HIP_IPC_HANDLE_SIZE];
} hipIpcMemHandle_t;

// TODO: IPC event handle currently unsupported
struct ihipIpcEventHandle_t;
typedef struct ihipIpcEventHandle_t* hipIpcEventHandle_t;


// END TODO

typedef struct ihipModule_t* hipModule_t;

typedef struct ihipModuleSymbol_t* hipFunction_t;

typedef struct hipFuncAttributes {
    int binaryVersion;
    int cacheModeCA;
    size_t constSizeBytes;
    size_t localSizeBytes;
    int maxDynamicSharedSizeBytes;
    int maxThreadsPerBlock;
    int numRegs;
    int preferredShmemCarveout;
    int ptxVersion;
    size_t sharedSizeBytes;
} hipFuncAttributes;

typedef struct ihipEvent_t* hipEvent_t;

enum hipLimit_t {
    hipLimitMallocHeapSize = 0x02,
};

#define hipStreamDefault                                                                           \
    0x00  
#define hipStreamNonBlocking 0x01  


#define hipEventDefault 0x0  
#define hipEventBlockingSync                                                                       \
    0x1  
#define hipEventDisableTiming                                                                      \
    0x2  
#define hipEventInterprocess 0x4  
#define hipEventReleaseToDevice                                                                    \
    0x40000000  
#define hipEventReleaseToSystem                                                                    \
    0x80000000  


#define hipHostMallocDefault 0x0
#define hipHostMallocPortable 0x1  
#define hipHostMallocMapped                                                                        \
    0x2  
#define hipHostMallocWriteCombined 0x4
#define hipHostMallocCoherent                                                                      \
    0x40000000  
#define hipHostMallocNonCoherent                                                                   \
    0x80000000  

#define hipMemAttachGlobal 0x0
#define hipMemAttachHost 0x1

#define hipDeviceMallocDefault 0x0
#define hipDeviceMallocFinegrained 0x1  

#define hipHostRegisterDefault 0x0   
#define hipHostRegisterPortable 0x1  
#define hipHostRegisterMapped                                                                      \
    0x2  
#define hipHostRegisterIoMemory 0x4  
#define hipExtHostRegisterCoarseGrained 0x8  

#define hipDeviceScheduleAuto 0x0  
#define hipDeviceScheduleSpin                                                                      \
    0x1  
#define hipDeviceScheduleYield                                                                     \
    0x2  
#define hipDeviceScheduleBlockingSync 0x4
#define hipDeviceScheduleMask 0x7

#define hipDeviceMapHost 0x8
#define hipDeviceLmemResizeToMax 0x16

#define hipArrayDefault 0x00  
#define hipArrayLayered 0x01
#define hipArraySurfaceLoadStore 0x02
#define hipArrayCubemap 0x04
#define hipArrayTextureGather 0x08

/*
 * @brief hipJitOption
 * @enum
 * @ingroup Enumerations
 */
typedef enum hipJitOption {
    hipJitOptionMaxRegisters = 0,
    hipJitOptionThreadsPerBlock,
    hipJitOptionWallTime,
    hipJitOptionInfoLogBuffer,
    hipJitOptionInfoLogBufferSizeBytes,
    hipJitOptionErrorLogBuffer,
    hipJitOptionErrorLogBufferSizeBytes,
    hipJitOptionOptimizationLevel,
    hipJitOptionTargetFromContext,
    hipJitOptionTarget,
    hipJitOptionFallbackStrategy,
    hipJitOptionGenerateDebugInfo,
    hipJitOptionLogVerbose,
    hipJitOptionGenerateLineInfo,
    hipJitOptionCacheMode,
    hipJitOptionSm3xOpt,
    hipJitOptionFastCompile,
    hipJitOptionNumOptions
} hipJitOption;


typedef enum hipFuncCache_t {
    hipFuncCachePreferNone,    
    hipFuncCachePreferShared,  
    hipFuncCachePreferL1,      
    hipFuncCachePreferEqual,   
} hipFuncCache_t;


typedef enum hipSharedMemConfig {
    hipSharedMemBankSizeDefault,  
    hipSharedMemBankSizeFourByte,  
    hipSharedMemBankSizeEightByte  
} hipSharedMemConfig;


typedef struct dim3 {
    uint32_t x;  
    uint32_t y;  
    uint32_t z;  
#ifdef __cplusplus
    dim3(uint32_t _x = 1, uint32_t _y = 1, uint32_t _z = 1) : x(_x), y(_y), z(_z){};
#endif
} dim3;


// Doxygen end group GlobalDefs
//-------------------------------------------------------------------------------------------------


// The handle allows the async commands to use the stream even if the parent hipStream_t goes
// out-of-scope.
// typedef class ihipStream_t * hipStream_t;


/*
 * Opaque structure allows the true event (pointed at by the handle) to remain "live" even if the
 * surrounding hipEvent_t goes out-of-scope. This is handy for cases where the hipEvent_t goes
 * out-of-scope but the true event is being written by some async queue or device */
// typedef struct hipEvent_t {
//    struct ihipEvent_t *_handle;
//} hipEvent_t;


hipError_t hipDeviceSynchronize(void);


hipError_t hipDeviceReset(void);


hipError_t hipSetDevice(int deviceId);


hipError_t hipGetDevice(int* deviceId);


hipError_t hipGetDeviceCount(int* count);

hipError_t hipDeviceGetAttribute(int* pi, hipDeviceAttribute_t attr, int deviceId);

hipError_t hipGetDeviceProperties(hipDeviceProp_t* prop, int deviceId);


hipError_t hipDeviceSetCacheConfig(hipFuncCache_t cacheConfig);


hipError_t hipDeviceGetCacheConfig(hipFuncCache_t* cacheConfig);

hipError_t hipDeviceGetLimit(size_t* pValue, enum hipLimit_t limit);


hipError_t hipFuncSetCacheConfig(const void* func, hipFuncCache_t config);

hipError_t hipDeviceGetSharedMemConfig(hipSharedMemConfig* pConfig);


hipError_t hipDeviceSetSharedMemConfig(hipSharedMemConfig config);

hipError_t hipSetDeviceFlags(unsigned flags);

hipError_t hipChooseDevice(int* device, const hipDeviceProp_t* prop);

hipError_t hipExtGetLinkTypeAndHopCount(int device1, int device2, uint32_t* linktype, uint32_t* hopcount);

// end doxygen Device
hipError_t hipGetLastError(void);


hipError_t hipPeekAtLastError(void);


const char* hipGetErrorName(hipError_t hip_error);


const char* hipGetErrorString(hipError_t hipError);

// end doxygen Error
hipError_t hipStreamCreate(hipStream_t* stream);


hipError_t hipStreamCreateWithFlags(hipStream_t* stream, unsigned int flags);


hipError_t hipStreamCreateWithPriority(hipStream_t* stream, unsigned int flags, int priority);


hipError_t hipDeviceGetStreamPriorityRange(int* leastPriority, int* greatestPriority);


hipError_t hipStreamDestroy(hipStream_t stream);


hipError_t hipStreamQuery(hipStream_t stream);


hipError_t hipStreamSynchronize(hipStream_t stream);


hipError_t hipStreamWaitEvent(hipStream_t stream, hipEvent_t event, unsigned int flags);


hipError_t hipStreamGetFlags(hipStream_t stream, unsigned int* flags);


hipError_t hipStreamGetPriority(hipStream_t stream, int* priority);


typedef void (*hipStreamCallback_t)(hipStream_t stream, hipError_t status, void* userData);

hipError_t hipStreamAddCallback(hipStream_t stream, hipStreamCallback_t callback, void* userData,
                                unsigned int flags);


// end doxygen Stream
hipError_t hipEventCreateWithFlags(hipEvent_t* event, unsigned flags);


hipError_t hipEventCreate(hipEvent_t* event);


#ifdef __cplusplus
hipError_t hipEventRecord(hipEvent_t event, hipStream_t stream = NULL);
#else
hipError_t hipEventRecord(hipEvent_t event, hipStream_t stream);
#endif

hipError_t hipEventDestroy(hipEvent_t event);


hipError_t hipEventSynchronize(hipEvent_t event);


hipError_t hipEventElapsedTime(float* ms, hipEvent_t start, hipEvent_t stop);


hipError_t hipEventQuery(hipEvent_t event);


// end doxygen Events
hipError_t hipPointerGetAttributes(hipPointerAttribute_t* attributes, const void* ptr);

hipError_t hipMalloc(void** ptr, size_t size);

hipError_t hipExtMallocWithFlags(void** ptr, size_t sizeBytes, unsigned int flags);

DEPRECATED("use hipHostMalloc instead")
hipError_t hipMallocHost(void** ptr, size_t size);

hipError_t hipHostMalloc(void** ptr, size_t size, unsigned int flags);

hipError_t hipMallocManaged(void** devPtr, size_t size, unsigned int flags __dparm(0));

DEPRECATED("use hipHostMalloc instead")
hipError_t hipHostAlloc(void** ptr, size_t size, unsigned int flags);

hipError_t hipHostGetDevicePointer(void** devPtr, void* hstPtr, unsigned int flags);

hipError_t hipHostGetFlags(unsigned int* flagsPtr, void* hostPtr);

hipError_t hipHostRegister(void* hostPtr, size_t sizeBytes, unsigned int flags);

hipError_t hipHostUnregister(void* hostPtr);

hipError_t hipMallocPitch(void** ptr, size_t* pitch, size_t width, size_t height);

hipError_t hipFree(void* ptr);

DEPRECATED("use hipHostFree instead")
hipError_t hipFreeHost(void* ptr);

hipError_t hipHostFree(void* ptr);

hipError_t hipMemcpy(void* dst, const void* src, size_t sizeBytes, hipMemcpyKind kind);

hipError_t hipMemcpyHtoD(hipDeviceptr_t dst, void* src, size_t sizeBytes);

hipError_t hipMemcpyDtoH(void* dst, hipDeviceptr_t src, size_t sizeBytes);

hipError_t hipMemcpyDtoD(hipDeviceptr_t dst, hipDeviceptr_t src, size_t sizeBytes);

hipError_t hipMemcpyHtoDAsync(hipDeviceptr_t dst, void* src, size_t sizeBytes, hipStream_t stream);

hipError_t hipMemcpyDtoHAsync(void* dst, hipDeviceptr_t src, size_t sizeBytes, hipStream_t stream);

hipError_t hipMemcpyDtoDAsync(hipDeviceptr_t dst, hipDeviceptr_t src, size_t sizeBytes,
                              hipStream_t stream);

#if __HIP_VDI__
hipError_t hipModuleGetGlobal(hipDeviceptr_t* dptr, size_t* bytes,
    hipModule_t hmod, const char* name);

hipError_t hipGetSymbolAddress(void** devPtr, const void* symbolName);
hipError_t hipGetSymbolSize(size_t* size, const void* symbolName);
hipError_t hipMemcpyToSymbol(const void* symbolName, const void* src,
                             size_t sizeBytes, size_t offset __dparm(0),
                             hipMemcpyKind kind __dparm(hipMemcpyHostToDevice));
hipError_t hipMemcpyToSymbolAsync(const void* symbolName, const void* src,
                                  size_t sizeBytes, size_t offset,
                                  hipMemcpyKind kind, hipStream_t stream __dparm(0));
hipError_t hipMemcpyFromSymbol(void* dst, const void* symbolName,
                               size_t sizeBytes, size_t offset __dparm(0),
                               hipMemcpyKind kind __dparm(hipMemcpyDeviceToHost));
hipError_t hipMemcpyFromSymbolAsync(void* dst, const void* symbolName,
                                    size_t sizeBytes, size_t offset,
                                    hipMemcpyKind kind,
                                    hipStream_t stream __dparm(0));
#else
hipError_t hipModuleGetGlobal(void**, size_t*, hipModule_t, const char*);

namespace hip_impl {
inline
__attribute__((visibility("hidden")))
hipError_t read_agent_global_from_process(hipDeviceptr_t* dptr, size_t* bytes,
                                          const char* name);
} // Namespace hip_impl.

inline
__attribute__((visibility("hidden")))
hipError_t hipGetSymbolAddress(void** devPtr, const void* symbolName) {
    //HIP_INIT_API(hipGetSymbolAddress, devPtr, symbolName);
    hip_impl::hip_init();
    size_t size = 0;
    return hip_impl::read_agent_global_from_process(devPtr, &size, (const char*)symbolName);
}


inline
__attribute__((visibility("hidden")))
hipError_t hipGetSymbolSize(size_t* size, const void* symbolName) {
    // HIP_INIT_API(hipGetSymbolSize, size, symbolName);
    hip_impl::hip_init();
    void* devPtr = nullptr;
    return hip_impl::read_agent_global_from_process(&devPtr, size, (const char*)symbolName);
}

#if defined(__cplusplus)
} // extern "C"
#endif

namespace hip_impl {
hipError_t hipMemcpyToSymbol(void*, const void*, size_t, size_t, hipMemcpyKind,
                             const char*);
} // Namespace hip_impl.

#if defined(__cplusplus)
extern "C" {
#endif

inline
__attribute__((visibility("hidden")))
hipError_t hipMemcpyToSymbol(const void* symbolName, const void* src,
                             size_t sizeBytes, size_t offset __dparm(0),
                             hipMemcpyKind kind __dparm(hipMemcpyHostToDevice)) {
    if (!symbolName) return hipErrorInvalidSymbol;

    hipDeviceptr_t dst = NULL;
    hipGetSymbolAddress(&dst, (const char*)symbolName);

    return hip_impl::hipMemcpyToSymbol(dst, src, sizeBytes, offset, kind,
                                       (const char*)symbolName);
}

#if defined(__cplusplus)
} // extern "C"
#endif

namespace hip_impl {
hipError_t hipMemcpyToSymbolAsync(void*, const void*, size_t, size_t,
                                  hipMemcpyKind, hipStream_t, const char*);
hipError_t hipMemcpyFromSymbol(void*, const void*, size_t, size_t,
                               hipMemcpyKind, const char*);
hipError_t hipMemcpyFromSymbolAsync(void*, const void*, size_t, size_t,
                                    hipMemcpyKind, hipStream_t, const char*);
} // Namespace hip_impl.

#if defined(__cplusplus)
extern "C" {
#endif

inline
__attribute__((visibility("hidden")))
hipError_t hipMemcpyToSymbolAsync(const void* symbolName, const void* src,
                                  size_t sizeBytes, size_t offset,
                                  hipMemcpyKind kind, hipStream_t stream __dparm(0)) {
    if (!symbolName) return hipErrorInvalidSymbol;

    hipDeviceptr_t dst = NULL;
    hipGetSymbolAddress(&dst, symbolName);

    return hip_impl::hipMemcpyToSymbolAsync(dst, src, sizeBytes, offset, kind,
                                            stream,
                                            (const char*)symbolName);
}

inline
__attribute__((visibility("hidden")))
hipError_t hipMemcpyFromSymbol(void* dst, const void* symbolName,
                               size_t sizeBytes, size_t offset __dparm(0),
                               hipMemcpyKind kind __dparm(hipMemcpyDeviceToHost)) {
    if (!symbolName) return hipErrorInvalidSymbol;

    hipDeviceptr_t src = NULL;
    hipGetSymbolAddress(&src, symbolName);

    return hip_impl::hipMemcpyFromSymbol(dst, src, sizeBytes, offset, kind,
                                         (const char*)symbolName);
}

inline
__attribute__((visibility("hidden")))
hipError_t hipMemcpyFromSymbolAsync(void* dst, const void* symbolName,
                                    size_t sizeBytes, size_t offset,
                                    hipMemcpyKind kind,
                                    hipStream_t stream __dparm(0)) {
    if (!symbolName) return hipErrorInvalidSymbol;

    hipDeviceptr_t src = NULL;
    hipGetSymbolAddress(&src, symbolName);

    return hip_impl::hipMemcpyFromSymbolAsync(dst, src, sizeBytes, offset, kind,
                                              stream,
                                              (const char*)symbolName);
}

#endif // __HIP_VDI__

hipError_t hipMemcpyAsync(void* dst, const void* src, size_t sizeBytes, hipMemcpyKind kind,
                          hipStream_t stream __dparm(0));

hipError_t hipMemset(void* dst, int value, size_t sizeBytes);

hipError_t hipMemsetD8(hipDeviceptr_t dest, unsigned char value, size_t sizeBytes);

hipError_t hipMemsetD32(hipDeviceptr_t dest, int value, size_t count);

hipError_t hipMemsetAsync(void* dst, int value, size_t sizeBytes, hipStream_t stream __dparm(0));

hipError_t hipMemsetD32Async(hipDeviceptr_t dst, int value, size_t count,
                             hipStream_t stream __dparm(0));

hipError_t hipMemset2D(void* dst, size_t pitch, int value, size_t width, size_t height);

hipError_t hipMemset2DAsync(void* dst, size_t pitch, int value, size_t width, size_t height,hipStream_t stream __dparm(0));

hipError_t hipMemset3D(hipPitchedPtr pitchedDevPtr, int  value, hipExtent extent );

hipError_t hipMemset3DAsync(hipPitchedPtr pitchedDevPtr, int  value, hipExtent extent ,hipStream_t stream __dparm(0));

hipError_t hipMemGetInfo(size_t* free, size_t* total);


hipError_t hipMemPtrGetInfo(void* ptr, size_t* size);


hipError_t hipMallocArray(hipArray** array, const hipChannelFormatDesc* desc, size_t width,
                          size_t height __dparm(0), unsigned int flags __dparm(hipArrayDefault));
hipError_t hipArrayCreate(hipArray** pHandle, const HIP_ARRAY_DESCRIPTOR* pAllocateArray);

hipError_t hipArray3DCreate(hipArray** array, const HIP_ARRAY_DESCRIPTOR* pAllocateArray);

hipError_t hipMalloc3D(hipPitchedPtr* pitchedDevPtr, hipExtent extent);

hipError_t hipFreeArray(hipArray* array);

hipError_t hipMalloc3DArray(hipArray** array, const struct hipChannelFormatDesc* desc,
                            struct hipExtent extent, unsigned int flags);
hipError_t hipMemcpy2D(void* dst, size_t dpitch, const void* src, size_t spitch, size_t width,
                       size_t height, hipMemcpyKind kind);
hipError_t hipMemcpyParam2D(const hip_Memcpy2D* pCopy);

hipError_t hipMemcpy2DAsync(void* dst, size_t dpitch, const void* src, size_t spitch, size_t width,
                            size_t height, hipMemcpyKind kind, hipStream_t stream __dparm(0));

hipError_t hipMemcpy2DToArray(hipArray* dst, size_t wOffset, size_t hOffset, const void* src,
                              size_t spitch, size_t width, size_t height, hipMemcpyKind kind);

hipError_t hipMemcpyToArray(hipArray* dst, size_t wOffset, size_t hOffset, const void* src,
                            size_t count, hipMemcpyKind kind);

hipError_t hipMemcpyFromArray(void* dst, hipArray_const_t srcArray, size_t wOffset, size_t hOffset,
                              size_t count, hipMemcpyKind kind);

hipError_t hipMemcpyAtoH(void* dst, hipArray* srcArray, size_t srcOffset, size_t count);

hipError_t hipMemcpyHtoA(hipArray* dstArray, size_t dstOffset, const void* srcHost, size_t count);

hipError_t hipMemcpy3D(const struct hipMemcpy3DParms* p);

// doxygen end Memory
hipError_t hipDeviceCanAccessPeer(int* canAccessPeer, int deviceId, int peerDeviceId);


hipError_t hipDeviceEnablePeerAccess(int peerDeviceId, unsigned int flags);


hipError_t hipDeviceDisablePeerAccess(int peerDeviceId);

hipError_t hipMemGetAddressRange(hipDeviceptr_t* pbase, size_t* psize, hipDeviceptr_t dptr);

#ifndef USE_PEER_NON_UNIFIED
#define USE_PEER_NON_UNIFIED 1
#endif

#if USE_PEER_NON_UNIFIED == 1

hipError_t hipMemcpyPeer(void* dst, int dstDeviceId, const void* src, int srcDeviceId,
                         size_t sizeBytes);

hipError_t hipMemcpyPeerAsync(void* dst, int dstDeviceId, const void* src, int srcDevice,
                              size_t sizeBytes, hipStream_t stream __dparm(0));
#endif


// doxygen end PeerToPeer
// TODO-ctx - more description on error codes.
hipError_t hipInit(unsigned int flags);


DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxCreate(hipCtx_t* ctx, unsigned int flags, hipDevice_t device);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxDestroy(hipCtx_t ctx);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxPopCurrent(hipCtx_t* ctx);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxPushCurrent(hipCtx_t ctx);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxSetCurrent(hipCtx_t ctx);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxGetCurrent(hipCtx_t* ctx);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxGetDevice(hipDevice_t* device);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxGetApiVersion(hipCtx_t ctx, int* apiVersion);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxGetCacheConfig(hipFuncCache_t* cacheConfig);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxSetCacheConfig(hipFuncCache_t cacheConfig);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxSetSharedMemConfig(hipSharedMemConfig config);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxGetSharedMemConfig(hipSharedMemConfig* pConfig);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxSynchronize(void);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxGetFlags(unsigned int* flags);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxEnablePeerAccess(hipCtx_t peerCtx, unsigned int flags);

DEPRECATED(DEPRECATED_MSG)
hipError_t hipCtxDisablePeerAccess(hipCtx_t peerCtx);

hipError_t hipDevicePrimaryCtxGetState(hipDevice_t dev, unsigned int* flags, int* active);

hipError_t hipDevicePrimaryCtxRelease(hipDevice_t dev);

hipError_t hipDevicePrimaryCtxRetain(hipCtx_t* pctx, hipDevice_t dev);

hipError_t hipDevicePrimaryCtxReset(hipDevice_t dev);

hipError_t hipDevicePrimaryCtxSetFlags(hipDevice_t dev, unsigned int flags);

// doxygen end Context Management
hipError_t hipDeviceGet(hipDevice_t* device, int ordinal);

hipError_t hipDeviceComputeCapability(int* major, int* minor, hipDevice_t device);

hipError_t hipDeviceGetName(char* name, int len, hipDevice_t device);

hipError_t hipDeviceGetPCIBusId(char* pciBusId, int len, int device);


hipError_t hipDeviceGetByPCIBusId(int* device, const char* pciBusId);


hipError_t hipDeviceTotalMem(size_t* bytes, hipDevice_t device);

hipError_t hipDriverGetVersion(int* driverVersion);

hipError_t hipRuntimeGetVersion(int* runtimeVersion);

hipError_t hipModuleLoad(hipModule_t* module, const char* fname);

hipError_t hipModuleUnload(hipModule_t module);

hipError_t hipModuleGetFunction(hipFunction_t* function, hipModule_t module, const char* kname);

hipError_t hipFuncGetAttributes(struct hipFuncAttributes* attr, const void* func);

struct Agent_global {

    Agent_global() : name(nullptr), address(nullptr), byte_cnt(0) {}
    Agent_global(const char* name, hipDeviceptr_t address, uint32_t byte_cnt) 
      : name(nullptr), address(address), byte_cnt(byte_cnt) {
      if (name)
        this->name = strdup(name);
    }

    Agent_global& operator=(Agent_global&& t) {
      if (this == &t) return *this;

      if (name) free(name);
      name = t.name;
      address = t.address;
      byte_cnt = t.byte_cnt;

      t.name = nullptr;
      t.address = nullptr;
      t.byte_cnt = 0;

      return *this;
    }

    Agent_global(Agent_global&& t) 
      : name(nullptr), address(nullptr), byte_cnt(0) {
      *this = std::move(t);
    }

    // not needed, delete them to prevent bugs
    Agent_global(const Agent_global&) = delete;
    Agent_global& operator=(Agent_global& t) = delete;

    ~Agent_global() { if (name) free(name); }
    
    char* name;
    hipDeviceptr_t address;
    uint32_t byte_cnt;
};

#if !__HIP_VDI__
#if defined(__cplusplus)
} // extern "C"
#endif

namespace hip_impl {
hsa_executable_t executable_for(hipModule_t);
const char* hash_for(hipModule_t);

template<typename ForwardIterator>
std::pair<hipDeviceptr_t, std::size_t> read_global_description(
    ForwardIterator f, ForwardIterator l, const char* name) {
    const auto it = std::find_if(f, l, [=](const Agent_global& x) {
        return strcmp(x.name, name) == 0;
    });

    return it == l ?
        std::make_pair(nullptr, 0u) : std::make_pair(it->address, it->byte_cnt);
}

std::vector<Agent_global> read_agent_globals(hsa_agent_t agent,
                                             hsa_executable_t executable);
hsa_agent_t this_agent();


class agent_globals_impl {
private:
    std::pair<
        std::mutex,
        std::unordered_map<
            std::string, std::vector<Agent_global>>> globals_from_module;

    std::unordered_map<
        hsa_agent_t,
        std::pair<
            std::once_flag,
            std::vector<Agent_global>>> globals_from_process;

public:

    hipError_t read_agent_global_from_module(hipDeviceptr_t* dptr, size_t* bytes,
            hipModule_t hmod, const char* name) {
        // the key of the map would the hash of code object associated with the
        // hipModule_t instance
        std::string key(hash_for(hmod));

        if (globals_from_module.second.count(key) == 0) {
            std::lock_guard<std::mutex> lck{globals_from_module.first};

            if (globals_from_module.second.count(key) == 0) {
                globals_from_module.second.emplace(
                        key, read_agent_globals(this_agent(), executable_for(hmod)));
            }
        }

        const auto it0 = globals_from_module.second.find(key);
        if (it0 == globals_from_module.second.cend()) {
            hip_throw(
                    std::runtime_error{"agent_globals data structure corrupted."});
        }

        std::tie(*dptr, *bytes) = read_global_description(it0->second.cbegin(),
                it0->second.cend(), name);

        return *dptr ? hipSuccess : hipErrorNotFound;
    }

    hipError_t read_agent_global_from_process(hipDeviceptr_t* dptr, size_t* bytes,
            const char* name) {

        auto agent = this_agent();

        std::call_once(globals_from_process[agent].first, [this](hsa_agent_t aa) {
            std::vector<Agent_global> tmp0;
            for (auto&& executable : hip_impl::get_program_state().executables(aa)) {
                auto tmp1 = read_agent_globals(aa, executable);
                tmp0.insert(tmp0.end(), make_move_iterator(tmp1.begin()),
                            make_move_iterator(tmp1.end()));
            }
            globals_from_process[aa].second = move(move(tmp0));
        }, agent);

        const auto it = globals_from_process.find(agent);

        if (it == globals_from_process.cend()) return hipErrorNotInitialized;

        std::tie(*dptr, *bytes) = read_global_description(it->second.second.cbegin(),
                it->second.second.cend(), name);

        return *dptr ? hipSuccess : hipErrorNotFound;
    }
  
};

class agent_globals {
public:
    agent_globals() : impl(new agent_globals_impl()) { 
        if (!impl) 
            hip_throw(
                std::runtime_error{"Error when constructing agent global data structures."});
    }
    ~agent_globals() { delete impl; }

    hipError_t read_agent_global_from_module(hipDeviceptr_t* dptr, size_t* bytes,
                                             hipModule_t hmod, const char* name) {
        return impl->read_agent_global_from_module(dptr, bytes, hmod, name);
    }

    hipError_t read_agent_global_from_process(hipDeviceptr_t* dptr, size_t* bytes,
                                              const char* name) {
        return impl->read_agent_global_from_process(dptr, bytes, name);
    }

private:
    agent_globals_impl* impl;
};

inline
__attribute__((visibility("hidden")))
agent_globals& get_agent_globals() {
    static agent_globals ag;
    return ag;
}


extern "C"
inline
__attribute__((visibility("hidden")))
hipError_t read_agent_global_from_process(hipDeviceptr_t* dptr, size_t* bytes,
                                          const char* name) {
    return get_agent_globals().read_agent_global_from_process(dptr, bytes, name);
}


} // Namespace hip_impl.

#if defined(__cplusplus)
extern "C" {
#endif

hipError_t hipModuleGetGlobal(hipDeviceptr_t* dptr, size_t* bytes,
                              hipModule_t hmod, const char* name);
#endif // __HIP_VDI__

hipError_t hipModuleGetTexRef(textureReference** texRef, hipModule_t hmod, const char* name);

hipError_t hipModuleLoadData(hipModule_t* module, const void* image);

hipError_t hipModuleLoadDataEx(hipModule_t* module, const void* image, unsigned int numOptions,
                               hipJitOption* options, void** optionValues);

hipError_t hipModuleLaunchKernel(hipFunction_t f, unsigned int gridDimX, unsigned int gridDimY,
                                 unsigned int gridDimZ, unsigned int blockDimX,
                                 unsigned int blockDimY, unsigned int blockDimZ,
                                 unsigned int sharedMemBytes, hipStream_t stream,
                                 void** kernelParams, void** extra);

// doxygen end Version Management
// TODO - expand descriptions:
hipError_t hipProfilerStart();


hipError_t hipProfilerStop();


// TODO: implement IPC apis

hipError_t hipIpcGetMemHandle(hipIpcMemHandle_t* handle, void* devPtr);

hipError_t hipIpcOpenMemHandle(void** devPtr, hipIpcMemHandle_t handle, unsigned int flags);

hipError_t hipIpcCloseMemHandle(void* devPtr);


// hipError_t hipIpcGetMemHandle(hipIpcMemHandle_t* handle, void* devPtr);
// hipError_t hipIpcCloseMemHandle(void *devPtr);
// // hipError_t hipIpcOpenEventHandle(hipEvent_t* event, hipIpcEventHandle_t handle);
// hipError_t hipIpcOpenMemHandle(void** devPtr, hipIpcMemHandle_t handle, unsigned int flags);


hipError_t hipConfigureCall(dim3 gridDim, dim3 blockDim, size_t sharedMem __dparm(0), hipStream_t stream __dparm(0));


hipError_t hipSetupArgument(const void* arg, size_t size, size_t offset);


hipError_t hipLaunchByPtr(const void* func);



#ifdef __cplusplus
} /* extern "c" */
#endif

#ifdef __cplusplus
#include <hip/hcc_detail/hip_prof_api.h>
#endif

#ifdef __cplusplus
extern "C" {
#endif

hipError_t hipRegisterApiCallback(uint32_t id, void* fun, void* arg);
hipError_t hipRemoveApiCallback(uint32_t id);
hipError_t hipRegisterActivityCallback(uint32_t id, void* fun, void* arg);
hipError_t hipRemoveActivityCallback(uint32_t id);
static inline const char* hipApiName(const uint32_t& id) { return hip_api_name(id); }
const char* hipKernelNameRef(const hipFunction_t f);
#ifdef __cplusplus
} /* extern "C" */
#endif

#ifdef __cplusplus

hipError_t hipBindTexture(size_t* offset, textureReference* tex, const void* devPtr,
                          const hipChannelFormatDesc* desc, size_t size = UINT_MAX);

hipError_t ihipBindTextureImpl(int dim, enum hipTextureReadMode readMode, size_t* offset,
                               const void* devPtr, const struct hipChannelFormatDesc* desc,
                               size_t size, textureReference* tex);

/*
 * @brief hipBindTexture Binds size bytes of the memory area pointed to by @p devPtr to the texture
 *reference tex.
 *
 * @p desc describes how the memory is interpreted when fetching values from the texture. The @p
 *offset parameter is an optional byte offset as with the low-level hipBindTexture() function. Any
 *memory previously bound to tex is unbound.
 *
 *  @param[in]  offset - Offset in bytes
 *  @param[out]  tex - texture to bind
 *  @param[in]  devPtr - Memory area on device
 *  @param[in]  desc - Channel format
 *  @param[in]  size - Size of the memory area pointed to by devPtr
 *  @return #hipSuccess, #hipErrorInvalidValue, #hipErrorMemoryFree, #hipErrorUnknown
 **/
template <class T, int dim, enum hipTextureReadMode readMode>
hipError_t hipBindTexture(size_t* offset, struct texture<T, dim, readMode>& tex, const void* devPtr,
                          const struct hipChannelFormatDesc& desc, size_t size = UINT_MAX) {
    return ihipBindTextureImpl(dim, readMode, offset, devPtr, &desc, size, &tex);
}

/*
 * @brief hipBindTexture Binds size bytes of the memory area pointed to by @p devPtr to the texture
 *reference tex.
 *
 * @p desc describes how the memory is interpreted when fetching values from the texture. The @p
 *offset parameter is an optional byte offset as with the low-level hipBindTexture() function. Any
 *memory previously bound to tex is unbound.
 *
 *  @param[in]  offset - Offset in bytes
 *  @param[in]  tex - texture to bind
 *  @param[in]  devPtr - Memory area on device
 *  @param[in]  size - Size of the memory area pointed to by devPtr
 *  @return #hipSuccess, #hipErrorInvalidValue, #hipErrorMemoryFree, #hipErrorUnknown
 **/
template <class T, int dim, enum hipTextureReadMode readMode>
hipError_t hipBindTexture(size_t* offset, struct texture<T, dim, readMode>& tex, const void* devPtr,
                          size_t size = UINT_MAX) {
    return ihipBindTextureImpl(dim, readMode, offset, devPtr, &(tex.channelDesc), size, &tex);
}

// C API
hipError_t hipBindTexture2D(size_t* offset, textureReference* tex, const void* devPtr,
                            const hipChannelFormatDesc* desc, size_t width, size_t height,
                            size_t pitch);

hipError_t ihipBindTexture2DImpl(int dim, enum hipTextureReadMode readMode, size_t* offset,
                                 const void* devPtr, const struct hipChannelFormatDesc* desc,
                                 size_t width, size_t height, textureReference* tex);

template <class T, int dim, enum hipTextureReadMode readMode>
hipError_t hipBindTexture2D(size_t* offset, struct texture<T, dim, readMode>& tex,
                            const void* devPtr, size_t width, size_t height, size_t pitch) {
    return ihipBindTexture2DImpl(dim, readMode, offset, devPtr, &(tex.channelDesc), width, height,
                                 &tex);
}

template <class T, int dim, enum hipTextureReadMode readMode>
hipError_t hipBindTexture2D(size_t* offset, struct texture<T, dim, readMode>& tex,
                            const void* devPtr, const struct hipChannelFormatDesc& desc,
                            size_t width, size_t height, size_t pitch) {
    return ihipBindTexture2DImpl(dim, readMode, offset, devPtr, &desc, width, height, &tex);
}

// C API
hipError_t hipBindTextureToArray(textureReference* tex, hipArray_const_t array,
                                 const hipChannelFormatDesc* desc);

hipError_t ihipBindTextureToArrayImpl(int dim, enum hipTextureReadMode readMode,
                                      hipArray_const_t array,
                                      const struct hipChannelFormatDesc& desc,
                                      textureReference* tex);

template <class T, int dim, enum hipTextureReadMode readMode>
hipError_t hipBindTextureToArray(struct texture<T, dim, readMode>& tex, hipArray_const_t array) {
    return ihipBindTextureToArrayImpl(dim, readMode, array, tex.channelDesc, &tex);
}

template <class T, int dim, enum hipTextureReadMode readMode>
hipError_t hipBindTextureToArray(struct texture<T, dim, readMode>& tex, hipArray_const_t array,
                                 const struct hipChannelFormatDesc& desc) {
    return ihipBindTextureToArrayImpl(dim, readMode, array, desc, &tex);
}

template <class T, int dim, enum hipTextureReadMode readMode>
inline static hipError_t hipBindTextureToArray(struct texture<T, dim, readMode> *tex,
                                               hipArray_const_t array,
                                               const struct hipChannelFormatDesc* desc) {
    return ihipBindTextureToArrayImpl(dim, readMode, array, *desc, tex);
}

// C API
hipError_t hipBindTextureToMipmappedArray(const textureReference* tex,
                                          hipMipmappedArray_const_t mipmappedArray,
                                          const hipChannelFormatDesc* desc);

template <class T, int dim, enum hipTextureReadMode readMode>
hipError_t hipBindTextureToMipmappedArray(const texture<T, dim, readMode>& tex,
                                          hipMipmappedArray_const_t mipmappedArray) {
    return hipSuccess;
}

template <class T, int dim, enum hipTextureReadMode readMode>
hipError_t hipBindTextureToMipmappedArray(const texture<T, dim, readMode>& tex,
                                          hipMipmappedArray_const_t mipmappedArray,
                                          const hipChannelFormatDesc& desc) {
    return hipSuccess;
}

/*
 * @brief Unbinds the textuer bound to @p tex
 *
 *  @param[in]  tex - texture to unbind
 *
 *  @return #hipSuccess
 **/
hipError_t hipUnbindTexture(const textureReference* tex);

extern hipError_t ihipUnbindTextureImpl(const hipTextureObject_t& textureObject);

template <class T, int dim, enum hipTextureReadMode readMode>
hipError_t hipUnbindTexture(struct texture<T, dim, readMode>& tex) {
    return ihipUnbindTextureImpl(tex.textureObject);
}

hipError_t hipGetChannelDesc(hipChannelFormatDesc* desc, hipArray_const_t array);
hipError_t hipGetTextureAlignmentOffset(size_t* offset, const textureReference* texref);
hipError_t hipGetTextureReference(const textureReference** texref, const void* symbol);

hipError_t hipCreateTextureObject(hipTextureObject_t* pTexObject, const hipResourceDesc* pResDesc,
                                  const hipTextureDesc* pTexDesc,
                                  const hipResourceViewDesc* pResViewDesc);

hipError_t hipDestroyTextureObject(hipTextureObject_t textureObject);

hipError_t hipGetTextureObjectResourceDesc(hipResourceDesc* pResDesc,
                                           hipTextureObject_t textureObject);
hipError_t hipGetTextureObjectResourceViewDesc(hipResourceViewDesc* pResViewDesc,
                                               hipTextureObject_t textureObject);
hipError_t hipGetTextureObjectTextureDesc(hipTextureDesc* pTexDesc,
                                          hipTextureObject_t textureObject);
hipError_t hipTexRefSetArray(textureReference* tex, hipArray_const_t array, unsigned int flags);

hipError_t hipTexRefSetAddressMode(textureReference* tex, int dim, hipTextureAddressMode am);

hipError_t hipTexRefSetFilterMode(textureReference* tex, hipTextureFilterMode fm);

hipError_t hipTexRefSetFlags(textureReference* tex, unsigned int flags);

hipError_t hipTexRefSetFormat(textureReference* tex, hipArray_Format fmt, int NumPackedComponents);

hipError_t hipTexRefSetAddress(size_t* offset, textureReference* tex, hipDeviceptr_t devPtr,
                               size_t size);

hipError_t hipTexRefSetAddress2D(textureReference* tex, const HIP_ARRAY_DESCRIPTOR* desc,
                                 hipDeviceptr_t devPtr, size_t pitch);

hipError_t hipCreateSurfaceObject(hipSurfaceObject_t* pSurfObject, const hipResourceDesc* pResDesc);

hipError_t hipDestroySurfaceObject(hipSurfaceObject_t surfaceObject);

// doxygen end Texture
#endif


// end-group HCC_Specific
// doxygen end HIP API
#endif