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 
122 
126 typedef enum hipMemoryType {
127  hipMemoryTypeHost,
128  hipMemoryTypeDevice,
129  hipMemoryTypeArray,
131  hipMemoryTypeUnified
133 }hipMemoryType;
134 
135 
139 typedef struct hipPointerAttribute_t {
140  enum hipMemoryType memoryType;
141  int device;
142  void* devicePointer;
143  void* hostPointer;
144  int isManaged;
145  unsigned allocationFlags; /* flags specified when memory was allocated*/
146  /* peers? */
148 
149 
150 // hack to get these to show up in Doxygen:
157 // Ignoring error-code return values from hip APIs is discouraged. On C++17,
158 // we can make that yield a warning
159 #if __cplusplus >= 201703L
160 #define __HIP_NODISCARD [[nodiscard]]
161 #else
162 #define __HIP_NODISCARD
163 #endif
164 
165 /*
166  * @brief hipError_t
167  * @enum
168  * @ingroup Enumerations
169  */
170 // Developer note - when updating these, update the hipErrorName and hipErrorString functions in
171 // NVCC and HCC paths Also update the hipCUDAErrorTohipError function in NVCC path.
172 
173 typedef enum __HIP_NODISCARD hipError_t {
174  hipSuccess = 0,
175  hipErrorOutOfMemory = 2,
176  hipErrorNotInitialized = 3,
177  hipErrorDeinitialized = 4,
178  hipErrorProfilerDisabled = 5,
179  hipErrorProfilerNotInitialized = 6,
180  hipErrorProfilerAlreadyStarted = 7,
181  hipErrorProfilerAlreadyStopped = 8,
182  hipErrorInsufficientDriver = 35,
183  hipErrorInvalidImage = 200,
184  hipErrorInvalidContext = 201,
185  hipErrorContextAlreadyCurrent = 202,
186  hipErrorMapFailed = 205,
187  hipErrorUnmapFailed = 206,
188  hipErrorArrayIsMapped = 207,
189  hipErrorAlreadyMapped = 208,
190  hipErrorNoBinaryForGpu = 209,
191  hipErrorAlreadyAcquired = 210,
192  hipErrorNotMapped = 211,
193  hipErrorNotMappedAsArray = 212,
194  hipErrorNotMappedAsPointer = 213,
195  hipErrorECCNotCorrectable = 214,
196  hipErrorUnsupportedLimit = 215,
197  hipErrorContextAlreadyInUse = 216,
198  hipErrorPeerAccessUnsupported = 217,
199  hipErrorInvalidKernelFile = 218,
200  hipErrorInvalidGraphicsContext = 219,
201  hipErrorInvalidSource = 300,
202  hipErrorFileNotFound = 301,
203  hipErrorSharedObjectSymbolNotFound = 302,
204  hipErrorSharedObjectInitFailed = 303,
205  hipErrorOperatingSystem = 304,
206  hipErrorSetOnActiveProcess = 305,
207  hipErrorInvalidHandle = 400,
208  hipErrorNotFound = 500,
209  hipErrorIllegalAddress = 700,
210  hipErrorInvalidSymbol = 701,
211  // Runtime Error Codes start here.
212  hipErrorMissingConfiguration = 1001,
213  hipErrorMemoryAllocation = 1002,
214  hipErrorInitializationError = 1003,
215  hipErrorLaunchFailure =
216  1004,
217  hipErrorPriorLaunchFailure = 1005,
218  hipErrorLaunchTimeOut = 1006,
219  hipErrorLaunchOutOfResources = 1007,
220  hipErrorInvalidDeviceFunction = 1008,
221  hipErrorInvalidConfiguration = 1009,
222  hipErrorInvalidDevice = 1010,
223  hipErrorInvalidValue = 1011,
224  hipErrorInvalidDevicePointer = 1017,
226  hipErrorInvalidMemcpyDirection = 1021,
227  hipErrorUnknown = 1030,
228  hipErrorInvalidResourceHandle = 1033,
229  hipErrorNotReady = 1034,
230  hipErrorNoDevice = 1038,
234  hipErrorPeerAccessAlreadyEnabled =
235  1050,
236 
237  hipErrorPeerAccessNotEnabled =
238  1051,
239  hipErrorRuntimeMemory = 1052,
240  hipErrorRuntimeOther = 1053,
242  hipErrorHostMemoryAlreadyRegistered =
244  1061,
245  hipErrorHostMemoryNotRegistered =
246  1062,
247  hipErrorMapBufferObjectFailed =
248  1071,
249  hipErrorAssert =
250  1081,
251  hipErrorTbd
252 } hipError_t;
253 
254 #undef __HIP_NODISCARD
255 
256 /*
257  * @brief hipDeviceAttribute_t
258  * @enum
259  * @ingroup Enumerations
260  */
261 typedef enum hipDeviceAttribute_t {
299 
300 enum hipComputeMode {
301  hipComputeModeDefault = 0,
302  hipComputeModeExclusive = 1,
303  hipComputeModeProhibited = 2,
304  hipComputeModeExclusiveProcess = 3
305 };
306 
311 #if defined(__HIP_PLATFORM_HCC__) && !defined(__HIP_PLATFORM_NVCC__)
313 #elif defined(__HIP_PLATFORM_NVCC__) && !defined(__HIP_PLATFORM_HCC__)
314 #include "hip/nvcc_detail/hip_runtime_api.h"
315 #else
316 #error("Must define exactly one of __HIP_PLATFORM_HCC__ or __HIP_PLATFORM_NVCC__");
317 #endif
318 
319 
331 #if defined(__cplusplus) && !defined(__HIP_DISABLE_CPP_FUNCTIONS__)
332 template <class T>
333 static inline hipError_t hipMalloc(T** devPtr, size_t size) {
334  return hipMalloc((void**)devPtr, size);
335 }
336 
337 // Provide an override to automatically typecast the pointer type from void**, and also provide a
338 // default for the flags.
339 template <class T>
340 static inline hipError_t hipHostMalloc(T** ptr, size_t size,
341  unsigned int flags = hipHostMallocDefault) {
342  return hipHostMalloc((void**)ptr, size, flags);
343 }
344 
345 template <class T>
346 static inline hipError_t hipMallocManaged(T** devPtr, size_t size,
347  unsigned int flags = hipMemAttachGlobal) {
348  return hipMallocManaged((void**)devPtr, size, flags);
349 }
350 #endif
351 
352 #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:263
Maximum x-dimension of a grid.
Definition: hip_runtime_api.h:266
Global memory bus width in bits.
Definition: hip_runtime_api.h:279
int minor
Definition: hip_runtime_api.h:99
int canMapHostMemory
Check whether HIP can map host memory.
Definition: hip_runtime_api.h:115
Definition: hip_runtime_api.h:273
int regsPerBlock
Registers per block.
Definition: hip_runtime_api.h:87
Definition: hip_runtime_api.h:282
#define hipHostMallocDefault
Flags that can be used with hipHostMalloc.
Definition: hip_runtime_api.h:168
iGPU
Definition: hip_runtime_api.h:295
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:277
Definition: hip_runtime_api.h:139
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:268
Minor compute capability version number.
Definition: hip_runtime_api.h:287
Definition: hip_runtime_api.h:269
int pciBusID
PCI Bus ID.
Definition: hip_runtime_api.h:111
Maximum y-dimension of a grid.
Definition: hip_runtime_api.h:267
Multiple GPU devices.
Definition: hip_runtime_api.h:294
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:264
hipError_t hipHostMalloc(void **ptr, size_t size, unsigned int flags)
Allocate device accessible page locked host memory.
Definition: hip_memory.cpp:372
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:297
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:261
Major compute capability version number.
Definition: hip_runtime_api.h:286
Maximum number of threads per block.
Definition: hip_runtime_api.h:262
int gcnArch
AMD GCN Arch Value. Eg: 803, 701.
Definition: hip_runtime_api.h:116
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:265
PCI Bus ID.
Definition: hip_runtime_api.h:290
Warp size in threads.
Definition: hip_runtime_api.h:272
int major
Definition: hip_runtime_api.h:96
Peak memory clock frequency in kilohertz.
Definition: hip_runtime_api.h:278
Definition: hip_runtime_api.h:284
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:271
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:281
PCI Device ID.
Definition: hip_runtime_api.h:291
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:280
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:296
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
Definition: hip_runtime_api.h:288
int multiProcessorCount
Number of multi-processors (compute units).
Definition: hip_runtime_api.h:102