HIP: Heterogenous-computing Interface for Portability
hip_runtime_api.h
1 /*
2 Copyright (c) 2015 - present Advanced Micro Devices, Inc. All rights reserved.
3 
4 Permission is hereby granted, free of charge, to any person obtaining a copy
5 of this software and associated documentation files (the "Software"), to deal
6 in the Software without restriction, including without limitation the rights
7 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 copies of the Software, and to permit persons to whom the Software is
9 furnished to do so, subject to the following conditions:
10 
11 The above copyright notice and this permission notice shall be included in
12 all copies or substantial portions of the Software.
13 
14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20 THE SOFTWARE.
21 */
22 
30 #ifndef HIP_INCLUDE_HIP_HIP_RUNTIME_API_H
31 #define HIP_INCLUDE_HIP_HIP_RUNTIME_API_H
32 
33 
34 #include <string.h> // for getDeviceProp
35 #include <hip/hip_common.h>
36 
37 enum {
38  HIP_SUCCESS = 0,
39  HIP_ERROR_INVALID_VALUE,
40  HIP_ERROR_NOT_INITIALIZED,
41  HIP_ERROR_LAUNCH_OUT_OF_RESOURCES
42 };
43 
44 typedef struct {
45  // 32-bit Atomics
46  unsigned hasGlobalInt32Atomics : 1;
47  unsigned hasGlobalFloatAtomicExch : 1;
48  unsigned hasSharedInt32Atomics : 1;
49  unsigned hasSharedFloatAtomicExch : 1;
50  unsigned hasFloatAtomicAdd : 1;
51 
52  // 64-bit Atomics
53  unsigned hasGlobalInt64Atomics : 1;
54  unsigned hasSharedInt64Atomics : 1;
55 
56  // Doubles
57  unsigned hasDoubles : 1;
58 
59  // Warp cross-lane operations
60  unsigned hasWarpVote : 1;
61  unsigned hasWarpBallot : 1;
62  unsigned hasWarpShuffle : 1;
63  unsigned hasFunnelShift : 1;
64 
65  // Sync
66  unsigned hasThreadFenceSystem : 1;
67  unsigned hasSyncThreadsExt : 1;
68 
69  // Misc
70  unsigned hasSurfaceFuncs : 1;
71  unsigned has3dGrid : 1;
72  unsigned hasDynamicParallelism : 1;
74 
75 
76 //---
77 // Common headers for both NVCC and HCC paths:
78 
83 typedef struct hipDeviceProp_t {
84  char name[256];
85  size_t totalGlobalMem;
88  int warpSize;
90  int maxThreadsDim[3];
91  int maxGridSize[3];
92  int clockRate;
95  size_t totalConstMem;
96  int major;
97  int minor;
100  int multiProcessorCount;
111  int pciBusID;
116  int gcnArch;
121  int maxTexture2D[2];
122  int maxTexture3D[3];
123  unsigned int* hdpMemFlushCntl;
124  unsigned int* hdpRegFlushCntl;
125  size_t memPitch;
130  int tccDriver;
138  int isLargeBar;
141 
142 
146 typedef enum hipMemoryType {
147  hipMemoryTypeHost,
148  hipMemoryTypeDevice,
149  hipMemoryTypeArray,
151  hipMemoryTypeUnified
153 }hipMemoryType;
154 
155 
159 typedef struct hipPointerAttribute_t {
160  enum hipMemoryType memoryType;
161  int device;
162  void* devicePointer;
163  void* hostPointer;
164  int isManaged;
165  unsigned allocationFlags; /* flags specified when memory was allocated*/
166  /* peers? */
168 
169 
170 // hack to get these to show up in Doxygen:
177 // Ignoring error-code return values from hip APIs is discouraged. On C++17,
178 // we can make that yield a warning
179 #if __cplusplus >= 201703L
180 #define __HIP_NODISCARD [[nodiscard]]
181 #else
182 #define __HIP_NODISCARD
183 #endif
184 
185 /*
186  * @brief hipError_t
187  * @enum
188  * @ingroup Enumerations
189  */
190 // Developer note - when updating these, update the hipErrorName and hipErrorString functions in
191 // NVCC and HCC paths Also update the hipCUDAErrorTohipError function in NVCC path.
192 
193 typedef enum __HIP_NODISCARD hipError_t {
194  hipSuccess = 0,
195  hipErrorInvalidValue = 1,
196  hipErrorOutOfMemory = 2,
198  // Deprecated
199  hipErrorMemoryAllocation = 2,
200  hipErrorNotInitialized = 3,
201  // Deprecated
202  hipErrorInitializationError = 3,
203  hipErrorDeinitialized = 4,
204  hipErrorProfilerDisabled = 5,
205  hipErrorProfilerNotInitialized = 6,
206  hipErrorProfilerAlreadyStarted = 7,
207  hipErrorProfilerAlreadyStopped = 8,
208  hipErrorInvalidConfiguration = 9,
209  hipErrorInvalidSymbol = 13,
210  hipErrorInvalidDevicePointer = 17,
211  hipErrorInvalidMemcpyDirection = 21,
212  hipErrorInsufficientDriver = 35,
213  hipErrorMissingConfiguration = 52,
214  hipErrorPriorLaunchFailure = 53,
215  hipErrorInvalidDeviceFunction = 98,
216  hipErrorNoDevice = 100,
217  hipErrorInvalidDevice = 101,
218  hipErrorInvalidImage = 200,
219  hipErrorInvalidContext = 201,
220  hipErrorContextAlreadyCurrent = 202,
221  hipErrorMapFailed = 205,
222  // Deprecated
223  hipErrorMapBufferObjectFailed = 205,
224  hipErrorUnmapFailed = 206,
225  hipErrorArrayIsMapped = 207,
226  hipErrorAlreadyMapped = 208,
227  hipErrorNoBinaryForGpu = 209,
228  hipErrorAlreadyAcquired = 210,
229  hipErrorNotMapped = 211,
230  hipErrorNotMappedAsArray = 212,
231  hipErrorNotMappedAsPointer = 213,
232  hipErrorECCNotCorrectable = 214,
233  hipErrorUnsupportedLimit = 215,
234  hipErrorContextAlreadyInUse = 216,
235  hipErrorPeerAccessUnsupported = 217,
236  hipErrorInvalidKernelFile = 218,
237  hipErrorInvalidGraphicsContext = 219,
238  hipErrorInvalidSource = 300,
239  hipErrorFileNotFound = 301,
240  hipErrorSharedObjectSymbolNotFound = 302,
241  hipErrorSharedObjectInitFailed = 303,
242  hipErrorOperatingSystem = 304,
243  hipErrorInvalidHandle = 400,
244  // Deprecated
245  hipErrorInvalidResourceHandle = 400,
246  hipErrorNotFound = 500,
247  hipErrorNotReady = 600,
248  hipErrorIllegalAddress = 700,
252  hipErrorLaunchOutOfResources = 701,
253  hipErrorLaunchTimeOut = 702,
254  hipErrorPeerAccessAlreadyEnabled =
255  704,
256  hipErrorPeerAccessNotEnabled =
257  705,
258  hipErrorSetOnActiveProcess = 708,
259  hipErrorAssert = 710,
260  hipErrorHostMemoryAlreadyRegistered =
261  712,
262  hipErrorHostMemoryNotRegistered =
263  713,
264  hipErrorLaunchFailure =
265  719,
266  hipErrorCooperativeLaunchTooLarge =
267  720,
268  hipErrorNotSupported = 801,
271  hipErrorUnknown = 999, //< Unknown error.
272  // HSA Runtime Error Codes start here.
273  hipErrorRuntimeMemory = 1052,
274  hipErrorRuntimeOther = 1053,
276  hipErrorTbd
278 } hipError_t;
279 
280 #undef __HIP_NODISCARD
281 
282 /*
283  * @brief hipDeviceAttribute_t
284  * @enum
285  * @ingroup Enumerations
286  */
287 typedef enum hipDeviceAttribute_t {
330 
333 
340 
350 
351 enum hipComputeMode {
352  hipComputeModeDefault = 0,
353  hipComputeModeExclusive = 1,
354  hipComputeModeProhibited = 2,
355  hipComputeModeExclusiveProcess = 3
356 };
357 
362 #if defined(__HIP_PLATFORM_HCC__) && !defined(__HIP_PLATFORM_NVCC__)
364 #elif defined(__HIP_PLATFORM_NVCC__) && !defined(__HIP_PLATFORM_HCC__)
365 #include "hip/nvcc_detail/hip_runtime_api.h"
366 #else
367 #error("Must define exactly one of __HIP_PLATFORM_HCC__ or __HIP_PLATFORM_NVCC__");
368 #endif
369 
370 
382 #if defined(__cplusplus) && !defined(__HIP_DISABLE_CPP_FUNCTIONS__)
383 template <class T>
384 static inline hipError_t hipMalloc(T** devPtr, size_t size) {
385  return hipMalloc((void**)devPtr, size);
386 }
387 
388 // Provide an override to automatically typecast the pointer type from void**, and also provide a
389 // default for the flags.
390 template <class T>
391 static inline hipError_t hipHostMalloc(T** ptr, size_t size,
392  unsigned int flags = hipHostMallocDefault) {
393  return hipHostMalloc((void**)ptr, size, flags);
394 }
395 
396 template <class T>
397 static inline hipError_t hipMallocManaged(T** devPtr, size_t size,
398  unsigned int flags = hipMemAttachGlobal) {
399  return hipMallocManaged((void**)devPtr, size, flags);
400 }
401 #endif
402 
403 #endif
size_t totalConstMem
Size of shared memory region (in bytes).
Definition: hip_runtime_api.h:95
Maximum x-dimension of a block.
Definition: hip_runtime_api.h:289
Maximum x-dimension of a grid.
Definition: hip_runtime_api.h:292
int isLargeBar
1: if it is a large PCI bar device, else 0
Definition: hip_runtime_api.h:139
Maximum pitch in bytes allowed by memory copies.
Definition: hip_runtime_api.h:334
int cooperativeMultiDeviceUnmatchedBlockDim
Definition: hip_runtime_api.h:135
Global memory bus width in bits.
Definition: hip_runtime_api.h:305
int minor
Definition: hip_runtime_api.h:99
unsigned int * hdpRegFlushCntl
Addres of HDP_REG_COHERENCY_FLUSH_CNTL register.
Definition: hip_runtime_api.h:124
size_t texturePitchAlignment
Pitch alignment requirement for texture references bound to pitched memory.
Definition: hip_runtime_api.h:127
int canMapHostMemory
Check whether HIP can map host memory.
Definition: hip_runtime_api.h:115
Definition: hip_runtime_api.h:299
int regsPerBlock
Registers per block.
Definition: hip_runtime_api.h:87
int maxTexture3D[3]
Maximum dimensions (width, height, depth) of 3D images, in image elements.
Definition: hip_runtime_api.h:122
Definition: hip_runtime_api.h:308
Run time limit for kernels executed on the device.
Definition: hip_runtime_api.h:337
#define hipHostMallocDefault
Flags that can be used with hipHostMalloc.
Definition: hip_runtime_api.h:168
Maximum dimension width of 3D images in image elements.
Definition: hip_runtime_api.h:327
iGPU
Definition: hip_runtime_api.h:321
int isMultiGpuBoard
1 if device is on a multi-GPU board, 0 if not.
Definition: hip_runtime_api.h:114
Peak clock frequency in kilohertz.
Definition: hip_runtime_api.h:303
int maxTexture1D
Maximum number of elements in 1D images.
Definition: hip_runtime_api.h:120
Definition: hip_runtime_api.h:159
int clockRate
Max clock frequency of the multiProcessors in khz.
Definition: hip_runtime_api.h:92
Maximum z-dimension of a grid.
Definition: hip_runtime_api.h:294
Minor compute capability version number.
Definition: hip_runtime_api.h:313
Definition: hip_runtime_api.h:295
int pciBusID
PCI Bus ID.
Definition: hip_runtime_api.h:111
Maximum y-dimension of a grid.
Definition: hip_runtime_api.h:293
Multiple GPU devices.
Definition: hip_runtime_api.h:320
int tccDriver
1:If device is Tesla device using TCC driver, else 0
Definition: hip_runtime_api.h:130
int maxThreadsPerBlock
Max work items per work group or workgroup max size.
Definition: hip_runtime_api.h:89
Maximum y-dimension of a block.
Definition: hip_runtime_api.h:290
hipError_t hipHostMalloc(void **ptr, size_t size, unsigned int flags)
Allocate device accessible page locked host memory.
Definition: hip_memory.cpp:762
size_t sharedMemPerBlock
Size of shared memory region (in bytes).
Definition: hip_runtime_api.h:86
Support cooperative launch on multiple devices.
Definition: hip_runtime_api.h:323
int maxThreadsPerMultiProcessor
Maximum resident threads per multi-processor.
Definition: hip_runtime_api.h:104
size_t memPitch
Maximum pitch in bytes allowed by memory copies.
Definition: hip_runtime_api.h:125
int l2CacheSize
L2 cache size.
Definition: hip_runtime_api.h:103
hipDeviceAttribute_t
Definition: hip_runtime_api.h:287
size_t textureAlignment
Alignment requirement for textures.
Definition: hip_runtime_api.h:126
Major compute capability version number.
Definition: hip_runtime_api.h:312
Maximum number of threads per block.
Definition: hip_runtime_api.h:288
int gcnArch
AMD GCN Arch Value. Eg: 803, 701.
Definition: hip_runtime_api.h:116
Maximum dimensions depth of 3D images in image elements.
Definition: hip_runtime_api.h:329
int kernelExecTimeoutEnabled
Run time limit for kernels executed on the device.
Definition: hip_runtime_api.h:128
hipDeviceArch_t arch
Architectural feature flags. New for HIP.
Definition: hip_runtime_api.h:108
int maxGridSize[3]
Max grid dimensions (XYZ).
Definition: hip_runtime_api.h:91
int computeMode
Compute mode.
Definition: hip_runtime_api.h:105
Maximum z-dimension of a block.
Definition: hip_runtime_api.h:291
PCI Bus ID.
Definition: hip_runtime_api.h:316
unsigned int * hdpMemFlushCntl
Addres of HDP_MEM_COHERENCY_FLUSH_CNTL register.
Definition: hip_runtime_api.h:123
Maximum dimension height of 2D images in image elements.
Definition: hip_runtime_api.h:326
Warp size in threads.
Definition: hip_runtime_api.h:298
int major
Definition: hip_runtime_api.h:96
Maximum dimensions height of 3D images in image elements.
Definition: hip_runtime_api.h:328
Peak memory clock frequency in kilohertz.
Definition: hip_runtime_api.h:304
Definition: hip_runtime_api.h:310
Address of the HDP_REG_COHERENCY_FLUSH_CNTL register.
Definition: hip_runtime_api.h:332
hipError_t hipMallocManaged(void **devPtr, size_t size, unsigned int flags __dparm(0))
Allocates memory that will be automatically managed by the Unified Memory system. ...
int clockInstructionRate
Definition: hip_runtime_api.h:106
int cooperativeMultiDeviceLaunch
HIP device supports cooperative launch on multiple devices.
Definition: hip_runtime_api.h:119
Constant memory size in bytes.
Definition: hip_runtime_api.h:297
Pitch alignment requirement for 2D texture references bound to pitched memory;.
Definition: hip_runtime_api.h:336
int warpSize
Warp size.
Definition: hip_runtime_api.h:88
int concurrentKernels
Device can possibly execute multiple kernels concurrently.
Definition: hip_runtime_api.h:109
Alignment requirement for textures.
Definition: hip_runtime_api.h:335
size_t totalGlobalMem
Size of global memory region (in bytes).
Definition: hip_runtime_api.h:85
hipError_t hipMalloc(void **ptr, size_t size)
Allocate memory on the default accelerator.
Definition: hip_memory.cpp:695
Compute mode that device is currently in.
Definition: hip_runtime_api.h:307
PCI Device ID.
Definition: hip_runtime_api.h:317
Device can map host memory into device address space.
Definition: hip_runtime_api.h:338
int maxThreadsDim[3]
Max number of threads in each dimension (XYZ) of a block.
Definition: hip_runtime_api.h:90
Number of multiprocessors on the device.
Definition: hip_runtime_api.h:306
int integrated
APU vs dGPU.
Definition: hip_runtime_api.h:117
int memoryBusWidth
Global memory bus width in bits.
Definition: hip_runtime_api.h:94
Definition: hip_runtime_api.h:83
size_t maxSharedMemoryPerMultiProcessor
Maximum Shared Memory Per Multiprocessor.
Definition: hip_runtime_api.h:113
int cooperativeLaunch
HIP device supports cooperative launch.
Definition: hip_runtime_api.h:118
Support cooperative launch.
Definition: hip_runtime_api.h:322
Maximum number of elements in 1D images.
Definition: hip_runtime_api.h:324
int pciDeviceID
PCI Device ID.
Definition: hip_runtime_api.h:112
int pciDomainID
PCI Domain ID.
Definition: hip_runtime_api.h:110
int ECCEnabled
Device has ECC support enabled.
Definition: hip_runtime_api.h:129
char name[256]
Device name.
Definition: hip_runtime_api.h:84
Definition: hip_runtime_api.h:44
Contains C function APIs for HIP runtime. This file does not use any HCC builtin or special language ...
int cooperativeMultiDeviceUnmatchedSharedMem
Definition: hip_runtime_api.h:137
int memoryClockRate
Max global memory clock frequency in khz.
Definition: hip_runtime_api.h:93
Maximum dimension width of 2D images in image elements.
Definition: hip_runtime_api.h:325
Address of the HDP_MEM_COHERENCY_FLUSH_CNTL register.
Definition: hip_runtime_api.h:331
int maxTexture2D[2]
Maximum dimensions (width, height) of 2D images, in image elements.
Definition: hip_runtime_api.h:121
Device has ECC support enabled.
Definition: hip_runtime_api.h:339
int cooperativeMultiDeviceUnmatchedFunc
Definition: hip_runtime_api.h:131
int cooperativeMultiDeviceUnmatchedGridDim
Definition: hip_runtime_api.h:133
Definition: hip_runtime_api.h:314
int multiProcessorCount
Number of multi-processors (compute units).
Definition: hip_runtime_api.h:102