hip_runtime_api.h

/*
Copyright (c) 2015-2016 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


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

#include <hcc_detail/host_defines.h>

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


// hip_api_hcc.h
// Contains C function APIs for HIP runtime.
// This file does not use any HCC builtins or special language extensions (-hc mode) ; those functions in hip_hcc.h.


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

#define hipStreamDefault     0x00 
#define hipStreamNonBlocking 0x01 


#define hipEventDefault       0x0  
#define hipEventBlockingSync  0x1  
#define hipEventDisableTiming 0x2  
#define hipEventInterprocess  0x4  


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


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



typedef struct dim3 {
  uint32_t x;                 
  uint32_t y;                 
  uint32_t z;                 

  dim3(uint32_t _x=1, uint32_t _y=1, uint32_t _z=1) : x(_x), y(_y), z(_z) {};
} dim3;



enum hipMemcpyKind {
   hipMemcpyHostToHost = 0    
  ,hipMemcpyHostToDevice = 1  
  ,hipMemcpyDeviceToHost = 2  
  ,hipMemcpyDeviceToDevice =3 
  ,hipMemcpyDefault = 4,      
} ;


// 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 struct 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;






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




//==================================================================================================
#ifdef __cplusplus
extern "C" {
#endif

hipError_t hipDeviceSynchronize(void);



hipError_t hipDeviceReset(void) ;


hipError_t hipSetDevice(int device);


hipError_t hipGetDevice(int *device);


hipError_t hipGetDeviceCount(int *count);


hipError_t hipDeviceGetProperties(hipDeviceProp_t* prop, int device);



//Cache partitioning functions:

hipError_t hipDeviceSetCacheConfig ( hipFuncCache cacheConfig );


hipError_t hipDeviceGetCacheConfig ( hipFuncCache *cacheConfig );


hipError_t hipFuncSetCacheConfig ( hipFuncCache config ); 

//--- 
//Shared bank config functions:

hipError_t hipDeviceGetSharedMemConfig ( hipSharedMemConfig * pConfig ); 


hipError_t hipDeviceSetSharedMemConfig ( hipSharedMemConfig config ); 


// end doxygen Device
hipError_t hipGetLastError(void);


hipError_t hipPeekAtLastError(void);



const char *hipGetErrorName(hipError_t hip_error);


const char *hipGetErrorString(hipError_t hip_error);

// end doxygen Error
hipError_t hipStreamCreateWithFlags(hipStream_t *stream, unsigned int flags);



static inline hipError_t hipStreamCreate(hipStream_t *stream) 
{
    return hipStreamCreateWithFlags(stream, hipStreamDefault);
}


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


hipError_t hipStreamSynchronize(hipStream_t stream);


hipError_t hipStreamDestroy(hipStream_t stream);


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


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


static inline hipError_t hipEventCreate(hipEvent_t* event)
{
    return hipEventCreateWithFlags(event, 0);
}


hipError_t hipEventRecord(hipEvent_t event, hipStream_t stream = NULL);


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 hipMalloc(void** ptr, size_t size) ;


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



// TODO-doc (error codes)
hipError_t hipFree(void* ptr);



// TODO-doc (error codes)
hipError_t hipFreeHost(void* ptr);




// TODO-doc (error codes)
hipError_t hipMemcpy(void* dst, const void* src, size_t sizeBytes, hipMemcpyKind kind);


hipError_t hipMemcpyToSymbol(const char* symbolName, const void *src, size_t sizeBytes, size_t offset, hipMemcpyKind kind);



// TODO-doc (error codes)
hipError_t hipMemcpyAsync(void* dst, const void* src, size_t sizeBytes, hipMemcpyKind kind, hipStream_t stream=0);


// TODO-doc
/*
 * This function is host-asynchronous and may return before the memset operation completes.
 * Same as hipMemsetAsync with null stream.
 *
 * */
hipError_t hipMemset(void* dst, int  value, size_t sizeBytes );
hipError_t hipMemsetAsync(void* dst, int  value, size_t sizeBytes, hipStream_t = 0 );


/*
 * @brief Query memory info.  Return snapshot of free memory, and total allocatable memory on the device.
 *
 * Returns in *free a snapshot of the current free memory o
 **/
hipError_t hipMemGetInfo  (size_t * free, size_t * total)   ;

// doxygen end Memory
hipError_t hipDeviceCanAccessPeer ( int* canAccessPeer, int  device, int  peerDevice );

// TODO-DOC
hipError_t  hipDeviceDisablePeerAccess ( int  peerDevice );

// TODO-DOC
hipError_t  hipDeviceEnablePeerAccess ( int  peerDevice, unsigned int  flags );

// TODO-DOC
hipError_t hipMemcpyPeer ( void* dst, int  dstDevice, const void* src, int  srcDevice, size_t sizeBytes );

// TODO-DOC
hipError_t hipMemcpyPeerAsync ( void* dst, int  dstDevice, const void* src, int  srcDevice, size_t sizeBytes, hipStream_t stream=0 );
// doxygen end PeerToPeer
hipError_t hipDriverGetVersion(int *driverVersion) ;



// doxygen end Version Management
#ifdef __cplusplus
} /* extern "c" */
#endif


#ifdef __HCC__ 
#include <hc.hpp>
hipError_t hipHccGetAccelerator(int deviceId, hc::accelerator *acc);

hipError_t hipHccGetAcceleratorView(hipStream_t stream, hc::accelerator_view **av);
#endif


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