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