# ROCm Documentation has moved to docs.amd.com

Initialization and Version

hipInit

hipError_t hipInit(unsigned int flags)

Explicitly initializes the HIP runtime.

Most HIP APIs implicitly initialize the HIP runtime. This API provides control over the timing of the initialization.

hipDeviceGet

hipError_t hipDeviceGet(hipDevice_t *device, int ordinal)

Returns a handle to a compute device.

Return

#hipSuccess, #hipErrorInavlidDevice

Parameters

  • [out] device:

  • [in] ordinal:

hipDeviceComputeCapability

hipError_t hipDeviceComputeCapability(int *major, int *minor, hipDevice_t device)

Returns the compute capability of the device.

Return

#hipSuccess, #hipErrorInavlidDevice

Parameters

  • [out] major:

  • [out] minor:

  • [in] device:

hipDeviceGetName

hipError_t hipDeviceGetName(char *name, int len, hipDevice_t device)

Returns an identifer string for the device.

Return

#hipSuccess, #hipErrorInavlidDevice

Parameters

  • [out] name:

  • [in] len:

  • [in] device:

hipDeviceGetPCIBusId

hipError_t hipDeviceGetPCIBusId(char *pciBusId, int len, int device)

Returns a PCI Bus Id string for the device, overloaded to take int device ID.

Return

#hipSuccess, #hipErrorInavlidDevice

Parameters

  • [out] pciBusId:

  • [in] len:

  • [in] device:

hipDeviceGetByPCIBusId

hipError_t hipDeviceGetByPCIBusId(int *device, const char *pciBusId)

Returns a handle to a compute device.

Return

#hipSuccess, #hipErrorInavlidDevice, #hipErrorInvalidValue

Parameters

  • [out] device: handle

  • [in] PCI: Bus ID

hipDeviceTotalMem

hipError_t hipDeviceTotalMem(size_t *bytes, hipDevice_t device)

Returns the total amount of memory on the device.

Return

#hipSuccess, #hipErrorInavlidDevice

Parameters

  • [out] bytes:

  • [in] device:

hipDriverGetVersion

hipError_t hipDriverGetVersion(int *driverVersion)

Returns the approximate HIP driver version.

Return

#hipSuccess, #hipErrorInavlidValue

Warning

The HIP feature set does not correspond to an exact CUDA SDK driver revision. This function always set *driverVersion to 4 as an approximation though HIP supports some features which were introduced in later CUDA SDK revisions. HIP apps code should not rely on the driver revision number here and should use arch feature flags to test device capabilities or conditional compilation.

See

hipRuntimeGetVersion

Parameters

  • [out] driverVersion:

hipRuntimeGetVersion

hipError_t hipRuntimeGetVersion(int *runtimeVersion)

Returns the approximate HIP Runtime version.

Return

#hipSuccess, #hipErrorInavlidValue

Warning

On HIP/HCC path this function returns HIP runtime patch version however on HIP/NVCC path this function return CUDA runtime version.

See

hipDriverGetVersion

Parameters

  • [out] runtimeVersion:

hipModuleLoad

hipError_t hipModuleLoad(hipModule_t *module, const char *fname)

Loads code object from file into a hipModule_t.

Return

hipSuccess, hipErrorInvalidValue, hipErrorInvalidContext, hipErrorFileNotFound, hipErrorOutOfMemory, hipErrorSharedObjectInitFailed, hipErrorNotInitialized

Parameters

  • [in] fname:

  • [out] module:

hipModuleUnload

hipError_t hipModuleUnload(hipModule_t module)

Frees the module.

Return

hipSuccess, hipInvalidValue module is freed and the code objects associated with it are destroyed

Parameters

  • [in] module:

hipModuleGetFunction

hipError_t hipModuleGetFunction(hipFunction_t *function, hipModule_t module, const char *kname)

Function with kname will be extracted if present in module.

Return

hipSuccess, hipErrorInvalidValue, hipErrorInvalidContext, hipErrorNotInitialized, hipErrorNotFound,

Parameters

  • [in] module:

  • [in] kname:

  • [out] function:

hipModuleGetGlobal

hipError_t hipModuleGetGlobal(hipDeviceptr_t *dptr, size_t *bytes, hipModule_t hmod, const char *name)

returns device memory pointer and size of the kernel present in the module with symbol name

Return

hipSuccess, hipErrorInvalidValue, hipErrorNotInitialized

Parameters

  • [out] dptr:

  • [out] bytes:

  • [in] hmod:

  • [in] name:

hipModuleLoadData

hipError_t hipModuleLoadData(hipModule_t *module, const void *image)

builds module from code object which resides in host memory.

Image is pointer to that location.

Return

hipSuccess, hipErrorNotInitialized, hipErrorOutOfMemory, hipErrorNotInitialized

Parameters

  • [in] image:

  • [out] module:

hipModuleLoadDataEx

hipError_t hipModuleLoadDataEx(hipModule_t *module, const void *image, unsigned int numOptions, hipJitOption *options, void **optionValues)

builds module from code object which resides in host memory.

Image is pointer to that location. Options are not used. hipModuleLoadData is called.

Return

hipSuccess, hipErrorNotInitialized, hipErrorOutOfMemory, hipErrorNotInitialized

Parameters

  • [in] image:

  • [out] module:

  • [in] number: of options

  • [in] options: for JIT

  • [in] option: values for JIT

hipModuleLaunchKernel

hipError_t hipModuleLaunchKernel(hipFunction_t f, unsigned int gridDimX, unsigned int gridDimY, unsigned int gridDimZ, unsigned int blockDimX, unsigned int blockDimY, unsigned int blockDimZ, unsigned int sharedMemBytes, hipStream_t stream, void **kernelParams, void **extra)

launches kernel f with launch parameters and shared memory on stream with arguments passed to kernelparams or extra

Return

hipSuccess, hipInvalidDevice, hipErrorNotInitialized, hipErrorInvalidValue

Warning

kernellParams argument is not yet implemented in HIP. Please use extra instead. Please refer to hip_porting_driver_api.md for sample usage.

Parameters

  • [in] f: Kernel to launch.

  • [in] gridDimX: X grid dimension specified as multiple of blockDimX.

  • [in] gridDimY: Y grid dimension specified as multiple of blockDimY.

  • [in] gridDimZ: Z grid dimension specified as multiple of blockDimZ.

  • [in] blockDimX: X block dimensions specified in work-items

  • [in] blockDimY: Y grid dimension specified in work-items

  • [in] blockDimZ: Z grid dimension specified in work-items

  • [in] sharedMemBytes: Amount of dynamic shared memory to allocate for this kernel. The kernel can access this with HIP_DYNAMIC_SHARED.

  • [in] stream: Stream where the kernel should be dispatched. May be 0, in which case th default stream is used with associated synchronization rules.

  • [in] kernelParams:

  • [in] extra: Pointer to kernel arguments. These are passed directly to the kernel and must be in the memory layout and alignment expected by the kernel.