From 49741f67c6fb18abfa1bfd48f52b8635c77bc080 Mon Sep 17 00:00:00 2001 From: Sebastian Luzynski Date: Thu, 14 Aug 2025 11:45:46 +0000 Subject: [PATCH] SWDEV-546303 - Add declarations for Library Management API This commit lays some groundwork to implement Library Management API calls. This change introduces function declarations and documentation. Included APIs: * hipKernelGetAttribute * hipKernelGetFunction * hipKernelGetLibrary * hipKernelGetName * hipKernelGetParamInfo * hipKernelSetAttribute * hipKernelSetCacheConfig * hipLibraryEnumerateKernels * hipLibraryGetGlobal * hipLibraryGetKernel * hipLibraryGetKernelCount * hipLibraryGetManaged * hipLibraryGetModule * hipLibraryGetUnifiedFunction * hipLibraryUnload Signed-off-by: Sebastian Luzynski --- include/hip/driver_types.h | 10 ++ include/hip/hip_runtime_api.h | 297 ++++++++++++++++++++++++++++++++++ 2 files changed, 307 insertions(+) diff --git a/include/hip/driver_types.h b/include/hip/driver_types.h index 49307d4d50c8..799e7be14304 100644 --- a/include/hip/driver_types.h +++ b/include/hip/driver_types.h @@ -510,6 +510,16 @@ typedef enum hipFunction_attribute { HIP_FUNC_ATTRIBUTE_MAX } hipFunction_attribute; +/** + * @brief Function cache configurations + */ +typedef enum hipFunc_cache { + CU_FUNC_CACHE_PREFER_NONE = 1, ///< no preference for shared memory or L1 (default) + CU_FUNC_CACHE_PREFER_SHARED = 2, ///< prefer larger shared memory and smaller L1 cache + CU_FUNC_CACHE_PREFER_L1 = 3, ///< prefer larger L1 cache and smaller shared memory + CU_FUNC_CACHE_PREFER_EQUAL = 4, ///< prefer equal sized L1 cache and shared memory +} hipFunc_cache; + typedef enum hipPointer_attribute { HIP_POINTER_ATTRIBUTE_CONTEXT = 1, ///< The context on which a pointer was allocated ///< @warning This attribute is not supported in HIP diff --git a/include/hip/hip_runtime_api.h b/include/hip/hip_runtime_api.h index 511fa0d77f1c..30f74f247389 100644 --- a/include/hip/hip_runtime_api.h +++ b/include/hip/hip_runtime_api.h @@ -3149,6 +3149,303 @@ hipError_t hipGraphExecBatchMemOpNodeSetParams(hipGraphExec_t hGraphExec, hipGra const hipBatchMemOpNodeParams* nodeParams); // end doxygen Stream Memory Operations +/** + * @} + */ +/** + *------------------------------------------------------------------------------------------------- + *------------------------------------------------------------------------------------------------- + * @defgroup Library Library Management + * @{ + * This section describes the library management functions of HIP runtime API. + */ + +typedef int hipDevice; +typedef unsigned int hipDevicePtr; + +// Placeholder types +struct hipKernel; +struct hipLibrary; + +/** + * @brief Returns information about a kernel. + * + * @param[out] pi Returned attribute value + * @param[in] attrib Attribute requested + * @param[in] kernel Kernel to query attribute of + * @param[in] dev Device to query attribute of + * + * @returns #hipSuccess, #hipErrorDeinitialized, #hipErrorNotInitialized, #hipErrorInvalidHandle, + #hipErrorInvalidValue, #hipErrorInvalidDevice + * + * Returns in *pi the integer value of the attribute attrib for the kernel kernel for the requested + device dev. The supported attributes are: + * + * @see hipLibraryLoadData, hipLibraryLoadFromFile, hipLibraryUnload, hipKernelSetAttribute, + hipLibraryGetKernel, hipLaunchKernel, hipKernelGetFunction, hipLibraryGetModule, + hipModuleGetFunction, hipFuncGetAttribute + */ +hipError_t hipKernelGetAttribute(int* pi, hipFuncAttribute attrib, hipKernel kernel, hipDevice dev); + +/** + * @brief Returns a function handle. + * + * @param[out] pFunc Returned function handle + * @param[in] kernel Kernel to retrieve function for the requested context + * + * @returns #hipSuccess, #hipErrorDeinitialized, #hipErrorNotInitialized, #hipErrorInvalidValue, + #hipErrorInvalidHandle, #hipErrorNotFound, #hipErrorInvalidContext, #hipErrorContextIsDestroyed + * + * Returns in pFunc the handle of the function for the requested kernel and the current context. + If function handle is not found, the call returns hipErrorNotFound. + * + * @see hipLibraryLoadData, hipLibraryLoadFromFile, hipLibraryUnload, hipLibraryGetKernel, + hipLibraryGetModule, hipModuleGetFunction + */ +hipError_t hipKernelGetFunction(hipFunction_t* pFunc, hipKernel kernel); + +/** + * @brief Returns a library handle. + * + * @param[out] pLib Returned library handle + * @param[in] kernel Kernel to retrieve library handle + * + * @returns #hipSuccess, #hipErrorDeinitialized, #hipErrorNotInitialized, #hipErrorInvalidValue, + #hipErrorInvalidHandle, #hipErrorNotFound + * + * Returns in pLib the handle of the library for the requested kernel. + * + * @see hipLibraryLoadData, hipLibraryLoadFromFile, hipLibraryUnload, hipLibraryGetKernel + */ +hipError_t hipKernelGetLibrary(hipLibrary* pLib, hipKernel kernel); + +/** + * @brief Returns the function name for a CUkernel handle. + * + * @param[out] name The returned name of the function + * @param[in] hfunc The function handle to retrieve the name for + * + * @returns #hipSuccess, #hipErrorInvalidValue + * + * Returns in **name the function name associated with the kernel handle hfunc. The function name + is returned as a null-terminated string. The returned name is only valid when the kernel handle + is valid. If the library is unloaded or reloaded, one must call the API again to get the updated + name. This API may return a mangled name if the function is not declared as having C linkage. + If either **name or hfunc is NULL, hipErrorInvalidValue is returned. + * + * @note Note that this function may also return error codes from previous, asynchronous launches. + */ +hipError_t hipKernelGetName(const char** name, hipKernel hfunc); + +/** + * @brief Returns the offset and size of a kernel parameter in the device-side parameter layout. + * + * @param[in] kernel The kernel to query + * @param[in] paramIndex The parameter index to query + * @param[out] paramOffset Returns the offset into the device-side parameter layout at which the + parameter resides + * @param[out] paramSize Optionally returns the size of the parameter in the device-side parameter + layout + * + * @returns #hipSuccess, #hipErrorInvalidValue + * + * Queries the kernel parameter at paramIndex into kernel's list of parameters, and returns in + paramOffset and paramSize the offset and size, respectively, where the parameter will reside in + the device-side parameter layout. This information can be used to update kernel node parameters + from the device via hipGraphKernelNodeSetParam() and hipGraphKernelNodeUpdatesApply(). + paramIndex must be less than the number of parameters that kernel takes. paramSize can be set to + NULL if only the parameter offset is desired. + * + * @note Note that this function may also return error codes from previous, asynchronous launches. + * + * @see hipFuncGetParamInfo + */ +hipError_t hipKernelGetParamInfo(hipKernel kernel, size_t paramIndex, size_t* paramOffset, size_t* paramSize); + +/** + * @brief Sets information about a kernel. + * + * @param[in] attrib Attribute requested + * @param[in] val Value to set + * @param[in] kernel Kernel to set attribute of + * @param[in] dev Device to set attribute of + * + * This call sets the value of a specified attribute attrib on the kernel for the requested device + dev to an integer value specified by val. This function returns hipSuccess if the new value of the + attribute could be successfully set. If the set fails, this call will return an error. Not all + attributes can have values set. Attempting to set a value on a read-only attribute will result in + an error (hipErrorInvalidValue). + * + * Note that attributes set using hipFuncSetAttribute() will override the attribute set by this API + irrespective of whether the call to hipFuncSetAttribute() is made before or after this API call. + However, hipKernelGetAttribute() will always return the attribute value set by this API. + * + * @returns #hipSuccess, #hipErrorDeinitialized, #hipErrorNotInitialized, #hipErrorInvalidHandle, + #hipErrorInvalidValue, #hipErrorInvalidDevice, #hipErrorOutOfMemory + * + * @note Note that this function may also return error codes from previous, asynchronous launches. + * + * @see hipCtxGetCacheConfig, hipCtxSetCacheConfig, hipFuncSetCacheConfig, hipLaunchKernel, + hipFuncGetAttributes, hipFuncSetAttribute, hipFuncIsLoaded, hipFuncLoad, hipKernelGetAttribute + */ +hipError_t hipKernelSetAttribute(hipFunction_attribute attrib, int val, hipKernel kernel, hipDevice dev); + +/** + * @brief Sets the preferred cache configuration for a device kernel. + * + * @param[in] kernel Kernel to configure cache for + * @param[in] config Requested cache configuration + * @param[in] dev Device to set attribute of + * + * On devices where the L1 cache and shared memory use the same hardware resources, this sets + through config the preferred cache configuration for the device kernel on the requested device + dev. This is only a preference. The driver will use the requested configuration if possible, but + it is free to choose a different configuration if required to execute kernel. Any context-wide + preference set via hipCtxSetCacheConfig() will be overridden by this per-kernel setting. + * + * @returns #hipSuccess, #hipErrorDeinitialized, #hipErrorNotInitialized, #hipErrorInvalidHandle, + #hipErrorInvalidValue, #hipErrorInvalidDevice, #hipErrorOutOfMemory + * + * @see hipLibraryLoadData, hipLibraryLoadFromFile, hipLibraryUnload, hipLibraryGetKernel, + hipKernelGetFunction, hipLibraryGetModule, hipModuleGetFunction, hipFuncSetCacheConfig, + hipCtxSetCacheConfig, hipLaunchKernel + */ +hipError_t hipKernelSetCacheConfig(hipKernel kernel, hipFunc_cache config, hipDevice dev); + +/** + * @brief Retrieve the kernel handles within a library. + * + * @param[out] kernels Buffer where the kernel handles are returned to + * @param[in] numKernels Maximum number of kernel handles may be returned to the buffer + * @param[in] lib Library to query from + * + * Returns in kernels a maximum number of numKernels kernel handles within lib. The returned + * kernel handle becomes invalid when the library is unloaded. + * + * @returns #hipSuccess, #hipErrorInvalidHandle, #hipErrorInvalidValue + * + * @see hipLibraryGetKernelCount + */ +hipError_t hipLibraryEnumerateKernels(hipKernel* kernels, unsigned int numKernels, hipLibrary lib); + +/** + * @brief Returns a global device pointer. + * + * @param[out] dptr Returned global device pointer for the requested context + * @param[out] bytes Returned global size in bytes + * @param[in] library Library to retrieve global from + * @param[in] name Name of global to retrieve + * + * Returns in *dptr and *bytes the base pointer and size of the global with name name for the + requested library library and the current context. If no global for the requested name name + exists, the call returns hipErrorNotFound. One of the parameters dptr or bytes (not both) can + be NULL in which case it is ignored. + * + * @returns #hipSuccess, #hipErrorDeinitialized, #hipErrorNotInitialized, #hipErrorInvalidHandle, + #hipErrorInvalidValue, #hipErrorNotFound, #hipErrorInvalidContext, #hipErrorContextIsDestroyed + * + * @see hipLibraryLoadData, hipLibraryLoadFromFile, hipLibraryUnload, hipLibraryGetModule, + hipModuleGetGlobal + */ +hipError_t hipLibraryGetGlobal(hipDevicePtr* dptr, size_t* bytes, hipLibrary library, const char* name); + +/** + * @brief Returns a kernel handle. + * + * @param[out] pKernel Returned kernel handle + * @param[in] library Library to retrieve kernel from + * @param[in] name Name of kernel to retrieve + * + * Returns in pKernel the handle of the kernel with name name located in library library. If kernel handle is not found, the call returns CUDA_ERROR_NOT_FOUND. + * + * @returns #hipSuccess, #hipErrorDeinitialized, #hipErrorNotInitialized, #hipErrorInvalidHandle, + #hipErrorInvalidValue, #hipErrorNotFound + * + * @see hipLibraryLoadData, hipLibraryLoadFromFile, hipLibraryUnload, hipKernelGetFunction, hipLibraryGetModule, hipModuleGetFunction + */ +hipError_t hipLibraryGetKernel(hipKernel* pKernel, hipLibrary library, const char* name); + +/** + * @brief Returns the number of kernels within a library. + * + * @param[out] count Number of kernels found within the library + * @param[in] lib Library to query + * + * Returns in count the number of kernels in lib. + * + * @returns #hipSuccess, #hipErrorInvalidHandle, #hipErrorInvalidValue + * + */ +hipError_t hipLibraryGetKernelCount(unsigned int* count, hipLibrary lib); + +/** + * @brief Returns a pointer to managed memory. + * + * @param[out] dptr Returned pointer to the managed memory + * @param[out] bytes Returned memory size in bytes + * @param[in] library Library to retrieve managed memory from + * @param[in] name Name of managed memory to retrieve + * + * Returns in *dptr and *bytes the base pointer and size of the managed memory with name name for + the requested library library. If no managed memory with the requested name name exists, the call + returns hipErrorNotFound. One of the parameters dptr or bytes (not both) can be NULL in which case + it is ignored. Note that managed memory for library library is shared across devices and is + registered when the library is loaded into atleast one context. + * + * @returns #hipSuccess, #hipErrorDeinitialized, #hipErrorNotInitialized, #hipErrorInvalidHandle, + #hipErrorInvalidValue, #hipErrorNotFound + * + * @see hipLibraryLoadData, hipLibraryLoadFromFile, hipLibraryUnload + */ +hipError_t hipLibraryGetManaged(hipDevicePtr* dptr, size_t* bytes, hipLibrary library, const char* name); + +/** + * @brief Returns a module handle. + * + * @param[out] pMod Returned module handle + * @param[in] library Library to retrieve module from + * + * Returns in pMod the module handle associated with the current context located in library library. + If module handle is not found, the call returns hipErrorNotFound. + * + * @returns #hipSuccess, #hipErrorDeinitialized, #hipErrorNotInitialized, #hipErrorInvalidHandle, + #hipErrorInvalidValue, #hipErrorNotFound, #hipErrorInvalidContext, #hipErrorContextIsDestroyed + * + * @see hipLibraryLoadData, hipLibraryLoadFromFile, hipLibraryUnload, hipModuleGetFunction + */ +hipError_t hipLibraryGetModule(hipModule_t* pMod, hipLibrary library); + +/** + * @brief Returns a pointer to a unified function. + * + * @param[out] fptr Returned pointer to a unified function + * @param[in] library Library to retrieve function pointer memory from + * @param[in] symbol Name of function pointer to retrieve + * + * Returns in *fptr the function pointer to a unified function denoted by symbol. If no unified + function with name symbol exists, the call returns hipErrorNotFound. + * + * @returns #hipSuccess, #hipErrorDeinitialized, #hipErrorNotInitialized, #hipErrorInvalidHandle, + #hipErrorInvalidValue, #hipErrorNotFound + * + * @see hipLibraryLoadData, hipLibraryLoadFromFile, hipLibraryUnload + */ +hipError_t hipLibraryGetUnifiedFunction(void** fptr, hipLibrary library, const char* symbol); + +/** + * @brief Unloads a library. + * + * @param[in] library Library to unload + * + * Unloads the library specified with library + * + * @returns #hipSuccess, #hipErrorDeinitialized, #hipErrorNotInitialized, #hipErrorInvalidValue + * + * @see hipLibraryLoadData, hipLibraryLoadFromFile, hipModuleUnload + */ +hipError_t hipLibraryUnload(hipLibrary library); + +// end doxygen Library Management /** * @} */