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;
129  int tccDriver;
130 
132 
133 
137 typedef enum hipMemoryType {
138  hipMemoryTypeHost,
139  hipMemoryTypeDevice,
140  hipMemoryTypeArray,
142  hipMemoryTypeUnified
144 }hipMemoryType;
145 
146 
150 typedef struct hipPointerAttribute_t {
151  enum hipMemoryType memoryType;
152  int device;
153  void* devicePointer;
154  void* hostPointer;
155  int isManaged;
156  unsigned allocationFlags; /* flags specified when memory was allocated*/
157  /* peers? */
159 
160 
161 // hack to get these to show up in Doxygen:
168 // Ignoring error-code return values from hip APIs is discouraged. On C++17,
169 // we can make that yield a warning
170 #if __cplusplus >= 201703L
171 #define __HIP_NODISCARD [[nodiscard]]
172 #else
173 #define __HIP_NODISCARD
174 #endif
175 
176 /*
177  * @brief hipError_t
178  * @enum
179  * @ingroup Enumerations
180  */
181 // Developer note - when updating these, update the hipErrorName and hipErrorString functions in
182 // NVCC and HCC paths Also update the hipCUDAErrorTohipError function in NVCC path.
183 
184 typedef enum __HIP_NODISCARD hipError_t {
185  hipSuccess = 0,
186  hipErrorOutOfMemory = 2,
187  hipErrorNotInitialized = 3,
188  hipErrorDeinitialized = 4,
189  hipErrorProfilerDisabled = 5,
190  hipErrorProfilerNotInitialized = 6,
191  hipErrorProfilerAlreadyStarted = 7,
192  hipErrorProfilerAlreadyStopped = 8,
193  hipErrorInsufficientDriver = 35,
194  hipErrorInvalidImage = 200,
195  hipErrorInvalidContext = 201,
196  hipErrorContextAlreadyCurrent = 202,
197  hipErrorMapFailed = 205,
198  hipErrorUnmapFailed = 206,
199  hipErrorArrayIsMapped = 207,
200  hipErrorAlreadyMapped = 208,
201  hipErrorNoBinaryForGpu = 209,
202  hipErrorAlreadyAcquired = 210,
203  hipErrorNotMapped = 211,
204  hipErrorNotMappedAsArray = 212,
205  hipErrorNotMappedAsPointer = 213,
206  hipErrorECCNotCorrectable = 214,
207  hipErrorUnsupportedLimit = 215,
208  hipErrorContextAlreadyInUse = 216,
209  hipErrorPeerAccessUnsupported = 217,
210  hipErrorInvalidKernelFile = 218,
211  hipErrorInvalidGraphicsContext = 219,
212  hipErrorInvalidSource = 300,
213  hipErrorFileNotFound = 301,
214  hipErrorSharedObjectSymbolNotFound = 302,
215  hipErrorSharedObjectInitFailed = 303,
216  hipErrorOperatingSystem = 304,
217  hipErrorSetOnActiveProcess = 305,
218  hipErrorInvalidHandle = 400,
219  hipErrorNotFound = 500,
220  hipErrorIllegalAddress = 700,
221  hipErrorInvalidSymbol = 701,
222  // Runtime Error Codes start here.
223  hipErrorMissingConfiguration = 1001,
224  hipErrorMemoryAllocation = 1002,
225  hipErrorInitializationError = 1003,
226  hipErrorLaunchFailure =
227  1004,
228  hipErrorPriorLaunchFailure = 1005,
229  hipErrorLaunchTimeOut = 1006,
230  hipErrorLaunchOutOfResources = 1007,
231  hipErrorInvalidDeviceFunction = 1008,
232  hipErrorInvalidConfiguration = 1009,
233  hipErrorInvalidDevice = 1010,
234  hipErrorInvalidValue = 1011,
235  hipErrorInvalidDevicePointer = 1017,
237  hipErrorInvalidMemcpyDirection = 1021,
238  hipErrorUnknown = 1030,
239  hipErrorInvalidResourceHandle = 1033,
240  hipErrorNotReady = 1034,
241  hipErrorNoDevice = 1038,
245  hipErrorPeerAccessAlreadyEnabled =
246  1050,
247 
248  hipErrorPeerAccessNotEnabled =
249  1051,
250  hipErrorRuntimeMemory = 1052,
251  hipErrorRuntimeOther = 1053,
253  hipErrorHostMemoryAlreadyRegistered =
255  1061,
256  hipErrorHostMemoryNotRegistered =
257  1062,
258  hipErrorMapBufferObjectFailed =
259  1071,
260  hipErrorAssert =
261  1081,
262  hipErrorNotSupported =
263  1082,
264  hipErrorTbd
265 } hipError_t;
266 
267 #undef __HIP_NODISCARD
268 
269 /*
270  * @brief hipDeviceAttribute_t
271  * @enum
272  * @ingroup Enumerations
273  */
274 typedef enum hipDeviceAttribute_t {
311 
318 
321 
327 
329 
330 enum hipComputeMode {
331  hipComputeModeDefault = 0,
332  hipComputeModeExclusive = 1,
333  hipComputeModeProhibited = 2,
334  hipComputeModeExclusiveProcess = 3
335 };
336 
341 #if defined(__HIP_PLATFORM_HCC__) && !defined(__HIP_PLATFORM_NVCC__)
343 #elif defined(__HIP_PLATFORM_NVCC__) && !defined(__HIP_PLATFORM_HCC__)
344 #include "hip/nvcc_detail/hip_runtime_api.h"
345 #else
346 #error("Must define exactly one of __HIP_PLATFORM_HCC__ or __HIP_PLATFORM_NVCC__");
347 #endif
348 
349 
361 #if defined(__cplusplus) && !defined(__HIP_DISABLE_CPP_FUNCTIONS__)
362 template <class T>
363 static inline hipError_t hipMalloc(T** devPtr, size_t size) {
364  return hipMalloc((void**)devPtr, size);
365 }
366 
367 // Provide an override to automatically typecast the pointer type from void**, and also provide a
368 // default for the flags.
369 template <class T>
370 static inline hipError_t hipHostMalloc(T** ptr, size_t size,
371  unsigned int flags = hipHostMallocDefault) {
372  return hipHostMalloc((void**)ptr, size, flags);
373 }
374 
375 template <class T>
376 static inline hipError_t hipMallocManaged(T** devPtr, size_t size,
377  unsigned int flags = hipMemAttachGlobal) {
378  return hipMallocManaged((void**)devPtr, size, flags);
379 }
380 #endif
381 
382 #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:276
Maximum x-dimension of a grid.
Definition: hip_runtime_api.h:279
Maximum pitch in bytes allowed by memory copies.
Definition: hip_runtime_api.h:322
Global memory bus width in bits.
Definition: hip_runtime_api.h:292
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:286
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:295
Run time limit for kernels executed on the device.
Definition: hip_runtime_api.h:324
#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:315
iGPU
Definition: hip_runtime_api.h:308
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:290
int maxTexture1D
Maximum number of elements in 1D images.
Definition: hip_runtime_api.h:120
Definition: hip_runtime_api.h:150
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:281
Minor compute capability version number.
Definition: hip_runtime_api.h:300
Definition: hip_runtime_api.h:282
int pciBusID
PCI Bus ID.
Definition: hip_runtime_api.h:111
Maximum y-dimension of a grid.
Definition: hip_runtime_api.h:280
Multiple GPU devices.
Definition: hip_runtime_api.h:307
int tccDriver
1:If device is Tesla device using TCC driver, else 0
Definition: hip_runtime_api.h:129
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:277
hipError_t hipHostMalloc(void **ptr, size_t size, unsigned int flags)
Allocate device accessible page locked host memory.
Definition: hip_memory.cpp:402
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:310
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:274
size_t textureAlignment
Alignment requirement for textures.
Definition: hip_runtime_api.h:126
Major compute capability version number.
Definition: hip_runtime_api.h:299
Maximum number of threads per block.
Definition: hip_runtime_api.h:275
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:317
int kernelExecTimeoutEnabled
Run time limit for kernels executed on the device.
Definition: hip_runtime_api.h:127
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:278
PCI Bus ID.
Definition: hip_runtime_api.h:303
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:314
Warp size in threads.
Definition: hip_runtime_api.h:285
int major
Definition: hip_runtime_api.h:96
Maximum dimensions height of 3D images in image elements.
Definition: hip_runtime_api.h:316
Peak memory clock frequency in kilohertz.
Definition: hip_runtime_api.h:291
Definition: hip_runtime_api.h:297
Address of the HDP_REG_COHERENCY_FLUSH_CNTL register.
Definition: hip_runtime_api.h:320
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:284
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:323
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:337
Compute mode that device is currently in.
Definition: hip_runtime_api.h:294
PCI Device ID.
Definition: hip_runtime_api.h:304
Device can map host memory into device address space.
Definition: hip_runtime_api.h:325
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:293
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:309
Maximum number of elements in 1D images.
Definition: hip_runtime_api.h:312
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:128
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:313
Address of the HDP_MEM_COHERENCY_FLUSH_CNTL register.
Definition: hip_runtime_api.h:319
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:326
Definition: hip_runtime_api.h:301
int multiProcessorCount
Number of multi-processors (compute units).
Definition: hip_runtime_api.h:102