diff --git a/hipamd/include/hip/amd_detail/amd_hiprtc.h b/hipamd/include/hip/amd_detail/amd_hiprtc.h index 5933fd1c8a..2d89c61086 100644 --- a/hipamd/include/hip/amd_detail/amd_hiprtc.h +++ b/hipamd/include/hip/amd_detail/amd_hiprtc.h @@ -38,7 +38,7 @@ extern "C" { #pragma GCC visibility push (default) #endif -/* +/** * @brief hiprtcResult * @enum * @@ -60,30 +60,79 @@ typedef enum hiprtcResult { } hiprtcResult; /** - * @brief Return text string message to explain the error which occurred + * @brief Returns text string message to explain the error which occurred * - * @param [in] hiprtcResult result code to convert to string. - * @return const char pointer to the NULL-terminated error string + * @param [in] result code to convert to string. + * @return const char pointer to the NULL-terminated error string * - * @warning In HIP, this function returns the name of the error, - * if the hiprtc result is defined, it will return "Invalid HIPRTC error code" + * @warning In HIP, this function returns the name of the error, + * if the hiprtc result is defined, it will return "Invalid HIPRTC error code" * * @see hiprtcResult */ - const char* hiprtcGetErrorString(hiprtcResult result); +/** + * @brief Sets the parameters as major and minor version. + * + * @param [out] major HIP Runtime Compilation major version. + * @param [out] minor HIP Runtime Compilation minor version. + * + */ hiprtcResult hiprtcVersion(int* major, int* minor); typedef struct _hiprtcProgram* hiprtcProgram; +/** + * @brief Adds the given name exprssion to the runtime compilation program. + * + * @param [in] prog runtime compilation program instance. + * @param [in] name_expression const char pointer to the name expression. + * @return HIPRTC_SUCCESS + * + * If const char pointer is NULL, it will return HIPRTC_ERROR_INVALID_INPUT. + * + * @see hiprtcResult + */ hiprtcResult hiprtcAddNameExpression(hiprtcProgram prog, const char* name_expression); +/** + * @brief Compiles the given runtime compilation program. + * + * @param [in] prog runtime compilation program instance. + * @param [in] numOptions number of compiler options. + * @param [in] options compiler options as const array of strins. + * @return HIPRTC_SUCCESS + * + * If the compiler failed to build the runtime compilation program, + * it will return HIPRTC_ERROR_COMPILATION. + * + * @see hiprtcResult + */ hiprtcResult hiprtcCompileProgram(hiprtcProgram prog, int numOptions, const char** options); +/** + * @brief Creates an instance of hiprtcProgram with the given input parameters, + * and sets the output hiprtcProgram prog with it. + * + * @param [in, out] prog runtime compilation program instance. + * @param [in] src const char pointer to the program source. + * @param [in] name const char pointer to the program name. + * @param [in] numHeaders number of headers. + * @param [in] headers array of strings pointing to headers. + * @param [in] includeNames array of strings pointing to names included in program source. + * @return HIPRTC_SUCCESS + * + * Any invalide input parameter, it will return HIPRTC_ERROR_INVALID_INPUT + * or HIPRTC_ERROR_INVALID_PROGRAM. + * + * If failed to create the program, it will return HIPRTC_ERROR_PROGRAM_CREATION_FAILURE. + * + * @see hiprtcResult + */ hiprtcResult hiprtcCreateProgram(hiprtcProgram* prog, const char* src, const char* name, @@ -91,19 +140,82 @@ hiprtcResult hiprtcCreateProgram(hiprtcProgram* prog, const char** headers, const char** includeNames); +/** + * @brief Destroys an instance of given hiprtcProgram. + * + * @param [in] prog runtime compilation program instance. + * @return HIPRTC_SUCCESS + * + * If prog is NULL, it will return HIPRTC_ERROR_INVALID_INPUT. + * + * @see hiprtcResult + */ hiprtcResult hiprtcDestroyProgram(hiprtcProgram* prog); +/** + * @brief Gets the lowered (mangled) name from an instance of hiprtcProgram with the given input parameters, + * and sets the output lowered_name with it. + * + * @param [in] prog runtime compilation program instance. + * @param [in] name_expression const char pointer to the name expression. + * @param [in, out] lowered_name const char array to the lowered (mangled) name. + * @return HIPRTC_SUCCESS + * + * If any invalide nullptr input parameters, it will return HIPRTC_ERROR_INVALID_INPUT + * + * If name_expression is not found, it will return HIPRTC_ERROR_NAME_EXPRESSION_NOT_VALID + * + * If failed to get lowered_name from the program, it will return HIPRTC_ERROR_COMPILATION. + * + * @see hiprtcResult + */ hiprtcResult hiprtcGetLoweredName(hiprtcProgram prog, const char* name_expression, const char** lowered_name); +/** + * @brief Gets the log generated by the runtime compilation program instance. + * + * @param [in] prog runtime compilation program instance. + * @param [out] log memory pointer to the generated log. + * @return HIPRTC_SUCCESS + * + * @see hiprtcResult + */ hiprtcResult hiprtcGetProgramLog(hiprtcProgram prog, char* log); +/** + * @brief Gets the size of log generated by the runtime compilation program instance. + * + * @param [in] prog runtime compilation program instance. + * @param [out] logSizeRet size of generated log. + * @return HIPRTC_SUCCESS + * + * @see hiprtcResult + */ hiprtcResult hiprtcGetProgramLogSize(hiprtcProgram prog, size_t* logSizeRet); +/** + * @brief Gets the pointer of compilation binary by the runtime compilation program instance. + * + * @param [in] prog runtime compilation program instance. + * @param [out] code char pointer to binary. + * @return HIPRTC_SUCCESS + * + * @see hiprtcResult + */ hiprtcResult hiprtcGetCode(hiprtcProgram prog, char* code); +/** + * @brief Gets the size of compilation binary by the runtime compilation program instance. + * + * @param [in] prog runtime compilation program instance. + * @param [out] code the size of binary. + * @return HIPRTC_SUCCESS + * + * @see hiprtcResult + */ hiprtcResult hiprtcGetCodeSize(hiprtcProgram prog, size_t* codeSizeRet); #if !defined(_WIN32)