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