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;
126 
127 
131 typedef enum hipMemoryType {
132  hipMemoryTypeHost,
133  hipMemoryTypeDevice,
134  hipMemoryTypeArray,
136  hipMemoryTypeUnified
138 }hipMemoryType;
139 
140 
144 typedef struct hipPointerAttribute_t {
145  enum hipMemoryType memoryType;
146  int device;
147  void* devicePointer;
148  void* hostPointer;
149  int isManaged;
150  unsigned allocationFlags; /* flags specified when memory was allocated*/
151  /* peers? */
153 
154 
155 // hack to get these to show up in Doxygen:
162 // Ignoring error-code return values from hip APIs is discouraged. On C++17,
163 // we can make that yield a warning
164 #if __cplusplus >= 201703L
165 #define __HIP_NODISCARD [[nodiscard]]
166 #else
167 #define __HIP_NODISCARD
168 #endif
169 
170 /*
171  * @brief hipError_t
172  * @enum
173  * @ingroup Enumerations
174  */
175 // Developer note - when updating these, update the hipErrorName and hipErrorString functions in
176 // NVCC and HCC paths Also update the hipCUDAErrorTohipError function in NVCC path.
177 
178 typedef enum __HIP_NODISCARD hipError_t {
179  hipSuccess = 0,
180  hipErrorOutOfMemory = 2,
181  hipErrorNotInitialized = 3,
182  hipErrorDeinitialized = 4,
183  hipErrorProfilerDisabled = 5,
184  hipErrorProfilerNotInitialized = 6,
185  hipErrorProfilerAlreadyStarted = 7,
186  hipErrorProfilerAlreadyStopped = 8,
187  hipErrorInsufficientDriver = 35,
188  hipErrorInvalidImage = 200,
189  hipErrorInvalidContext = 201,
190  hipErrorContextAlreadyCurrent = 202,
191  hipErrorMapFailed = 205,
192  hipErrorUnmapFailed = 206,
193  hipErrorArrayIsMapped = 207,
194  hipErrorAlreadyMapped = 208,
195  hipErrorNoBinaryForGpu = 209,
196  hipErrorAlreadyAcquired = 210,
197  hipErrorNotMapped = 211,
198  hipErrorNotMappedAsArray = 212,
199  hipErrorNotMappedAsPointer = 213,
200  hipErrorECCNotCorrectable = 214,
201  hipErrorUnsupportedLimit = 215,
202  hipErrorContextAlreadyInUse = 216,
203  hipErrorPeerAccessUnsupported = 217,
204  hipErrorInvalidKernelFile = 218,
205  hipErrorInvalidGraphicsContext = 219,
206  hipErrorInvalidSource = 300,
207  hipErrorFileNotFound = 301,
208  hipErrorSharedObjectSymbolNotFound = 302,
209  hipErrorSharedObjectInitFailed = 303,
210  hipErrorOperatingSystem = 304,
211  hipErrorSetOnActiveProcess = 305,
212  hipErrorInvalidHandle = 400,
213  hipErrorNotFound = 500,
214  hipErrorIllegalAddress = 700,
215  hipErrorInvalidSymbol = 701,
216  // Runtime Error Codes start here.
217  hipErrorMissingConfiguration = 1001,
218  hipErrorMemoryAllocation = 1002,
219  hipErrorInitializationError = 1003,
220  hipErrorLaunchFailure =
221  1004,
222  hipErrorPriorLaunchFailure = 1005,
223  hipErrorLaunchTimeOut = 1006,
224  hipErrorLaunchOutOfResources = 1007,
225  hipErrorInvalidDeviceFunction = 1008,
226  hipErrorInvalidConfiguration = 1009,
227  hipErrorInvalidDevice = 1010,
228  hipErrorInvalidValue = 1011,
229  hipErrorInvalidDevicePointer = 1017,
231  hipErrorInvalidMemcpyDirection = 1021,
232  hipErrorUnknown = 1030,
233  hipErrorInvalidResourceHandle = 1033,
234  hipErrorNotReady = 1034,
235  hipErrorNoDevice = 1038,
239  hipErrorPeerAccessAlreadyEnabled =
240  1050,
241 
242  hipErrorPeerAccessNotEnabled =
243  1051,
244  hipErrorRuntimeMemory = 1052,
245  hipErrorRuntimeOther = 1053,
247  hipErrorHostMemoryAlreadyRegistered =
249  1061,
250  hipErrorHostMemoryNotRegistered =
251  1062,
252  hipErrorMapBufferObjectFailed =
253  1071,
254  hipErrorAssert =
255  1081,
256  hipErrorNotSupported =
257  1082,
258  hipErrorTbd
259 } hipError_t;
260 
261 #undef __HIP_NODISCARD
262 
263 /*
264  * @brief hipDeviceAttribute_t
265  * @enum
266  * @ingroup Enumerations
267  */
268 typedef enum hipDeviceAttribute_t {
305 
312 
316 
317 enum hipComputeMode {
318  hipComputeModeDefault = 0,
319  hipComputeModeExclusive = 1,
320  hipComputeModeProhibited = 2,
321  hipComputeModeExclusiveProcess = 3
322 };
323 
328 #if defined(__HIP_PLATFORM_HCC__) && !defined(__HIP_PLATFORM_NVCC__)
330 #elif defined(__HIP_PLATFORM_NVCC__) && !defined(__HIP_PLATFORM_HCC__)
331 #include "hip/nvcc_detail/hip_runtime_api.h"
332 #else
333 #error("Must define exactly one of __HIP_PLATFORM_HCC__ or __HIP_PLATFORM_NVCC__");
334 #endif
335 
336 
348 #if defined(__cplusplus) && !defined(__HIP_DISABLE_CPP_FUNCTIONS__)
349 template <class T>
350 static inline hipError_t hipMalloc(T** devPtr, size_t size) {
351  return hipMalloc((void**)devPtr, size);
352 }
353 
354 // Provide an override to automatically typecast the pointer type from void**, and also provide a
355 // default for the flags.
356 template <class T>
357 static inline hipError_t hipHostMalloc(T** ptr, size_t size,
358  unsigned int flags = hipHostMallocDefault) {
359  return hipHostMalloc((void**)ptr, size, flags);
360 }
361 
362 template <class T>
363 static inline hipError_t hipMallocManaged(T** devPtr, size_t size,
364  unsigned int flags = hipMemAttachGlobal) {
365  return hipMallocManaged((void**)devPtr, size, flags);
366 }
367 #endif
368 
369 #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:270
Maximum x-dimension of a grid.
Definition: hip_runtime_api.h:273
Global memory bus width in bits.
Definition: hip_runtime_api.h:286
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
int canMapHostMemory
Check whether HIP can map host memory.
Definition: hip_runtime_api.h:115
Definition: hip_runtime_api.h:280
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:289
#define hipHostMallocDefault
Flags that can be used with hipHostMalloc.
Definition: hip_runtime_api.h:169
Maximum dimension width of 3D images in image elements.
Definition: hip_runtime_api.h:309
iGPU
Definition: hip_runtime_api.h:302
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:284
int maxTexture1D
Maximum number of elements in 1D images.
Definition: hip_runtime_api.h:120
Definition: hip_runtime_api.h:144
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:275
Minor compute capability version number.
Definition: hip_runtime_api.h:294
Definition: hip_runtime_api.h:276
int pciBusID
PCI Bus ID.
Definition: hip_runtime_api.h:111
Maximum y-dimension of a grid.
Definition: hip_runtime_api.h:274
Multiple GPU devices.
Definition: hip_runtime_api.h:301
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:271
hipError_t hipHostMalloc(void **ptr, size_t size, unsigned int flags)
Allocate device accessible page locked host memory.
Definition: hip_memory.cpp:371
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:304
int maxThreadsPerMultiProcessor
Maximum resident threads per multi-processor.
Definition: hip_runtime_api.h:104
int l2CacheSize
L2 cache size.
Definition: hip_runtime_api.h:103
hipDeviceAttribute_t
Definition: hip_runtime_api.h:268
Major compute capability version number.
Definition: hip_runtime_api.h:293
Maximum number of threads per block.
Definition: hip_runtime_api.h:269
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:311
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:272
PCI Bus ID.
Definition: hip_runtime_api.h:297
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:308
Warp size in threads.
Definition: hip_runtime_api.h:279
int major
Definition: hip_runtime_api.h:96
Maximum dimensions height of 3D images in image elements.
Definition: hip_runtime_api.h:310
Peak memory clock frequency in kilohertz.
Definition: hip_runtime_api.h:285
Definition: hip_runtime_api.h:291
Address of the HDP_REG_COHERENCY_FLUSH_CNTL register.
Definition: hip_runtime_api.h:314
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:278
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
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:239
Compute mode that device is currently in.
Definition: hip_runtime_api.h:288
PCI Device ID.
Definition: hip_runtime_api.h:298
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:287
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:303
Maximum number of elements in 1D images.
Definition: hip_runtime_api.h:306
int pciDeviceID
PCI Device ID.
Definition: hip_runtime_api.h:112
int pciDomainID
PCI Domain ID.
Definition: hip_runtime_api.h:110
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 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:307
Address of the HDP_MEM_COHERENCY_FLUSH_CNTL register.
Definition: hip_runtime_api.h:313
int maxTexture2D[2]
Maximum dimensions (width, height) of 2D images, in image elements.
Definition: hip_runtime_api.h:121
Definition: hip_runtime_api.h:295
int multiProcessorCount
Number of multi-processors (compute units).
Definition: hip_runtime_api.h:102